mirror of
https://github.com/curl/curl.git
synced 2024-12-09 06:30:06 +08:00
68784d73c3
The file format for each option now features a "Example:" header that can provide one or more examples that get rendered appropriately in the output. All options MUST have at least one example or gen.pl complains at build-time. This fix also does a few other minor format and consistency cleanups. Closes #7654
60 lines
2.0 KiB
Markdown
60 lines
2.0 KiB
Markdown
# curl man page generator
|
|
|
|
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 output
|
|
gets `page-header` prepended and `page-footer` appended. The format is
|
|
described below.
|
|
|
|
## Option files
|
|
|
|
Each command line option is described in a file named `<long name>.d`, where
|
|
option name is written without any prefixing dashes. Like the file name for
|
|
the -v, --verbose option is named `verbose.d`.
|
|
|
|
Each file has a set of meta-data and a body of text.
|
|
|
|
### Meta-data
|
|
|
|
Short: (single letter, without dash)
|
|
Long: (long form name, without dashes)
|
|
Arg: (the argument the option takes)
|
|
Magic: (description of "magic" options)
|
|
Tags: (space separated list)
|
|
Protocols: (space separated list for which protocols this option works)
|
|
Added: (version number in which this was added)
|
|
Mutexed: (space separated list of options this overrides, no dashes)
|
|
Requires: (space separated list of features this requires, no dashes)
|
|
See-also: (space separated list of related options, no dashes)
|
|
Help: (short text for the --help output for this option)
|
|
Example: (example command line, without "curl" and can use `$URL`)
|
|
--- (end of meta-data)
|
|
|
|
### 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
|
|
correct markup that shows both short and long version.
|
|
|
|
Text written within `*asterisks*` will get shown using italics. Text within
|
|
two `**asterisks**` will get shown using bold.
|
|
|
|
## 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
|
|
|
|
`./gen.pl mainpage`
|
|
|
|
This command outputs a single huge nroff file, meant to become `curl.1`. The
|
|
full curl man page.
|
|
|
|
`./gen.pl listhelp`
|
|
|
|
Generates a full `curl --help` output for all known command line options.
|