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


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


Written by
Andreas Kupries
Description
Toplevel class of documentation extractor. Defines external interface to extractor engine, as used by autodoc application. Manages everything for a single distribution of files, hence the name.
Depends on
Pool_Base, Pool_Net
Keywords
interface, toplevel, distribution

Class 'distribution'

Superclasses
formatterInterface, problems
Options
adlocation, outputdir, psort, ptable, replyaddr, srcdir, tables, up-image, up-imglink, up-link, up-title
Membervariables
attributeName, attributeValue, attrs, classContext, context, docFileList, hasFiles, hasPackages, imgC, imgS, inDocFile, index, jumpbar, log, moreFiles, morePages, sidebarText, xrefPat
Methods
Author, CleanImages, CompleteDatabase, CompleteDependencies, CopyMoreFiles, CurrentClass, GatherStatistics, GenerateImage, HandleDocFiles, HandleFiles, HandlePackages, HandlePredocFiles, InitPatterns, Maintainer, NewPage, PrepareCRefIp, PrepareDocIp, ReadDescription, ReportNumber, SearchDocFiles, SearchForFiles, SearchPackages, SidebarLink, StatText, TrackAd, TrackFormatter, TrackOut, TrackReply, Write, WriteDescription, WriteHomepage, WriteSidebar, WriteStatistics, XrOld, Xra, Xrc, Xrcs, Xri, add2Sidebar, classRef, clear, crResolve, depDef, depRef, distribution, docfile, fileRef, getIndex, imgConverter, imgDef, imgRef, log, methodRef, optionRef, page, pkgRef, popContext, procRef, pushContext, scan, theContext, varRef, writeJumpbar, xRef, xrefDef, ~distribution

-adlocation
Location of the documentation of AutoDOC. Required for generation of backreferences for any generated page.
-outputdir
Path to directory to store the generated files into.
-psort
Boolean flag. If set procedure documentation is sorted alphabetically.
-ptable
Boolean flag. If set procedure documentation is written as table.
-replyaddr
Address of person to reply to in case of problems with the documented distribution.
-srcdir
Path to directory containing the tcl #sources to document.
-tables
Boolean flag. If set the root page is written with tables.
-up-image
The symbolic name of the image to use in the uplink to the site containing the generated documentation, as defined with a call imgDef.
-up-imglink
A boolean flag. Determines wether the image is made a part of the generated uplink or not. Ignored if no text was given, the image has to be the link in such a case.
-up-link
The url to use as target in the uplink to the site containing the generated documentation. Ignored if neither <o up-title> nor <o up-image> is set.
-up-title
The string to use in the uplink to the site containing the generated documentation.

attributeName
Maps from the attribute names used in DESCRIPTION files to the texts used in the generated documentation.
attributeValue
Maps from the attribute names used in DESCRIPTION files to their respective values.
attrs
List of attributes defined by the distribution description file.
classContext
The class currently writing its documentation.
context
The stack of objects currently writing their documentation.
docFileList
List of files with extension '.doc'.
hasFiles
Boolean flag. Set if some files were found.
hasPackages
Boolean flag. Set if some packages were found
imgC
Table of scripts for the conversion of an image file into the format required by the browser. The following special strings are recognized by the system: %in%, %tmp% and %out%. See <x ...> for their meaning.
imgS
State of images (requested or not)
inDocFile
Boolean flag. Set during evaluation of '.doc'-files.
index
Maps from a logical index name to the object managing it.
jumpbar
A cache holding the formatted jumpbar texts for the various callers of writeJumpbar.
log
Handle of the syslogConnection object used for logging.
moreFiles
List of files marked as required by '.doc'-files.
morePages
List of additional files generated by the '.doc'-files.
sidebarText
Used by add2Sidebar to record the texts for the hyperlinks pointing to the additional pages.
xrefPat
Contains all patterns used to detect crossreferences and the code to replace any found instance of the pattern.

Author ()

Determines author of distribution.

CleanImages ()

Removes all defined, yet unreferenced pictures from the output directory.

CompleteDatabase ()

Completes database (author information, keyword index, dependencies).

CompleteDependencies (internalPkgs)

Takes the list of packages required by the scanned distribution and removes all packages defined by it. This is required to avoid false dependencies.
Argument: internalPkgsList containing the names of all packages defined by the scanned distribution.

CopyMoreFiles ()

Files marked as required (by '.doc'-files) are copied into the htm target directory.

CurrentClass ()

Returns: the handle of the class currently writing its documentation. Different from theContext as the current object can be one of its methods.

GatherStatistics ()

Checks the main indices for problems and causes the generation of their problem reports if they do have such. Records the number of problems for inclusion into the main statistics.

GenerateImage (converter in out)

Transfers the image file in to out and converts it along the way, using the converter.
Argument: converterHandle of the converter to use.
Argument: inThe name of the #source image file
Argument: outName of the target file.
Returns: out, extended by the path of the output directory.

HandleDocFiles ()

Executes the remebered '.doc'-files in a safe(?) environment.

HandleFiles ()

Tell the found files to scan themselves.
Notes: Is done only if no packages were found.

HandlePackages ()

Tell the found packages to scan themselves.

HandlePredocFiles ()

Searches for files ending in '.predoc' and executes them in a safe(?) environment.

InitPatterns ()

Initialize the regular expression pattern used to detect and resolve embedded crossreferences.
Dangers: Order is important here! Longer matching patterns must be applied before shorter ones as they may consume the same input, but with an improperly split into constituents. To achieve this the internal pattern identifiers are sorted before processing them (crResolve), so we have just to ensure that longer patterns get identifiers alphabetically sorted before the shorter patterns.

Maintainer ()

Determines maintainer of distribution.

NewPage (file title firstheading)

Calls are forwarded to genericFormatter:newPage. Additionally the standard jumpbar is generated too.
Argument: fileSee genericFormatter:newPage.
Argument: titleSee genericFormatter:newPage.
Argument: firstheading (= {})See genericFormatter:newPage.

PrepareCRefIp (ipName)

Prepare the specified interpreter for evaluation of texts containing cross references. A separate interpreter is used to allow usage of various formatting commands without polluting the global namespace, or this class.
Argument: ipNameThe name of the interpreter to prepare.

PrepareDocIp (ipName)

Prepare the specified interpreter for evaluation of the .doc files found in the distribution.
Argument: ipNameThe name of the interpreter to prepare.

ReadDescription ()

Reads the description file for the entire distribution.
Notes: Assumes to be in the module directory

ReportNumber (n singular plural)

Report the number of found entities to the log.
Argument: nThe number of found items.
Argument: singularThe singular form of the found entities.
Argument: pluralThe plural form of the found entities.

SearchDocFiles ()

Searches for files ending in '.doc' and remembers them for later usage. 'pkg.doc's are excluded, as they have a special meaning as package description files.

SearchForFiles ()

Searches for files containing tcl-code.
Notes: Is done only if no packages were found.

SearchPackages ()

Searches for packages in the distribution. Detects them by the presence of 'pkg.doc' in a directory.
Notes: Assumes to be in the module directory.

SidebarLink (p)

Argument: pThe code of the page whose link shall be retrieved.
Returns: a hyperlink pointing to the specified additional documentation page p.

StatText (statvar idx)

Internal helper used by the method generating the main statistics. Merges the problem information recorded by GatherStatistics into the string containing the number of scanned entities.
Argument: statvarThe name of the variable containing the statistics.
Argument: idxThe name of the index whose information is requested.
Returns: a string containing the number of entities found, and the number of problematic ones.

TrackAd (o oldValue)

Internal method. Called by the generic option tracking mechanism for any change made to adlocation. Propagates the new value to the internal shadow and causes the configuration of the specified object.
Argument: oThe name of the changed option, here always -adlocation.
Argument: oldValueThe value of the option before the change. Ignored here.

TrackFormatter (o oldValue)

Internal method. Called by the generic option tracking mechanism for any change made to formatter. Propagates the new value to the internal shadow and causes the configuration of the specified object.
Argument: oThe name of the changed option, here always -formatter.
Argument: oldValueThe value of the option before the change. Ignored here.

TrackOut (o oldValue)

Internal method. Called by the generic option tracking mechanism for any change made to outputdir. Propagates the new value to the internal shadow and causes the configuration of the specified object.
Argument: oThe name of the changed option, here always -outputdir.
Argument: oldValueThe value of the option before the change. Ignored here.

TrackReply (o oldValue)

Internal method. Called by the generic option tracking mechanism for any change made to replyaddr. Propagates the new value to the internal shadow and causes the configuration of the specified object.
Argument: oThe name of the changed option, here always -replyaddr.
Argument: oldValueThe value of the option before the change. Ignored here.

Write ()

Writes out the documentation of the entire distribution.

WriteDescription ()

Writes out the distribution description.

WriteHomepage ()

Internal method. Generates the main page of the distribution, the entry point for all documentation users.

WriteSidebar (inTable)

Writes the text containing the references to additional files, as registered via '.doc'-files.
Argument: inTableflag, 1 if code shall be placed in a table, 0 else.

WriteStatistics ()

Generates a summary page containing statistics about the scanned distribution. Additionally refers to pages with listings of problematic files, classes and procedures, if any.

XrOld (what args)

Crossreference using old syntax, just report as problem.
Argument: whatType of reference
Argument: argsThe name of the referenced entity.

Xra (name)

Resolve crossreference to a procedure argument.
Argument: nameThe name of the referenced argument.
Returns: the name, but specially formatted.

Xrc (partref class name)

Resolve crossreference to a part of a class.
Argument: partrefThe method to call at the class index.
Argument: classThe name of the class to search the part in.
Argument: nameThe name of the referenced part.
Returns: a hyperlink to the definition of the entity.

Xrcs (partref name)

Resolve a short crossreference to a part of a class.
Argument: partrefThe method to call at the class index.
Argument: nameThe name of the referenced part.
Returns: a hyperlink to the definition of the entity.

Xri (idx name)

Resolve crossreference based on one of the main indices.
Argument: idxThe name of the index to question.
Argument: nameThe name of the referenced entity.
Returns: a hyperlink to the definition of the entity.

add2Sidebar (aPage text)

Adds the aPage to the sidebar referencing additional documentation pages.
Argument: aPageName of the page to add, generated earlier by genericFormatter:newPage
Argument: text (= {})Text to use in the hyperlink. Defaults to the basename of aPage, without extension.

classRef (name)

See classIndex:ref
Argument: nameSee classIndex:ref

clear ()

Resets state information of scan to initial values, to allow future reconfiguration and scanning.

crResolve (text)

Resolves crossreferences found in the text.
Argument: textThe text to reformat.
Returns: The text, but crossreferences resolved into hyperlinks.

depDef (name url)

Defines additional information for a 'required' package, to allow conversion of usage in descriptions into hyperlinks.
Argument: nameThe name of the package
Argument: urlPage to refer to for information about the package.

depRef (name)

Converts the name of an external package into a hyperlink. The argument is returned unchanged, if that is not possible.
Argument: nameName of package to link to.
Returns: a string containing a hyperlink to name, if possible.

distribution ()

Constructor. Creates and initializes all subordinate indices. These objects are nested into the namespace of this one, reducing the possibility of conflicts with command outside.

docfile (path)

Marks file path as required by the documentation. It will be copied into the output directory later.
Argument: pathThe path of the required file, relative to the #source directory of the distribution.

fileRef (name)

See fileIndex:ref
Argument: nameSee fileIndex:ref

getIndex (idxName)

Argument: idxNameThe internal name of the requested index.
Returns: the object managing the specified index.

imgConverter (code script)

Register a script to transfer an image #source into the html tree, doing format conversion if necessary. The script may contain the special strings %in%, %out% and %tmp%. They refer to the input file, output file and a temporary file. The latter is generated only if the string is present in the script.
Argument: codeThe internal code used to refer to the new converter.
Argument: scriptThe script to evaluate for transfer and conversion.

imgDef (code text converter ext basefile)

Defines a new image. The given #source is transfered into the output directory, and converted along the way. If the picture is never referenced it will be removed later.
Argument: codeInternal symbolic name of the new picture.
Argument: textAlternative text describing the contents of the picture.
Argument: converterHandle of the converter to use.
Argument: extExtension to give to the target file.
Argument: basefileSource of the picture.

imgRef (code)

Return hyperlink to image code.
Argument: codeInternal symbolic name of the requested image

log (level text)

Accessor for the log maintained by this object.
Argument: levelThe importance level of the message.
Argument: textText to log.

methodRef (class name)

See classIndex:mref
Argument: classSee classIndex:mref
Argument: nameSee classIndex:mref

optionRef (class name)

See classIndex:oref
Argument: classSee classIndex:oref
Argument: nameSee classIndex:oref

page ()

Notes: The codes assumes that no more than one such page exists.
Returns: The filename of the distribution page.

pkgRef (name)

See packageIndex:ref
Argument: nameSee packageIndex:ref

popContext ()

Removes the topmost object from the stack of object writing their documentation.

procRef (name)

See procIndex:ref
Argument: nameSee procIndex:ref

pushContext (object)

Adds the specified object to the top of the stack of objects writing their documentation.
Argument: objectThe handle of the object now writing its documentation.

scan ()

Reads DESCRIPTION residing in #source directory, scans subdirectories for packages/files, evaluates these then too.

theContext ()

Returns: the handle of the object currently writing its output. If there is no such this one is given to the caller.

varRef (class name)

See classIndex:vref
Argument: classSee classIndex:vref
Argument: nameSee classIndex:vref

writeJumpbar (caller)

Writes the formatted text of a jumpbar for placement at the top of every page, or whereever the caller likes.
Argument: caller (= {})contains the name of a calling special page (home, indices) or else an empty list. Used to deactivate the corresponding entry in the jumpbar.

xRef (code)

Return hyperlink to external page code.
Argument: codeInternal symbolic name of external reference.

xrefDef (code text url)

Defines an external reference.
Argument: codeThe internal symbolic name to reach this hyperlink
Argument: textText to use in the link.
Argument: urlPage refered by the link.

~distribution ()

Removes all traces of the distribution from memory
Notes: There is no need to delete the subordinate objects explicitly. They are nested into this namespace and therefore automatically removed. It would still be necessary if they were using outside re#sources, like channels, but they don't.


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