cmdline refactors

SUMMARY.md

@@ -51,7 +51,11 @@
     * [BoringSSL](build/boringssl.md)
 * [Command line concepts](cmdline/README.md)
   * [Differences](cmdline/differences.md)
-  * [Command line options](cmdline/options.md)
+  * [Command line options](cmdline/options/README.md)
+    * [Short options](cmdline/options/short.md)
+    * [Long options](cmdline/options/long.md)
+    * [Arguments to options](cmdline/options/args.md)
+    * [Negative options](cmdline/options/negative.md)
   * [Options depend on version](cmdline/versions.md)
   * [URLs](cmdline/urls/README.md)
     * [Scheme](cmdline/urls/scheme.md)
@@ -64,17 +68,16 @@
     * [Fragment](cmdline/urls/fragment.md)
     * [Browsers](cmdline/urls/browsers.md)
     * [Many options and URLs](cmdline/urls/options.md)
+    * [URL globbing](cmdline/urls/globbing.md)
     * [Connection reuse](cmdline/urls/connreuse.md)
     * [Parallel transfers](cmdline/urls/parallel.md)
     * [trurl](cmdline/urls/trurl.md)
-  * [URL globbing](cmdline/globbing.md)
   * [List options](cmdline/listopts.md)
   * [Config file](cmdline/configfile.md)
   * [Variables](cmdline/variables.md)
   * [Passwords](cmdline/passwords.md)
   * [Progress meter](cmdline/progressmeter.md)
   * [Version](cmdline/curlver.md)
-  * [Persistent connections](cmdline/persist.md)
   * [Exit code](cmdline/exitcode.md)
   * [Copy as curl](cmdline/copyas.md)
 * [Command line transfers](usingcurl/README.md)

cmdline/README.md

@@ -17,16 +17,14 @@ protocol communications and you can have curl massage your server
 implementations in the most creative ways.
 
   * [Differences](differences.md)
-  * [Command line options](options.md)
+  * [Command line options](options/)
   * [Options depend on version](versions.md)
   * [URLs](urls/)
-  * [URL globbing](globbing.md)
   * [List options](listopts.md)
   * [Config file](configfile.md)
   * [Variables](variables.md)
   * [Passwords](passwords.md)
   * [Progress meter](progressmeter.md)
   * [Version](curlver.md)
-  * [Persistent connections](persist.md)
   * [Exit code](exitcode.md)
   * [Copy as curl](copyas.md)

cmdline/options/args.md

@@ -0,0 +1,51 @@
+# Arguments to options
+
+Not all options are just simple boolean flags that enable or disable
+features. For some of them you need to pass on data, like perhaps a username
+or a path to a file. You do this by writing first the option and then the
+argument, separated with a space. Like, for example, if you want to send an
+arbitrary string of data in an HTTP POST to a server:
+
+    curl -d arbitrary http://example.com
+
+and it works the same way even if you use the long form of the option:
+
+    curl --data arbitrary http://example.com
+
+When you use the short options with arguments, you can, in fact, also write the
+data without the space separator:
+
+    curl -darbitrary http://example.com
+
+## Arguments with spaces
+
+At times you want to pass on an argument to an option, and that argument
+contains one or more spaces. For example you want to set the user-agent field
+curl uses to be exactly `I am your father`, including those three spaces. Then
+you need to put quotes around the string when you pass it to curl on the
+command line. The exact quotes to use varies depending on your shell/command
+prompt, but generally it works with double quotes in most places:
+
+    curl -A "I am your father" http://example.com
+
+Failing to use quotes, like if you would write the command line like this:
+
+    curl -A I am your father http://example.com
+
+… makes curl only use 'I' as a user-agent string, and the following strings,
+`am`, `your` and `father` are instead treated as separate URLs since they do
+not start with `-` to indicate that they are options and curl only ever
+handles options and URLs.
+
+To make the string itself contain double quotes, which is common when you for
+example want to send a string of JSON to the server, you may need to use
+single quotes (except on Windows, where single quotes do not work the same
+way). Send the JSON string `{ "name": "Darth" }`:
+
+    curl -d '{ "name": "Darth" }' http://example.com
+
+Or if you want to avoid the single quote thing, you may prefer to send the
+data to curl via a file, which then does not need the extra quoting. Assuming
+we call the file 'json' that contains the above mentioned data:
+
+    curl -d @json http://example.com

cmdline/options/long.md

@@ -0,0 +1,19 @@
+# Long options
+
+Single-letter options are convenient since they are quick to write and use, but
+as there are only a limited number of letters in the alphabet and there are
+many things to control, not all options are available like that. Long option
+names are therefore provided for those. Also, as a convenience and to allow
+scripts to become more readable, most short options have longer name
+aliases.
+
+Long options are always written with *two* minuses (or *dashes*, whichever you
+prefer to call them) and then the name and you can only write one option name
+per double-minus. Asking for verbose mode using the long option format looks
+like:
+
+    curl --verbose http://example.com
+
+and asking for HTTP redirects as well using the long format looks like:
+
+    curl --verbose --location http://example.com

cmdline/options/negative.md

@@ -0,0 +1,7 @@
+# Negative options
+
+For options that switch on something, boolean options, there is also a way to
+switch them off. You then use the long form of the option with an initial
+`no-` prefix before the name. As an example, to switch off verbose mode:
+
+    curl --no-verbose http://example.com

cmdline/options/short.md

@@ -0,0 +1,25 @@
+# Short options
+
+Command line options pass on information to curl about how you want it to
+behave. Like you can ask curl to switch on verbose mode with the -v option:
+
+    curl -v http://example.com
+
+-v is here used as a "short option". You write those with the minus symbol and
+a single letter immediately following it. Many options are just switches that
+switch something on or change something between two known states. They can
+be used with just that option name. You can then also combine several
+single-letter options after the minus. To ask for both verbose mode and that
+curl follows HTTP redirects:
+
+    curl -vL http://example.com
+
+The command-line parser in curl always parses the entire line and you can put
+the options anywhere you like; they can also appear after the URL:
+
+    curl http://example.com -Lv
+
+and the two separate short options can of course also be specified separately,
+like:
+
+    curl -v -L http://example.com

cmdline/urls/README.md

@@ -23,6 +23,7 @@ describes how that particular URI format works.
 * [Fragment](fragment.md)
 * [Browsers](browsers.md)
 * [Many options and URLs](options.md)
+* [URL globbing](globbing.md)
 * [Connection reuse](connreuse.md)
 * [Parallel transfers](parallel.md)
 * [trurl](trurl.md)

cmdline/urls/connreuse.md

@@ -1,14 +1,21 @@
 # Connection reuse
 
-Setting up a TCP connection and especially a TLS connection can be a slow
-process, even on high bandwidth networks.
-
-It can be useful to remember that curl has a connection pool internally which
-keeps previously used connections alive and around for a while after they were
-used so that subsequent requests to the same hosts can reuse an already
-established connection.
-
-Of course, they can only be kept alive for as long as the curl tool is
-running. It is a good reason for trying to get several transfers done
-within the same command line instead of running several independent curl
-command line invocations.
+When setting up connections to sites, curl keeps old connections around for a
+while so that if the next transfer is done using the same host as a previous
+transfer, it can reuse the same connection again and thus save a lot of
+time. We call this persistent connections. curl always tries to keep
+connections alive and reuses existing connections as far as it can.
+
+Connections are kept in the *connection pool*, sometimes also called the
+*connection cache*.
+
+The curl command-line tool can, however, only keep connections alive for as
+long as it runs, so as soon as it exits back to your command line it has to
+close down all currently open connections (and also free and clean up all the
+other caches it uses to decrease time of subsequent operations). We call the
+pool of alive connections the *connection cache*.
+
+If you want to perform N transfers or operations against the same host or same
+base URL, you could gain a lot of speed by trying to do them in as few curl
+command lines as possible instead of repeatedly invoking curl with one URL at
+a time.

ftp/upload.md

@@ -19,8 +19,8 @@ overwriting, with the `--append` option:
 
     curl -T uploadthis --append ftp://example.com/directory/remotename
 
-curl also supports [globbing](../cmdline/globbing.md) in the `-T` argument so
-you can opt to easily upload a range of files:
+curl also supports [globbing](../cmdline/urls/globbing.md) in the `-T`
+argument so you can opt to easily upload a range of files:
 
     curl -T 'image[1-99].jpg' ftp://ftp.example.com/upload/