167 lines
5.8 KiB
Markdown
Vendored
167 lines
5.8 KiB
Markdown
Vendored
<!--
|
|
Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
|
|
SPDX-License-Identifier: curl
|
|
-->
|
|
|
|
# curl man page generator
|
|
|
|
`managen` is the curl man page generator. It generates a single nroff man page
|
|
output from the set of sources files in this directory.
|
|
|
|
The `mainpage.idx` file lists all files that are rendered in that order to
|
|
produce the output. The special `%options` keyword inserts all command line
|
|
options documented.
|
|
|
|
The `%options` documentation is created with one source file for each
|
|
supported command line option.
|
|
|
|
The documentation file format is described below. It is meant to look similar
|
|
to markdown which is why it uses `.md` file extensions.
|
|
|
|
## 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 filename for the
|
|
`-v, --verbose` option is named `verbose.d`.
|
|
|
|
Each file has a set of meta-data in the top of the file, followed by a body of
|
|
text.
|
|
|
|
The documentation files that do not document options have no meta-data part.
|
|
|
|
A line that starts with `<!--` is a comment. It should also end with `-->`.
|
|
|
|
### Meta-data
|
|
|
|
--- (start of meta-data)
|
|
Added: (version number in which this was added)
|
|
Arg: (the argument the option takes)
|
|
c: (copyright line)
|
|
Example:
|
|
- (an example command line, without "curl" and can use `$URL`)
|
|
- (another example)
|
|
Experimental: yes (if so)
|
|
Help: (short text for the --help output for this option)
|
|
Long: (long form name, without dashes)
|
|
Magic: (description of "magic" options)
|
|
Multi: single/append/boolean/mutex/custom/per-URL (if used more than once)
|
|
Mutexed: (space separated list of options this overrides, no dashes)
|
|
Protocols: (space separated list for which protocols this option works)
|
|
Requires: (space separated list of features this requires, no dashes)
|
|
Scope: global (if the option is global)
|
|
See-also:
|
|
- (a related option, no dashes)
|
|
- (another related option, no dashes)
|
|
Short: (single letter, without dash)
|
|
SPDX-License-Identifier: curl
|
|
Tags: (space separated list)
|
|
--- (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 replaces such option with the
|
|
correct markup that shows both short and long version.
|
|
|
|
Text written within `*asterisks*` is shown using italics. Text within two
|
|
`**asterisks**` is shown using bold.
|
|
|
|
Text that is prefixed with a space is treated like an "example" and gets
|
|
output in monospace.
|
|
|
|
Within the body, describe a list of items like this:
|
|
|
|
## item 1
|
|
description
|
|
|
|
## item 2
|
|
second description
|
|
|
|
The list is automatically terminated at end of file, or you can do it
|
|
explicitly with an empty "header":
|
|
|
|
##
|
|
|
|
Angle brackets (`<>`) need to be escaped when used in text like `\<` and
|
|
`\>`. This, to ensure that the text renders nicely as markdown.
|
|
|
|
### Headers
|
|
|
|
The `#` header can be used by non-option files and it produces a
|
|
`.SH` output.
|
|
|
|
If the `#` header is used for a command line option file, that header is
|
|
ignored in the generated output. It can still serve a purpose in the
|
|
source file as it helps the user identify what option the file is for.
|
|
|
|
### Variables
|
|
|
|
There are three different "variables" that can be used when creating the
|
|
output. They need to be written within backticks in the source file (to escape
|
|
getting spellchecked by CI jobs): `%DATE`, `%VERSION` and `%GLOBALS`.
|
|
|
|
During rendering, the generator expands them as follows:
|
|
|
|
- `%VERSION` -- replaced with the curl version string read from
|
|
`include/curl/curlver.h` (e.g. `8.12.0`). Can be overridden by setting
|
|
the `CURL_MAKETGZ_VERSION` environment variable.
|
|
- `%DATE` -- replaced with the current date in `YYYY-MM-DD` format, or
|
|
the date derived from `SOURCE_DATE_EPOCH` if that environment variable
|
|
is set (for reproducible builds).
|
|
- `%GLOBALS` -- replaced with a comma-separated list of all command line
|
|
options that have `Scope: global` in their meta-data.
|
|
|
|
## Generate
|
|
|
|
`managen mainpage [list of markdown option file names]`
|
|
|
|
This command outputs a single huge nroff file, meant to become `curl.1`. The
|
|
full curl man page.
|
|
|
|
`managen ascii [list of markdown option file names]`
|
|
|
|
This command outputs a single text file, meant to become `curl.txt`. The full
|
|
curl man page in text format, used to build `tool_hugehelp.c`.
|
|
|
|
`managen listhelp`
|
|
|
|
Generates a full `curl --help` output for all known command line options.
|
|
|
|
## Generating the man page
|
|
|
|
The `curl.1` man page is generated from the source files in this directory
|
|
using the `managen` Perl script located in `scripts/managen`. The build
|
|
system runs this automatically, but it can also be invoked manually.
|
|
|
|
### Prerequisites
|
|
|
|
The generator requires Perl. The version string is read from
|
|
`include/curl/curlver.h` (or from the `CURL_MAKETGZ_VERSION` environment
|
|
variable if set). The date defaults to the current date unless
|
|
`SOURCE_DATE_EPOCH` is set.
|
|
|
|
### Manual invocation
|
|
|
|
From the `docs/cmdline-opts` directory, run:
|
|
|
|
cd docs/cmdline-opts
|
|
perl ../../scripts/managen -I ../../include mainpage ./*.md > curl.1
|
|
|
|
This produces the complete `curl.1` nroff man page. To produce a plain-text
|
|
version instead, replace `mainpage` with `ascii`:
|
|
|
|
perl ../../scripts/managen -I ../../include ascii ./*.md > curl.txt
|
|
|
|
The `-d` flag specifies the directory containing `mainpage.idx` and the
|
|
`.md` option files. The `-I` flag specifies the include directory root
|
|
used to locate `curl/curlver.h` for the version string.
|
|
|
|
### How it works
|
|
|
|
The generator reads `mainpage.idx`, which lists the documentation source
|
|
files in their intended order. Each line names one `.md` file to render.
|
|
When the generator encounters the `%options` keyword in `mainpage.idx`,
|
|
it inserts the documentation for every command line option (one `.md` file
|
|
per option), sorted alphabetically by long option name.
|