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 9`managen` 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 filename for the 26`-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 86Angle brackets (`<>`) need to be escaped when used in text like `\<` and 87`\>`. This, to ensure that the text renders nicely as markdown. 88 89### Headers 90 91The `#` header can be used by non-option files and it produces a 92`.SH` output. 93 94If the `#` header is used for a command line option file, that header is 95simply ignored in the generated output. It can still serve a purpose in the 96source file as it helps the user identify what option the file is for. 97 98### Variables 99 100There are three different "variables" that can be used when creating the 101output. They need to be written within backticks in the source file (to escape 102getting spellchecked by CI jobs): `%DATE`, `%VERSION` and `%GLOBALS`. 103 104## Generate 105 106`managen mainpage [list of markdown option file names]` 107 108This command outputs a single huge nroff file, meant to become `curl.1`. The 109full curl man page. 110 111`managen ascii [list of markdown option file names]` 112 113This command outputs a single text file, meant to become `curl.txt`. The full 114curl man page in text format, used to build `tool_hugehelp.c`. 115 116`managen listhelp` 117 118Generates a full `curl --help` output for all known command line options. 119
