summaryrefslogtreecommitdiff
path: root/docs/cmdline-opts/MANPAGE.md
blob: b903bc25e09da55936bb947c02e9187b06b7387e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
# 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)
    --- (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.