tcl-quill 0.3.0: Quill Project Automation System for Tcl/Tk

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

SYNOPSIS

<document title>...</document>
<contents>
<preface id title>
<section id title>
<appendix id title>
<xref ref ?text?>
<version>

DESCRIPTION

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).

Document Structure

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 Formatting

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.

Cross-References

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>"

MACROS

quilldoc(5) includes the following macro sets:

macro(n) The basic set of macros.
macroset_html(n) Macros for use in HTML-like documents.

In addition, it defines the following format-specific macros:

Structural 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:

Listing Macros

Cross-Reference Macros

<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.

Other Macros

<version>
Returns the version number string given to the quilldoc(n) object's format subcommand This is usually the project's version number..

HISTORY

This is a new format and macro set, based loosely on many similar efforts I've written in the past in other contexts.

AUTHOR

Will Duquette.

SEE ALSO

macro(n), manpage(5), quilldoc(n).


Generated from quilldoc.manpage on Sat Nov 08 09:29:58 PST 2014