1Specification of the API a manpage/tcl has to conform to so that rule
2files are able to process it properly.
3======================================================================
4
5The available commands are listed in the file 'manpage.api' too.  The
6definitions in that file return errors. They should be loaded before
7the actual definitions so that usage of an unimplemented command
8causes a proper error message.
9
10----------------------------------------------------------------------
11
12The main commands are "manpage_begin", "manpage_end" and
13"description". All three are required. The first two are the first and
14last commands in a manpage. Neither text nor other commands may
15precede "manpage_begin" nor follow "manpage_end". The command
16"description" separates header and body of the manpage and may not be
17omitted.
18
19The only allowed text between "manpage_begin" and "description" is the
20command "require". Other commands or normal text are not
21permitted. "require" is used to list the packages the described
22command(s) depend(s) on for its operation. This list can be empty.
23
24After "description" text all other commands are allowed. The text can
25be separated into highlevel blocks using named "section"s. Each block
26can be further divided into paragraphs via "para".
27
28The commands "see_also" and "keywords" define whole sections named
29"SEE ALSO" and "KEYWORDS". They can occur everywhere in the manpage
30but making them the last section is the usual thing to do. They can be
31omitted.
32
33There are four commands available to mark words, "arg", "cmd", "emph"
34and "strong". The first two are used to mark words as command
35arguments and as command names. The other two are visual markup to
36emphasize words.
37
38Another set of four commands is available to construct (nested)
39lists. These are "list_begin", "list_end", "lst_item" and "call".  The
40first two of these begin and end a list respectively. The argument to
41the first command is either 'bullet' or 'enum' denoting the type of
42the list (unordered vs. ordered). The third command starts list
43items. Each item has some text directly associated with the bullet but
44the major bulk of the item is the text following the item until the
45next list command.
46
47The last list command, "call" is special. It is used to describe the
48syntax of a command and its arguments. It should not only cause the
49appropriate markup of a list item at its place but also add the syntax
50to the table of contents (synopsis) if supported by the output format
51in question. nroff and HTML for example do. A logical format like TMML
52doesn't.
53
54
55I currently use the ?...? notation in my example to mark optional
56arguments. This should better be done through a command. This command
57is "opt". _Not_ "optarg" as it may span several arguments.
58
59======================================================================
60
61   [list_begin "bullet"] --
62    	Starts a bulleted (unordered) list.
63    [bullet] --
64    	Starts a new item in a bulleted list.
65
66    [list_begin "enum"] --
67    	Starts a numbered list.
68    [enum] --
69    	Starts a new item in a numbered (ordered) list.  Successive list
70	items are numbered [1], [2],  ... etc.
71
72    [list_begin "definitions"] --
73    	Starts a definition list.
74    [lst_item _text_] --
75    	Starts a new entry in a definition list.  _text_ is
76	the list item header.
77
78    [list_begin commands] --
79    	Starts a command list, for describing the syntax of a
80	command and its arguments.
81    [call _cmd_ ? _arg_ _arg_ ... ? ] --
82    	Starts an entry in a command list.  In addition, adds the
83	command syntax summary "_cmd_ _args_..." to the SYNOPSIS section.
84