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
<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>
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).
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.
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:
- docRoot/man1/
- docRoot/man5/
- docRoot/mann/
That is, there are sibling subdirectories for each section called
man1, man5, mann, and mani respectively.
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.
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.
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.
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".
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.
manpage(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.
- <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 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.
- <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.
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.
- Section titles and item names are in the same namespace, and so
can conflict. As item names are usually lower case and titles
are usually mixed case with initial caps, this isn't generally
a problem.
- <defopt> options are not included in the itemlist.
- <defopt> options cannot be linked to!
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(n).
Generated from manpage.manpage on Sat Nov 08 09:38:04 PST 2014