manpages(n) ?.? manpages "Manpage generation"

NAME

manpages - Generate manpage from tcl markup

SYNOPSIS

DESCRIPTION

This manpage actually does not belong into the memchan package. It is here only because the format was developed while working on the memchan documentation, i.e. manpages. It specifies

1. The overall format of manpages using this markup, and
2. the tcl commands used as the markup

The manpage format described here simpler than TMML, but convertible into it (and other formats, like HTML and nroff).

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.

OVERVIEW

• The main commands are manpage_begin, manpage_end and description. 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 manpage_begin nor follow manpage_end. The command description separates header and body of the manpage and may not be omitted.
• The only text allowed between manpage_begin and description is the command require. Other commands or normal text are not permitted. require is used to list the packages the described command(s) depend(s) on for its operation. This list can be empty.
• After description text and all other commands are allowed. The text can be separated into highlevel blocks using named sections. Each block can be further divided into paragraphs via para.
• The commands see_also and keywords define whole sections named SEE ALSO and KEYWORDS. They can occur everywhere in the manpage but making them the last section is the usual thing to do. They can be omitted.
• There are five commands available to markup words, arg, cmd, opt, emph and strong. The first three are used to mark words as command arguments, as command names and as optional. The other two are visual markup to emphasize words in two different ways. The term words 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.
• Another set of six commands is available to construct (possibly nested) lists. These are list_begin, list_end, lst_item, bullet, enum and call. The first two of these begin and end a list respectively.
  The argument to the first command is either bullet, enum or definitions denoting the type of the list (unordered vs. ordered vs. definition list).
  The other commands start list items and each can be used only inside a list of their type. In other words, bullet is allowed in bulleted lists but nowhere else, enum in enumerated lists and lst_item and call 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.
  The last list command, call 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.

Commands

manpage_begin command section version module shortdesc description

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.

manpage_end

This command closes a manpage. Nothing is allowed to follow it.

description

This command separates the header part of the manpage from the main body. Only require may precede it.

require pkg ?version?

May occur only between manpage_begin and description. Is used to list the packages which are required for the described command to be operational.

section name

Used to structure the body of the manpage into named sections.

para

Used to structure sections into paragraphs.

see_also args

Creates a section SEE ALSO containing the arguments as cross-references.

keywords args

Creates a section KEYWORDS containing the arguments as words indexing the manpage.

arg text

Declares that the marked text is the name of a command argument.

cmd text

Declares that the marked text is the name of a command.

opt text

Declares that the marked text is something optional. Most often used in conjunction with arg to denote optional command arguments.

emph text

One way to emphasize text in a general manner.

strong text

Another way to emphasize text in a general manner.

nl

Vertical space to separate text without breaking it into a new paragraph.

list_begin what

Starts new list of type what. Allowed types are bullet, enum and definitions.

list_end

Ends the list opened by the last list_begin.

bullet

Starts a new item in a bulleted list.

enum

Starts a new item in an enumerated list.

lst_item text

Starts a new item in a definition list. The argument is the term to be defined.

call args

Starts a new item in a definition list, but the term defiuned by it is a command and its arguments.

KEYWORDS