1scdoc(5) 2 3# NAME 4 5scdoc - document format for writing manual pages 6 7# SYNTAX 8 9Input files must use the UTF-8 encoding. 10 11## PREAMBLE 12 13Each 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 18you'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 21positioned at those locations in the generated man page, and *must* be 22surrounded with double quotes. 23 24## SECTION HEADERS 25 26Each section of your man page should begin with something similar to the 27following: 28 29 # HEADER NAME 30 31Subsection headers are also understood - use two hashes. Each header must have 32an empty line on either side. 33 34## PARAGRAPHS 35 36Begin a new paragraph with an empty line. 37 38## LINE BREAKS 39 40Insert a line break by ending a line with \+\+. 41 42The result looks++ 43like this. 44 45## FORMATTING 46 47Text can be made *bold* or _underlined_ with asterisks and underscores: \*bold\* 48or \_underlined\_. Underscores in the_middle_of_words will be disregarded. 49 50## INDENTATION 51 52You may indent lines with tab characters (*\\t*) to indent them by 4 spaces in 53the 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 59Deindent to return to normal, or indent again to increase your indentation 60depth. 61 62## LISTS 63 64You 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 74The result looks like this: 75 76- Item 1 77- Item 2 78 - Subitem 1 79 - Subitem 2 80- Item 3 81 82You may also extend long entries onto another line by giving it the same indent 83level, 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 101Numbered lists are similar to normal lists, but begin with periods (.) instead 102of 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 118To begin a table, add an empty line followed by any number of rows. 119 120Each line of a table should start with | or : to start a new row or column 121respectively (or space to continue the previous cell on multiple lines), 122followed by [ or - or ] to align the contents to the left, center, or right, 123followed by a space and the contents of that cell. You may use a space instead 124of an alignment specifier to inherit the alignment of the same column in the 125previous row. 126 127The first character of the first row is not limited to | and has special 128meaning. [ will produce a table with borders around each cell. | will produce a 129table with no borders. ] will produce a table with one border around the whole 130table. 131 132To 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 160You may turn off scdoc formatting and output literal text with escape codes and 161literal blocks. Inserting a \\ into your source will cause the subsequent symbol 162to be treated as a literal and copied directly to the output. You may also make 163blocks of literal syntax like so: 164 165``` 166\``` 167_This formatting_ will *not* be interpreted by scdoc. 168\``` 169``` 170 171These blocks will be indented one level. Note that literal text is shown 172literally in the man viewer - that is, it's not a means for inserting your own 173roff macros into the output. Note that \\ is still interpreted within literal 174blocks, which for example can be useful to output \``` inside of a literal 175block. 176 177## COMMENTS 178 179Lines beginning with ; and a space are ignored. 180 181``` 182; This is a comment 183``` 184 185# CONVENTIONS 186 187By convention, all scdoc documents should be hard wrapped at 80 columns. 188 189# SEE ALSO 190 191*scdoc*(1) 192 193# AUTHORS 194 195Maintained by Drew DeVault <sir@cmpwn.com>. Up-to-date sources can be found at 196https://git.sr.ht/~sircmpwn/scdoc and bugs/patches can be submitted by email to 197~sircmpwn/public-inbox@lists.sr.ht. 198