TMML - Tcl Manual Markup Language: TMML

SYNOPSIS

<manpage id="id" cat="category" package="package">
...
</manpage>

<manual package="package">
...
</manual>

DESCRIPTION

TMML is an XML document type designed for for the documentation of Tcl, Tk and Tcl extensions.

MANPAGE STRUCTURE

Element name	Content Model
manpage	(namesection, synopsis?, section+, seealso?, keywords?)
Top-level element for a manual page
namesection	(name+, desc)
The ``NAME'' section of the manual page
synopsis	(syntax)
The ``SYNOPSIS'' section of the manual page
seealso	(ref\|url)+
The ``SEE ALSO'' section of the manual page
keywords	(keyword+)
The ``KEYWORDS'' section of the manual page
keyword	(#PCDATA)
A single keyword
section	(title, %m.top;, (subsection*))
General manual page section
subsection	(title, %m.top;)
Subsections, or second-level sections

The manpage element has the following attributes:

A unique identifier for the manual entry. For technical reasons, this should always be the same as the filename without the extension.

title

A short title for the manpage. Typically it is the name of the main command or function being defined; or, if the manpage defines multiple entities, the first of these.

cat

The manpage category; see SEMANTIC CATEGORIES below.

package

The name of the package to which this manpage belongs.

version

See VERSION IDENTIFICATION, below.

@@ Describe conventional manpage headings

COMMON CONSTRUCTS

Common Elements

Element name	Content Model
name	(#PCDATA)
The defining instance of a name.
desc	%m.mixed;
General-purpose description element.
title	(#PCDATA)
The title of a manual, section, subsection, or other structural element.

The name element is used in several contexts, including the namesection in optiondefs, argdefs, et cetera. It has the usual classification attributes, cat and name; these are rarely needed, as the category is typically determined from context and the name being defined is the content of the element.

Common Attributes

version

cat

Content Models

%m.inline;

Used for ``inline text,'' such as the content of a paragraph.

%m.code;

A restricted subset of %m.inline;, containing only the elements which are legal inside elements which designate Tcl or C code such as samp, syntax, example, et cetera.

%m.top;

Allows only ``block-level'' elements such as paragraphs and lists:

%m.mixed;

@@ Describe

BLOCK-LEVEL ELEMENTS

TMML includes many familiar structural elements from HTML 2.0.

Element name	Content Model
p	%m.inline;
Paragraphs
ol	(li)+
Ordered (numbered) lists
ul	(li)+
Unordered (bulleted) lists
sl	(li)+
``Simple'' lists; similar to an HTML 2.0 menu element
li	%m.mixed;
List items
dl	((dle+)
Definition lists
dle	((dt+, dd)+)
Definition list entries
dt	%m.inline;
A defined term in a definition list
dd	%m.mixed;
The definition of a term in a definition list
xl	(xlh, xle+)
Extended list; may be used for tabular data
xlh	(xh+)
Extended list heading
xh	%m.inline;
Extended list heading entry
xle	(xt+, desc?)
Extended list entry
xt	%m.inline;
Extended list term
example	%m.code;
Multi-line, displayed code sample
syntax	%m.code;
Used for the formal definitions of a terms

In addition to the HTML-style list-generating elements ol and ul TMML includes an sl (``simple'' or ``short'' list) element. This is used for short lists of names or identifiers (for example, the list of math functions in the expr(n) manpage). It takes two attributes, both optional:

cols

Suggested number of columns for multi-column display

cat

Category of elements in the list.

The dl or ``definition list'' element is different from the HTML element of the same name in that dt / dd pairs must be enclosed in a dle ``wrapper'' element. Also, TMML allows multiple dts to be associated with a single dd.

The xl or ``extended list'' element may be used for multi-column or tabular data. It is similar to a dl list except that each member of the list may have several associated terms. Typically, each term (xt) will appear in a separate column, with the description (desc) formatted as a block below the terms. Each xle element must contain the same number of xt children, and if an xlh element (which specifies a column heading for each of the terms) it must have the same number of xh children.

The example and syntax elements are similar to the HTML PRE element. in that all whitespace (including line breaks) are honored. example should be used for code samples, and syntax should be used for formal definitions. @@ describe syntax attributes cat, name, and scope.

INLINE ELEMENTS

Element name	Content Model
emph	%m.inline;
Emphasized text
samp	%m.code;
Sample code, presented inline. See also the example element
command	%m.code;
A command or multi-word command prefix.
ref	(#PCDATA)
A cross reference. See CROSS-REFERENCES, below.
url	(#PCDATA)
A URL
b	%m.inline;
Boldface
i	%m.inline;
Italics
o	%m.code;
Denotes an optional part of a command. By convention, in Tcl documentation optional text is indicated by enclosing it in question marks (`?`).
term	(#PCDATA)
generic element for terms
cmd	(#PCDATA)
Tcl commands, e.g., set
method	(#PCDATA)
Subcommands or methods, e.g., cget
option	(#PCDATA)
Command options or switches, e.g, -nocase
syscmd	(#PCDATA)
System commands, e.g., tclsh
file	(#PCDATA)
A file or directory name
widget	(#PCDATA)
Tk Widgets, e.g., listbox
fun	(#PCDATA)
C functions, e.,g, Tcl_EvalObjEx
variable	(#PCDATA)
Global variables, e.g., ::errorInfo
package	(#PCDATA)
Package names, e.g., Tk
type	(#PCDATA)
Type names, e.g., Tcl_DString
class	(#PCDATA)
The name of a class or interface, for example in C++, [incr Tcl], or other object extensions
m	(#PCDATA)
metasyntactic variable; often used in command synopses
l	(#PCDATA)
literal text

The character-level formatting elements b and i should not generally be used; in most cases one of the phrase-level semantic elements will be more appropriate.

TCL-SPECIFIC ELEMENTS

The ``ARGUMENTS'' section of manpages in section 3 (``library routines'', or TMML category fun) should consist of a single arglist element, which has an entry for each function argument listed in the ``SYNOPSIS'' section.

Element name	Content Model
arglist	(argdef+)
A list of argument descriptions.
argdef	(argtype, name, argmode, desc)
Definition of a single argument.
argtype	(#PCDATA)
The (C language) argument type;
argmode	(#PCDATA)
Specifies the ``mode'' or ``direction'' of the argument. Must be one of `in`, `out`, or `in/out`.

Element name	Content Model
commandlist	(commanddef+)
Describes all of the subcommands or methods of a ``compound'' Tcl command
commanddef	(command,desc)
Description of a single method
command	%m.code;
The subcommand being defined. This should include the full command prefix along with any arguments and options, for example: <command> string match ? <option>-nocase</option> ? <m>pattern</m> <m>string</m> </command>
optlist	(optdef+)
A list of command options. NOTE: for widget options, use the optionlist instead.
optdef	(optname, optarg?, desc)
Definition of a command option.
optname	(#PCDATA)
The option name, e.g., `-foo`
optarg	(#PCDATA)
(optional) replaceable text representing the option's argument

Tk widget manpages (TMML category widget) typically have a section named ``WIDGET-SPECIFIC OPTIONS''; this should contain a single optionlist element.

Element name	Content Model
optionlist	(optiondef+)
List of all the widget-specific configuration options supported by the widget
optiondef	( name, dbname, dbclass, desc )
Describes a single configuration option
name	(#PCDATA)
The ``command-line name'' of the option; that is, the option as passed to a `pathName configure` or `pathName cget` method), including the leading dash.
dbname	(#PCDATA)
The database name of the option
dbclass	(#PCDATA)
The database class of the option

SEMANTIC CATEGORIES

The following categories are predefined;

cmd: Tcl commands
fun: C functions
syscmd: System commands
widget: Tk Widgets
stdopt: Standard widget options
package: Packages
method: Subcommands
option: Command options
variable: Global variables
type: C language types
class: Classes
option: Options
misc: Miscellaneous; this category should only be used for manpages.

This list is open-ended; authors may use their own category names for classes of terms that are not accounted for in the above list.

CROSS-REFERENCES

The ref element is a general-purpose element used to indicate cross-references. It accepts several attributes:

cat
href
manpage
name
package
refid

How the reference is resolved depends on which attributes are present:

If refid is present, then this is a reference to a specific TMML element with an id attribute equal to the specified value. The manpage and package attributes may be used to reference a location in another manpage or package.
If href is present, then this is a Web reference to the The href attribute value must be a legal URI.
If either or both of name or cat are present, then this is a reference to the definition of the specified name. If the name attribute is omitted then the ref element's textual content is used as the referent.

(@@ Here: explain how name resolution works: which elements introduce definitions, meaning of the scope attribute, etc...)

VERSION INFORMATION

Element name	Content Model
new	%m.inline;
Used to mark additions or changes to a document

version

The version of the package in which the change was introduced

The version attribute may be used to indicate changes to a package. The value of the attribute should be the version of the package in which the change was introduced, optionally preceded by the package name. The version attribute can appear on most definitional elements.

On a manual element, version should indicate the current version of the package. On a manpage, it should indicate the version of the package in which the manual page was first introduced, not when it was most recently changed.

Use the new element to mark up changes within a paragraph or other block-level element.

COLLECTIONS OF MANPAGES

Element name	Content Model
manual	(title, (division* \| (manpage \| subdoc \| extref)*))
Container for all the of manpages in a package
division	(title, (division* \| (manpage \| subdoc \| extref)*))
Used to divide a large manual into sections
subdoc	EMTPY
Used to include a TMML manpage by reference. The mandatory href attribute specifies the location of the manpage.
extref	(#PCDATA)
Reference to a manual page that is written in a format other than TMML. The mandatory href attribute specifies the location of the manual page.

The manual element is used to collect all of the individual manpages making up a package. It has one mandatory attribute, package, which gives the name of the package, and consists of a title element followed by a series of manpages or a list of divisions.

Typically, each manpage is stored in a separate XML file and manuals reference them with the subdoc element. It is also possible to use XML's entity reference mechanism to include manpages directly in the master document.

The extref element may be used inside manuals and divisions to identify documentation for a package that is not written in TMML. The href attribute is a URI specifying the location of the document, and the content of the element is used as the title.

<manual package="FOO">
<title>Sample manual</title>
<subdoc href="manpage1.xml" />
<subdoc href="manpage2.xml" />
</manual>

The division element may be used for large packages to arrange the individual manpages into sections. division has the same content model as manual: a title followed either by a list of manpages or a list of divisions. (That is, divisions are recursive.)

KEYWORDS

DTD, XML, manpage, manual