'\"
'\" Copyright (c) 2000 Andreas Kupries
'\" All right reserved
'\"
'\" CVS: $Id$ manpages.n
'\"
.so man.macros
.TH "manpages" n ?.? manpages "Manpage generation"
.BS
'\" Note: do not modify the .SH NAME line immediately below!
.SH NAME
manpages \- Generate manpage from tcl markup
.SH "SYNOPSIS"
\fBmanpage_begin\fR \fIcommand\fR \fIsection\fR \fIversion\fR \fImodule\fR \fIshortdesc\fR \fIdescription\fR\fR
.sp
\fBmanpage_end\fR \fR
.sp
\fBdescription\fR \fR
.sp
\fBrequire\fR \fIpkg\fR ?\fIversion\fR?\fR
.sp
\fBsection\fR \fIname\fR\fR
.sp
\fBpara\fR \fR
.sp
\fBsee_also\fR \fIargs\fR\fR
.sp
\fBkeywords\fR \fIargs\fR\fR
.sp
\fBarg\fR \fItext\fR\fR
.sp
\fBcmd\fR \fItext\fR\fR
.sp
\fBopt\fR \fItext\fR\fR
.sp
\fBemph\fR \fItext\fR\fR
.sp
\fBstrong\fR \fItext\fR\fR
.sp
\fBnl\fR \fR
.sp
\fBlist_begin\fR \fIwhat\fR\fR
.sp
\fBlist_end\fR \fR
.sp
\fBbullet\fR \fR
.sp
\fBenum\fR \fR
.sp
\fBlst_item\fR \fItext\fR\fR
.sp
\fBcall\fR \fIargs\fR\fR
.sp
.BE
.SH "DESCRIPTION"
.PP
This manpage actually does not belong into the memchan package. It is
here only because the format was developed while working on the
\fBmemchan\fR documentation, i.e. manpages. It specifies
.IP [1]
The overall format of manpages using this markup, and
.IP [2]
the tcl commands used as the markup
.PP
The manpage format described here simpler than TMML, but convertible
into it (and other formats, like HTML and nroff).
.PP
The tcl sources of this manpage can serve as an example for all of the
markup described by it. Every possible construct is used here.
.SH "OVERVIEW"
.TP
*
The main commands are \fBmanpage_begin\fR, \fBmanpage_end\fR and
\fBdescription\fR. All three are required for a manpage. The first two
are the first and last commands in a manpage. Neither text nor other
commands may precede \fBmanpage_begin\fR nor follow \fBmanpage_end\fR.
The command \fBdescription\fR separates header and body of the manpage
and may not be omitted.
.TP
*
The only text allowed between \fBmanpage_begin\fR and
\fBdescription\fR is the command \fBrequire\fR. Other commands or
normal text are not permitted. \fBrequire\fR is used to list the
packages the described command(s) depend(s) on for its operation. This
list can be empty.
.TP
*
After \fBdescription\fR text and all other commands are allowed. The
text can be separated into highlevel blocks using named
\fBsection\fRs.  Each block can be further divided into paragraphs via
\fBpara\fR.
.TP
*
The commands \fBsee_also\fR and \fBkeywords\fR define whole sections
named \fISEE ALSO\fR and \fIKEYWORDS\fR. They can occur everywhere
in the manpage but making them the last section is the usual thing to
do. They can be omitted.
.TP
*
There are five commands available to markup words, \fBarg\fR,
\fBcmd\fR, \fBopt\fR, \fBemph\fR and \fBstrong\fR. The first three are
used to mark words as \fIcommand arguments\fR, as
\fIcommand names\fR and as \fIoptional\fR. The other two are visual
markup to emphasize words in two different ways. The term \fIwords\fR
is used in a loose sense here, i.e application of the commands to a
sequence of words is entierely possible, if they are properly quoted.
.TP
*
Another set of six commands is available to construct (possibly
nested) lists. These are \fBlist_begin\fR, \fBlist_end\fR,
\fBlst_item\fR, \fBbullet\fR, \fBenum\fR and \fBcall\fR.  The first
two of these begin and end a list respectively.
.sp
The argument to the first command is either \fIbullet\fR, \fIenum\fR
or \fIdefinitions\fR denoting the type of the list (unordered
vs. ordered vs. definition list).
.sp
The other commands start list items and each can be used only inside a
list of their type. In other words, \fBbullet\fR is allowed in
bulleted lists but nowhere else, \fBenum\fR in enumerated lists and
\fBlst_item\fR and \fBcall\fR are for definition lists. The last two
commands also have some text directly associated with the item
although the major bulk of the item is the text following the item
until the next list command.
.sp
The last list command, \fBcall\fR is special. It is used to describe
the syntax of a command and its arguments. It should not only cause
the appropriate markup of a list item at its place but also add the
syntax to the table of contents (synopsis) if supported by the output
format in question. nroff and HTML for example do. A format focused on
logical markup, like TMML, may not.
.SH "Commands"
.TP
\fBmanpage_begin\fR \fIcommand\fR \fIsection\fR \fIversion\fR \fImodule\fR \fIshortdesc\fR \fIdescription\fR\fR
This command begins a manpage. Nothing is allowed to precede
it. Arguments are the name of the command described by the manpage,
the section of the manpages this manpages lives in, the version of the
module containing the command, the nbame of the module itself and two
descriptions, one short for the command and one a bit longer for the
module. Both have to fit on one line.
.TP
\fBmanpage_end\fR \fR
This command closes a manpage. Nothing is allowed to follow it.
.TP
\fBdescription\fR \fR
This command separates the header part of the manpage from the main
body. Only \fBrequire\fR may precede it.
.TP
\fBrequire\fR \fIpkg\fR ?\fIversion\fR?\fR
May occur only between \fBmanpage_begin\fR and \fBdescription\fR. Is
used to list the packages which are required for the described command
to be operational.
.TP
\fBsection\fR \fIname\fR\fR
Used to structure the body of the manpage into named sections.
.TP
\fBpara\fR \fR
Used to structure sections into paragraphs.
.TP
\fBsee_also\fR \fIargs\fR\fR
Creates a section \fISEE ALSO\fR containing the arguments as
cross-references.
.TP
\fBkeywords\fR \fIargs\fR\fR
Creates a section \fIKEYWORDS\fR containing the arguments as words
indexing the manpage.
.TP
\fBarg\fR \fItext\fR\fR
Declares that the marked text is the name of a command argument.
.TP
\fBcmd\fR \fItext\fR\fR
Declares that the marked text is the name of a command.
.TP
\fBopt\fR \fItext\fR\fR
Declares that the marked text is something optional. Most often used
in conjunction with \fBarg\fR to denote optional command arguments.
.TP
\fBemph\fR \fItext\fR\fR
One way to emphasize text in a general manner.
.TP
\fBstrong\fR \fItext\fR\fR
Another way to emphasize text in a general manner.
.TP
\fBnl\fR \fR
Vertical space to separate text without breaking it into a new
paragraph.
.TP
\fBlist_begin\fR \fIwhat\fR\fR
Starts new list of type \fIwhat\fR. Allowed types are \fIbullet\fR,
\fIenum\fR and \fIdefinitions\fR.
.TP
\fBlist_end\fR \fR
Ends the list opened by the last \fBlist_begin\fR.
.TP
\fBbullet\fR \fR
Starts a new item in a bulleted list.
.TP
\fBenum\fR \fR
Starts a new item in an enumerated list.
.TP
\fBlst_item\fR \fItext\fR\fR
Starts a new item in a definition list. The argument is the term to be
defined.
.TP
\fBcall\fR \fIargs\fR\fR
Starts a new item in a definition list, but the term defiuned by it is
a command and its arguments.
.SH "KEYWORDS"
manpage, TMML, HTML, nroff, conversion, markup