Manual Pages for UNIX Darwin command on man doctools

Manual Pages for UNIX Darwin command on man doctools_fmt

doctoolsfmt(n) Documentation tools doctoolsfmt(n)

NAME

doctoolsfmt - Specification of simple tcl markup for manpages

SYNOPSIS

vvsseett varname value vvsseett varname iinncclluuddee filename mmaannppaaggeebbeeggiinn command section version mmaannppaaggeeeenndd mmooddddeesscc desc ttiittlleeddeesscc desc ccooppyyrriigghhtt text ddeessccrriippttiioonn rreeqquuiirree pkg ?version? sseeccttiioonn name ppaarraa sseeeeaallssoo args kkeeyywwoorrddss args aarrgg text ccmmdd text oopptt text eemmpphh text ssttrroonngg text ccoommmmeenntt text sseeccttrreeff text ssyyssccmmdd text mmeetthhoodd text ooppttiioonn text wwiiddggeett text ffuunn text ttyyppee text ppaacckkaaggee text ccllaassss text vvaarr text ffiillee text uurrii text tteerrmm text ccoonnsstt text nnll llbb rrbb eexxaammpplleebbeeggiinn eexxaammpplleeeenndd eexxaammppllee text lliissttbbeeggiinn what lliisstteenndd bbuulllleett eennuumm llssttiitteemm text ccaallll args aarrggddeeff type name ?mode? ooppttddeeff name ?arg? ccmmddddeeff command ttkkooppttiioonnddeeff name dbname dbclass uussaaggee args

DESCRIPTION

This manpage specifies a documentation format for manpages. It is intended to complement both the ddooccttoocc format for writing tables of contents and the ddoocciiddxx format for writing indices. See ddooccttooccffmmtt and ddoocciiddxxffmmtt for the specification of these two formats. This format is called ddooccttoooollss. It provides all the necessary commands to write manpages. Like for the ddooccttoocc and ddoocciiddxx formats a package is

provided implementing a generic framework for the conversion of ddoocc-

ttoooollss to a number of different output formats, like HTML, TMML, nroff, LaTeX, etc. The package is called ddooccttoooollss, its documentation can be found in ddooccttoooollss. People wishing to write a formatting engine for the

conversion of ddooccttoooollss into a new output format have to read ddoocc-

ttoooollssaappii. This manpage will explain the interface between the generic package and such engines. OOVVEERRVVIIEEWW ddooccttoocc is similar to LaTex in that it consists primarily of text, with markup commands embedded into it. The format used to mark something as command 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 ddooccttoocc and ddoocciiddxx this format does allow plain text beyond white space. This plain text will be the contents of the described manpage. FFOORRMMAATTTTIINNGG CCOOMMMMAANNDDSS +o The main commands are mmaannppaaggeebbeeggiinn, mmaannppaaggeeeenndd, mmooddddeesscc, ttiittlleeddeesscc, and ddeessccrriippttiioonn. Four of these five are required for a manpage. The optional command is ttiittlleeddeesscc. The first two are the first and last commands in a manpage. Neither text nor other commands may precede mmaannppaaggeebbeeggiinn nor follow mmaannppaaggeeeenndd. The command ddeessccrriippttiioonn separates header and body of the manpage and may not be omitted.

The remaining commands (mmooddddeesscc and ttiittlleeddeesscc) provide one-line

descriptions of module and specific title respectively. +o The only text allowed between mmaannppaaggeebbeeggiinn and ddeessccrriippttiioonn is

the command rreeqquuiirree. Other commands or normal text are not per-

mitted. rreeqquuiirree is used to list the packages the described com-

mand(s) depend(s) on for its operation. This list can be empty. +o After ddeessccrriippttiioonn text and all other commands are allowed. The

text can be separated into highlevel blocks using named sseecc-

ttiioonns. Each block can be further divided into paragraphs via ppaarraa. +o The commands sseeeeaallssoo and kkeeyywwoorrddss 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. +o There are five commands available to markup words, aarrgg, ccmmdd, oopptt, eemmpphh and ssttrroonngg. 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. The term words is used in a loose sense here, i.e application of the commands to a sequence of words is entirely possible, if they are properly quoted. Note that usage of ssttrroonngg is discouraged as this command is deprecated and only present for backwards compatibility +o Another set of commands is available to construct (possibly nested) lists. These are lliissttbbeeggiinn, lliisstteenndd, llssttiitteemm, bbuulllleett, eennuumm, ccaallll, aarrggddeeff, ooppttddeeff, ccmmddddeeff, and ttkkooppttiioonnddeeff. The first two of these begin and end a list respectively. The argument to the first command denotes the type of the list. The allowed values and their associated item command are explained later, in the section detailing the CCoommmmaannddss. The other commands start list items and each can be used only inside a list of their type. In other words, bbuulllleett is allowed in bulletted lists but nowhere else, eennuumm in enumerated lists

and llssttiitteemm and ccaallll are for definition lists. These two com-

mands 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, ccaallll 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 sup-

ported by the output format in question. nroff and HTML for example do. A format focused on logical markup, like TMML, may not. +o The command uussaaggee is similar to ccaallll in that it adds the syntax to the table of contents (synopsis) if supported by the output format. Unlike ccaallll, this command doesn't add any text to the output as a direct result of the command. Thus, it can be used anywhere within the document to add usage information. Typically it is used near the top of the document, in cases where it is not desireable to use ccaallll elsewhere in the document, or where additional usage information is desired (e.g.: to document a "package require" command). CCoommmmaannddss vvsseett varname value Sets the formatter variable varname to the specified value. Returns the empty string. vvsseett varname

Returns the value associated with the formatter variable var-

name. iinncclluuddee filename Reads the file named filename, runs it through the expansion process and returns the expanded result. mmaannppaaggeebbeeggiinn command section version 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, and the ver-

sion of the module containing the command. All have to fit on one line. mmaannppaaggeeeenndd This command closes a manpage. Nothing is allowed to follow it. mmooddddeesscc desc This command is required and comes after mmaannppaaggeebbeeggiinn, but before either rreeqquuiirree or ddeessccrriippttiioonn. Its argument provides a

one-line description of the module described by the manpage.

ttiittlleeddeesscc desc This command is optional and comes after mmaannppaaggeebbeeggiinn, but before either rreeqquuiirree or ddeessccrriippttiioonn. Its argument provides a

one-line expansion of the title for the manpage. If this command

is not used the manpage processor has to use information from mmooddddeesscc instead. ccooppyyrriigghhtt text This command is optional and comes after mmaannppaaggeebbeeggiinn, but before either rreeqquuiirree or ddeessccrriippttiioonn. Its argument declares the copyright assignment for the manpage. When invoked more than once the assignments are accumulated. A doctools processor is allowed to provide auch information too, but a formatting engine has to give the accumulated arguments of this command precedence over the data coming from the processor. ddeessccrriippttiioonn This command separates the header part of the manpage from the main body. Only rreeqquuiirree, mmooddddeesscc, or ttiittlleeddeesscc may precede it. rreeqquuiirree pkg ?version? May occur only between mmaannppaaggeebbeeggiinn and ddeessccrriippttiioonn. Is used to list the packages which are required for the described command to be operational. sseeccttiioonn name Used to structure the body of the manpage into named sections. This command is not allowed inside of a list or example. It implicitly closes the last ppaarraagraph before the command and also implicitly opens the first paragraph of the new section. ppaarraa Used to structure sections into paragraphs. Must not be used inside of a list or example. sseeeeaallssoo args

Creates a section SEE ALSO containing the arguments as cross-

references. Must not be used inside of a list or example. kkeeyywwoorrddss args Creates a section KEYWORDS containing the arguments as words

indexing the manpage. Must not be used inside of a list or exam-

ple. aarrgg text Declares that the marked text is the name of a command argument. ccmmdd text Declares that the marked text is the name of a command. oopptt text Declares that the marked text is something optional. Most often

used in conjunction with aarrgg to denote optional command argu-

ments. eemmpphh text Emphasize the text. ssttrroonngg text

Emphasize the text. Same as eemmpphh. Usage is discouraged. The com-

mand is deprecated and present only for backward compatibility. ccoommmmeenntt text Declares that the marked text is a comment. sseeccttrreeff text Declares that the marked text is a section reference. ssyyssccmmdd text Declares that the marked text is a system command. mmeetthhoodd text Declares that the marked text is a object method. ooppttiioonn text Declares that the marked text is a option. wwiiddggeett text Declares that the marked text is a widget. ffuunn text Declares that the marked text is a function. ttyyppee text Declares that the marked text is a data type. ppaacckkaaggee text Declares that the marked text is a package. ccllaassss text Declares that the marked text is a class. vvaarr text Declares that the marked text is a variable. ffiillee text Declares that the marked text is a file . uurrii text Declares that the marked text is a uri. tteerrmm text Declares that the marked text is a unspecific terminology. ccoonnsstt text Declares that the marked text is a constant value. nnll Vertical space to separate text without breaking it into a new paragraph. llbb Introduces a left bracket into the output. rrbb Introduces a right bracket into the output. The bracket commands

are necessary as plain brackets are used to denote the begin-

nings and endings of the formatting commands. eexxaammpplleebbeeggiinn Formats subsequent text as a code sample: line breaks, spaces, and tabs are preserved and, where appropriate, text is presented

in a fixed-width font.

eexxaammpplleeeenndd End of a code sample block. eexxaammppllee text

Formats text as a multi-line block of sample code. text should

be enclosed in braces. lliissttbbeeggiinn what

Starts new list of type what. The allowed types (and their asso-

ciated item commands) are: bullet bbuulllleett enum eennuumm definitions llssttiitteemm and ccaallll arg aarrggddeeff cmd ccmmddddeeff opt ooppttddeeff tkoption ttkkooppttiioonnddeeff lliisstteenndd Ends the list opened by the last lliissttbbeeggiinn. bbuulllleett Starts a new item in a bulletted list. eennuumm Starts a new item in an enumerated list. llssttiitteemm text Starts a new item in a definition list. The argument is the term to be defined. ccaallll args Starts a new item in a definition list, but the term defined by it is a command and its arguments. aarrggddeeff type name ?mode?

Starts a new item in an argument list. Specifies the data-type

of the described argument, its name and possibly its i/o-mode.

ooppttddeeff name ?arg? Starts a new item in an option list. Specifies the name of the option and possible (i.e. optional) arguments. ccmmddddeeff command Starts a new item in a command list. Specifies the name of the command. ttkkooppttiioonnddeeff name dbname dbclass Starts a new item in a widget option list. Specifies the name of the option, i.e. the name used in scripts, name used by the option database, and the class (type) of the option. uussaaggee args Defines a term to be used in the table of contents or synopsis section, depending on the format. This command is silent, as it doesn't add any text to the output as a direct result of the call. It merely defines data to appear in another section. EEXXAAMMPPLLEE The tcl sources of this manpage can serve as an example for all of the markup described by it. Almost every possible construct (with the exception of rreeqquuiirree) is used here.