From d7f737dd1359b20432bf5e65401ea4c22526fca5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 22 Mar 2021 16:50:57 +0100 Subject: [PATCH] docs: make gen.pl support *italic* and **bold** Remove some nroffisms from the cmdline doc files to simplify editing, and instead support this markdown style. Closes #6771 --- docs/cmdline-opts/MANPAGE.md | 16 +++++++++++----- docs/cmdline-opts/data-urlencode.d | 4 ++-- docs/cmdline-opts/disable.d | 2 +- docs/cmdline-opts/dns-servers.d | 2 +- docs/cmdline-opts/etag-compare.d | 2 +- docs/cmdline-opts/form.d | 10 +++++----- docs/cmdline-opts/gen.pl | 6 ++++++ docs/cmdline-opts/header.d | 4 ++-- docs/cmdline-opts/max-filesize.d | 2 +- docs/cmdline-opts/netrc-optional.d | 2 +- docs/cmdline-opts/netrc.d | 8 ++++---- docs/cmdline-opts/page-footer | 2 +- docs/cmdline-opts/page-header | 12 ++++++------ docs/cmdline-opts/proto-default.d | 4 ++-- docs/cmdline-opts/proto-redir.d | 2 +- docs/cmdline-opts/proxy-header.d | 2 +- docs/cmdline-opts/quote.d | 4 ++-- docs/cmdline-opts/remote-header-name.d | 2 +- docs/cmdline-opts/tcp-nodelay.d | 2 +- docs/cmdline-opts/time-cond.d | 2 +- docs/cmdline-opts/write-out.d | 4 ++-- 21 files changed, 53 insertions(+), 41 deletions(-) diff --git a/docs/cmdline-opts/MANPAGE.md b/docs/cmdline-opts/MANPAGE.md index 3a8270b03e..b903bc25e0 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 2f2a3645bc..2205f9db48 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 688fc0c54d..d909608844 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 8665426a83..0ff26636c1 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 cd8fe4a33a..c6ed39cb78 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 3cd8dce756..2c65ddd9b4 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 1fe4a92c99..e651f029a5 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 980467d5b0..121285ae37 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 1f6bdc663d..e1e2849fcf 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 fa92032bd2..e0b59d19b8 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 6aac568a64..cab3385b47 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 4ae7cad652..b101ace353 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 02e73e6c9e..4162d57664 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 1c2afea2c9..74d3932cf9 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 9a096f5319..10580ad834 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 9f1121d2f1..c2b0928f98 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 a33ed3571d..96b178cb5d 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 700da69fc0..325dade3f0 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 f1cf644a43..90483d2e40 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 f733eeb0bf..0b56c6ee39 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 0579cae693..89ac700f6a 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) -- 2.47.3