Page tree
Skip to end of metadata
Go to start of metadata

Need For Documentation

The users of the Promula tools and the system that underlies them need to know exactly what technology is included and how that technology can be used. This question can be answered explicitly by giving a complete specification of the code base that incorporates that technology and a complete specification of the tool and its user language. The problem is that these are all extendable by the user; therefore, the documentation must also be extendable by the user. In addition users will be adding their own packages to the user environment and these packages must be documented as well.

This document was created by the codedoc tool from a simple text-based set of document files and from embedded comments within the code. Some of the code is particular to this codedoc tool and some is part of the Information management library -- IMSLIB.

Once defined, the documentation specification is authored into an HTML form that can be viewed using a browser. The actual view consists of tabs across the top of the screen. Each tab has a set of pages that are listed in the left column of the screen. Each page can have a set of topics that are listed under a Table of Contents at the top in the right column of the screen. Finally, each topic can have a set of subtopics associated with it that are listed at the bottom of the text for the topic.

This tab describes the use of the documentation capability and the code base that implements it.

Documentation Commands

There are seven commands processed within a documentation specification:

Command Description of use
Documentation Identifies and begins a set of documents
Document Identifies and describes a document within the set
Page Identifies and describes a page within a document
Topic Identifies and describes a topic within a page
Code Identifies and loads source code documentation within a page
Subtopic Identifies and describes a subtopic within a topic
Content Contains the text content of a topic or subtopic

Once defined, the documentation specification is authored into an HTML form.

Documentation Command

The Documentation command begins the specification of a documentation set. It is recognized by the main entry point of the Document tool itself. All other commands within this set are only recognized by the documentation command processor.

The attributes of the Documentation command are as follows:

Attribute Description
id The identifier of the symbol used to contain this documentation. It is required. It is stored at the primary index level in the user storage area and must be unique relative to any other symbols stored at that level.
filename This is the name of the file that is to receive the authored HTML documented. Note that this is a bundled file, as are most output files produced by this tool set. If no output filename is specified, then the HTML is written to the standard output file.

The following shows the script file that created an early version of this documentation set.


 <Documentation id="pBasic" filename="docum.bnd"/>
    <Include Filename="Introduction.xml"/>
    <Include Filename="CommandLine.xml"/>
    <Include Filename="Configuration.xml"/>
    <Include Filename="Prototypes.xml"/>
    <Include Filename="Runtime.xml"/>
    <Include Filename="lpslib.xml" />
    <Include Filename="imslib.xml" />
 </Documentation>

To review topics discussed elsewhere as well, the initial tag Documentation is accepted by the main entry point of the Document capability. It identifies the overall purpose of this specification file. Obviously, the closing tag must match it. Also all the included files must also use the same initial and closing tag. This ties these files together and reduces the likelihood that one of the included files might be used in the wrong context.

This file is processed in the same manner as any other "XML script". Below is the listing of the "make.bat" file in the "source" subdirectory of the documentation being viewed that processes the above.


  del *.bnd
  CodeDoc pBasic.xml site=c:\gmTools\site

The "docum.bnd" file, specified on the Documentation command, Contains the individual html files making up the authored documentation in bundled form. Note that the site= command-line switch specifies the pathname to which the actual documentation will be deployed. Thus, the first few cat commands in this file look as follows.


 cat >c:\gmTools\Site\pBasic.html <<'!)(!'
 cat >c:\gmTools\Site\border_left.html <<'!)(!'
 cat >c:\gmTools\Site\Introduction_Header.html <<'!)(!'

The unbundling or "deployment" of the documentation is performed by the deployment tool. In this case, the actual tool invocation would be as follows.


 deploy docum.bnd REPLACE

The above is the listing of the "makesite.bat" file in the source subdirectory of the documentation being viewed.

Document Command

The Document command is by far the most complex command within the documentation specification. The attributes of this command are as follows:

Attribute Description
id The identifier of the symbol used to contain this document
label The label to be used in the main tab that accesses this document
title The title of the document to be used in the head section of html pages created for this document
tooltip The tooltip to be shown when the tag for this document is addressed by the mouse.
href The html filename for the frameset "index" file which begins the display of this document.
header The html filename for the header tab display that is used when this document is active.
body The html filename of the initial content to be displayed when this document is activated.
navigation The html filename of the navigation file displayed on the left side that allows the pages within the document to be selected and viewed.
type The type of the navigation selection entries to be used.
width, height The height and width of the navigation selection entries.
styleSheet The filename of the styleSheet to be used with the html pages within this document.

To make this discussion a bit simpler below is the actual document command which introduced this document.


<Document id="document" label="Documentation"
          title="Deployimng Documentation"
          tooltip="Description of Documentation Production"
          href="Document_Index.html"
          header="Document_Header.html"
          body="Document_Body.html"
          navigation="Document_Navigation.html"
          type="buttons" height="36" width="120"
          stylesheet="promula.css"
>

To begin, notice that the colored tab of the current display is "Documentation" which is the label specified above. The labels on the other tabs are the labels of the other documents in this set. The order of the tabs is the order in which the documents were defined within the documentation. The browser reports the filename being viewed as "Document_Index.html" which is the href attribute above. Placing the mouse over the Document tab displays the tooltip "Description of Documentation Production" which is the tooltip. The left side of the display Contains a series of "buttons" which are 36 pixels high. The left side display overall is 120 pixels wide -- all as specified above. The actual button labels are obtained from the page commands that are contained within this document. They are described below.

In general, documentation is viewed as a two-dimensional display, where the documents make up the first dimension across the top and the pages within the document make up the second dimension down the left side.

As with the Documentation command note that documents themselves contain no explicit content. They are organizational units.

In addition to the navigation type buttons there is the navigation type anchors. This type simply uses simple strings that can be selected. It is used when there are a large number of pages within a given document.

Page Command

The Page command is the final organizational command within the documentation specification. The attributes of this command are as follows:

Attribute Description
label The label of the page as displayed in the left side navigation buttons or entries.
href The html filename of the file containing the content of the topics introduced within this page.

The page labels are displayed in the navigation column in the order in which they are defined. By convention the href of the first page should be the same as the body specified by the parent document.

Topic Command

The Topic command is the primary command for entering content into the documentation specification. The attributes of this command are as follows:

Attribute Description
title Specifies the title for the topic which precedes it as a label and which is used to form a link at the top of the page.
name Specifies a name for the topic. This attribute is currently deprecated.
anchor An alternative identifier to be used in forming link references to this topic on the page.

Within the topic the actual content is entered via a content command. The topic may also contain subtopics, it more that one content is to be associated with the topic. These are entered with the subtopic command.

Subtopic Command

The Subtopic command is the secondary command for entering content into the documentation specification. It allows multiple content blocks to be associated with a topic. The attributes of this command are as follows:

Attribute Description
title Specifies the title for the subtopic which precedes it as a label and which is used to form a link at the bottom of the content display of the containing content.

Within the subtopic the actual content is entered via a content command.

Code Command

The Code command enters one or more topics into the document. The content of these topics is taken from the documentation embedded within external source files. Its attribute is as follows:

Attribute Description
dir Specifies the path containing the referenced source files.

As an example of this the first block below enters all of the documentation in the files listed in the \gmTools\codedoc subdirectory that pertain to the documentation capability.


 <code dir="\gmTools\codedoc">
    authordocumentation.c
    authorhtmlsource.c
    ...
 </code>

There is no limit on the number of source code files that may be included in a given Code command.

Though they vary somewhat depending upon the implementation language each source code entry-point description contains the following parts:

  1. Title -- Short description
  2. Synopsis
  3. Description of Service
  4. Properties of Service
  5. Return Value of Service
Generally each entry-point is assumed to provide some service to the user. Each does something. The arguments that must be provided by the caller of the service ascribe properties to that service. Within the functional view taken here, services have properties just like objects.

The title part gives a brief description of what the entry-point is. These title sections also appear in the table of contents. Hopefully, the descriptions are sufficiently clear that a developer looking for some capability can at least find possible candidates by browsing the table of contents.

The synopsis part shows exactly how the entry-point is called -- its type, its argument types, and what include files or packages are needed to validate its reference. This part also has a brief description of each argument. This is also the only part of the entry-point description that is language specific.

The description part attempts to explain exactly what service the entry-point provides. This can be very long or can be very short -- when the service performed is obvious from its short description. In general, each description is made as complete as possible with as little cross-referencing as possible. Again the assumption is made that this documentation is primarily intended for reference. It is not the great American novel.

The properties part describes exactly what characteristics each entry-point argument has with relation to the service being performed. These descriptions are made as complete as necessary and are made as implementation language independent as possible. Ideally, all language specific information about the entry-point is restricted to the synopsis -- but we can do no better than to strive towards ideals.

Finally, the return part describes what values, if any, are returned to the caller by the entry-point as a result of performing the service.

These entry-point descriptions are bound by ;/doc/ **** records, as shown in the example below


    /*
    ;/doc/ ***********************************************************************
    ;
    ; DocSourceError: Issue Source Code Documentation Error
    ;
    ; void DocSourceError                  Issue source code documentation error
    ; (
    ;    int   errNumber                   Specifies number for the error
    ;    char* message                     Specifies message for the error
    ; )
    ;
    ; Description of Service:
    ;
    ; This service issue an error message when the source code documentation
    ; processor detects a problem.
    ;
    ; Properties of Service:
    ;
    ; errNumber        This integer contains the unique number that identifies
    ;                  the error.
    ;
    ; message          This string contains a message describing the error.
    ;
    ; Return Value From Service: None
    ;
    ;/doc/ ************************************************************************
    */


Content Command

This command has no attributes. It contains text with optional marginal annotations. Each line of the text is simply entered from the margin to the end of the record. The margin annotation itself is the record associated information. Note the width of the margin is always the number of blanks at the front of the first record. If there are no blanks, then there are no margin annotations for the text. Text is stored as a starting record number and a record count.

The two margin characters that are recognized are '|' and '/'. The bar indicates that the lines are to be entered into the HTML page exactly as they are entered in a fixed font. The slash, when associated with a line, forces a line break.

In addition to annotations, text is also searched for lines ending in a colon. Such lines are assumed to introduce lists of some sort that receive special HTML tags to make them standout. There are four types -- Ordered_text, table_list, unordered_list, and unordered text.

Ordered_text is initiated when the first line non-blank line following a line ending in a colon begins with a numeric character. The entries may have multiple lines which are identified via a secondary margin.

Table_list is initiated when the second line after a line ending in a colon starts with a minus sign. The entries may have multiple lines which are identified via a secondary margin.

Unordered_list is initiated after a line ending in a colon and neither of the above criteria are met and there are no blank lines in the list range.

Unordered_text is initiated after a line ending in a colon and none of the above apply.

Tool specific Processing

Though the documentation capability uses the text processing and information storage services of IMSLIB, the tool itself contains the logic needed to load the documentation structures into the current storage area, to process the documentation embedded in the source codes files, and to produce the terminal level Html for the text components when the documentation is authored.

Documentation Storage Structures Used

There are four structures used by the documentation component:

Name Description of use
tDocument Describes a document within the documentation
tDocPage Controls a set of topics or a set of documents
tDocTopic Contains the actual text on some topic
tDocCode Contains code documentation taken from code comments

The tDocument and tDocPage structures are navigational. They contain information about how the documentation should be identified, organized, and formatted. They contain no actual textual content.

The tDocTopic structure and tDocCode which extends it contain the actual content of the documentation. This content can be a main topic, a subtopic, or derived code documentation.

The tDocument Structure

The tDocument structure retains the information supplied by the Document command. The tDocument symbols in the storage area are classified by the id attribute of the command. The remaining properties correspond on a one-to-one basis with the other command attributes. The properties are as follows:

Property Description
label This integer property contains the offset in storage of the label to be used in the main tab that accesses this document
title This integer property contains the offset in storage
title of the title of the document to be used in the head section of html pages created for this document
styleSheet This integer property contains the offset in storage of the filename of the styleSheet to be used with the html pages within this document
tooltip This integer property contains the offset in storage of the tooltip to be shown when the tag for this document is addressed by the mouse.
href This integer property contains the offset in storage of the html filename for the frameset "index" file which begins the display of this document.
header This integer property contains the offset in storage of the html filename for the header tab display that is used when this document is active.
body This integer property contains the offset in storage of the html filename of the initial content to be displayed when this document is activated.
navigation This integer property contains the offset in storage of the html filename of the navigation file displayed on the left side that allows the pages within the document to be selected and viewed.
type This integer property contains a code indicating the type of display to be used for the navigation page -- anchor string (1) or buttons (2).
width This integer property contains the width in pixels to be allowed for the navigation page.
height This integer property contains the height in pixels to be allowed for any buttons on the navigation page.

The child structures of the tDocument structure are all tDocPage structures.

The tDocPage Structure

The tDocPage structure forms the navigational glue around which content is eventually presented in a structured way. This structure is used both as the single parent of the tDocument structures and as their children. Its single property is as follows:

Property Description
href This integer property contains the offset in storage of the html filename of the file containing the content of the topics introduced within this page.

The child structures of the tDocPage structure are all tDocTopic structures.

The tDocTopic Structure

The tDocTopic structure is used to contain the content to be shown. It is created by the Topic, Subtopic, and Code commands. Its properties as are follows:

Property Description
content This integer property contains the root address of the variable information stream containing the actual content records.
refType This integer property contains a code indicating the type of the content -- topic (1), subtopic (2), or code documentation (3).
anchor This integer property contains the offset in storage of the anchor string to be used in authoring on-page subtopic links.
name This integer property contains the offset in storage of a name to be associated with the topic text.

The child structures of the tDocTopic structure are all tDocTopic structures containing subtopics.

The tCodeDoc Structure

The tCodeDoc structure extends the tDocTopic structure to partition the text content into its logical parts. Its additional properties are all line numbers or counts within the text content as follows:

Property Description
includename Include name
includedesc Include description
servtype Record number of service return type
nProperty Number of service properties
proptype[DOC_MAX_PROP] Record number property type description
propname[DOC_MAX_PROP] Record number of property name
proplabel[DOC_MAX_PROP] Record number of property label
description Record number of description of service
nDescription Number of lines in description
propdesc[DOC_MAX_PROP] Record number of property description
nPropdesc[DOC_MAX_PROP] Number of lines of property description
returnvalue; Record number, return value description
nReturnvalue; Number lines, return value description


Table of Contents

  • No labels