diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 3a8270b03e432f..b903bc25e09da5 100644 --- a/docs/cmdline-opts/MANPAGE.md +++ b/docs/cmdline-opts/MANPAGE.md @@ -3,7 +3,8 @@ This is the curl man page generator. It generates a single nroff man page output from the set of sources files in this directory. -There is one source file for each supported command line option. The format is +There is one source file for each supported command line option. The output +gets `page-header` prepended and `page-footer` appended. The format is described below. ## Option files @@ -32,13 +33,18 @@ Each file has a set of meta-data and a body of text. ### Body The body of the description. Only refer to options with their long form option -version, like --verbose. The output generator will replace such with the +version, like `--verbose`. The output generator will replace such with the correct markup that shows both short and long version. -## Header +Text written within `*asterisks*` will get shown using italics. Text within +two `**asterisks**` will get shown using bold. -`page-header` is the nroff formatted file that will be output before the -generated options output for the master man page. +## Header and footer + +`page-header` is the file that will be output before the generated options +output for the master man page. + +`page-footer` is appended after all the individual options. ## Generate diff --git a/docs/cmdline-opts/data-urlencode.d b/docs/cmdline-opts/data-urlencode.d index 2f2a3645bc408f..2205f9db481ca9 100644 --- a/docs/cmdline-opts/data-urlencode.d +++ b/docs/cmdline-opts/data-urlencode.d @@ -9,7 +9,7 @@ Category: http post upload This posts data, similar to the other --data options with the exception that this performs URL-encoding. -To be CGI-compliant, the part should begin with a \fIname\fP followed +To be CGI-compliant, the part should begin with a *name* followed by a separator and a content specification. The part can be passed to curl using one of the following syntaxes: .RS @@ -29,6 +29,6 @@ URL-encode that data and pass it on in the POST. .IP "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 \fIname=urlencoded-file-content\fP. Note that the +sign appended, resulting in *name=urlencoded-file-content*. Note that the name is expected to be URL-encoded already. .RE diff --git a/docs/cmdline-opts/disable.d b/docs/cmdline-opts/disable.d index 688fc0c54d2672..d9096088449895 100644 --- a/docs/cmdline-opts/disable.d +++ b/docs/cmdline-opts/disable.d @@ -3,6 +3,6 @@ Short: q Help: Disable .curlrc Category: curl --- -If used as the first parameter on the command line, the \fIcurlrc\fP config +If used as the first parameter on the command line, the *curlrc* config file will not be read and used. See the --config for details on the default config file search path. diff --git a/docs/cmdline-opts/dns-servers.d b/docs/cmdline-opts/dns-servers.d index 8665426a83a8a8..0ff26636c1f846 100644 --- a/docs/cmdline-opts/dns-servers.d +++ b/docs/cmdline-opts/dns-servers.d @@ -7,5 +7,5 @@ Category: dns --- Set the list of DNS servers to be used instead of the system default. The list of IP addresses should be separated with commas. Port numbers -may also optionally be given as \fI:\fP after each IP +may also optionally be given as *:* after each IP address. diff --git a/docs/cmdline-opts/etag-compare.d b/docs/cmdline-opts/etag-compare.d index cd8fe4a33a2baf..c6ed39cb787ce4 100644 --- a/docs/cmdline-opts/etag-compare.d +++ b/docs/cmdline-opts/etag-compare.d @@ -15,5 +15,5 @@ line with a desired ETag. An empty file is parsed as an empty ETag. Use the option --etag-save to first save the ETag from a response, and then use this option to compare using the saved ETag in a subsequent request. -\fBCOMPARISON\fP: There are 2 types of comparison or ETags: Weak and Strong. +**COMPARISON**: There are 2 types of comparison or ETags: Weak and Strong. This option expects, and uses a strong comparison. diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d index 3cd8dce756de49..2c65ddd9b4a1e4 100644 --- a/docs/cmdline-opts/form.d +++ b/docs/cmdline-opts/form.d @@ -121,11 +121,11 @@ text file: -F '=)' -F '=@textfile.txt' ... smtp://example.com Data can be encoded for transfer using encoder=. Available encodings are -\fIbinary\fP and \fI8bit\fP that do nothing else than adding the corresponding -Content-Transfer-Encoding header, \fI7bit\fP that only rejects 8-bit characters -with a transfer error, \fIquoted-printable\fP and \fIbase64\fP that encodes -data according to the corresponding schemes, limiting lines length to -76 characters. +*binary* and *8bit* that do nothing else than adding the corresponding +Content-Transfer-Encoding header, *7bit* that only rejects 8-bit characters +with a transfer error, *quoted-printable* and *base64* that encodes data +according to the corresponding schemes, limiting lines length to 76 +characters. Example: send multipart mail with a quoted-printable text message and a base64 attached file: diff --git a/docs/cmdline-opts/gen.pl b/docs/cmdline-opts/gen.pl index 1fe4a92c995160..e651f029a59bda 100755 --- a/docs/cmdline-opts/gen.pl +++ b/docs/cmdline-opts/gen.pl @@ -63,6 +63,12 @@ sub manpageify { sub printdesc { my @desc = @_; for my $d (@desc) { + if($d !~ /^.\\"/) { + # **bold** + $d =~ s/\*\*([^ ]*)\*\*/\\fB$1\\fP/g; + # *italics* + $d =~ s/\*([^ ]*)\*/\\fI$1\\fP/g; + } # skip lines starting with space (examples) if($d =~ /^[^ ]/) { for my $k (keys %optlong) { diff --git a/docs/cmdline-opts/header.d b/docs/cmdline-opts/header.d index 980467d5b0c5cd..121285ae37224a 100644 --- a/docs/cmdline-opts/header.d +++ b/docs/cmdline-opts/header.d @@ -18,7 +18,7 @@ header with no-value then its header must be terminated with a semicolon, such as \-H \&"X-Custom-Header;" to send "X-Custom-Header:". curl will make sure that each header you add/replace is sent with the proper -end-of-line marker, you should thus \fBnot\fP add that as a part of the header +end-of-line marker, you should thus **not** add that as a part of the header content: do not add newlines or carriage returns, they will only mess things up for you. @@ -36,7 +36,7 @@ Example: curl -H "X-First-Name: Joe" http://example.com/ -\fBWARNING\fP: headers set with this option will be set in all requests - even +**WARNING**: headers set with this option will be set in all requests - even after redirects are followed, like when told with --location. This can lead to the header being sent to other hosts than the original host, so sensitive headers should be used with caution combined with following redirects. diff --git a/docs/cmdline-opts/max-filesize.d b/docs/cmdline-opts/max-filesize.d index 1f6bdc663d1f86..e1e2849fcf4ad2 100644 --- a/docs/cmdline-opts/max-filesize.d +++ b/docs/cmdline-opts/max-filesize.d @@ -12,6 +12,6 @@ A size modifier may be used. For example, Appending 'k' or 'K' will count the number as kilobytes, 'm' or 'M' makes it megabytes, while 'g' or 'G' makes it gigabytes. Examples: 200K, 3m and 1G. (Added in 7.58.0) -\fBNOTE:\fP The file size is not always known prior to download, and for such +**NOTE**: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. diff --git a/docs/cmdline-opts/netrc-optional.d b/docs/cmdline-opts/netrc-optional.d index fa92032bd234f8..e0b59d19b87cc2 100644 --- a/docs/cmdline-opts/netrc-optional.d +++ b/docs/cmdline-opts/netrc-optional.d @@ -4,5 +4,5 @@ Mutexed: netrc See-also: netrc-file Category: curl --- -Very similar to --netrc, but this option makes the .netrc usage \fBoptional\fP +Very similar to --netrc, but this option makes the .netrc usage **optional** and not mandatory as the --netrc option does. diff --git a/docs/cmdline-opts/netrc.d b/docs/cmdline-opts/netrc.d index 6aac568a6438b4..cab3385b473269 100644 --- a/docs/cmdline-opts/netrc.d +++ b/docs/cmdline-opts/netrc.d @@ -3,15 +3,15 @@ Short: n Help: Must read .netrc for user name and password Category: curl --- -Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the user's -home directory for login name and password. This is typically used for FTP on +Makes curl scan the *.netrc* (*_netrc* on Windows) file in the user's home +directory for login name and password. This is typically used for FTP on Unix. If used with HTTP, curl will enable user authentication. See -\fInetrc(5)\fP \fIftp(1)\fP for details on the file format. Curl will not +*netrc(5)* *ftp(1)* for details on the file format. Curl will not complain if that file doesn't have the right permissions (it should not be either world- or group-readable). The environment variable "HOME" is used to find the home directory. -A quick and very simple example of how to setup a \fI.netrc\fP to allow curl +A quick and very simple example of how to setup a *.netrc* to allow curl to FTP to the machine host.domain.com with user name \&'myself' and password \&'secret' should look similar to: diff --git a/docs/cmdline-opts/page-footer b/docs/cmdline-opts/page-footer index 4ae7cad6520319..b101ace3536366 100644 --- a/docs/cmdline-opts/page-footer +++ b/docs/cmdline-opts/page-footer @@ -71,7 +71,7 @@ The supported proxy protocol prefixes are as follows: .IP "http://" Makes it use it as an HTTP proxy. The default if no scheme prefix is used. .IP "https://" -Makes it treated as an \fBHTTPS\fP proxy. +Makes it treated as an **HTTPS** proxy. .IP "socks4://" Makes it the equivalent of --socks4 .IP "socks4a://" diff --git a/docs/cmdline-opts/page-header b/docs/cmdline-opts/page-header index 02e73e6c9e1239..4162d57664186e 100644 --- a/docs/cmdline-opts/page-header +++ b/docs/cmdline-opts/page-header @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -41,7 +41,7 @@ resume, Metalink, and more. As you will see below, the number of features will make your head spin! curl is powered by libcurl for all transfer-related features. See -\fIlibcurl(3)\fP for details. +*libcurl(3)* for details. .SH URL The URL syntax is protocol-dependent. You'll find a detailed description in RFC 3986. @@ -92,7 +92,7 @@ with "ftp." curl will assume you want to speak FTP. curl will do its best to use what you pass to it as a URL. It is not trying to validate it as a syntactically correct URL by any means but is instead -\fBvery\fP liberal with what it accepts. +**very** liberal with what it accepts. curl will attempt to re-use connections for multiple file transfers, so that getting many files from the same server will not do multiple connects / @@ -166,7 +166,7 @@ bytes. 1M is 1048576 bytes. curl displays this data to the terminal by default, so if you invoke curl to do an operation and it is about to write data to the terminal, it -\fIdisables\fP the progress meter as otherwise it would mess up the output +*disables* the progress meter as otherwise it would mess up the output mixing progress meter and response data. If you want a progress meter for HTTP POST or PUT requests, you need to @@ -192,8 +192,8 @@ Short version options that don't need any additional values can be used immediately next to each other, like for example you can specify all the options -O, -L and -v at once as -OLv. -In general, all boolean options are enabled with --\fBoption\fP and yet again -disabled with --\fBno-\fPoption. That is, you use the exact same option name +In general, all boolean options are enabled with --**option** and yet again +disabled with --**no-**option. That is, you use the exact same option name but prefix it with "no-". However, in this list we mostly only list and show the --option version of them. (This concept with --no options was added in 7.19.0. Previously most options were toggled on/off on repeated use of the diff --git a/docs/cmdline-opts/proto-default.d b/docs/cmdline-opts/proto-default.d index 1c2afea2c91be0..74d3932cf95b12 100644 --- a/docs/cmdline-opts/proto-default.d +++ b/docs/cmdline-opts/proto-default.d @@ -4,14 +4,14 @@ Arg: Added: 7.45.0 Category: connection curl --- -Tells curl to use \fIprotocol\fP for any URL missing a scheme name. +Tells curl to use *protocol* for any URL missing a scheme name. Example: curl --proto-default https ftp.mozilla.org An unknown or unsupported protocol causes error -\fICURLE_UNSUPPORTED_PROTOCOL\fP (1). +*CURLE_UNSUPPORTED_PROTOCOL* (1). This option does not change the default proxy protocol (http). diff --git a/docs/cmdline-opts/proto-redir.d b/docs/cmdline-opts/proto-redir.d index 9a096f5319223f..10580ad834beb2 100644 --- a/docs/cmdline-opts/proto-redir.d +++ b/docs/cmdline-opts/proto-redir.d @@ -15,5 +15,5 @@ Example, allow only HTTP and HTTPS on redirect: By default curl will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). Older versions of curl allowed all protocols on redirect except several disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and -since 7.40.0 SMB and SMBS are also disabled. Specifying \fIall\fP or \fI+all\fP +since 7.40.0 SMB and SMBS are also disabled. Specifying *all* or *+all* enables all protocols on redirect, including those disabled for security. diff --git a/docs/cmdline-opts/proxy-header.d b/docs/cmdline-opts/proxy-header.d index 9f1121d2f16bea..c2b0928f986415 100644 --- a/docs/cmdline-opts/proxy-header.d +++ b/docs/cmdline-opts/proxy-header.d @@ -11,7 +11,7 @@ but is for proxy communication only like in CONNECT requests when you want a separate header sent to the proxy to what is sent to the actual remote host. curl will make sure that each header you add/replace is sent with the proper -end-of-line marker, you should thus \fBnot\fP add that as a part of the header +end-of-line marker, you should thus **not** add that as a part of the header content: do not add newlines or carriage returns, they will only mess things up for you. diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d index a33ed3571d6e18..96b178cb5d5d7b 100644 --- a/docs/cmdline-opts/quote.d +++ b/docs/cmdline-opts/quote.d @@ -30,7 +30,7 @@ all supported SFTP quote commands: .IP "atime date file" The atime command sets the last access time of the file named by the file operand. The can be all sorts of date strings, see the -\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) +*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) .IP "chgrp group file" The chgrp command sets the group ID of the file named by the file operand to the group ID specified by the group operand. The group operand is a decimal @@ -50,7 +50,7 @@ The mkdir command creates the directory named by the directory_name operand. .IP "mtime date file" The mtime command sets the last modification time of the file named by the file operand. The can be all sorts of date strings, see the -\fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) +*curl_getdate(3)* man page for date expression details. (Added in 7.73.0) .IP "pwd" The pwd command returns the absolute pathname of the current working directory. .IP "rename source target" diff --git a/docs/cmdline-opts/remote-header-name.d b/docs/cmdline-opts/remote-header-name.d index 700da69fc0ebb7..325dade3f072b8 100644 --- a/docs/cmdline-opts/remote-header-name.d +++ b/docs/cmdline-opts/remote-header-name.d @@ -15,6 +15,6 @@ effect. There's no attempt to decode %-sequences (yet) in the provided file name, so this option may provide you with rather unexpected file names. -\fBWARNING\fP: Exercise judicious use of this option, especially on Windows. A +**WARNING**: Exercise judicious use of this option, especially on Windows. A rogue server could send you the name of a DLL or other file that could possibly be loaded automatically by Windows or some third party software. diff --git a/docs/cmdline-opts/tcp-nodelay.d b/docs/cmdline-opts/tcp-nodelay.d index f1cf644a430c28..90483d2e404aeb 100644 --- a/docs/cmdline-opts/tcp-nodelay.d +++ b/docs/cmdline-opts/tcp-nodelay.d @@ -3,7 +3,7 @@ Help: Use the TCP_NODELAY option Added: 7.11.2 Category: connection --- -Turn on the TCP_NODELAY option. See the \fIcurl_easy_setopt(3)\fP man page for +Turn on the TCP_NODELAY option. See the *curl_easy_setopt(3)* man page for details about this option. Since 7.50.2, curl sets this option by default and you need to explicitly diff --git a/docs/cmdline-opts/time-cond.d b/docs/cmdline-opts/time-cond.d index f733eeb0bfa770..0b56c6ee39498f 100644 --- a/docs/cmdline-opts/time-cond.d +++ b/docs/cmdline-opts/time-cond.d @@ -9,7 +9,7 @@ Request a file that has been modified later than the given time and date, or one that has been modified before that time. The can be all sorts of date strings or if it doesn't match any internal ones, it is taken as a filename and tries to get the modification date (mtime) from -instead. See the \fIcurl_getdate(3)\fP man pages for date expression details. +instead. See the *curl_getdate(3)* man pages for date expression details. Start the date expression with a dash (-) to make it request for a document that is older than the given date/time, default is a document that is newer diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d index 0579cae693f15e..89ac700f6a983f 100644 --- a/docs/cmdline-opts/write-out.d +++ b/docs/cmdline-opts/write-out.d @@ -47,7 +47,7 @@ server. (Added in 7.15.4) .TP .B http_code The numerical response code that was found in the last retrieved HTTP(S) or -FTP(s) transfer. In 7.18.2 the alias \fBresponse_code\fP was added to show the +FTP(s) transfer. In 7.18.2 the alias **response_code** was added to show the same info. .TP .B http_connect @@ -91,7 +91,7 @@ requested. 0 means the verification was successful. (Added in 7.52.0) .B redirect_url When an HTTP request was made without --location to follow redirects (or when --max-redir is met), this variable will show the actual URL a redirect -\fIwould\fP have gone to. (Added in 7.18.2) +*would* have gone to. (Added in 7.18.2) .TP .B referer The Referer: header, if there was any. (Added in 7.76.0)