471 lines
8.1 KiB
HTML
471 lines
8.1 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of scdoc</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>scdoc</H1>
|
|
Section: File Formats (5)<BR>Updated: 2020-02-16<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<P>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
<P>
|
|
|
|
scdoc - document format for writing manual pages
|
|
<P>
|
|
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNTAX</H2>
|
|
|
|
<P>
|
|
|
|
Input files must use the UTF-8 encoding.
|
|
<P>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H3>PREAMBLE</H3>
|
|
|
|
<P>
|
|
|
|
Each scdoc file must begin with the following preamble:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="1"><DD>
|
|
<B>name</B>(<I>section</I>) ["left_footer" ["center_header"]]
|
|
<P>
|
|
|
|
</DL>
|
|
|
|
<B>name</B> is the name of the man page you are writing, and <I>section</I> is the section
|
|
you're writing for (see <B><A HREF="/cgi-bin/man/man2html?1+man">man</A></B>(1) for information on manual sections).
|
|
<P>
|
|
|
|
<I>left_footer</I> and <I>center_header</I> are optional arguments which set the text
|
|
positioned at those locations in the generated man page, and <B>must</B> be
|
|
surrounded with double quotes.
|
|
<P>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>SECTION HEADERS</H3>
|
|
|
|
<P>
|
|
|
|
Each section of your man page should begin with something similar to the
|
|
following:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="2"><DD>
|
|
# HEADER NAME
|
|
<P>
|
|
|
|
</DL>
|
|
|
|
Subsection headers are also understood - use two hashes. Each header must have
|
|
an empty line on either side.
|
|
<P>
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>PARAGRAPHS</H3>
|
|
|
|
<P>
|
|
|
|
Begin a new paragraph with an empty line.
|
|
<P>
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>LINE BREAKS</H3>
|
|
|
|
<P>
|
|
|
|
Insert a line break by ending a line with ++.
|
|
<P>
|
|
|
|
The result looks
|
|
<BR>
|
|
|
|
like this.
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>FORMATTING</H3>
|
|
|
|
<P>
|
|
|
|
Text can be made <B>bold</B> or <I>underlined</I> with asterisks and underscores: *bold*
|
|
or _underlined_. Underscores in the_middle_of_words will be disregarded.
|
|
<P>
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H3>INDENTATION</H3>
|
|
|
|
<P>
|
|
|
|
You may indent lines with tab characters (<B>\t</B>) to indent them by 4 spaces in
|
|
the output. Indented lines may not contain headers.
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="3"><DD>
|
|
The result looks something like this.
|
|
<P>
|
|
|
|
You may use multiple lines and most <I>formatting</I>.
|
|
<P>
|
|
|
|
</DL>
|
|
|
|
Deindent to return to normal, or indent again to increase your indentation
|
|
depth.
|
|
<P>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>LISTS</H3>
|
|
|
|
<P>
|
|
|
|
You may start bulleted lists with dashes (-), like so:
|
|
<P>
|
|
|
|
<PRE>
|
|
<DL COMPACT><DT id="4"><DD>- Item 1
|
|
- Item 2
|
|
- Subitem 1
|
|
- Subitem 2
|
|
- Item 3
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
The result looks like this:
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="5"><DD>
|
|
•
|
|
|
|
|
|
Item 1
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="6"><DD>
|
|
•
|
|
|
|
|
|
Item 2
|
|
<DL COMPACT><DT id="7"><DD>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="8"><DD>
|
|
•
|
|
|
|
|
|
Subitem 1
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="9"><DD>
|
|
•
|
|
|
|
|
|
Subitem 2
|
|
</DL>
|
|
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="10"><DD>
|
|
•
|
|
|
|
|
|
Item 3
|
|
<P>
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<PRE>
|
|
<DL COMPACT><DT id="11"><DD>- 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
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="12"><DD>
|
|
•
|
|
|
|
|
|
Item 1 is pretty long so let's
|
|
break it up onto two lines
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="13"><DD>
|
|
•
|
|
|
|
|
|
Item 2 is shorter
|
|
<DL COMPACT><DT id="14"><DD>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="15"><DD>
|
|
•
|
|
|
|
|
|
But its children can go on
|
|
for a while
|
|
<P>
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
</DL>
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>NUMBERED LISTS</H3>
|
|
|
|
<P>
|
|
|
|
Numbered lists are similar to normal lists, but begin with periods (.) instead
|
|
of dashes (-), like so:
|
|
<P>
|
|
|
|
<PRE>
|
|
<DL COMPACT><DT id="16"><DD>. Item 1
|
|
. Item 2
|
|
. Item 3,
|
|
with multiple lines
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<DL COMPACT><DT id="17"><DD>
|
|
1.
|
|
|
|
|
|
Item 1
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="18"><DD>
|
|
2.
|
|
|
|
|
|
Item 2
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="19"><DD>
|
|
3.
|
|
|
|
|
|
Item 3,
|
|
with multiple lines
|
|
<P>
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>TABLES</H3>
|
|
|
|
<P>
|
|
|
|
To begin a table, add an empty line followed by any number of rows.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
To conclude your table, add an empty line after the last row.
|
|
<P>
|
|
|
|
<PRE>
|
|
<DL COMPACT><DT id="20"><DD>[[ *Foo*
|
|
:- _Bar_
|
|
:-
|
|
| *Row 1*
|
|
: Hello
|
|
:] world!
|
|
| *Row 2*
|
|
: こんにちは
|
|
: 世界
|
|
!
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<TABLE>
|
|
<TR VALIGN=top><TD>
|
|
<B>Foo</B>
|
|
</TD><TD>
|
|
<I>Bar</I>
|
|
</TD><TD><B>
|
|
<P>
|
|
</B></TD><TD></TD><TD ALIGN=center></TD><TD ALIGN=center><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>Row 1</B>
|
|
</TD><TD ALIGN=center>
|
|
Hello
|
|
</TD><TD ALIGN=right>
|
|
world!
|
|
</TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>Row 2</B>
|
|
</TD><TD ALIGN=center>
|
|
こんにちは
|
|
</TD><TD ALIGN=right>
|
|
世界 !
|
|
</TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
You may also cause columns to expand to fill the available space with < (left
|
|
align), = (center align), and > (right align), like so:
|
|
<P>
|
|
|
|
<PRE>
|
|
<DL COMPACT><DT id="21"><DD>[[ *Normal column*
|
|
:< Expanded column
|
|
| *Foo*
|
|
: Bar
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<TABLE>
|
|
<TR VALIGN=top><TD>
|
|
<B>Normal column</B>
|
|
</TD><TD>
|
|
Expanded column
|
|
</TD><TD><B></B></TD><TD></TD><TD><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>Foo</B>
|
|
</TD><TD>
|
|
Bar
|
|
</TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
<A NAME="lbAM"> </A>
|
|
<H3>LITERAL TEXT</H3>
|
|
|
|
<P>
|
|
|
|
You may turn off scdoc formatting and output literal text with escape codes and
|
|
literal blocks. Inserting a \ 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:
|
|
<P>
|
|
|
|
<PRE>
|
|
<DL COMPACT><DT id="22"><DD>```
|
|
_This formatting_ will *not* be interpreted by scdoc.
|
|
```
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
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 \ is still interpreted within literal
|
|
blocks, which for example can be useful to output ``` inside of a literal
|
|
block.
|
|
<P>
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H3>COMMENTS</H3>
|
|
|
|
<P>
|
|
|
|
Lines beginning with ; and a space are ignored.
|
|
<P>
|
|
|
|
<PRE>
|
|
<DL COMPACT><DT id="23"><DD>; This is a comment
|
|
</PRE>
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H2>CONVENTIONS</H2>
|
|
|
|
<P>
|
|
|
|
By convention, all scdoc documents should be hard wrapped at 80 columns.
|
|
<P>
|
|
|
|
<A NAME="lbAP"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<P>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+scdoc">scdoc</A></B>(1)
|
|
<P>
|
|
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
<P>
|
|
|
|
Maintained by Drew DeVault <<A HREF="mailto:sir@cmpwn.com">sir@cmpwn.com</A>>. Up-to-date sources can be found at
|
|
<A HREF="https://git.sr.ht/~sircmpwn/scdoc">https://git.sr.ht/~sircmpwn/scdoc</A> and bugs/patches can be submitted by email to
|
|
~sircmpwn/<A HREF="mailto:public-inbox@lists.sr.ht">public-inbox@lists.sr.ht</A>.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="24"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="25"><A HREF="#lbAC">SYNTAX</A><DD>
|
|
<DL>
|
|
<DT id="26"><A HREF="#lbAD">PREAMBLE</A><DD>
|
|
<DT id="27"><A HREF="#lbAE">SECTION HEADERS</A><DD>
|
|
<DT id="28"><A HREF="#lbAF">PARAGRAPHS</A><DD>
|
|
<DT id="29"><A HREF="#lbAG">LINE BREAKS</A><DD>
|
|
<DT id="30"><A HREF="#lbAH">FORMATTING</A><DD>
|
|
<DT id="31"><A HREF="#lbAI">INDENTATION</A><DD>
|
|
<DT id="32"><A HREF="#lbAJ">LISTS</A><DD>
|
|
<DT id="33"><A HREF="#lbAK">NUMBERED LISTS</A><DD>
|
|
<DT id="34"><A HREF="#lbAL">TABLES</A><DD>
|
|
<DT id="35"><A HREF="#lbAM">LITERAL TEXT</A><DD>
|
|
<DT id="36"><A HREF="#lbAN">COMMENTS</A><DD>
|
|
</DL>
|
|
<DT id="37"><A HREF="#lbAO">CONVENTIONS</A><DD>
|
|
<DT id="38"><A HREF="#lbAP">SEE ALSO</A><DD>
|
|
<DT id="39"><A HREF="#lbAQ">AUTHORS</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:05 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|