xref: /curl/docs/CURLDOWN.md (revision 5a488251) 
1<!--
2Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3
4SPDX-License-Identifier: curl
5-->
6
7# curldown
8
9A markdown-like syntax for libcurl man pages.
10
11## Purpose
12
13A text format for writing libcurl documentation in the shape of man pages.
14
15Make it easier for users to contribute and write documentation. A format that
16is easier on the eye in its source format.
17
18Make it harder to do syntactical mistakes.
19
20Use a format that allows creating man pages that end up looking exactly like
21the man pages did when we wrote them in nroff format.
22
23Take advantage of the fact that people these days are accustomed to markdown
24by using a markdown-like syntax.
25
26This allows us to fix issues in the nroff format easier since now we generate
27them. For example: escaping minus to prevent them from being turned into
28Unicode by man.
29
30Generate nroff output that looks (next to) *identical* to the previous files,
31so that the look, existing test cases, HTML conversions, existing
32infrastructure etc remain mostly intact.
33
34Contains meta-data in a structured way to allow better output (for example the
35see also information) and general awareness of what the file is about.
36
37## File extension
38
39Since curldown looks similar to markdown, we use `.md` extensions on the
40files.
41
42## Conversion
43
44Convert **from curldown to nroff** with `cd2nroff`. Generates nroff man pages.
45
46Convert **from nroff to curldown** with `nroff2cd`. This is only meant to be
47used for the initial conversion to curldown and should ideally never be needed
48again.
49
50Convert, check or clean up an existing curldown to nicer, better, cleaner
51curldown with **cd2cd**.
52
53Mass-convert all curldown files to nroff in specified directories with
54`cdall`:
55
56    cdall [dir1] [dir2] [dir3] ..
57
58## Known issues
59
60The `cd2nroff` tool does not yet handle *italics* or **bold** where the start
61and the end markers are used on separate lines.
62
63The `nroff2cd` tool generates code style quotes for all `.fi` sections since
64the nroff format does not carry a distinction.
65
66# Format
67
68Each curldown starts with a header with meta-data:
69
70    ---
71    c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
72    SPDX-License-Identifier: curl
73    Title: CURLOPT_AWS_SIGV4
74    Section: 3
75    Source: libcurl
76    Protocol:
77      - HTTP
78    See-also:
79      - CURLOPT_HEADEROPT (3)
80      - CURLOPT_HTTPAUTH (3)
81    TLS-backend:
82      - [name]
83    Added-in: [version or "n/a"]
84    ---
85
86All curldown files *must* have all the headers present and at least one
87`See-also:` entry specified.
88
89If the man page is for section 3 (library related). The `Protocol` list must
90contain at least one protocol, which can be `*` if the option is virtually for
91everything. If `*` is used, it must be the only listed protocol. Recognized
92protocols are either URL schemes (in uppercase), `TLS` or `TCP`.
93
94If the `Protocol` list contains `TLS`, then there must also be a `TLS-backend`
95list, specifying `All` or a list of what TLS backends that work with this
96option. The available TLS backends are:
97
98- `BearSSL`
99- `GnuTLS`
100- `mbedTLS`
101- `OpenSSL` (also covers BoringSSL, LibreSSL, quictls, AWS-LC and AmiSSL)
102- `rustls`
103- `Schannel`
104- `Secure Transport`
105- `wolfSSL`
106- `All`: all TLS backends
107
108Following the header in the file, is the manual page using markdown-like
109syntax:
110
111~~~
112    # NAME
113    a page - this is a page descriving something
114
115    # SYNOPSIS
116    ~~~c
117    #include <curl/curl.h>
118
119    CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param);
120    ~~~
121~~~
122
123Quoted source code should start with `~~~c` and end with `~~~` while regular
124quotes can start with `~~~` or just be indented with 4 spaces.
125
126Headers at top-level `#` get converted to `.SH`.
127
128`nroff2cd` supports the `##` next level header which gets converted to `.IP`.
129
130Write bold words or phrases within `**` like:
131
132    This is a **bold** word.
133
134Write italics like:
135
136    This is *italics*.
137
138Due to how man pages do not support backticks especially formatted, such
139occurrences in the source are instead just using italics in the generated
140output:
141
142    This `word` appears in italics.
143
144When generating the nroff output, the tooling removes superfluous newlines,
145meaning they can be used freely in the source file to make the text more
146readable.
147
148To make sure curldown documents render correctly as markdown, all literal
149occurrences of `<` or `>` need to be escaped by a leading backslash.
150
151## Generating contents
152
153`# %PROTOCOLS%` - inserts a **PROTOCOLS** section based on the metadata
154provided in the header.
155
156`# %AVAILABILITY%` - inserts an **AVAILABILITY** section based on the metadata
157provided in the header.
158
159## Symbols
160
161All mentioned curl symbols that have their own man pages, like
162`curl_easy_perform(3)` are automatically rendered using italics in the output
163without having to enclose it with asterisks. This helps ensuring that they get
164converted to links properly later in the HTML version on the website, as
165converted with `roffit`. This makes the curldown text easier to read even when
166mentioning many curl symbols.
167
168This auto-linking works for patterns matching `(lib|)curl[^ ]*(3)`.
169