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