scdoc.5.scd (4389B)
1 scdoc(5) 2 3 # NAME 4 5 scdoc - document format for writing manual pages 6 7 # SYNTAX 8 9 Input files must use the UTF-8 encoding. 10 11 ## PREAMBLE 12 13 Each scdoc file must begin with the following preamble: 14 15 *name*(_section_) ["left\_footer" ["center\_header"]] 16 17 *name* is the name of the man page you are writing, and _section_ is the section 18 you're writing for (see *man*(1) for information on manual sections). 19 20 _left\_footer_ and _center\_header_ are optional arguments which set the text 21 positioned at those locations in the generated man page, and *must* be 22 surrounded with double quotes. 23 24 ## SECTION HEADERS 25 26 Each section of your man page should begin with something similar to the 27 following: 28 29 # HEADER NAME 30 31 Subsection headers are also understood - use two hashes. Each header must have 32 an empty line on either side. 33 34 ## PARAGRAPHS 35 36 Begin a new paragraph with an empty line. 37 38 ## LINE BREAKS 39 40 Insert a line break by ending a line with \+\+. 41 42 The result looks++ 43 like this. 44 45 ## FORMATTING 46 47 Text can be made *bold* or _underlined_ with asterisks and underscores: \*bold\* 48 or \_underlined\_. Underscores in the_middle_of_words will be disregarded. 49 50 ## INDENTATION 51 52 You may indent lines with tab characters (*\\t*) to indent them by 4 spaces in 53 the output. Indented lines may not contain headers. 54 55 The result looks something like this. 56 57 You may use multiple lines and most _formatting_. 58 59 Deindent to return to normal, or indent again to increase your indentation 60 depth. 61 62 ## LISTS 63 64 You may start bulleted lists with dashes (-), like so: 65 66 ``` 67 - Item 1 68 - Item 2 69 - Subitem 1 70 - Subitem 2 71 - Item 3 72 ``` 73 74 The result looks like this: 75 76 - Item 1 77 - Item 2 78 - Subitem 1 79 - Subitem 2 80 - Item 3 81 82 You may also extend long entries onto another line by giving it the same indent 83 level, plus two spaces. They will be rendered as a single list entry. 84 85 ``` 86 - Item 1 is pretty long so let's 87 break it up onto two lines 88 - Item 2 is shorter 89 - But its children can go on 90 for a while 91 ``` 92 93 - Item 1 is pretty long so let's 94 break it up onto two lines 95 - Item 2 is shorter 96 - But its children can go on 97 for a while 98 99 ## NUMBERED LISTS 100 101 Numbered lists are similar to normal lists, but begin with periods (.) instead 102 of dashes (-), like so: 103 104 ``` 105 . Item 1 106 . Item 2 107 . Item 3, 108 with multiple lines 109 ``` 110 111 . Item 1 112 . Item 2 113 . Item 3, 114 with multiple lines 115 116 ## TABLES 117 118 To begin a table, add an empty line followed by any number of rows. 119 120 Each line of a table should start with | or : to start a new row or column 121 respectively (or space to continue the previous cell on multiple lines), 122 followed by [ or - or ] to align the contents to the left, center, or right, 123 followed by a space and the contents of that cell. You may use a space instead 124 of an alignment specifier to inherit the alignment of the same column in the 125 previous row. 126 127 The first character of the first row is not limited to | and has special 128 meaning. [ will produce a table with borders around each cell. | will produce a 129 table with no borders. ] will produce a table with one border around the whole 130 table. 131 132 To conclude your table, add an empty line after the last row. 133 134 ``` 135 [[ *Foo* 136 :- _Bar_ 137 :- 138 | *Row 1* 139 : Hello 140 :] world! 141 | *Row 2* 142 : こんにちは 143 : 世界 144 ! 145 ``` 146 147 [[ *Foo* 148 :- _Bar_ 149 :- 150 | *Row 1* 151 : Hello 152 :] world! 153 | *Row 2* 154 : こんにちは 155 : 世界 156 ! 157 158 ## LITERAL TEXT 159 160 You may turn off scdoc formatting and output literal text with escape codes and 161 literal blocks. Inserting a \\ into your source will cause the subsequent symbol 162 to be treated as a literal and copied directly to the output. You may also make 163 blocks of literal syntax like so: 164 165 ``` 166 \``` 167 _This formatting_ will *not* be interpreted by scdoc. 168 \``` 169 ``` 170 171 These blocks will be indented one level. Note that literal text is shown 172 literally in the man viewer - that is, it's not a means for inserting your own 173 roff macros into the output. Note that \\ is still interpreted within literal 174 blocks, which for example can be useful to output \``` inside of a literal 175 block. 176 177 ## COMMENTS 178 179 Lines beginning with ; and a space are ignored. 180 181 ``` 182 ; This is a comment 183 ``` 184 185 # CONVENTIONS 186 187 By convention, all scdoc documents should be hard wrapped at 80 columns. 188 189 # SEE ALSO 190 191 *scdoc*(1) 192 193 # AUTHORS 194 195 Maintained by Drew DeVault <sir@cmpwn.com>. Up-to-date sources can be found at 196 https://git.sr.ht/~sircmpwn/scdoc and bugs/patches can be submitted by email to 197 ~sircmpwn/public-inbox@lists.sr.ht.