1scdoc(5)                      File Formats Manual                     scdoc(5)
2
3
4

NAME

6       scdoc - document format for writing manual pages
7

SYNTAX

9       Input files must use the UTF-8 encoding.
10
11   PREAMBLE
12       Each scdoc file must begin with the following preamble:
13
14           name(section) ["left_footer" ["center_header"]]
15
16       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
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       Each section of your man page should begin with something similar to
26       the following:
27
28           # HEADER NAME
29
30       Subsection headers are also understood - use two hashes. Each header
31       must have an empty line on either side.
32
33   PARAGRAPHS
34       Begin a new paragraph with an empty line.
35
36   LINE BREAKS
37       Insert a line break by ending a line with ++.
38
39       The result looks
40       like this.
41
42   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
47   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
51           The result looks something like this.
52
53           You may use multiple lines and most formatting.
54
55       Deindent to return to normal, or indent again to increase your indenta‐
56       tion depth.
57
58   LISTS
59       You may start bulleted lists with dashes (-), like so:
60
61           - Item 1
62           - Item 2
63                - Subitem 1
64                - Subitem 2
65           - Item 3
66
67       The result looks like this:
68
69       •   Item 1
70       •   Item 2
71           •   Subitem 1
72           •   Subitem 2
73       •   Item 3
74
75
76       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
80           - 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
86       •   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
90
91   NUMBERED LISTS
92       Numbered lists are similar to normal lists, but begin with periods (.)
93       instead of dashes (-), like so:
94
95           . Item 1
96           . Item 2
97           . Item 3,
98             with multiple lines
99
100       1.   Item 1
101       2.   Item 2
102       3.   Item 3, with multiple lines
103
104
105   TABLES
106       To begin a table, add an empty line followed by any number of rows.
107
108       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.
114
115       The first character of the first row is not limited to | and has spe‐
116       cial meaning. [ will produce a table with borders around each cell. |
117       will produce a table with no borders. ] will produce a table with one
118       border around the whole table.
119
120       To conclude your table, add an empty line after the last row.
121
122           [[ *Foo*
123           :- _Bar_
124           :-
125           |  *Row 1*
126           :  Hello
127           :] world!
128           |  *Row 2*
129           :  こんにちは
130           :  世界
131              !
132
133       ┌──────┬────────────┬────────┐
134Foo   Bar     │        │
135       ├──────┼────────────┼────────┤
136Row 1 │   Hello    │ world! │
137       ├──────┼────────────┼────────┤
138Row 2 │ こんにちは │ 世界 ! │
139       └──────┴────────────┴────────┘
140       You may also cause columns to expand to fill the available space with <
141       (left align), = (center align), and > (right align), like so:
142
143           [[ *Normal column*
144           :< Expanded column
145           |  *Foo*
146           :  Bar
147
148       ┌──────────────┬───────────────────────────────────────────────────────┐
149Normal column │ Expanded column                                       │
150       ├──────────────┼───────────────────────────────────────────────────────┤
151Foo           │ Bar                                                   │
152       └──────────────┴───────────────────────────────────────────────────────┘
153
154   LITERAL TEXT
155       You may turn off scdoc formatting and output literal text with escape
156       codes and literal blocks. Inserting a \ into your source will cause the
157       subsequent symbol to be treated as a literal and copied directly to the
158       output. You may also make blocks of literal syntax like so:
159
160           ```
161           _This formatting_ will *not* be interpreted by scdoc.
162           ```
163
164       These blocks will be indented one level. Note that literal text is
165       shown literally in the man viewer - that is, it's not a means for in‐
166       serting your own roff macros into the output. Note that \ is still in‐
167       terpreted within literal blocks, which for example can be useful to
168       output ``` inside of a literal block.
169
170   COMMENTS
171       Lines beginning with ; and a space are ignored.
172
173           ; This is a comment
174

CONVENTIONS

176       By convention, all scdoc documents should be hard wrapped at 80 col‐
177       umns.
178

SEE ALSO

180       scdoc(1)
181

AUTHORS

183       Maintained by Drew DeVault <sir@cmpwn.com>. Up-to-date sources can be
184       found at https://git.sr.ht/~sircmpwn/scdoc and bugs/patches can be sub‐
185       mitted by email to ~sircmpwn/public-inbox@lists.sr.ht.
186
187
188
189                                  2021-01-27                          scdoc(5)
Impressum