.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "SCDOC" "5" "2024-02-18"
.PP
.SH NAME
.PP
scdoc - document format for writing manual pages
.PP
.SH SYNTAX
.PP
Input files must use the UTF-8 encoding.\&
.PP
.SS Preamble
.PP
Each scdoc file must begin with the following preamble:
.PP
.RS 4
\fINAME\fR(\fIsection\fR) ["left_footer" ["center_header"]]
.PP
.RE
\fINAME\fR is the name of the man page you are writing, and \fIsection\fR is the section
you'\&re writing for (see \fIman\fR(1) for information on manual sections).\&
.PP
\fIleft_footer\fR and \fIcenter_header\fR are optional arguments which set the text
positioned at those locations in the generated man page, and \fBmust\fR be
surrounded with double quotes.\&
.PP
.SS Section headers
.PP
Each section of your man page should begin with something similar to the
following:
.PP
.RS 4
# HEADER NAME
.PP
.RE
Subsection headers are also understood - use two hashes.\& Each header must have
an empty line on either side.\&
.PP
.SS Paragraphs
.PP
Begin a new paragraph with an empty line.\&
.PP
.SS Line breaks
.PP
Insert a line break by ending a line with ++.\&
.PP
The result looks
.br
like this.\&
.PP
.SS Formatting
.PP
Text can be made \fBbold\fR or \fIunderlined\fR with asterisks and underscores: *bold*
or _underlined_.\& Underscores in the_middle_of_words will be disregarded.\&
.PP
.SS Indentation
.PP
You may indent lines with tab characters (\fB\et\fR) to indent them by 4 spaces in
the output.\& Indented lines may not contain headers.\&
.PP
.RS 4
The result looks something like this.\&
.PP
You may use multiple lines and most \fIformatting\fR.\&
.PP
.RE
Deindent to return to normal, or indent again to increase your indentation
depth.\&
.PP
.SS Lists
.PP
You may start bulleted lists with dashes (-), like so:
.PP
.nf
.RS 4
- Item 1
- Item 2
	- Subitem 1
	- Subitem 2
- Item 3
.fi
.RE
.PP
The result looks like this:
.PP
.PD 0
.IP \(bu 4
Item 1
.IP \(bu 4
Item 2
.RS 4
.IP \(bu 4
Subitem 1
.IP \(bu 4
Subitem 2
.RE
.IP \(bu 4
Item 3
.PD
.PP
You may also extend long entries onto another line by giving it the same indent
level, plus two spaces.\& They will be rendered as a single list entry.\&
.PP
.nf
.RS 4
- Item 1 is pretty long so let\&'s
  break it up onto two lines
- Item 2 is shorter
	- But its children can go on
	  for a while
.fi
.RE
.PP
.PD 0
.IP \(bu 4
Item 1 is pretty long so let'\&s
break it up onto two lines
.IP \(bu 4
Item 2 is shorter
.RS 4
.IP \(bu 4
But its children can go on
for a while
.PD
.PP
.RE
.SS Numbered lists
.PP
Numbered lists are similar to normal lists, but begin with periods (.\&) instead
of dashes (-), like so:
.PP
.nf
.RS 4
\&. Item 1
\&. Item 2
\&. Item 3,
  with multiple lines
.fi
.RE
.PP
.PD 0
.IP 1. 4
Item 1
.IP 2. 4
Item 2
.IP 3. 4
Item 3,
with multiple lines
.PD
.PP
.SS Tables
.PP
To begin a table, add an empty line followed by any number of rows.\&
.PP
Each line of a table should start with | or : to start a new row or column
respectively (or space to continue the previous cell on multiple lines),
followed by [ or - or ] to align the contents to the left, center, or right,
followed by a space and the contents of that cell.\& You may use a space instead
of an alignment specifier to inherit the alignment of the same column in the
previous row.\& Each row must have the same number of columns; empty columns are
permitted.\&
.PP
The first character of the first row is not limited to | and has special
meaning.\& [ will produce a table with borders around each cell.\& | will produce a
table with no borders.\& ] will produce a table with one border around the whole
table.\&
.PP
To conclude your table, add an empty line after the last row.\&
.PP
.nf
.RS 4
[[ *Foo*
:- _Bar_
:-
|  *Row 1*
:  Hello
:] world!
|  *Row 2*
:  こんにちは
:  世界
   !
.fi
.RE
.PP
.TS
allbox;l c c
l c r
l c r.
T{
\fBFoo\fR
T}	T{
\fIBar\fR
T}	T{

T}
T{
\fBRow 1\fR
T}	T{
Hello
T}	T{
world!\&
T}
T{
\fBRow 2\fR
T}	T{
こんにちは
T}	T{
世界 !\&
T}
.TE
.sp 1
You may also cause columns to expand to fill the available space with < (left
align), = (center align), and > (right align), like so:
.PP
.nf
.RS 4
[[ *Normal column*
:< Expanded column
|  *Foo*
:  Bar
.fi
.RE
.PP
.TS
allbox;l lx
l lx.
T{
\fBNormal column\fR
T}	T{
Expanded column
T}
T{
\fBFoo\fR
T}	T{
Bar
T}
.TE
.sp 1
.SS Literal text
.PP
You may turn off scdoc formatting and output literal text with escape codes and
literal blocks.\& Inserting a \e into your source will cause the subsequent symbol
to be treated as a literal and copied directly to the output.\& You may also make
blocks of literal syntax like so:
.PP
.nf
.RS 4
```
_This formatting_ will *not* be interpreted by scdoc\&.
```
.fi
.RE
.PP
These blocks will be indented one level.\& Note that literal text is shown
literally in the man viewer - that is, it'\&s not a means for inserting your own
roff macros into the output.\& Note that \e is still interpreted within literal
blocks, which for example can be useful to output \``` inside of a literal
block.\&
.PP
.SS Comments
.PP
Lines beginning with ; and a space are ignored.\&
.PP
.nf
.RS 4
; This is a comment
.fi
.RE
.PP
.SH CONVENTIONS
.PP
By convention, all scdoc documents should be hard wrapped at 80 columns.\&
.PP
.SH SEE ALSO
.PP
\fIscdoc\fR(1)
.PP
.SH AUTHORS
.PP
Maintained by Drew DeVault <sir@cmpwn.\&com>.\& Up-to-date sources can be found at
https://git.\&sr.\&ht/~sircmpwn/scdoc and bugs/patches can be submitted by email to
~sircmpwn/public-inbox@lists.\&sr.\&ht.\&