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