Artifactspublic-v0

curl

master
ply4 git calls62 ms289 KiB3 cachedprotocol v2
166 lines5.8 KiBRaw

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 filenames]

This command outputs a single huge nroff file, meant to become curl.1. The full curl man page.

managen ascii [list of markdown option filenames]

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.

1<!--
2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
4 SPDX-License-Identifier: curl
5-->
7# curl man page generator
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.
12The `mainpage.idx` file lists all files that are rendered in that order to
13produce the output. The special `%options` keyword inserts all command line
14options documented.
16The `%options` documentation is created with one source file for each
17supported command line option.
19The documentation file format is described below. It is meant to look similar
20to markdown which is why it uses `.md` file extensions.
22## Option files
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`.
28Each file has a set of meta-data in the top of the file, followed by a body of
29text.
31The documentation files that do not document options have no meta-data part.
33A line that starts with `<!--` is a comment. It should also end with `-->`.
35### Meta-data
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/per-URL (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)
61### Body
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.
67Text written within `*asterisks*` is shown using italics. Text within two
68`**asterisks**` is shown using bold.
70Text that is prefixed with a space is treated like an "example" and gets
71output in monospace.
73Within the body, describe a list of items like this:
75 ## item 1
76 description
78 ## item 2
79 second description
81The list is automatically terminated at end of file, or you can do it
82explicitly with an empty "header":
84 ##
86Angle brackets (`<>`) need to be escaped when used in text like `\<` and
87`\>`. This, to ensure that the text renders nicely as markdown.
89### Headers
91The `#` header can be used by non-option files and it produces a
92`.SH` output.
94If the `#` header is used for a command line option file, that header is
95ignored 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.
98### Variables
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`.
104During rendering, the generator expands them as follows:
106- `%VERSION` -- replaced with the curl version string read from
107 `include/curl/curlver.h` (e.g. `8.12.0`). Can be overridden by setting
108 the `CURL_MAKETGZ_VERSION` environment variable.
109- `%DATE` -- replaced with the current date in `YYYY-MM-DD` format, or
110 the date derived from `SOURCE_DATE_EPOCH` if that environment variable
111 is set (for reproducible builds).
112- `%GLOBALS` -- replaced with a comma-separated list of all command line
113 options that have `Scope: global` in their meta-data.
115## Generate
117`managen mainpage [list of markdown option filenames]`
119This command outputs a single huge nroff file, meant to become `curl.1`. The
120full curl man page.
122`managen ascii [list of markdown option filenames]`
124This command outputs a single text file, meant to become `curl.txt`. The full
125curl man page in text format, used to build `tool_hugehelp.c`.
127`managen listhelp`
129Generates a full `curl --help` output for all known command line options.
131## Generating the man page
133The `curl.1` man page is generated from the source files in this directory
134using the `managen` Perl script located in `scripts/managen`. The build
135system runs this automatically, but it can also be invoked manually.
137### Prerequisites
139The generator requires Perl. The version string is read from
140`include/curl/curlver.h` (or from the `CURL_MAKETGZ_VERSION` environment
141variable if set). The date defaults to the current date unless
142`SOURCE_DATE_EPOCH` is set.
144### Manual invocation
146From the `docs/cmdline-opts` directory, run:
148 cd docs/cmdline-opts
149 perl ../../scripts/managen -I ../../include mainpage ./*.md > curl.1
151This produces the complete `curl.1` nroff man page. To produce a plain-text
152version instead, replace `mainpage` with `ascii`:
154 perl ../../scripts/managen -I ../../include ascii ./*.md > curl.txt
156The `-d` flag specifies the directory containing `mainpage.idx` and the
157`.md` option files. The `-I` flag specifies the include directory root
158used to locate `curl/curlver.h` for the version string.
160### How it works
162The generator reads `mainpage.idx`, which lists the documentation source
163files in their intended order. Each line names one `.md` file to render.
164When the generator encounters the `%options` keyword in `mainpage.idx`,
165it inserts the documentation for every command line option (one `.md` file
166per option), sorted alphabetically by long option name.
Diagnostics4 git calls · 62 ms
CallStatusSizeTime062 ms
discover200152 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.5 KiB · hit57 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=57
git.response.bytes=2572
git.response.cache=HIT
git.response.duration_ms=57
git.fetch.wants=972fc9a51bb230a0d5fcad3364e5e9be277d9e6c
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2572
git.pkt.payload.max=2551
git.sideband.band1.bytes=2550
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e347b1ece64652
Request
963385b4…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format