1scdoc(5) File Formats Manual scdoc(5)
2
6 scdoc - document format for writing manual pages
7
9 Input files must use the UTF-8 encoding.
10 PREAMBLE
12 Each scdoc file must begin with the following preamble:
13 name(section) ["left_footer" ["center_header"]]
15 name is the name of the man page you are writing, and section is the
17 section you're writing for (see man(1) for information on manual sec‐
18 tions).
19 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 SECTION HEADERS
25 Each section of your man page should begin with something similar to
26 the following:
27 # HEADER NAME
29 Subsection headers are also understood - use two hashes. Each header
31 must have an empty line on either side.
32 PARAGRAPHS
34 Begin a new paragraph with an empty line.
35 LINE BREAKS
37 Insert a line break by ending a line with ++.
38 The result looks
40 like this.
41 FORMATTING
43 Text can be made bold or underlined with asterisks and underscores:
44 *bold* or _underlined_. Underscores in the_middle_of_words will be dis‐
45 regarded.
46 INDENTATION
48 You may indent lines with tab characters (\t) to indent them by 4 spa‐
49 ces in the output. Indented lines may not contain headers.
50 The result looks something like this.
52 You may use multiple lines and most formatting.
54 Deindent to return to normal, or indent again to increase your indenta‐
56 tion depth.
57 LISTS
59 You may start bulleted lists with dashes (-), like so:
60 - Item 1
62 - Item 2
63 - Subitem 1
64 - Subitem 2
65 - Item 3
66 The result looks like this:
68 • Item 1
70 • Item 2
71 • Subitem 1
72 • Subitem 2
73 • Item 3
74 You may also extend long entries onto another line by giving it the
77 same indent level, plus two spaces. They will be rendered as a single
78 list entry.
79 - Item 1 is pretty long so let's
81 break it up onto two lines
82 - Item 2 is shorter
83 - But its children can go on
84 for a while
85 • Item 1 is pretty long so let's break it up onto two lines
87 • Item 2 is shorter
88 • But its children can go on for a while
89 NUMBERED LISTS
92 Numbered lists are similar to normal lists, but begin with periods (.)
93 instead of dashes (-), like so:
94 . Item 1
96 . Item 2
97 . Item 3,
98 with multiple lines
99 1. Item 1
101 2. Item 2
102 3. Item 3, with multiple lines
103 TABLES
106 To begin a table, add an empty line followed by any number of rows.
107 Each line of a table should start with | or : to start a new row or
109 column respectively (or space to continue the previous cell on multiple
110 lines), followed by [ or - or ] to align the contents to the left, cen‐
111 ter, or right, followed by a space and the contents of that cell. You
112 may use a space instead of an alignment specifier to inherit the align‐
113 ment of the same column in the previous row. Each row must have the
114 same number of columns; empty columns are permitted.
115 The first character of the first row is not limited to | and has spe‐
117 cial meaning. [ will produce a table with borders around each cell. |
118 will produce a table with no borders. ] will produce a table with one
119 border around the whole table.
120 To conclude your table, add an empty line after the last row.
122 [[ *Foo*
124 :- _Bar_
125 :-
126 | *Row 1*
127 : Hello
128 :] world!
129 | *Row 2*
130 : こんにちは
131 : 世界
132 !
133 ┌──────┬────────────┬────────┐
135 │Foo │ Bar │ │
136 ├──────┼────────────┼────────┤
137 │Row 1 │ Hello │ world! │
138 ├──────┼────────────┼────────┤
139 │Row 2 │ こんにちは │ 世界 ! │
140 └──────┴────────────┴────────┘
141 You may also cause columns to expand to fill the available space with <
142 (left align), = (center align), and > (right align), like so:
143 [[ *Normal column*
145 :< Expanded column
146 | *Foo*
147 : Bar
148 ┌──────────────┬───────────────────────────────────────────────────────┐
150 │Normal column │ Expanded column │
151 ├──────────────┼───────────────────────────────────────────────────────┤
152 │Foo │ Bar │
153 └──────────────┴───────────────────────────────────────────────────────┘
154 LITERAL TEXT
156 You may turn off scdoc formatting and output literal text with escape
157 codes and literal blocks. Inserting a \ into your source will cause the
158 subsequent symbol to be treated as a literal and copied directly to the
159 output. You may also make blocks of literal syntax like so:
160 ```
162 _This formatting_ will *not* be interpreted by scdoc.
163 ```
164 These blocks will be indented one level. Note that literal text is
166 shown literally in the man viewer - that is, it's not a means for in‐
167 serting your own roff macros into the output. Note that \ is still in‐
168 terpreted within literal blocks, which for example can be useful to
169 output ``` inside of a literal block.
170 COMMENTS
172 Lines beginning with ; and a space are ignored.
173 ; This is a comment
175
177 By convention, all scdoc documents should be hard wrapped at 80 col‐
178 umns.
179
181 scdoc(1)
182
184 Maintained by Drew DeVault <sir@cmpwn.com>. Up-to-date sources can be
185 found at https://git.sr.ht/~sircmpwn/scdoc and bugs/patches can be sub‐
186 mitted by email to ~sircmpwn/public-inbox@lists.sr.ht.
187 2023-07-22 scdoc(5)