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. Each row must have the same number of columns; empty columns are
126permitted.
127
128The first character of the first row is not limited to | and has special
129meaning. [ will produce a table with borders around each cell. | will produce a
130table with no borders. ] will produce a table with one border around the whole
131table.
132
133To conclude your table, add an empty line after the last row.
134
135```
136[[ *Foo*
137:- _Bar_
138:-
139|  *Row 1*
140:  Hello
141:] world!
142|  *Row 2*
143:  こんにちは
144:  世界
145   !
146```
147
148[[ *Foo*
149:- _Bar_
150:-
151|  *Row 1*
152:  Hello
153:] world!
154|  *Row 2*
155:  こんにちは
156:  世界
157   !
158
159You may also cause columns to expand to fill the available space with < (left
160align), = (center align), and > (right align), like so:
161
162```
163[[ *Normal column*
164:< Expanded column
165|  *Foo*
166:  Bar
167```
168
169[[ *Normal column*
170:< Expanded column
171|  *Foo*
172:  Bar
173
174## LITERAL TEXT
175
176You may turn off scdoc formatting and output literal text with escape codes and
177literal blocks. Inserting a \\ into your source will cause the subsequent symbol
178to be treated as a literal and copied directly to the output. You may also make
179blocks of literal syntax like so:
180
181```
182\```
183_This formatting_ will *not* be interpreted by scdoc.
184\```
185```
186
187These blocks will be indented one level. Note that literal text is shown
188literally in the man viewer - that is, it's not a means for inserting your own
189roff macros into the output. Note that \\ is still interpreted within literal
190blocks, which for example can be useful to output \``` inside of a literal
191block.
192
193## COMMENTS
194
195Lines beginning with ; and a space are ignored.
196
197```
198; This is a comment
199```
200
201# CONVENTIONS
202
203By convention, all scdoc documents should be hard wrapped at 80 columns.
204
205# SEE ALSO
206
207*scdoc*(1)
208
209# AUTHORS
210
211Maintained by Drew DeVault <sir@cmpwn.com>. Up-to-date sources can be found at
212https://git.sr.ht/~sircmpwn/scdoc and bugs/patches can be submitted by email to
213~sircmpwn/public-inbox@lists.sr.ht.
214