xref: /aosp_15_r20/external/curl/docs/cmdline-opts/MANPAGE.md (revision 6236dae45794135f37c4eb022389c904c8b0090d)
1*6236dae4SAndroid Build Coastguard Worker<!--
2*6236dae4SAndroid Build Coastguard Worker  Copyright (C) Daniel Stenberg, <[email protected]>, et al.
3*6236dae4SAndroid Build Coastguard Worker
4*6236dae4SAndroid Build Coastguard Worker  SPDX-License-Identifier: curl
5*6236dae4SAndroid Build Coastguard Worker-->
6*6236dae4SAndroid Build Coastguard Worker
7*6236dae4SAndroid Build Coastguard Worker# curl man page generator
8*6236dae4SAndroid Build Coastguard Worker
9*6236dae4SAndroid Build Coastguard Worker`managen` is the curl man page generator. It generates a single nroff man page
10*6236dae4SAndroid Build Coastguard Workeroutput from the set of sources files in this directory.
11*6236dae4SAndroid Build Coastguard Worker
12*6236dae4SAndroid Build Coastguard WorkerThe `mainpage.idx` file lists all files that are rendered in that order to
13*6236dae4SAndroid Build Coastguard Workerproduce the output. The magic `%options` keyword inserts all command line
14*6236dae4SAndroid Build Coastguard Workeroptions documented.
15*6236dae4SAndroid Build Coastguard Worker
16*6236dae4SAndroid Build Coastguard WorkerThe `%options` documentation is created with one source file for each
17*6236dae4SAndroid Build Coastguard Workersupported command line option.
18*6236dae4SAndroid Build Coastguard Worker
19*6236dae4SAndroid Build Coastguard WorkerThe documentation file format is described below. It is meant to look similar
20*6236dae4SAndroid Build Coastguard Workerto markdown which is why it uses `.md` file extensions.
21*6236dae4SAndroid Build Coastguard Worker
22*6236dae4SAndroid Build Coastguard Worker## Option files
23*6236dae4SAndroid Build Coastguard Worker
24*6236dae4SAndroid Build Coastguard WorkerEach command line option is described in a file named `<long name>.d`, where
25*6236dae4SAndroid Build Coastguard Workeroption name is written without any prefixing dashes. Like the filename for the
26*6236dae4SAndroid Build Coastguard Worker`-v, --verbose` option is named `verbose.d`.
27*6236dae4SAndroid Build Coastguard Worker
28*6236dae4SAndroid Build Coastguard WorkerEach file has a set of meta-data in the top of the file, followed by a body of
29*6236dae4SAndroid Build Coastguard Workertext.
30*6236dae4SAndroid Build Coastguard Worker
31*6236dae4SAndroid Build Coastguard WorkerThe documentation files that do not document options have no meta-data part.
32*6236dae4SAndroid Build Coastguard Worker
33*6236dae4SAndroid Build Coastguard WorkerA line that starts with `<!--` is a comment. It should also end with `-->`.
34*6236dae4SAndroid Build Coastguard Worker
35*6236dae4SAndroid Build Coastguard Worker### Meta-data
36*6236dae4SAndroid Build Coastguard Worker
37*6236dae4SAndroid Build Coastguard Worker    --- (start of meta-data)
38*6236dae4SAndroid Build Coastguard Worker    Added: (version number in which this was added)
39*6236dae4SAndroid Build Coastguard Worker    Arg: (the argument the option takes)
40*6236dae4SAndroid Build Coastguard Worker    c: (copyright line)
41*6236dae4SAndroid Build Coastguard Worker    Example:
42*6236dae4SAndroid Build Coastguard Worker      - (an example command line, without "curl" and can use `$URL`)
43*6236dae4SAndroid Build Coastguard Worker      - (another example)
44*6236dae4SAndroid Build Coastguard Worker    Experimental: yes (if so)
45*6236dae4SAndroid Build Coastguard Worker    Help: (short text for the --help output for this option)
46*6236dae4SAndroid Build Coastguard Worker    Long: (long form name, without dashes)
47*6236dae4SAndroid Build Coastguard Worker    Magic: (description of "magic" options)
48*6236dae4SAndroid Build Coastguard Worker    Multi: single/append/boolean/mutex/custom/per-URL (if used more than once)
49*6236dae4SAndroid Build Coastguard Worker    Mutexed: (space separated list of options this overrides, no dashes)
50*6236dae4SAndroid Build Coastguard Worker    Protocols: (space separated list for which protocols this option works)
51*6236dae4SAndroid Build Coastguard Worker    Requires: (space separated list of features this requires, no dashes)
52*6236dae4SAndroid Build Coastguard Worker    Scope: global (if the option is global)
53*6236dae4SAndroid Build Coastguard Worker    See-also:
54*6236dae4SAndroid Build Coastguard Worker      - (a related option, no dashes)
55*6236dae4SAndroid Build Coastguard Worker      - (another related option, no dashes)
56*6236dae4SAndroid Build Coastguard Worker    Short: (single letter, without dash)
57*6236dae4SAndroid Build Coastguard Worker    SPDX-License-Identifier: curl
58*6236dae4SAndroid Build Coastguard Worker    Tags: (space separated list)
59*6236dae4SAndroid Build Coastguard Worker    --- (end of meta-data)
60*6236dae4SAndroid Build Coastguard Worker
61*6236dae4SAndroid Build Coastguard Worker### Body
62*6236dae4SAndroid Build Coastguard Worker
63*6236dae4SAndroid Build Coastguard WorkerThe body of the description. Only refer to options with their long form option
64*6236dae4SAndroid Build Coastguard Workerversion, like `--verbose`. The output generator replaces such option with the
65*6236dae4SAndroid Build Coastguard Workercorrect markup that shows both short and long version.
66*6236dae4SAndroid Build Coastguard Worker
67*6236dae4SAndroid Build Coastguard WorkerText written within `*asterisks*` is shown using italics. Text within two
68*6236dae4SAndroid Build Coastguard Worker`**asterisks**` is shown using bold.
69*6236dae4SAndroid Build Coastguard Worker
70*6236dae4SAndroid Build Coastguard WorkerText that is prefixed with a space is treated like an "example" and gets
71*6236dae4SAndroid Build Coastguard Workeroutput in monospace.
72*6236dae4SAndroid Build Coastguard Worker
73*6236dae4SAndroid Build Coastguard WorkerWithin the body, describe a list of items like this:
74*6236dae4SAndroid Build Coastguard Worker
75*6236dae4SAndroid Build Coastguard Worker    ## item 1
76*6236dae4SAndroid Build Coastguard Worker    description
77*6236dae4SAndroid Build Coastguard Worker
78*6236dae4SAndroid Build Coastguard Worker    ## item 2
79*6236dae4SAndroid Build Coastguard Worker    second description
80*6236dae4SAndroid Build Coastguard Worker
81*6236dae4SAndroid Build Coastguard WorkerThe list is automatically terminated at end of file, or you can do it
82*6236dae4SAndroid Build Coastguard Workerexplicitly with an empty "header":
83*6236dae4SAndroid Build Coastguard Worker
84*6236dae4SAndroid Build Coastguard Worker    ##
85*6236dae4SAndroid Build Coastguard Worker
86*6236dae4SAndroid Build Coastguard WorkerAngle brackets (`<>`) need to be escaped when used in text like `\<` and
87*6236dae4SAndroid Build Coastguard Worker`\>`. This, to ensure that the text renders nicely as markdown.
88*6236dae4SAndroid Build Coastguard Worker
89*6236dae4SAndroid Build Coastguard Worker### Headers
90*6236dae4SAndroid Build Coastguard Worker
91*6236dae4SAndroid Build Coastguard WorkerThe `#` header can be used by non-option files and it produces a
92*6236dae4SAndroid Build Coastguard Worker`.SH` output.
93*6236dae4SAndroid Build Coastguard Worker
94*6236dae4SAndroid Build Coastguard WorkerIf the `#` header is used for a command line option file, that header is
95*6236dae4SAndroid Build Coastguard Workersimply ignored in the generated output. It can still serve a purpose in the
96*6236dae4SAndroid Build Coastguard Workersource file as it helps the user identify what option the file is for.
97*6236dae4SAndroid Build Coastguard Worker
98*6236dae4SAndroid Build Coastguard Worker### Variables
99*6236dae4SAndroid Build Coastguard Worker
100*6236dae4SAndroid Build Coastguard WorkerThere are three different "variables" that can be used when creating the
101*6236dae4SAndroid Build Coastguard Workeroutput. They need to be written within backticks in the source file (to escape
102*6236dae4SAndroid Build Coastguard Workergetting spellchecked by CI jobs): `%DATE`, `%VERSION` and `%GLOBALS`.
103*6236dae4SAndroid Build Coastguard Worker
104*6236dae4SAndroid Build Coastguard Worker## Generate
105*6236dae4SAndroid Build Coastguard Worker
106*6236dae4SAndroid Build Coastguard Worker`managen mainpage [list of markdown option file names]`
107*6236dae4SAndroid Build Coastguard Worker
108*6236dae4SAndroid Build Coastguard WorkerThis command outputs a single huge nroff file, meant to become `curl.1`. The
109*6236dae4SAndroid Build Coastguard Workerfull curl man page.
110*6236dae4SAndroid Build Coastguard Worker
111*6236dae4SAndroid Build Coastguard Worker`managen ascii [list of markdown option file names]`
112*6236dae4SAndroid Build Coastguard Worker
113*6236dae4SAndroid Build Coastguard WorkerThis command outputs a single text file, meant to become `curl.txt`. The full
114*6236dae4SAndroid Build Coastguard Workercurl man page in text format, used to build `tool_hugehelp.c`.
115*6236dae4SAndroid Build Coastguard Worker
116*6236dae4SAndroid Build Coastguard Worker`managen listhelp`
117*6236dae4SAndroid Build Coastguard Worker
118*6236dae4SAndroid Build Coastguard WorkerGenerates a full `curl --help` output for all known command line options.
119