cmdline/urls/query.md: document --url-query

closes #311

Author: bagder

SUMMARY.md

@@ -57,6 +57,7 @@
     * [Host](cmdline/urls/host.md)
     * [Port number](cmdline/urls/port.md)
     * [Path](cmdline/urls/path.md)
+    * [Query](cmdline/urls/query.md)
     * [FTP type](cmdline/urls/ftptype.md)
     * [Fragment](cmdline/urls/fragment.md)
     * [Browsers' address bar](cmdline/urls/browsers.md)

cmdline/urls.md

@@ -18,6 +18,7 @@ describes how that particular URI format works.
 * [Host](urls/host.md)
 * [Port number](urls/port.md)
 * [Path](urls/path.md)
+* [Query](urls/query.md)
 * [FTP type](urls/ftptype.md)
 * [Fragment](urls/fragment.md)
 * [Browsers' address bar](urls/browsers.md)

cmdline/urls/query.md

@@ -0,0 +1,42 @@
+# Query
+
+The query part of a URL is the data that is to the right of a question mark
+(`?`) but to the left of the [fragment](fragment.md), which begins with a hash
+(`#`).
+
+The query can be any string of characters really as long as they are URL
+encoded. It is a common practice to use a sequence of key/value pairs
+separated by ampersands (`&`). Like in
+`https://example.com/?name=daniel&tool=curl`.
+
+To help users create such query sets, properly encoded, curl offers the
+command line option `--url-query [content]`. This option adds content, usually
+a name + value pair, to the end of the query part of the provided URL.
+
+When adding query parts, curl adds ampersand separators.
+
+The syntax is identical to that used `--data-urlencode` with one extension:
+the `+` prefix. See below.
+
+ - `content`: This will make curl URL encode the content and add that to the
+   query. Just be careful so that the content does not contain any `=` or `@`
+   symbols, as that will then make the syntax match one of the other cases
+   below!
+
+ - `=content`: This will make curl URL encode the content and add that to the
+   query. The initial `=` symbol is not included in the data.
+
+ - `name=content`: This will make curl URL encode the content part and add
+   that to the query. Note that the name part is expected to be URL encoded
+   already.
+
+ - `@filename`: This will make curl load data from the given file (including
+   any newlines), URL encode that data and that to the query.
+
+ - `name@filename`: This will make curl load data from the given file
+   (including any newlines), URL encode that data and add it to the query.
+   The name part gets an equal sign appended, resulting in
+   `name=urlencoded-file-content`. Note that the name is expected to be URL
+   encoded already.
+
+ - `+content`: Add the content to the query without doing any encoding.

http/post/url-encode.md

@@ -19,11 +19,12 @@ followed by a separator and a content specification. The **data** part can be
 passed to curl using one of the following syntaxes:
 
  - `content`: This will make curl URL encode the content and pass that
-   on. Just be careful so that the content does not contain any = or @ symbols,
-   as that will then make the syntax match one of the other cases below!
+   on. Just be careful so that the content does not contain any `=` or `@`
+   symbols, as that will then make the syntax match one of the other cases
+   below!
 
  - `=content`: This will make curl URL encode the content and pass that
-   on. The initial '=' symbol is not included in the data.
+   on. The initial `=` symbol is not included in the data.
 
  - `name=content`: This will make curl URL encode the content part and pass
    that on. Note that the name part is expected to be URL encoded already.
@@ -34,7 +35,7 @@ passed to curl using one of the following syntaxes:
  - `name@filename`: This will make curl load data from the given file
    (including any newlines), URL encode that data and pass it on in the POST.
    The name part gets an equal sign appended, resulting in
-   name=urlencoded-file-content. Note that the name is expected to be URL
+   `name=urlencoded-file-content`. Note that the name is expected to be URL
    encoded already.
 
 As an example, you could POST a name to have it encoded by curl:

index-words

@@ -78,6 +78,7 @@
 --trace
 --trace-ascii
 --trace-time
+--url-query
 --variable
 --verbose
 --version