File 'lib/genericFormatter.cls' (part of 'AutoDOC')


Home | Packages | Files | Procedures | Classes | Keywords | External packages


Written by
Andreas Kupries
Description
The base class of all formatters
Keywords
Output formatter, formatting output, interface to formatter

Class 'genericFormatter'

Description
This class defines the interface used by the autodoc engine to produce the documentation from data embedded into tcl code.
Superclasses
distInterface
Options
adlocation, ip, outputdir, replyaddr
Membervariables
currentPage, extension
Methods
MakeError, ampersand, caption, chapter, clear, closePage, commaList, crError, definitionList, defterm, defterm2, enumerate, formattedRow, formattedRowVar, formattedTerm, formattedTermVar, getAnchor, getString, hrule, imgDef, imgRef, item, itemize, link, linkCommaList, linkDef, linkMail, linkRef, mailToDefterm, markError, missingDescError, newPage, pageFile, par, parbreak, prepareForOutput, quote, section, setAnchor, sortByName, sortedObjectList, strong, table, table_data, table_head, table_row, termVar, write

-adlocation
Location of the Autodoc documentation. Required for generation of backreferences for any generated page.
-ip
Requests the formatter to use the specified interpreter for script evaluation instead of uplevel. Only if not empty.
-outputdir
Path to the directory to store the generated files into.
-replyaddr
Address of person to reply to in case of problems with the documented distribution.

currentPage
A token allowing the high level formatting routines to use the current page as target of hyperlinks.
extension
The extension to add to a page name to convert it into the name of the associated file (if there is any). Has to contain the separating dot or whatever is used on the particular platform to separate file names adn their extensions.

MakeError (category output error)

Internal method to generate a problem report. The report is added to the object currently writing its documentation linking it to the place of the problem.
Argument: categoryCategory of the problem, either desc or crossref
Argument: outputThe text to print at the place of the problem.
Argument: errorThe text to use in the problem report to describe it.
Returns: a string containing the output formatted as problem and having an anchor the report can link to.

ampersand ()

Writes an ampersand (&) into the current page.

caption (args)

Executes the specified script (last argument) in the calling context, captures the produced formatted text and organizes it into a table caption. The arguments before the script are interpreted as 'name=value'-style parameterization.
Argument: argsA list of 'name=value' parameters and a script to evaluate in the calling context (last element).

chapter (title)

Adds a chapter title to the current page.
Argument: titleThe text of the title.

clear ()

Clear internal state, prepare for new scan.

closePage ()

Completes the generation of the current page

commaList (textList)

Takes the specified list of strings and converts it into a comma separated list.
Argument: textListList of strings.
Returns: a string separating the incoming texts by commas.

crError (outputText errorText)

Generates a crossreference problem at the place of its calling. Uses MakeError as workhorse.
Argument: outputTextThe text to print at the place of the problem.
Argument: errorTextThe text to use in the problem report to describe it.

definitionList (script)

Executes the specified script in the calling context and captures any generated output in a string, which is then formatted as definition list.
Argument: scriptThe tcl code to execute in the calling context.

defterm (term text)

Generates an item in a definition list.
Argument: termThe name of the thing to explain.
Argument: textThe text explaining the term.

defterm2 (term)

Generates an item in a definition list.
Argument: termThe name of the thing to explain. But without explanation.

enumerate (script)

Executes the specified script in the calling context and captures any generated output in a string, which is then formatted as enumerated list.
Argument: scriptThe tcl code to execute in the calling context.

formattedRow (term text)

See formattedTerm, but writes out a table row, not a term of a definition list.
Argument: termThe name of the thing to explain.
Argument: textThe text explaining the term.

formattedRowVar (term var)

Same as formattedRow, but the explanation is specified as name of a variable. An empty explanation causes the system to ignore the call. Crossreferences are resolved too.
Argument: termThe name of the thing to explain.
Argument: varThe name of the variable containing the epxlanatory text.

formattedTerm (term text)

Like defterm, but crossreferences in text are resolved.
Argument: termThe name of the thing to explain.
Argument: textThe text explaining the term.

formattedTermVar (term var)

Same as formattedTerm, but the explanation is specified as name of a variable. An empty explanation causes the system to ignore the call.
Argument: termThe name of the thing to explain.
Argument: varThe name of the variable containing the epxlanatory text.

getAnchor (name)

Generates a named anchor and returns the HTML to the caller.
Argument: nameThe name of the generated anchor.
Returns: the HTML string defining the named anchor.

getString (script)

Executes the specified script in the calling context and captures any generated output in a string, which is then returned as the result of the call.
Argument: scriptThe tcl code to execute in the calling context.
Returns: a string containing all output produced by the script

hrule ()

Writes a horizontal rule into the current page.

imgDef (code text geometry imgfile)

Stores an hyperlink to an image under code, allowing later retrieval via imgRef.
Argument: codeThe identifier for storage and retrieval of the image link.
Argument: textAlternative text describing the contents of the picture.
Argument: geometryA list containing the width and height of the image, in this order. Can be empty. Used to insert geometry information into the link, for better display even if the image is not loaded.
Argument: imgfileThe location to point at, i.e. the image file.

imgRef (code)

Argument: codeThe identifier for storage and retrieval of the image link.
Returns: the image link generated by imgDef and then stored under code.

item (text)

Generates an item in an itemized list.
Argument: textThe paragraph to format as item in the list.

itemize (script)

Executes the specified script in the calling context and captures any generated output in a string, which is then formatted as itemized list.
Argument: scriptThe tcl code to execute in the calling context.

link (text url)

Combines its arguments into a hyperlink having the text and pointing to the location specified via url
Argument: textThe string to use as textual part of the hyperlink.
Argument: urlThe location to point at.
Returns: the formatted hyperlink.

linkCommaList (objList)

Takes the specified list of objects and converts it into a comma separated list of hyperlinks to the pages describing them.
Argument: objListList of object handles. The objects in it have to understand the link method.
Returns: a string containing several hyperlinks.

linkDef (code text url)

The same as in link, but the result is stored internally instead, using code as reference.
Argument: codeThe identifier for storage and retrieval of the hyperlink.
Argument: textThe string to use as textual part of the hyperlink.
Argument: urlThe location to point at.

linkMail (prefix nameVar addrVar)

Generates hyperlink for name (in attr)
Argument: prefixString to write before the actual hyperlink
Argument: nameVarName of the variable containing the name to write.
Argument: addrVarName of the variable containing the address.
Returns: A string containing a hyperlink to the given mail address.

linkRef (code)

Argument: codeThe identifier for storage and retrieval of the hyperlink.
Returns: the hyperlink generated by linkDef and then stored under code.

mailToDefterm (prefix nameVar addrVar)

Writes hyperlink for a person and its mail address.
Argument: prefixString to write before the actual hyperlink
Argument: nameVarName of the variable containing the name to write.
Argument: addrVarName of the variable containing the address.

markError (text)

Formats the incoming text as error and returns the modified information.
Argument: textThe text to reformat.
Returns: a string containing the given text formatted as error.

missingDescError (errorText)

Generates a documention missing problem at the place of its calling. Uses MakeError as workhorse.
Argument: errorTextThe text to use in the problem report to describe it.

newPage (file title firstheading)

Start a new page, implicitly completes the current page.
Argument: filename of file to contain the generated page
Argument: titlestring to be used as title of the page
Argument: firstheading (= {})string to use in toplevel heading. Defaults to title. Required to allow hyperlinks in toplevel headings without violating HTML syntax in the title.

pageFile (pageName)

Converts the name of page into the name of the file containing it.
Argument: pageNameGuess what :-)
Returns: the name of the file containing the specified page.

par (args)

Writes a paragraph into the current page, uses all arguments as one string.
Argument: argsThe text to format and write as paragraph. Actually a list of arguments put together into one string

parbreak ()

Writes a paragraph break into the current page.

prepareForOutput ()

Called just before the generation of output starts. Checks for the existence of a target directory and creates it, if necessary.

quote (string)

Takes the specified string, add protective signs to all character (sequences) having special meaning for the formatter and returns the so enhanced text.
Argument: stringThe string to protect against interpretation by the formatter.
Returns: a string containing no unprotected special character (sequences).

section (title)

Adds a section title to the current page.
Argument: titleThe text of the title.

setAnchor (name)

Generates a named anchor at the current location in the current page.
Argument: nameThe name of the generated anchor.

sortByName (objList)

Sorts the specified list of objects alphabetically in ascending order by the name of the objects.
Argument: objListList of object handles. The objects in it have to understand the name method.
Returns: the sorted list.

sortedObjectList (objlist)

Takes the specified list of objects, sorts them by name, then generates a definition list containing hyperlinks to the object pages as terms and their short descriptions as explanation.
Argument: objlistList of object handles. The objects in it have to understand the methods link and short.

strong (text)

Adds the appropriate formatting to the given text to emphasize it as strong, then returns the result.
Argument: textThe string to mark as strong.
Returns: The emphasized text.

table (args)

Executes the specified script (last argument) in the calling context, captures the produced formatted text and organizes it into a table. The arguments before the scripts are interpreted as 'name=value'-style parameterization.
Argument: argsA list of 'name=value' parameters and a script to evaluate in the calling context (last element).

table_data (args)

Executes the specified script (last argument) in the calling context, captures the produced formatted text and organizes it into a table cell. The arguments before the script are interpreted as 'name=value'-style parameterization.
Argument: argsA list of 'name=value' parameters and a script to evaluate in the calling context (last element).

table_head (args)

Executes the specified script (last argument) in the calling context, captures the produced formatted text and organizes it into a table cell formatted as heading. The arguments before the script are interpreted as 'name=value'-style parameterization.
Argument: argsA list of 'name=value' parameters and a script to evaluate in the calling context (last element).

table_row (args)

Executes the specified script (last argument) in the calling context, captures the produced formatted text and organizes it into a table row. The arguments before the script are interpreted as 'name=value'-style parameterization.
Argument: argsA list of 'name=value' parameters and a script to evaluate in the calling context (last element).

termVar (term var)

Same as formattedTerm, but the explanation is specified as name of a variable. An empty explanation causes the system to ignore the call. There is no crossreference resolution.
Argument: termThe name of the thing to explain.
Argument: varThe name of the variable containing the epxlanatory text.

write (text)

Has to write the specified text into the current page.
Argument: textThe string to place into the current page.


Generated by AutoDoc 2.1 at 02/15/1999, invoked by Andreas Kupries