--- name: "doctools_fmt" section: "3tcl" platform: "linux" package: "tcllib" version: "1.8-1" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/doctools_fmt" --- # doctools\_fmt(3tcl) Specification of a simple Tcl Markup Language for Manpages ``` ``` ## NAME doctools\_fmt - Specification of a simple Tcl Markup Language for Manpages ## SYNOPSIS **comment** *text* **include** *filename* **vset** *varname* *value* **vset** *varname* **lb** **rb** **manpage\_begin** *command* *section* *version* **manpage\_end** **moddesc** *desc* **titledesc** *desc* **copyright** *text* **description** **require** *pkg* ?*version*? **section** *name* **subsection** *name* **para** **see\_also** *args* **keywords** *args* **arg** *text* **cmd** *text* **opt** *text* **emph** *text* **strong** *text* **sectref** *text* ?*label*? **syscmd** *text* **method** *text* **namespace** *text* **option** *text* **widget** *text* **fun** *text* **type** *text* **package** *text* **class** *text* **var** *text* **file** *text* **uri** *text* ?*text*? **term** *text* **const** *text* **nl** **example\_begin** **example\_end** **example** *text* **list\_begin** *what* **list\_end** **bullet** **enum** **lst\_item** *text* **call** *args* **arg\_def** *type* *name* ?*mode*? **opt\_def** *name* ?*arg*? **cmd\_def** *command* **tkoption\_def** *name* *dbname* *dbclass* **usage** *args* ``` ``` ## DESCRIPTION This document specifies version 1 of a text format for man pages. The name of this format is *doctools* and it provides all the necessary commands to write a manpage. It is complemented by both the *doctoc* format for writing tables of contents and the *docidx* format for writing keyword indices. The formal specifications for these two formats can be found in the companion documents *doctoc\_fmt* and *docidx\_fmt*. A third companion document describes the package **doctools**, which provides commands for the processing of text in *doctools* format. Like for the formats *doctoc* and *docidx* a generic framework for the conversion of *doctools* to any number of different output formats is provided. This framework is provided by the package **doctools**. Anyone who wishes to write a toc formatting engine which plugs into this framework has to read the document *doctools\_api*. This is the formal specification of the API between the framework and its engines. ## FORMAT SPECIFICATION ### OVERVIEW *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. ### GRAMMAR 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 ``` ### COMMANDS 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 **para**graph 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 **para**graph 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. ## EXAMPLE The sources of this manpage can serve as an example for all of the markup described by it. Almost every possible construct is used here. ## SEE ALSO docidx\_fmt, doctoc\_fmt, doctools, doctools\_api ## KEYWORDS HTML, LaTeX, TMML, generic markup, manpage, markup, nroff ## COPYRIGHT ``` Copyright (c) 2002-2004 Andreas Kupries ```