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