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