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 --- 84 85All curldown files *must* have all the headers present and at least one 86`See-also:` entry specified. 87 88If the man page is for section 3 (library related). The `Protocol` list must 89contain at least one protocol, which can be `*` if the option is virtually for 90everything. If `*` is used, it must be the only listed protocol. Recognized 91protocols are either URL schemes (in uppercase), `TLS` or `TCP`. 92 93If the `Protocol` list contains `TLS`, then there must also be a `TLS-backend` 94list, specifying `All` or a list of what TLS backends that work with this 95option. The available TLS backends are: 96 97- `BearSSL` 98- `GnuTLS` 99- `mbedTLS` 100- `OpenSSL` (also covers BoringSSL, libressl, quictls, AWS-LC and AmiSSL) 101- `rustls` 102- `Schannel` 103- `Secure Transport` 104- `wolfSSL` 105- `All`: all TLS backends 106 107Following the header in the file, is the manual page using markdown-like 108syntax: 109 110~~~ 111 # NAME 112 a page - this is a page descriving something 113 114 # SYNOPSIS 115 ~~~c 116 #include <curl/curl.h> 117 118 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); 119 ~~~ 120~~~ 121 122Quoted source code should start with `~~~c` and end with `~~~` while regular 123quotes can start with `~~~` or just be indented with 4 spaces. 124 125Headers at top-level `#` get converted to `.SH`. 126 127`nroff2cd` supports the `##` next level header which gets converted to `.IP`. 128 129Write bold words or phrases within `**` like: 130 131 This is a **bold** word. 132 133Write italics like: 134 135 This is *italics*. 136 137Due to how man pages do not support backticks especially formatted, such 138occurrences in the source are instead just using italics in the generated 139output: 140 141 This `word` appears in italics. 142 143When generating the nroff output, the tooling removes superfluous newlines, 144meaning they can be used freely in the source file to make the text more 145readable. 146 147To make sure curldown documents render correctly as markdown, all literal 148occurrences of `<` or `>` need to be escaped by a leading backslash. 149 150## symbols 151 152All mentioned curl symbols that have their own man pages, like 153`curl_easy_perform(3)` are automatically rendered using italics in the output 154without having to enclose it with asterisks. This helps ensuring that they get 155converted to links properly later in the HTML version on the website, as 156converted with `roffit`. This makes the curldown text easier to read even when 157mentioning many curl symbols. 158 159This auto-linking works for patterns matching `(lib|)curl[^ ]*(3)`. 160