quilldoc(5): Quill Documentation Syntax
SYNOPSIS
DESCRIPTION
Document Structure
Prose Formatting
Cross-References
MACROS
Structural Macros
Listing Macros
Cross-Reference Macros
Other Macros
HISTORY
AUTHOR
SEE ALSO
<document title>...</document>
<contents>
<preface id title>
<section id title>
<appendix id title>
<xref ref ?text?>
<version>
quilldoc(5) is a format for producing technical documents with section
numbers, cross-references, and tables of contents. The Quill User's
Guide is written using quilldoc(5). It is an HTML-like format in which
the tags are actually macros: Tcl commands which return text. The
tags are replaced by the returned text. See macro(n) for an
explanation of how macros are handled.
quilldoc(5) defines a number of macros suitable for formatting the
content of documents. Individual documents can define additional
macros as needed.
The quilldoc(n) processor translates quilldoc(5) files into
HTML; in principle, however, additional back-ends could be defined to
translate the format into other kinds of output.
This section explains how to prepare document files for use with
quilldoc(n).
A document consists of a number of sections contained within
<document>...</document> macros. There are several
kinds of sections:
- Preface Sections
-
Preface sections have titles but no section numbers. They generally
go at the beginning of the document.
Preface sections are begun with a <preface> tag which states the
section's ID and title:
<preface intro "Introduction">
...
The ID is used in cross-references to the preface.
- Numbered Sections
-
Numbered sections have titles and automatically generated section numbers,
e.g., "1.", "1.2", "1.2.3". They are used in the body of the document.
Numbered sections are begun with a <section> tag which states the
section's ID and title. The ID can consist of multiple components,
separated by periods; these indicate the relation of the sections.
For example, these sections might be numbered "1.", "1.1", and "1.1.1":
<section overview "Overview">
...
<section overview.part "Overview of Some Part">
...
<section overview.part.detail "Detail of Some Part">
...
- Appendix Sections
-
Appendix sections have titles and automatically generated section numbers,
e.g., "Appendix A", "Appendix B.1", "Appendix C.1.2". They are used at the
end of the document.
Appendices are begun with an <appendix> tag that states the section's
ID and title. IDs are defined as for numbered sections; for example,
these appendices might be numbered "Appendix A", "Appendix A.1", and
"Appendix A.1.1":
<appendix background "Background">
...
<appendix background.part "Background of Some Part">
...
<appendix background.part.detail "Detail of Som Part">
...
A complete document skeleton might look like this:
<document "My Document Title">
<contents>
<preface intro "Introduction">
...
<section usage "Using My Software">
...
<appendix options "Standard Options">
</document>
Prose is styled and formatted using the macros in the
macroset_html(n) macro set. For example, to boldface text
use the <b> tag:
<b>text</b> or <b text>
In addition, the HTML macro set includes macros for more complex
structures.
The <xref> macro creates cross-reference links to sections within
the same document; to the project's man pages; to other project documents;
or to arbitrary web pages. Cross-reference links may be specified in a
number of ways.
- <xref sectionId>
-
References a section within the same document, where the
sectionId is the ID given to the <preface>,
<section>, or <appendix> macro, e.g.,
"<xref intro>".
- <xref name(section)>
-
References the named man page, e.g., "<xref quilldoc(5)>"
- <xref url>
-
References a web page by its URL. At present, only "http" URLs
are supported. E.g., "<xref http://my.sample.url>"
quilldoc(5) includes the following macro sets:
In addition, it defines the following format-specific macros:
These macros are used to define the structure of the man page.
They are presented in the order in which they are ordinarily used.
- <document title>...</document>
-
These tags should be the first and last to appear in every document file.
The tag <document> tag begins the document, and provides all of the HTML header boilerplate. Similarly, the </document> tag provides the
HTML footer and boilerplate.
<document "Quill User's Guide">
...
</document>
- <contents>
-
This macro is replaced with a formatted table of contents of all
sections in the document.
- <preface id title>
-
This macro begins a "preface" section, an unnumbered section usually found
at the beginning of the document The id must be a valid identifier
containing no period characters; it used to refer to the section in
cross-references.
<preface intro "Introduction">
...
- <section id title>
-
Defines a numbered section within the document. Sections are numbered
automatically, based on the structure of their IDs. A top-level section
will have an ID that is a simple identifier (letters, numbers, and
underscores, beginning with a letter). Its immediate children will have
IDs consisting of the same identifier, a period ("."), and another
identifier. Their children will add another period and identifier, and
so on. The tree of sections may be arbitrarily deep.
The IDs are generally intended to be mnemonic.
quilldoc(n) requires that the sections be presented in the
correct reading order.
<section aaa "Top Level Section">
<section aaa.aaa "First Subsection">
<section aaa.aaa.aaa "First Subsubsection">
<section aaa.bbb "Second Subsection">
<section aaa.ccc "Third Subsection">
<section bbb "Another Top Level Section">
- <appendix id title>
-
Defines an appendix within the document. Appendices are just like
sections, with this few differences:
- All appendices must appear after all <section> macros.
- Top-level appendix sections are numbered as "Appendix A",
"Appendix B", and so forth.
- <xref ref ?text?>
-
Creates a cross-reference link to the page/anchor identified by
ref; see Cross-References for the many kinds of
reference understood by <xref>.
If text is given, it is used as the link text. Otherwise,
the link text depends on the kind of cross reference.
- <xref listutils(n)>
-
Links to the named man page, and uses the man page name as the link
text.
- <xref intro>
-
Links to the section with ID "intro". If the section is a
<preface>, the link text is the section title. If the section is
a numbered <section>, the link text is "Section number". If the
section is an <appendix>, the link text is "Appendix number".
- <xref http://example.com>
-
Links to the URL; the link text is the URL.
- <version>
-
Returns the version number string given to the
quilldoc(n) object's format subcommand This
is usually the project's version number..
This is a new format and macro set, based loosely on many similar efforts
I've written in the past in other contexts.
Will Duquette.
macro(n), manpage(5), quilldoc(n).
Generated from quilldoc.manpage on Sat Nov 08 09:29:58 PST 2014