cmdline: more content

cmdline.md

@@ -52,10 +52,142 @@ line lengths and force the users to limit how large amount of data that can be
 put into a single line. curl adapts to this by offering a way to provide
 command line options through a file or on stdin - using the -K option.
 
+## Garbage in, garbage out
+
+curl has very little will of its own. It tries to please you and your wishes
+to a very large extent. It also means that it will try to play with what you
+give it. If you misspell an option, it might do something unintended. If you
+pass in a slightly illegal URL, chances are curl will still deal with it and
+proceed. It means that you can pass in crazy data in some options and you can
+have curl pass on that crazy data in its transfer operation.
+
+This is a design choice, as it allows you to really tweak how curl does its
+the protocol communications and you can have curl massage your server
+implemenations in the most creative ways.
+
+## Command line options
+
+When telling curl to do something, you invoke curl with zero, one or several
+command line options to accompany the URL or set of URLs you want the transfer
+to be about. curl supports almost two hundred different options.
+
+### 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
+switches something on or changes 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
+
+### Long options
+
+Single letter options are convient 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, all the 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
+
+### 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 user name
+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 send an
+arbitrary string of data in a 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
+
+## URLs
+
+curl is called curl exactly because a substring in its name is URL (Uniform
+Resource Locator). It operates on URLs. URL is the name we casually use for
+the web address strings, like the ones we usually see prefixed with http:// or
+starting with www.
+
+URL is strictly speaking the former name for this. URI (Uniform Resource
+Identifier) is the more modern and correct name for it. It is defined in
+RFC3986.
+
+Where curl accepts a "URL" as input, it is then really a "URI". Most of the
+protocols curl understands also have a corresponding URI syntax document that
+describes how that particular URI format works.
+
+curl assumes that you give it a valid URL and it only does limited checks of
+the format in order to extract the information it deems necessary to perform
+its operation. You can for example most probably pass in illegal letters in
+the URL without curl noticing or caring and it will just pass them on.
+
+### Browsers' "address bar"
+
+It is important to realize that when you use a modern web browser, the
+"address bar" they tend to feature at the top of their main windows are not
+using "URLs" or even "URIs". They are in fact mostly using IRIs, which is a
+superset of URIs to allow internationalization like non-latin symbols and
+more, but it usually goes beyond that too as they tend to for example handle
+spaces and do magic things on percent encoding in ways none of these mention
+specifications say a client should do.
+
+The address bar is quite simply an interface for humans to enter and see
+URI-like strings.
+
+Sometimes the differences between what you see in a browser's address bar and
+what you can pass in to curl is significant.
+
 ## Many options and URLs
 
+As mentioned above, curl supports hundreds of command line options and it also
+supports an unlimited number of URLs. If your shell or command line system
+supports it, there's really no limit to how long command line you can pass to
+curl.
+
+curl will parse the entire command line first, apply the wishes from the
+command line options used, and then go over the URLs one by one (in a left to
+right order) to perform the operations.
+
+For some options (for example -o or -O that tell curl where to store the
+transfer), you may want to specify one option for each URL on the command
+line.
+
+curl will return an exit code for its operation on the last URL used.
+
 ## Separate options per URL
 
+## URL Globbing
+
 ## Config file
 
 ## Passwords and snooping