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

manpage(5): Man Page Documentation Syntax

SYNOPSIS
DESCRIPTION
Manual Sections
Directory Layout
Man Page Names and Files
Man Page Sections
Man Page Items
Cross-References
Man Page Skeleton
MACROS
Structural Macros
Definition List Extensions
Cross-Reference Macros
Other Macros
BUGS
HISTORY
AUTHOR
SEE ALSO

SYNOPSIS

<manpage name title ?parent?>...</manpage>
<section title>
<subsection title>
<defitem name text>
<defopt option text>
<itemlist>
<xref ref ?text?>
<xtag name>
<tag name ?text?>
<version>

DESCRIPTION

This is the format used to produce man pages for Quill's internal libraries; it is also available to other Quill projects. manpage(5) 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.

manpage(5) defines a number of macros suitable for formatting the content of man pages. Individual man pages can define additional macros as needed.

The manpage(n) processor translates manpage(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 man page files for use with manpage(n).

Manual Sections

Following Unix conventions, it is pretended that the manual pages written using manpage(5) fall into one of the standard Unix manual sections. At present, manpage(5) supports sections:

Section 1: Applications
I.e., commands that can be entered at the command-line.

Section 5: File formats
E.g., this man page.

Section n: Tcl commands
For some reason Tcl documents its commands in section "n", and so we will follow suit.

Section i: Tcl interfaces
This is a new section, used to define standard Tcl interfaces that are shared by many different objects.

Most man pages written with manpage(5) will fit into one of these sections; however, manpage(n) allows the client to define additional sections as needed.

Also by convention, man pages have a short name, usually followed by section number in parentheses. Thus, "manpage(5)" is the "manpage" man page in section 5; it is the page that documents the "manpage" file format. manpage(n), on the other hand, documents the "manpage" module that produces formatted HTML output from manpage(5) input.

Directory Layout

manpage(n) can create links to the other man pages defined in the same project, provided that the following directory tree is used for all man pages:

That is, there are sibling subdirectories for each section called man1, man5, mann, and mani respectively.

Man Page Names and Files

Further, manpage(n) assumes that each man page file has the same bare file name as its man page name. For example, this man page is manpage(5). The source for this page is docs/man5/manpage.manpage, and the formatted page is docs/man5/manpage.html.

Man Page Sections

Each man page is divided into sections, and possibly into subsections, using the <section> and <subsection> macros. The standard sections are as follows:

SYNOPSIS
A brief statement of the calling sequence of the application (section 1) or library (section n), possibly followed by a list of Man Page Items defined in the man page.

DESCRIPTION
An overview of the documented command, format, or library, possibly with subsections describing its background or use.

COMMANDS
For section n, Tcl commands defined by the man page.

BUGS
Any known bugs.

HISTORY
The module's history.

AUTHOR
The man page/module's author.

SEE ALSO
Links to related man pages and other documents.

Other sections may be defined as needed.

Man Page Items

A single man page will often document a series of "items". A section n man page will document the Tcl commands in a library, for example, and this man page documents a collection of MACROS used to write man pages. Items are documented in definition lists using the <deflist> macro; each item in a definition list is defined using the <defitem> macro. Each <defitem> macro is followed by prose documenting the item. Finally, each definition list is concluded by a </deflist> macro.

Cross-References

The <xref> macro creates cross-reference links to sections within the same manpage or to other manpages or, in fact, to arbitrary web pages. Cross-reference links may be specified in a number of ways.
#section
#item
References a section or subsection, given its title, or an item, given its name, within the current man page. E.g., "#DESCRIPTION" or "#xref".

name(sec)
References the named man page, e.g., "manpage(5)"

name(sec)#section
name(sec)#item
References a section by its title or an item by its name within the named man page. E.g., "manpage(5)#DESCRIPTION" or "manpage(5)#xref".

url
References a web page by its URL. E.g., "http://example.com".

Man Page Skeleton

A man page file defines a single man page.

Each man page file begins with a <manpage> macro which names and titles the man page. This is followed by one or sections and subsections, each introduced by the <section> or <subsection> macro. The "SYNOPSIS" section will frequently contain an <itemlist> macro, which expands to a list of links to each of the items defined in the body of the web page.

Other sections may contain definition lists, which define one or more items (i.e, commands, macros, etc.). Each definition list begins with a <deflist> macro and ends with a </deflist> macro; individual items begin with the <defitem> macro, followed by prose which documents the item.

Prose may contain cross-references, defined using the <xref> macro.

Each man page file ends with the </manpage> macro.

MACROS

manpage(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.
<manpage name title ?parent?>...</manpage>
These macros should be the first and last to appear in every man page file. The name is the man page's name, e.g., "listutils(n)". The title is a short description of the documented module. For example,

<manpage quilldoc(5) "Quill Document Syntax">

If the documented module is part of a larger package, then parent should be the name of that package's overall man page.

<manpage listutils(n) "List Manipulation Commands" quill(n)>

<section title>
Defines a major section within the man page; the section title will be added to the table of contents, and can be used as an <xref> reference. By convention, section titles are in ALL CAPS. For example,

<section DESCRIPTION>
    ...
<section "SEE ALSO">
    ...

<subsection title>
Defines a subsection of a major section. The subsection title will be added to the table of contents, and can be used as an <xref> reference. By convention, subsection titles are in Mixed Case. For example,

<section DESCRIPTION>
    ...
<subsection "The Specifics">
    ...

Definition List Extensions

Definition lists are the primary means of documenting items of code: Tcl commands and subcommands, macros, and anything else. They display an item in bold, left-justified, followed by one or more indented paragraphs describing the item.

The basic definition list macros, <deflist> and </deflist> are defined in macroset_html(n). manpage(5) extends the basic set with two new macros, one for defining entities (i.e., commands) that should appear in the man page's "SYNOPSIS" section, and one for defining lists of options.

<defitem name text>
Defines an item to be included in the "SYNOPSIS" section. The name is the item's name, by which it will be linked. In a list of commands, for example, name is the command name. The text is the complete representation of the item. For a command, text would be the signature of the command. For example,

<deflist>
...
<defitem mycommand {mycommand <i arg1>}>
...
</deflist>
Tcl conventions are followed for command signatures. Literal text is in normal type, dummy arguments are in italics, optional arguments are bracketed by question marks, and arguments which can be repeated include "...".

<defopt option text>
Begins the documentation of an option in a definition list of options. For example,

<deflist>
...

<defopt -myoption {-myoption <i value>}>
...
</deflist>
At present options are not listed in the <itemlist>, but that may change in the future.

<itemlist>
This macro returns a list of links to the items defined in the page. It's usually placed in the "SYNOPSIS" section.

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, if ref explicitly names an anchor, i.e., a section title or item name, the anchor is used; otherwise, the page name is used.

This reference links to the named man page, and uses the man page name as the link text:

<xref manpage(1)>
This reference links to the "COMMANDS" section and uses the section title as the link text:

<xref #COMMANDS>
This reference links to the "xref" item in "manpage(5)", and uses the item name as the link text:

<xref manpage(5)#xref>
This reference links to the "xref" item, but uses "cross-reference" as the link text:

<xtag xref "cross-reference">

<xtag name>
Creates a cross-reference to an item defining a macro, in man pages (like this one) that define macros.

Other Macros

manpage(5) provides a number of other macros.

<tag name ?text?>
The <tag> macro is provided for use in man pages that define macros. It expands to the macro as it would appear in manpage(5) input. The text, if included, represents macro arguments and may contain macros for expansion.

<version>
Returns the version number string given to the manpage(n) object's format subcommand.

BUGS

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


Generated from manpage.manpage on Sat Nov 08 09:38:04 PST 2014