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

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

Class 'distribution'

Options

Methods

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: internalPkgs	List containing the names of all packages defined by the scanned distribution.

CopyMoreFiles ()

Files marked as required (by '.doc'-files) are copied into the html 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.

Excluded (filename)
Checks the specified filename for exclusion by matching it against the patterns stored in exclude.
Argument: filename	The name of the file to check for exclusion.
Returns: a boolean value. True signals that the file has to be excluded.

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. The generation of their problem reports can be suppressed by setting the option <o no-problems>.

GenerateImage (converter in out)
Transfers the image file in to out and converts it along the way, using the converter.
Argument: converter	Handle of the converter to use.
Argument: in	The name of the #source image file
Argument: out	Name 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: file	See genericFormatter:newPage.
Argument: title	See 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: ipName	The name of the interpreter to prepare.

PrepareDocIp (ipName)
Prepare the specified interpreter for evaluation of the .doc files found in the distribution.
Argument: ipName	The 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: n	The number of found items.
Argument: singular	The singular form of the found entities.
Argument: plural	The 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: p	The 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. If option <o no-problem> is not set the merged information will contain a link to the appropriate high level problem report for the index refered to (idx). Else it will just be the number of problems.
Argument: statvar	The name of the variable containing the statistics.
Argument: idx	The 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: o	The name of the changed option, here always -adlocation.
Argument: oldValue	The value of the option before the change. Ignored here.

TrackFormatter (o oldValue)
Overrides formatterInterface:TrackFormatter, problems:TrackFormatter 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: o	The name of the changed option, here always -formatter.
Argument: oldValue	The 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: o	The name of the changed option, here always -outputdir.
Argument: oldValue	The 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: o	The name of the changed option, here always -replyaddr.
Argument: oldValue	The 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: inTable	flag, 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. If option <o no-problems> is set this procedure will not write the list of general problems after the statistics.

Xpar ()

Resolves & p into paragraph breaks. Used by crResolve.

XrOld (what args)
Crossreference using old syntax, just report as problem.
Argument: what	Type of reference
Argument: args	The name of the referenced entity.

Xra (name)
Resolve crossreference to a procedure argument.
Argument: name	The name of the referenced argument.
Returns: the name, but specially formatted.

Xrc (partref class name)
Resolve crossreference to a part of a class.
Argument: partref	The method to call at the class index.
Argument: class	The name of the class to search the part in.
Argument: name	The 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: partref	The method to call at the class index.
Argument: name	The 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: idx	The name of the index to question.
Argument: name	The 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: aPage	Name 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: name	See classIndex:ref

clear ()

Overrides problems:clear Resets state information of scan to initial values, to allow future reconfiguration and scanning.

crResolve (text)
Resolves crossreferences found in the text.
Argument: text	The 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: name	The name of the package
Argument: url	Page 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: name	Name 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: path	The path of the required file, relative to the #source directory of the distribution.

fileRef (name)
See fileIndex:ref
Argument: name	See fileIndex:ref

getIndex (idxName)
Argument: idxName	The 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: code	The internal code used to refer to the new converter.
Argument: script	The 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: code	Internal symbolic name of the new picture.
Argument: text	Alternative text describing the contents of the picture.
Argument: converter	Handle of the converter to use.
Argument: ext	Extension to give to the target file.
Argument: basefile	Source of the picture.

imgRef (code)
Return hyperlink to image code.
Argument: code	Internal symbolic name of the requested image

log (level text)
Accessor for the log maintained by this object.
Argument: level	The importance level of the message.
Argument: text	Text to log.

methodRef (class name)
See classIndex:mref
Argument: class	See classIndex:mref
Argument: name	See classIndex:mref

nsContaining (name)
Returns the namespace object describing the namespace containing the object with the specified name. Will generate the necessary namespace object if not already existing.
Argument: name	The name of the object whose containing namespace the caller is looking for.

nsRef (name)
See namespaceIndex:ref
Argument: name	See namespaceIndex:ref

optionRef (class name)
See classIndex:oref
Argument: class	See classIndex:oref
Argument: name	See classIndex:oref

page ()

Overrides problems: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: name	See packageIndex:ref

popContext ()

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

procRef (name)
See procIndex:ref
Argument: name	See procIndex:ref

pushContext (object)
Adds the specified object to the top of the stack of objects writing their documentation.
Argument: object	The 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: class	See classIndex:vref
Argument: name	See 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: code	Internal symbolic name of external reference.

xrefDef (code text url)
Defines an external reference.
Argument: code	The internal symbolic name to reach this hyperlink
Argument: text	Text to use in the link.
Argument: url	Page 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.

Membervariables

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

Generated by AutoDoc 2.4 at 09/28/2001, invoked by Andreas Kupries,,,