From: Daniel Stenberg Date: Sat, 16 Dec 2023 10:46:31 +0000 (+0100) Subject: cmdline-docs: use .IP consistently X-Git-Tag: curl-8_6_0~215 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=67211e95402df28c8730e52b9803ba95bdadbb7f;p=thirdparty%2Fcurl.git cmdline-docs: use .IP consistently Remove use of .TP and some .B. The idea is to reduce nroff syntax as much as possible and to use it consistently. Ultimately, we should be able to introduce our own easier-to-use-and-read syntax/formatting and convert on generation time. Closes #12535 --- diff --git a/docs/cmdline-opts/form.d b/docs/cmdline-opts/form.d index e53e93ae0d..ac0e4bfefb 100644 --- a/docs/cmdline-opts/form.d +++ b/docs/cmdline-opts/form.d @@ -101,12 +101,12 @@ Here is an example of a header file contents: another header To support sending multipart mail messages, the syntax is extended as follows: -.br + - name can be omitted: the equal sign is the first character of the argument, -.br + - if data starts with '(', this signals to start a new multipart: it can be followed by a content type specification. -.br + - a multipart can be terminated with a '=)' argument. Example: the following command sends an SMTP mime email consisting in an diff --git a/docs/cmdline-opts/proto.d b/docs/cmdline-opts/proto.d index ac024bf428..6788ee567d 100644 --- a/docs/cmdline-opts/proto.d +++ b/docs/cmdline-opts/proto.d @@ -13,33 +13,23 @@ Tells curl to limit what protocols it may use for transfers. Protocols are evaluated left to right, are comma separated, and are each a protocol name or 'all', optionally prefixed by zero or more modifiers. Available modifiers are: .RS -.TP 3 -.B + +.IP + Permit this protocol in addition to protocols already permitted (this is the default if no modifier is used). -.TP -.B - +.IP - Deny this protocol, removing it from the list of protocols already permitted. -.TP -.B = +.IP = Permit only this protocol (ignoring the list already permitted), though subject to later modification by subsequent entries in the comma separated list. .RE .IP -For example: -.RS -.TP 15 -.B --proto -ftps -uses the default protocols, but disables ftps -.TP -.B --proto -all,https,+http -only enables http and https -.TP -.B --proto =http,https -also only enables http and https -.RE -.IP +For example: --proto -ftps uses the default protocols, but disables ftps + +--proto -all,https,+http only enables http and https + +--proto =http,https also only enables http and https + Unknown and disabled protocols produce a warning. This allows scripts to safely rely on being able to disable potentially dangerous protocols, without relying upon support for that protocol being built into curl to avoid an error. diff --git a/docs/cmdline-opts/quote.d b/docs/cmdline-opts/quote.d index 5008d49321..51f7917fc3 100644 --- a/docs/cmdline-opts/quote.d +++ b/docs/cmdline-opts/quote.d @@ -35,53 +35,41 @@ itself before sending them to the server. File names may be quoted shell-style to embed spaces or special characters. Following is the list of all supported SFTP quote commands: .RS -.TP -**"atime date file"** +.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 *curl_getdate(3)* man page for date expression details. (Added in 7.73.0) -.TP -**"chgrp group file"** +.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 integer group ID. -.TP -**"chmod mode file"** +.IP "chmod mode file" The chmod command modifies the file mode bits of the specified file. The mode operand is an octal integer mode number. -.TP -**"chown user file"** +.IP "chown user file" The chown command sets the owner of the file named by the file operand to the user ID specified by the user operand. The user operand is a decimal integer user ID. -.TP -**"ln source_file target_file"** +.IP "ln source_file target_file" The ln and symlink commands create a symbolic link at the target_file location pointing to the source_file location. -.TP -**"mkdir directory_name"** +.IP "mkdir directory_name" The mkdir command creates the directory named by the directory_name operand. -.TP -**"mtime date file"** +.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 *curl_getdate(3)* man page for date expression details. (Added in 7.73.0) -.TP -**"pwd"** +.IP "pwd" The pwd command returns the absolute path name of the current working directory. -.TP -**"rename source target"** +.IP "rename source target" The rename command renames the file or directory named by the source operand to the destination path named by the target operand. -.TP -**"rm file"** +.IP "rm file" The rm command removes the file specified by the file operand. -.TP -**"rmdir directory"** +.IP "rmdir directory" The rmdir command removes the directory entry specified by the directory operand, provided it is empty. -.TP -**"symlink source_file target_file"** +.IP "symlink source_file target_file" See ln. .RE .IP diff --git a/docs/cmdline-opts/range.d b/docs/cmdline-opts/range.d index eba7220e1e..09ccf5f310 100644 --- a/docs/cmdline-opts/range.d +++ b/docs/cmdline-opts/range.d @@ -14,23 +14,17 @@ Multi: single Retrieve a byte range (i.e. a partial document) from an HTTP/1.1, FTP or SFTP server or a local FILE. Ranges can be specified in a number of ways. .RS -.TP 10 -.B 0-499 +.IP 0-499 specifies the first 500 bytes -.TP -.B 500-999 +.IP 500-999 specifies the second 500 bytes -.TP -.B -500 +.IP -500 specifies the last 500 bytes -.TP -.B 9500- +.IP 9500- specifies the bytes from offset 9500 and forward -.TP -.B 0-0,-1 +.IP 0-0,-1 specifies the first and last byte only(*)(HTTP) -.TP -.B 100-199,500-599 +.IP 100-199,500-599 specifies two separate 100-byte ranges(*) (HTTP) .RE .IP diff --git a/docs/cmdline-opts/request.d b/docs/cmdline-opts/request.d index 6afd535648..41d81c55af 100644 --- a/docs/cmdline-opts/request.d +++ b/docs/cmdline-opts/request.d @@ -16,8 +16,7 @@ Change the method to use when starting the transfer. curl passes on the verbatim string you give it its the request without any filter or other safe guards. That includes white space and control characters. .RS -.TP 15 -**HTTP** +.IP HTTP Specifies a custom request method to use when communicating with the HTTP server. The specified request method is used instead of the method otherwise used (which defaults to *GET*). Read the HTTP 1.1 specification for details @@ -36,19 +35,15 @@ The method string you set with --request is used for all requests, which if you for example use --location may cause unintended side-effects when curl does not change request method according to the HTTP 30x response codes - and similar. -.TP -**FTP** +.IP FTP Specifies a custom FTP command to use instead of *LIST* when doing file lists with FTP. -.TP -**POP3** +.IP POP3 Specifies a custom POP3 command to use instead of *LIST* or *RETR*. (Added in 7.26.0) -.TP -**IMAP** +.IP IMAP Specifies a custom IMAP command to use instead of *LIST*. (Added in 7.30.0) -.TP -**SMTP** +.IP SMTP Specifies a custom SMTP command to use instead of *HELP* or **VRFY**. (Added in 7.34.0) .RE .IP diff --git a/docs/cmdline-opts/telnet-option.d b/docs/cmdline-opts/telnet-option.d index 651ce4203e..56bf5be636 100644 --- a/docs/cmdline-opts/telnet-option.d +++ b/docs/cmdline-opts/telnet-option.d @@ -13,11 +13,11 @@ Multi: append Pass options to the telnet protocol. Supported options are: .RS -.TP 15 -**TTYPE**= Sets the terminal type. -.TP -**XDISPLOC**= Sets the X display location. -.TP -**NEW_ENV**= Sets an environment variable. +.IP "TTYPE=" +Sets the terminal type. +.IP "XDISPLOC=" +Sets the X display location. +.IP "NEW_ENV=" +Sets an environment variable. .RE .IP diff --git a/docs/cmdline-opts/variable.d b/docs/cmdline-opts/variable.d index d7d773edab..2029601976 100644 --- a/docs/cmdline-opts/variable.d +++ b/docs/cmdline-opts/variable.d @@ -39,17 +39,13 @@ error. Available functions: .RS -.TP 15 -**trim** +.IP trim removes all leading and trailing white space. -.TP -**json** +.IP json outputs the content using JSON string quoting rules. -.TP -**url** +.IP url shows the content URL (percent) encoded. -.TP -**b64** +.IP b64 expands the variable base64 encoded .RE .IP diff --git a/docs/cmdline-opts/write-out.d b/docs/cmdline-opts/write-out.d index e069afcf1e..d21a747dc5 100644 --- a/docs/cmdline-opts/write-out.d +++ b/docs/cmdline-opts/write-out.d @@ -46,31 +46,24 @@ the % cannot be escaped and unintended expansion is possible. The variables available are: .RS -.TP 15 -**certs** +.IP certs Output the certificate chain with details. Supported only by the OpenSSL, GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0) -.TP -**content_type** +.IP content_type The Content-Type of the requested document, if there was any. -.TP -**errormsg** +.IP errormsg The error message. (Added in 7.75.0) -.TP -**exitcode** +.IP exitcode The numerical exit code of the transfer. (Added in 7.75.0) -.TP -**filename_effective** +.IP filename_effective The ultimate filename that curl writes out to. This is only meaningful if curl is told to write to a file with the --remote-name or --output option. It's most useful in combination with the --remote-header-name option. (Added in 7.26.0) -.TP -**ftp_entry_path** +.IP ftp_entry_path The initial path curl ended up in when logging on to the remote FTP server. (Added in 7.15.4) -.TP -**header_json** +.IP header_json A JSON object with all HTTP response headers from the recent transfer. Values are provided as arrays, since in the case of multiple headers there can be multiple values. (Added in 7.83.0) @@ -78,214 +71,156 @@ multiple values. (Added in 7.83.0) The header names provided in lowercase, listed in order of appearance over the wire. Except for duplicated headers. They are grouped on the first occurrence of that header, each value is presented in the JSON array. -.TP -**http_code** +.IP http_code The numerical response code that was found in the last retrieved HTTP(S) or FTP(s) transfer. -.TP -**http_connect** +.IP http_connect The numerical code that was found in the last response (from a proxy) to a curl CONNECT request. (Added in 7.12.4) -.TP -**http_version** +.IP http_version The http version that was effectively used. (Added in 7.50.0) -.TP -**json** +.IP json A JSON object with all available keys. (Added in 7.70.0) -.TP -**local_ip** +.IP local_ip The IP address of the local end of the most recently done connection - can be either IPv4 or IPv6. (Added in 7.29.0) -.TP -**local_port** +.IP local_port The local port number of the most recently done connection. (Added in 7.29.0) -.TP -**method** +.IP method The http method used in the most recent HTTP request. (Added in 7.72.0) -.TP -**num_certs** +.IP num_certs Number of server certificates received in the TLS handshake. Supported only by the OpenSSL, GnuTLS, Schannel and Secure Transport backends. (Added in 7.88.0) -.TP -**num_connects** +.IP num_connects Number of new connects made in the recent transfer. (Added in 7.12.3) -.TP -**num_headers** +.IP num_headers The number of response headers in the most recent request (restarted at each redirect). Note that the status line IS NOT a header. (Added in 7.73.0) -.TP -**num_redirects** +.IP num_redirects Number of redirects that were followed in the request. (Added in 7.12.3) -.TP -**onerror** +.IP onerror The rest of the output is only shown if the transfer returned a non-zero error. (Added in 7.75.0) -.TP -**proxy_ssl_verify_result** +.IP "proxy_ssl_verify_result" The result of the HTTPS proxy's SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.52.0) -.TP -**redirect_url** +.IP redirect_url When an HTTP request was made without --location to follow redirects (or when --max-redirs is met), this variable shows the actual URL a redirect *would* have gone to. (Added in 7.18.2) -.TP -**referer** +.IP referer The Referer: header, if there was any. (Added in 7.76.0) -.TP -**remote_ip** +.IP remote_ip The remote IP address of the most recently done connection - can be either IPv4 or IPv6. (Added in 7.29.0) -.TP -**remote_port** +.IP remote_port The remote port number of the most recently done connection. (Added in 7.29.0) -.TP -**response_code** +.IP response_code The numerical response code that was found in the last transfer (formerly known as "http_code"). (Added in 7.18.2) -.TP -**scheme** +.IP scheme The URL scheme (sometimes called protocol) that was effectively used. (Added in 7.52.0) -.TP -**size_download** +.IP size_download The total amount of bytes that were downloaded. This is the size of the body/data that was transferred, excluding headers. -.TP -**size_header** +.IP size_header The total amount of bytes of the downloaded headers. -.TP -**size_request** +.IP size_request The total amount of bytes that were sent in the HTTP request. -.TP -**size_upload** +.IP size_upload The total amount of bytes that were uploaded. This is the size of the body/data that was transferred, excluding headers. -.TP -**speed_download** +.IP speed_download The average download speed that curl measured for the complete download. Bytes per second. -.TP -**speed_upload** +.IP speed_upload The average upload speed that curl measured for the complete upload. Bytes per second. -.TP -**ssl_verify_result** +.IP ssl_verify_result The result of the SSL peer certificate verification that was requested. 0 means the verification was successful. (Added in 7.19.0) -.TP -**stderr** +.IP stderr From this point on, the --write-out output is written to standard error. (Added in 7.63.0) -.TP -**stdout** +.IP stdout From this point on, the --write-out output is written to standard output. This is the default, but can be used to switch back after switching to stderr. (Added in 7.63.0) -.TP -**time_appconnect** +.IP time_appconnect The time, in seconds, it took from the start until the SSL/SSH/etc connect/handshake to the remote host was completed. (Added in 7.19.0) -.TP -**time_connect** +.IP time_connect The time, in seconds, it took from the start until the TCP connect to the remote host (or proxy) was completed. -.TP -**time_namelookup** +.IP time_namelookup The time, in seconds, it took from the start until the name resolving was completed. -.TP -**time_pretransfer** +.IP time_pretransfer The time, in seconds, it took from the start until the file transfer was just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. -.TP -**time_redirect** +.IP time_redirect The time, in seconds, it took for all redirection steps including name lookup, connect, pretransfer and transfer before the final transaction was started. time_redirect shows the complete execution time for multiple redirections. (Added in 7.12.3) -.TP -**time_starttransfer** +.IP time_starttransfer The time, in seconds, it took from the start until the first byte is received. This includes time_pretransfer and also the time the server needed to calculate the result. -.TP -**time_total** +.IP time_total The total time, in seconds, that the full operation lasted. -.TP -**url** +.IP url The URL that was fetched. (Added in 7.75.0) -.TP -**url.scheme** +.IP url.scheme The scheme part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.user** +.IP url.user The user part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.password** +.IP url.password The password part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.options** +.IP url.options The options part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.host** +.IP url.host The host part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.port** +.IP url.port The port number of the URL that was fetched. If no port number was specified, but the URL scheme is known, that scheme's default port number is shown. (Added in 8.1.0) -.TP -**url.path** +.IP url.path The path part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.query** +.IP url.query The query part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.fragment** +.IP url.fragment The fragment part of the URL that was fetched. (Added in 8.1.0) -.TP -**url.zoneid** +.IP url.zoneid The zone id part of the URL that was fetched. (Added in 8.1.0) -.TP -**urle.scheme** +.IP urle.scheme The scheme part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.user** +.IP urle.user The user part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.password** +.IP urle.password The password part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.options** +.IP urle.options The options part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.host** +.IP urle.host The host part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.port** +.IP urle.port The port number of the effective (last) URL that was fetched. If no port number was specified, but the URL scheme is known, that scheme's default port number is shown. (Added in 8.1.0) -.TP -**urle.path** +.IP urle.path The path part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.query** +.IP urle.query The query part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.fragment** +.IP urle.fragment The fragment part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urle.zoneid** +.IP urle.zoneid The zone id part of the effective (last) URL that was fetched. (Added in 8.1.0) -.TP -**urlnum** +.IP urlnum The URL index number of this transfer, 0-indexed. Unglobbed URLs share the same index number as the origin globbed URL. (Added in 7.75.0) -.TP -**url_effective** +.IP url_effective The URL that was fetched last. This is most meaningful if you have told curl to follow location: headers. .RE