doctools is similar to LaTeX. Input written in this format consists primarily of text, with markup commands embedded into it. The format used to mark commands is different from LaTeX however. All text between matching pairs of [ and ] is a command, possibly with arguments. Note that both brackets have to be on the same line for a command to be recognized.

In contrast to both doctoc and docidx this format does allow arbitrary text between markup commands. Only some places are restricted to only white space.

The overall syntax of a manpage is best captured in a formal context-free grammar. Our notation for the grammar is EBNF. Strings will stand for markup commands, however their arguments (if they have any) are not part of the grammar. Our grammar contains lexical elements as well.

First we specify the whitespace and other text at the lexical level, which also includes comments.

    COMMENT  ::= "comment"
    WHITE    ::= { '\n' | '\t' | ' ' | '\r' | COMMENT }
    TEXT     ::= { All characters except '[' }

Then we define rules for all the keywords. Here we introduce our knowledge that some commands allow only whitespace after them.

    BEGIN      ::= "manpage_begin" WHITE
    END        ::= "manpage_end"
    TITLE      ::= "titledesc"     WHITE
    MODULE     ::= "moddesc"       WHITE
    REQUIRE    ::= "require"       WHITE
    COPYRIGHT  ::= "copyright"     WHITE
    DESC       ::= "description"

SECTION ::= "section" SUBSEC ::= "subsection" PARA ::= "para" NL ::= "nl" SEE_ALSO ::= "see_also" KEYWORDS ::= "keywords"

ARG ::= "arg" CMD ::= "cmd" OPT ::= "opt" EMPH ::= "emph" STRONG ::= "strong" SECTREF ::= "sectref" USAGE ::= "usage" SYSCMD ::= "syscmd" METHOD ::= "method" NAMESPACE ::= "namespace" OPTION ::= "option" WIDGET ::= "widget" FUN ::= "fun" TYPE ::= "type" PACKAGE ::= "package" CLASS ::= "class" VAR ::= "var" FILE ::= "file" URI ::= "uri" TERM ::= "term" CONST ::= "const" LB ::= "lb" RB ::= "rb" EX_BEGIN ::= "example_begin" EX_END ::= "example_end" EXAMPLE ::= "example"

LIST_BEGIN ::= "list_begin" WHITE LIST_END ::= "list_end" LIST_ITEM ::= "lst_item" BULLET ::= "bullet" ENUM ::= "enum" CALL ::= "call" ARGDEF ::= "arg_def" OPTDEF ::= "opt_def" CMDDEF ::= "cmd_def" TKODEF ::= "tkoption_def"

INCLUDE ::= "include" VSET ::= "vset" DEFUN ::= { INCLUDE | VSET } At last we can specify the whole manpage. Here we introduce our knowledge that inclusion of other files may happen essentially everywhere, like the definition of document variables and comments. The content of any included file has to fit into the including file according to the location in the grammar the inclusion is at.

    MANPAGE      ::= DEFUN BEGIN HEADER DESC BODY END

HEADER ::= { TITLE | MODULE | COPYRIGHT } { REQUIRE } BODY ::= REGULAR_TEXT { SECTION SECBODY } SECBODY ::= REGULAR_TEXT { SUBSEC SUBSECBODY } SUBSECBODY ::= REGULAR_TEXT

REGULAR_TEXT ::= TEXT_CHUNK { PARA TEXT_CHUNK } TEXT_CHUNK ::= { TEXT | DEFUN | XREF | MARKUP | COMMENT | A_LIST | AN_EXAMPLE }

A_LIST ::= LIST_BEGIN { ( LIST_ITEM | CALL ) LIST_TEXT } LIST_END | LIST_BEGIN { BULLET LIST_TEXT } LIST_END | LIST_BEGIN { ENUM LIST_TEXT } LIST_END | LIST_BEGIN { ARGDEF LIST_TEXT } LIST_END | LIST_BEGIN { OPTDEF LIST_TEXT } LIST_END | LIST_BEGIN { CMDDEF LIST_TEXT } LIST_END | LIST_BEGIN { TKODEF LIST_TEXT } LIST_END

LIST_TEXT ::= TEXT_CHUNK { NL TEXT_CHUNK }

AN_EXAMPLE ::= EXAMPLE | EX_BEGIN EXAMPLE_TEXT EX_END EXAMPLE_TEXT ::= { TEXT | DEFUN | MARKUP }

MARKUP ::= { BRACKETS | SEMANTIC }

XREF ::= SEE_ALSO | KEYWORDS BRACKETS ::= LB | RB SEMANTIC ::= ARG | EMPH | CLASS | STRONG | OPTION | CMD | TYPE | CONST | METHOD | SECTREF | OPT | TERM | FUN | SYSCMD | PACKAGE | VAR | FILE | USAGE | WIDGET | NAMESPACE | URI

Here we specify the commands used in the grammar. Some commands specified here were not used in the grammar at all. The usage of these commands is confined to the arguments of other commands.

comment text

The command declares that the argument text is a comment.

include filename

This command loads the contents of the file filename for processing at its own place.

vset varname value

This form of the command sets the document variable varname to the specified value. It does not generate output.

vset varname

This form of the command returns the value associated with the document variable varname.

lb

This command adds a left bracket to the output. Note that the bracket commands are necessary as plain brackets are used to begin and end the formatting commands.

rb

This command adds a right bracket to the output. Note that the bracket commands are necessary as plain brackets are used to begin and end the formatting commands.

manpage_begin command section version

This is the command to start a manpage. The arguments are the name of the command described by the manpage, the section of the manpages this manpage resides in, and the version of the module containing the command.

manpage_end

This is the command to close a manpage.

moddesc desc

This command is optional. When used it will register its argument desc as a short description of the module the manpage resides in.

titledesc desc

This command is optional. When used it will register its argument desc as the title of the manpage. When not used the information from moddesc will be used for the title as well.

copyright text

This command is optional. When used its argument text will declare a copyright assignment for the manpage. When invoked more than once the assignments are accumulated. A doctools processor application (like dtplite) is allowed to provide such information too, but a formatting engine has to give the accumulated arguments of this command precedence over the data coming from the application.

description

This is the command to separate the header part of the manpage from the main body.

require pkg ?version?

This is the command to list the packages which are required by an application or other library to import the described package and its prerequisites.

section name

This is the command to partition the body of the manpage into named sections. Note that the command description at the beginning of the manpage body implicitly starts a section named "DESCRIPTION". A section command implicitly closes the last paragraph coming before it and also implicitly opens the first paragraph of the new section.

subsection name

This is the command to partition the body of a section into named sub-sections. A subsection command implicitly closes the last paragraph coming before it and also implicitly opens the first paragraph of the new section.

para

This is the command to partition the text in a section or sub-section into paragraphs. Each invokation closes the paragraph coming before it and opens a new paragraph for the text coming after.

see_also args

This is the command to define direct cross-references to other documents. Each argument is a label identifying the referenced document. If this command is used multiple times all the arguments accumulate.

keywords args

This is the command to define the keywords applying to this document. Each argument is a single keyword. If this command is used multiple times all the arguments accumulate.

arg text

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

cmd text

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

opt text

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

    [arg foo]
        A regular argument.

[opt [arg foo]] An optional argument.

emph text

Emphasize the text.

strong text

Emphasize the text. Same as emph. Usage of this command is discouraged. The command is deprecated and present only for backward compatibility.

sectref text ?label?

Declares that the argument text is the name of a section somewhere else in the document, and the current location should refer to it. Without an explicit label for the reference within the text the section title text is used.

syscmd text

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

method text

Declares that the argument text is the name of an object method.

namespace text

Declares that the argument text is the name of a namespace.

option text

Declares that the argument text is the name of an option.

widget text

Declares that the argument text is the name of a widget.

fun text

Declares that the argument text is the name of a function.

type text

Declares that the argument text is the name of a data type.

package text

Declares that the argument text is the name of a package.

class text

Declares that the argument text is the name of a class.

var text

Declares that the argument text is the name of a variable.

file text

Declares that the argument text is a file .

uri text ?text?

Declares that the argument text is an uri. The second argument, if it is present, is the human-readable description of the uri. In other words, the label for the link. Without a labeling text the uri is used as its own label.

term text

Declares that the argument text contains some unspecific terminology.

const text

Declares that the argument text is a constant value.

nl

This command signals vertical space to separate blocks of text.

example_begin

This command begins an example block. Subsequent text belongs to the example. Line breaks, spaces, and tabs have to be preserved literally.

example_end

This command closes the example block.

example text

This command wraps its argument text into an example. In other words, it is a simpler form of markup for the creation of an example. It should be used if the example text does not need need special markup.

list_begin what

This command starts new list. The value of the argument what determines what type of list is opened. This also defines what command has to be used to start an item in the new list. The allowed types (and their associated item commands) are:

bullet

bullet

enum

enum

definitions

lst_item and call

arg

arg_def

cmd

cmd_def

opt

opt_def

tkoption

tkoption_def

list_end

This command ends the list opened by the last list_begin.

bullet

This command starts a new list item in a bulletted list. The previous item is automatically closed.

enum

This command starts a new list item in an enumerated list. The previous item is automatically closed.

lst_item text

This command starts a new list item in a definition list. The argument is the term to be defined. The previous item is automatically closed.

call args

This command starts a new list item in a definition list, but the term defined by it is a command and its arguments. The previous item is automatically closed. The first argument is the name of the described command, and everything after that are descriptions of the command arguments.

arg_def type name ?mode?

This command starts a new list item in an argument list. The previous item is automatically closed. Specifies the data-type of the described argument, its name and its i/o-mode. The latter is optional.

opt_def name ?arg?

This command starts a new list item in an option list. The previous item is automatically closed. Specifies the name of the option and its arguments (arg). The latter is a list, and can be left out.

cmd_def command

This command starts a new list item in a command list. The previous item is automatically closed. Specifies the name of the command.

tkoption_def name dbname dbclass

This command starts a new list item in a widget option list. The previous item is automatically closed. Specifies the name of the option, i.e. the name used in scripts, the name used by the option database (dbname), and the class (type) of the option (dbclass).

usage args

This command is like call, except that a formatting engine must not generate output at the location of the command. In other words, this command is silent. The data it defines may appear in a different section of the output, for example a table of contents, or synopsis, depending on the formatting engine and its output format.