Manual Pages for UNIX Darwin command on man doctools

Manual Pages for UNIX Darwin command on man doctools_api

doctoolsapi(n) Documentation tools doctoolsapi(n)

NAME

doctoolsapi - Interface specification for formatter code

DESCRIPTION

This manpage specifies the interface between formatting engines for data in the ddooccttoooollss format as specified in ddooccttoooollssffmmtt, and ddooccttoooollss,

the package for the generic handling of such data, as described in ddoocc-

ttoooollss.

Each formatting engine has to implement the conversion of input in ddoocc-

ttoooollss format to one particular output format as chosen by the author of the formatting engine. IINNTTEERRFFAACCEE Each formatting engine has to provide [1] Implementations of all the formatting commands as specified in ddooccttoooollssffmmtt, using the defined names, but prefixed with the

string ffmmtt. The sole exceptions to this are the formatting com-

mands vvsseett and iinncclluuddee. These two commands are processed by the generic layer and will never be seen by the formatting engine. [2] and additionally implementations for ffmmttnnuummppaasssseess This command is called immediately after the formatter is loaded and has to return the number of passes required by this formatter to process a manpage. This information has to be an integer number greater or equal to one. ffmmttiinniittiiaalliizzee

This command is called at the beginning of every conver-

sion run and is responsible for initializing the general state of the formatting engine. ffmmttsseettuupp n This command is called at the beginning of each pass over the input and is given the id of the current pass as its first argument. It is responsible for setting up the internal state of the formatting for this particular pass. ffmmttppoossttpprroocceessss text This command is called immediately after the last pass, with the expansion result of that pass as argument, and

can do any last-ditch modifications of the generated

result. Its result will be the final result of the con-

version. Most formats will use identity here. ffmmttsshhuuttddoowwnn This command is called at the end of every conversion run and is responsible for cleaning up of all the state in the formatting engine. ffmmttppllaaiinntteexxtt text This command is called for any plain text encountered by

the processor in the input and can do any special pro-

cessing required for plain text. Its result is the string written into the expansion. Most formats will use identity here. ffmmttlliissttvvaarriiaabblleess The command is called after loading a formatting engine to determine which parameters are supported by that engine. The return value is a list containing the names of these parameters. ffmmttvvaarrsseett varname text The command is called by the generic layer to set the value of an engine specific parameter. The parameter to change is specified by varname, and the value to set is given in text. The command will throw an error if an unknown varname is used. Only the names returned by ffmmttlliissttvvaarriiaabblleess are considered known. The tcl code of a formatting engine implementing all of the above can make the following assumptions about its environment [1] It has full access to its own safe interpreter. In other words, the engine cannot damage the other parts of the processor, nor can it damage the filesystem. [2] The surrounding system provides the engine with the following commands: Doctools commands ddttffiillee

Returns the full name of the file currently pro-

cessed by the engine. ddttffiilleeiidd Returns the name of the file currently processed by the engine, without path, nor extension ddttffoorrmmaatt Returns the name of format loaded into the engine ddttllnneessttiinngg Returns the number lists currently open ddttmmoodduullee Returns the name of the module the file currently processed belongs to. ddttssoouurrccee file This command allows the engine to load additional tcl code. The file being loaded has to be in the same directory as the file the format engine was loaded from. Any path specified for file is ignored. Expander commands All of the commands below are methods of the expander object (without the prefix eexx) handling the input. Their arguments and results are described in eexxppaannddeerr((nn)). eexxccaappppeenndd eexxccggeett eexxcciiss eexxccnnaammee eexxccppoopp eexxccppuusshh eexxccsseett eexxllbb eexxrrbb common.tcl commands Any engine loading (ddttssoouurrccee) the file "common.tcl" has default implementations of the ffmmtt commands explicitly listed in this document, and can additionally use cciinnppaassss Returns the id of the pass currently executing ccbbeeggiinn Use this to mark that processing of the text after mmaannppaaggeebbeeggiinn has begun. ccbbeegguunn Checks the flag set by ccbbeeggiinn. ccsseettmmoodduullee text Remember text as module information. ccggeettmmoodduullee

Retrieve module information stored by ccsseettmmoodd-

uullee. ccsseettttiittllee text Remember text as title. ccggeettttiittllee Retrieve title stored by ccsseettttiittllee. ccpprroovveennaannccee

Returns a string describing how the input was pro-

cessed. ccppaassss pass proc arguments body Define a procedure which is valid when pass pass of the engine is executed. cchhoollddBBuuffffeerrss args Define one or more buffers for holding data between passes. cchhoolldd buffer entry Add an entry to the specified buffer. The buffer has to be defined by an earlier invocation of the command cchhoollddBBuuffffeerrss. cchheelldd buffer Retrieves the contents of the specified buffer. The buffer is empty afterwards. All entries in the buffer are joined by newlines. ccccnneexxtt Increment the counter and return its current value. cccciinniitt

Push the current counter on the stack and reini-

tialize the counter to zero. ccccrreesseett Reinitialize the counter with the value on the counter stack and remove that value from the stack. NNOOPP args Do nothing command. Can be used in conjunction with ccppaassss to visibly declare in which passes a formatting command has nothing to do. NNYYII ?message? Throws the error "message NNoott yyeett iimmpplleemmeenntteedd". ccsseeccttiioonnIIdd name

Remembers the name of the section for later cross-

referencing ccppoossssiibblleeRReeffeerreennccee text gi Checks if a section is available for text. This command is currently tuned for use by engines like HTML and TMML.