1# curldown 2 3A markdown-like syntax for libcurl man pages. 4 5## Purpose 6 7A text format for writing libcurl documentation in the shape of man pages. 8 9Make it easier for users to contribute and write documentation. A format that 10is easier on the eye in its source format. 11 12Make it harder to do syntactical mistakes. 13 14Use a format that allows creating man pages that end up looking exactly like 15the man pages did when we wrote them in nroff format. 16 17Take advantage of the fact that people these days are accustomed to markdown 18by using a markdown-like syntax. 19 20This allows us to fix issues in the nroff format easier since now we generate 21them. For example: escaping minus to prevent them from being turned into 22Unicode by man. 23 24Generate nroff output that looks (next to) *identical* to the previous files, 25so that the look, existing test cases, HTML conversions, existing 26infrastructure etc remain mostly intact. 27 28Contains meta-data in a structured way to allow better output (for example the 29see also information) and general awareness of what the file is about. 30 31## File extension 32 33Since curldown looks similar to markdown, we use `.md` extensions on the 34files. 35 36## Conversion 37 38Convert **from curldown to nroff** with `cd2nroff`. Generates nroff man pages. 39 40Convert **from nroff to curldown** with `nroff2cd`. This is only meant to be 41used for the initial conversion to curldown and should ideally never be needed 42again. 43 44Convert, check or clean up an existing curldown to nicer, better, cleaner 45curldown with **cd2cd**. 46 47Mass-convert all curldown files to nroff in specified directories with 48`cdall`: 49 50 cdall [dir1] [dir2] [dir3] .. 51 52## Known issues 53 54The `cd2nroff` tool does not yet handle *italics* or **bold** where the start 55and the end markers are used on separate lines. 56 57The `nroff2cd` tool generates code style quotes for all `.fi` sections since 58the nroff format does not carry a distinction. 59 60# Format 61 62Each curldown starts with a header with meta-data: 63 64 --- 65 c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 66 SPDX-License-Identifier: curl 67 Title: CURLOPT_AWS_SIGV4 68 Section: 3 69 Source: libcurl 70 See-also: 71 - CURLOPT_HEADEROPT (3) 72 - CURLOPT_HTTPAUTH (3) 73 --- 74 75All curldown files *must* have all the headers present and at least one 76`See-also:` entry specified. 77 78Following the header in the file, is the manual page using markdown-like 79syntax: 80 81~~~ 82 # NAME 83 a page - this is a page descriving something 84 85 # SYNOPSIS 86 ~~~c 87 #include <curl/curl.h> 88 89 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); 90 ~~~ 91~~~ 92 93Quoted source code should start with `~~~c` and end with `~~~` while regular 94quotes can start with `~~~` or just be indented with 4 spaces. 95 96Headers at top-level `#` get converted to `.SH`. 97 98`nroff2cd` supports the `##` next level header which gets converted to `.IP`. 99 100Write bold words or phrases within `**` like: 101 102 This is a **bold** word. 103 104Write italics like: 105 106 This is *italics*. 107 108Due to how man pages do not support backticks especially formatted, such 109occurrences in the source will instead just use italics in the generated 110output: 111 112 This `word` appears in italics. 113 114When generating the nroff output, the tooling will remove superfluous newlines, 115meaning they can be used freely in the source file to make the text more 116readable. 117 118All mentioned curl symbols that have their own man pages, like 119`curl_easy_perform(3)` will automatically be rendered using italics in the 120output without having to enclose it with asterisks. This helps ensuring that 121they get converted to links properly later in the HTML version on the website, 122as converted with `roffit`. This makes the curldown text easier to read even 123when mentioning many curl symbols. 124 125This auto-linking works for patterns matching `(lib|)curl[^ ]*(3)`. 126