\*(C'\fR tags
will be added to the \s-1HTML\s0 output.
.PP
There is no need to escape any character except \f(CW\*(C`\e\*(C'\fR (which should be written
as \f(CW\*(C`\e\e\*(C'\fR) and an unbalanced \f(CW\*(C`[\*(C'\fR or \f(CW\*(C`]\*(C'\fR (which should be written as
\&\f(CW\*(C`\eentity[91]\*(C'\fR or \f(CW\*(C`\eentity[93]\*(C'\fR respectively). Escaping \f(CW\*(C`[\*(C'\fR or \f(CW\*(C`]\*(C'\fR is not
necessary if the brackets are balanced within the paragraph, and therefore is
only rarely needed.
.PP
Commands begin with \f(CW\*(C`\e\*(C'\fR. For example, the command to insert a line break
(corresponding to the \f(CW\*(C`
\*(C'\fR tag in \s-1HTML\s0) is \f(CW\*(C`\ebreak\*(C'\fR. If the command
takes arguments, they are enclosed in square brackets after the command. If
there are multiple arguments, they are each enclosed in square brackets and
follow each other. Any amount of whitespace (but nothing else) is allowed
between the command and the arguments, or between the arguments. So, for
example, all of the following are entirely equivalent:
.PP
.Vb 2
\& \elink[index.html][Main page]
\& \elink [index.html] [Main page]
\&
\& \elink[index.html]
\& [Main page]
\&
\& \elink
\& [index.html]
\& [Main page]
.Ve
.PP
(\f(CW\*(C`\elink\*(C'\fR is a command that takes two arguments.)
.PP
Command arguments may contain paragraphs of text, other commands, and so
forth, nested arbitrarily (although this may not make sense for all arguments
of all commands, of course).
.PP
Some commands take an additional optional formatting instruction argument.
That argument is enclosed in parentheses and placed before any other
arguments. It specifies the \f(CW\*(C`class\*(C'\fR attribute for that \s-1HTML\s0 tag, for use
with style sheets, or the \f(CW\*(C`id\*(C'\fR attribute, for use with style sheets or as an
anchor. If the argument begins with \f(CW\*(C`#\*(C'\fR, it will be taken to be an \f(CW\*(C`id\*(C'\fR.
Otherwise, it will be taken as a \f(CW\*(C`class\*(C'\fR.
.PP
For example, a first-level heading is normally written as:
.PP
.Vb 1
\& \eh1[Heading]
.Ve
.PP
(with one argument). Either of the following will add a class attribute of
\&\f(CW\*(C`header\*(C'\fR to that \s-1HTML\s0 container that can be referred to in style sheets:
.PP
.Vb 2
\& \eh1(header)[Heading]
\& \eh1 (header) [Heading]
.Ve
.PP
and the following would add an id attribute of \f(CW\*(C`intro\*(C'\fR to the heading so that
it could be referred to with the anchor \f(CW\*(C`#intro\*(C'\fR:
.PP
.Vb 1
\& \eh1(#intro)[Introduction]
.Ve
.PP
Note that the heading commands have special handling for \f(CW\*(C`id\*(C'\fR attributes; see
below for more details.
.SS "Basic Format"
.IX Subsection "Basic Format"
There are two commands that are required to occur in every document.
.PP
The first is \f(CW\*(C`\eheading\*(C'\fR, which must occur before any regular page text. It
takes two arguments: the page title (the title that shows up in the window
title bar for the browser and is the default text for bookmarks, not anything
that's displayed as part of the body of the page), and the style sheet to use.
If there is no style sheet for this page, the second argument is still
required but should be empty (\f(CW\*(C`[]\*(C'\fR).
.PP
The second required command is \f(CW\*(C`\esignature\*(C'\fR, which must be the last command
in the file. \f(CW\*(C`\esignature\*(C'\fR will take care of appending the signature,
appending navigation links, closing any open blocks, and any other cleanup
that has to happen at the end of a generated \s-1HTML\s0 page.
.PP
You can include other files with the \f(CW\*(C`\einclude\*(C'\fR command, although it has a
few restrictions. The \f(CW\*(C`\einclude\*(C'\fR command must appear either at the beginning
of the file or after a blank line, and should be followed by a blank line. Be
careful not to include the same file recursively as there is no current
protection against infinite loops.
.PP
Thread files will not be automatically respun when included files change, so
you will need touch the thread file to force the corresponding output file to
be regenerated.
.PP
All further thread commands are divided into block commands and inline
commands. These roughly correspond to \s-1HTML 5\s0's \*(L"flow content\*(R" and \*(L"phrasing
content\*(R" respectively.
.SS "Block Commands"
.IX Subsection "Block Commands"
Block commands are commands that should occur in a paragraph by themselves,
not contained in a paragraph with other text. They indicate high-level
structural elements of the page. \f(CW\*(C`\eheading\*(C'\fR and \f(CW\*(C`\einclude\*(C'\fR were already
discussed above, but here is a complete list. Any argument of \s-1TEXT\s0 can be
multiple paragraphs and contain other embedded block commands (so you can nest
a list inside another list, for example).
.IP "\eblock[\s-1TEXT\s0]" 4
.IX Item "block[TEXT]"
Put \s-1TEXT\s0 in an indented block, equivalent to \f(CW\*(C`
\*(C'\fR in \s-1HTML.\s0 Used primarily for quotations or license statements embedded in regular text. .IP "\ebullet[\s-1TEXT\s0]" 4 .IX Item "bullet[TEXT]" \&\s-1TEXT\s0 is formatted as an item in a bullet list. This is like \f(CW\*(C`\*(C'\fR inside \f(CW\*(C` \*(C'\fR in \s-1HTML,\s0 but the surrounding list tags are inferred automatically and handled correctly when multiple \f(CW\*(C`\ebullet\*(C'\fR commands are used in a row. .Sp Normally, \s-1TEXT\s0 is treated like a paragraph. If used with a formatting instruction of \f(CW\*(C`packed\*(C'\fR, such as: .Sp .Vb 1 \& \ebullet(packed)[First item] .Ve .Sp then the \s-1TEXT\s0 argument will not be treated as a paragraph and will not be surrounded in \f(CW\*(C`
\*(C'\fR. No block commands should be used inside this type of \f(CW\*(C`\ebullet\*(C'\fR command. This variation will, on most browsers, not put any additional whitespace around the line, which will produce better formatting for bullet lists where each item is a single line. .IP "\edesc[\s-1HEADING\s0][\s-1TEXT\s0]" 4 .IX Item "desc[HEADING][TEXT]" An element in a description list, where each item has a tag \s-1HEADING\s0 and an associated body text of \s-1TEXT,\s0 like \f(CW\*(C`
- \*(C'\fR and \f(CW\*(C`
- \*(C'\fR in \s-1HTML.\s0 As with \f(CW\*(C`\ebullet\*(C'\fR, the \f(CW\*(C`
\*(C'\fR tags are inferred automatically. .IP "\ediv[\s-1TEXT\s0]" 4 .IX Item "div[TEXT]" Does nothing except wrap \s-1TEXT\s0 in an \s-1HTML\s0 \f(CW\*(C`
\*(C'\fR tag. The only purpose of this command is to use it with a formatting instruction to generate an \s-1HTML\s0 \&\f(CW\*(C`class\*(C'\fR attribute on the \f(CW\*(C`\*(C'\fR tag. .IP "\eh1[\s-1HEADING\s0] .. \eh6[\s-1HEADING\s0]" 4 .IX Item "h1[HEADING] .. h6[HEADING]" Level one through level six headings, just like \f(CW\*(C`\*(C'\fR .. \f(CW\*(C`
\*(C'\fR in \&\s-1HTML.\s0 If given an \f(CW\*(C`id\*(C'\fR formatting instruction, such as: .Sp .Vb 1 \& \eh1(#anchor)[Heading] .Ve .Sp then not only will an id attribute be added to the \f(CW\*(C`
\*(C'\fR container but the text of the heading will also be enclosed in an \f(CW\*(C`\*(C'\fR container to ensure that \f(CW\*(C`#anchor\*(C'\fR can be used as an anchor in a link in older browsers that don't understand \f(CW\*(C`id\*(C'\fR attributes. This is special handling that only works with \f(CW\*(C`\eh1\*(C'\fR through \f(CW\*(C`\eh6\*(C'\fR, not with other commands. .IP "\eheading[\s-1TITLE\s0][\s-1STYLE\s0]" 4 .IX Item "heading[TITLE][STYLE]" Set the page title to \s-1TITLE\s0 and the style sheet to \s-1STYLE\s0 and emit the \s-1HTML\s0 page header. If a \f(CW\*(C`style\-url\*(C'\fR argument was given, that base \s-1URL\s0 will be prepended to \s-1STYLE\s0 to form the \s-1URL\s0 for the style sheet; otherwise, \s-1STYLE\s0 will be used verbatim as a \s-1URL\s0 except with \f(CW\*(C`.css\*(C'\fR appended. .Sp This command must come after any \f(CW\*(C`\eid\*(C'\fR or \f(CW\*(C`\erss\*(C'\fR commands and may come after commands that don't produce any output (such as macro definitions or \&\f(CW\*(C`\einclude\*(C'\fR of files that produce no output) but otherwise must be the first command of the file. .IP "\eid[\s-1ID\s0]" 4 .IX Item "id[ID]" Sets the Subversion, \s-1CVS,\s0 or \s-1RCS\s0 revision number and time. \s-1ID\s0 should be the string \f(CW\*(C`$Id$\*(C'\fR, which will be expanded by Subversion, \s-1CVS,\s0 and \s-1RCS.\s0 This string is embedded verbatim in an \s-1HTML\s0 comment near the beginning of the generated output, and is used to determine last modified information for the file (used by the \f(CW\*(C`\esignature\*(C'\fR command). .Sp For this command to behave properly, it must be given before \f(CW\*(C`\eheading\*(C'\fR. .IP "\einclude[\s-1FILE\s0]" 4 .IX Item "include[FILE]" Include \s-1FILE\s0 after the current paragraph. If multiple files are included in the same paragraph, they're included in reverse order, but this behavior may change in later versions and should not be relied on. It's strongly recommended to always put the \f(CW\*(C`\einclude\*(C'\fR command in its own paragraph. Don't put \f(CW\*(C`\eheading\*(C'\fR or \f(CW\*(C`\esignature\*(C'\fR into an included file; the results won't be correct. .IP "\enumber[\s-1TEXT\s0]" 4 .IX Item "number[TEXT]" \&\s-1TEXT\s0 is formatted as an item in a numbered list, like \f(CW\*(C`
- \*(C'\fR inside \f(CW\*(C`
\*(C'\fR in \s-1HTML.\s0 As with \f(CW\*(C`\ebullet\*(C'\fR and \f(CW\*(C`\edesc\*(C'\fR, the surrounding tags are inferred automatically. .Sp As with \f(CW\*(C`\ebullet\*(C'\fR, a formatting instruction of \f(CW\*(C`packed\*(C'\fR will omit the paragraph tags around \s-1TEXT\s0 for better formatting with a list of short items. See the description under \f(CW\*(C`\ebullet\*(C'\fR for more information. .IP "\epre[\s-1TEXT\s0]" 4 .IX Item "pre[TEXT]" Insert \s-1TEXT\s0 preformatted, preserving spacing and line breaks. This uses the \&\s-1HTML\s0 \f(CW\*(C`
\*(C'\fR tag, and therefore is normally also shown in a fixed-width font by the browser. .Sp When using \f(CW\*(C`\epre\*(C'\fR inside indented blocks or lists, some care must be taken with indentation whitespace. Normally, the browser indents text inside \&\f(CW\*(C`\epre\*(C'\fR relative to the enclosing block, so you should only put as much whitespace before each line in \f(CW\*(C`\epre\*(C'\fR as those lines should be indented relative to the enclosing text. However \fBlynx\fR, unfortunately, indents relative to the left margin, so it's difficult to use indentation that looks correct in both \fBlynx\fR and other browsers. .IP "\equote[\s-1TEXT\s0][\s-1AUTHOR\s0][\s-1CITATION\s0]" 4 .IX Item "quote[TEXT][AUTHOR][CITATION]" Used for quotes at the top of a web page. .Sp The whole text will be enclosed in a \f(CW\*(C`\*(C'\fR tag with class \&\f(CW\*(C`quote\*(C'\fR for style sheets. \s-1TEXT\s0 may be multiple paragraphs. Any formatting instruction given to \f(CW\*(C`\equote\*(C'\fR will be used as the formatting instruction for each paragraph in \s-1TEXT\s0 (so an \f(CW\*(C`id\*(C'\fR is normally not appropriate). .Sp If the formatting instruction is \f(CW\*(C`broken\*(C'\fR, line breaks in \s-1TEXT\s0 will be honored by inserting \f(CW\*(C`
\*(C'\fR tags at the end of each line. Use this for poetry or other cases where line breaks are significant. .Sp A final paragraph will then be added with class \f(CW\*(C`attribution\*(C'\fR if the formatting instruction is \f(CW\*(C`broken\*(C'\fR or \f(CW\*(C`short\*(C'\fR and class \f(CW\*(C`long\-attrib\*(C'\fR otherwise. This paragraph will contain the \s-1AUTHOR,\s0 a comma, and then \&\s-1CITATION.\s0 \s-1CITATION\s0 will be omitted if empty. .IP "\erss[\s-1URL\s0][\s-1TITLE\s0]" 4 .IX Item "rss[URL][TITLE]" Indicates that this page has a corresponding \s-1RSS\s0 feed at the \s-1URL URL.\s0 The title of the \s-1RSS\s0 feed (particularly important if a page has more than one feed) is given by \s-1TITLE.\s0 .Sp The feed links are included in the page header output by \f(CW\*(C`\eheading\*(C'\fR, so this command must be given before \f(CW\*(C`\eheading\*(C'\fR to be effective. .IP "\erule" 4 .IX Item "rule" A horizontal rule, \f(CW\*(C`
\*(C'\fR in \s-1HTML.\s0 .IP "\esitemap" 4 .IX Item "sitemap" Inserts a bullet list showing the structure of the whole site. A \f(CW\*(C`sitemap\*(C'\fR argument must be provided to the constructor to use this command. (If invoked via App::DocKnot::Spin, this means a \fI.sitemap\fR file must be present at the root of the source directory.) .Sp Be aware that \fBspin\fR doesn't know whether a file contains a \f(CW\*(C`\esitemap\*(C'\fR command and hence won't know to regenerate a file when the \fI.sitemap\fR file has changed. You will need touch the source file to force it to be respun. .IP "\etable[\s-1OPTIONS\s0][\s-1BODY\s0]" 4 .IX Item "table[OPTIONS][BODY]" Creates a table. .Sp The \s-1OPTIONS\s0 text is added verbatim to the