Document gmniUtility Statement Summary
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 the 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. 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 topic 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 |
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. |
| Code Block |
|---|
| language | none |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
<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.
| Code Block |
|---|
| language | none |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
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.
| Code Block |
|---|
| language | none |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
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.
| Code Block |
|---|
| language | none |
|---|
| theme | Eclipse |
|---|
| linenumbers | true |
|---|
|
deploy docum.bnd REPLACE
|
The above is the listing of the "makesite.bat" file in the source subdirectory of the documentation being viewed. ubtopic>
btopic title="Document Command"> ntent> The <b>Document</b> command is by far the most complex command within the documentation specification. The attributes of this command are as follows: <p/><table> <tr><td><b>Attribute </b></td><td><b>Description</b> </td></tr><tr><td>id </td><td>The identifier of the symbol used to contain this document </td></tr><tr><td>label </td><td>The label to be used in the main tab that accesses this document </td></tr><tr><td>title </td><td>The title of the document to be used in the head section of html pages created for this document </td></tr><tr><td>tooltip </td><td>The tooltip to be shown when the tag for this document is addressed by the mouse. </td></tr><tr><td>href </td><td>The html filename for the frameset "index" file which begins the display of this document. </td></tr><tr><td>header </td><td>The html filename for the header tab display that is used when this document is active. </td></tr><tr><td>body </td><td>The html filename of the initial content to be displayed when this document is activated. </td></tr><tr><td>navigation </td><td>The html filename of the navigation file displayed on the left side that allows the pages within the document to be selected and viewed. </td></tr><tr><td>type </td><td>The type of the navigation selection entries to be used. </td></tr><tr><td>width, height </td><td>The height and width of the navigation selection entries. </td></tr><tr><td>styleSheet </td><td>The filename of the styleSheet to be used with the html pages within this document. </td></tr></table><br/>To make this discussion a bit simpler below is the actual <b>document</b> command which introduced this document. <p/> </p><ac:macro ac:name="code"><ac:parameter ac:name="language">none</ac:parameter><ac:parameter ac:name="theme">Eclipse</ac:parameter><ac:parameter ac:name="linenumbers">true</ac:parameter><ac:plain-text-body><![CDATA[ <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. ubtopic>
btopic title="Page Command"> ntent> The <b>Page</b> command is the final organizational command within the documentation specification. The attributes of this command are as follows: <p/><table> <tr><td><b>Attribute </b></td><td><b>Description</b> </td></tr><tr><td>label </td><td>The label of the page as displayed in the left side navigation buttons or entries. </td></tr><tr><td>href </td><td>The html filename of the file containing the content of the topics introduced within this page. </td></tr></table><br/>The page labels are displayed in the navigation column in the order in which they are defined. By convention the <b>href</b> of the first page should be the same as the <b>body</b> specified by the parent document. </content> ubtopic> <p/> btopic title="Topic Command"> ntent><![CDATA[ The <b>Topic</b> command is the primary command for entering content into the documentation specification. The attributes of this command are as follows: <p/><table> <tr><td><b>Attribute </b></td><td><b>Description</b> </td></tr><tr><td>title </td><td>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. </td></tr><tr><td>name </td><td>Specifies a name for the topic. This attribute is currently deprecated. </td></tr><tr><td>anchor </td><td>An alternative identifier to be used in forming link references to this topic on the page. </td></tr></table><br/>Within the topic the actual content is entered via a <b>content</b> command. The topic may also contain subtopics, it more that one content is to be associated with the topic. These are entered with the <b>subtopic</b> command. </content> ubtopic> <p/> btopic title="Subtopic Command"> ntent><![CDATA[ The <b>Subtopic</b> 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: <p/><table> <tr><td><b>Attribute </b></td><td><b>Description</b> </td></tr><tr><td>title </td><td>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. </td></tr></table><br/>Within the subtopic the actual content is entered via a <b>content</b> command. </content> ubtopic> <p/> btopic title="Code Command"> ntent><![CDATA[ The <b>Code</b> 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: <p/><table> <tr><td><b>Attribute </b></td><td><b>Description</b> </td></tr><tr><td>dir </td><td>Specifies the path containing the referenced source files. </td></tr></table><br/>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. <p/> </p><ac:macro ac:name="code"><ac:parameter ac:name="language">none</ac:parameter><ac:parameter ac:name="theme">Eclipse</ac:parameter><ac:parameter ac:name="linenumbers">true</ac:parameter><ac:plain-text-body><![CDATA[ <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 give Code command.
Though they vary somewhat depending upon the implementation language each source code entry-point description contains the following parts:
- Title -- Short description
- Synopsis
- Description of Service
- Properties of Service
- 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 -- it's type it's 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. These 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. ubtopic>
btopic title="Content Command"> ntent> his command has no attributes. It contains text with optional marginal nnotations. Each line of the text is simply entered from the margin to the nd of the record. The margin annotation itself is the record associated nformation. Note the width of the margin is always the number of blanks t the front of the first record. If there are no blanks then there are no argin annotations for the text. Text is stored as a starting record number nd a record count. <p/> he two margin characters that are recognized are '|' and '/'. The bar indicates hat the lines are to be entered into the HTML page exactly as they are ntered in a fixed font. The slash when associated with a line forces a line reak. <p/> n addition to annotations, text is also searched for lines ending in a colon. uch lines are assumed to introduce lists of some sort that receive special TML tags to make them standout. There are four types -- Ordered_text, able_list, unordered_list, and unordered text. <p/> rdered_text is initiated when the first line non-blank line following a line nding in a colon begins with a numeric character. The entries may have ultiple lines which are identified via a secondary margin. <p/> able_list is initiated when the second line after a line ending in a colon tarts with a minus sign. The entries may have multiple lines which are dentified via a secondary margin. <p/> 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. <p/> Unordered_text is initiated after a line ending in a colon and none of the above apply. </content> ubtopic> btopic title="Tool specific Processing"> ntent><![CDATA[ hough the documentation capability uses the text processing and information torage services of <b>IMSLIB</b>, the tool itself contains the logic needed o load the documentation structures into the current storage area, to rocess the documentation embedded in the source codes files, and to produce he terminal level Html for the text components when the documentation is uthored. </content> ubtopic> btopic title="Documentation Storage Structures Used"> ntent> re are four structures used by the documentation component: <p/><table> <tr><td><b>ame </b></td><td><b>Description of use</b> </td></tr><tr><td>Document </td><td>Describes a document within the documentation </td></tr><tr><td>DocPage </td><td>Controls a set of topics or a set of documents </td></tr><tr><td>DocTopic </td><td>Contains the actual text on some topic </td></tr><tr><td>DocCode </td><td>Contains code documentation taken from code comments </td></tr></table><br/> tDocument and tDocPage structures are navigational. They contain information ut how the documentation should be identified, organized, and formatted. They tain no actual textual content. <p/> tDocTopic structure and tDocCode which extends it contain the actual content the documentation. This content can be a main topic, a subtopic, or derived e documentation. <br/> <H2>The tDocument Structure</H2> The <b>tDocument</b> structure retains the information supplied by the <b>Document</b> command. The tDocument symbols in the storage area are classified by the <b>id</b> attribute of the command. The remaining properties correspond on a one-to-one basis with the other command attributes. The properties are as follows: <p/><table> <tr><td><b>Property </b></td><td><b>Description</b> </td></tr><tr><td>label </td><td>This integer property contains the offset in storage of the label to be used in the main tab that accesses this document </td></tr><tr><td>title </td><td>This integer property contains the offset in storage </td></tr><tr><td>title </td><td>of the title of the document to be used in the head section of html pages created for this document </td></tr><tr><td>styleSheet </td><td>This integer property contains the offset in storage of the filename of the styleSheet to be used with the html pages within this document </td></tr><tr><td>tooltip </td><td>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. </td></tr><tr><td>href </td><td>This integer property contains the offset in storage of the html filename for the frameset "index" file which begins the display of this document. </td></tr><tr><td>header </td><td>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. </td></tr><tr><td>body </td><td>This integer property contains the offset in storage of the html filename of the initial content to be displayed when this document is activated. </td></tr><tr><td>navigation </td><td>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. </td></tr><tr><td>type </td><td>This integer property contains a code indicating the type of display to be used for the navigation page -- anchor string (1) or buttons (2). </td></tr><tr><td>width </td><td>This integer property contains the width in pixels to be allowed for the navigation page. </td></tr><tr><td>height </td><td>This integer property contains the height in pixels to be allowed for any buttons on the navigation page. </td></tr></table><br/>The child structures of the <b>tDocument</b> structure are all <b>tDocPage</b> structures. <br/> <H2>The tDocPage Structure</H2> The <b>tDocPage</b> 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 <b>tDocument</b> structures and as their children. Its single property is as follows: <p/><table> <tr><td><b>Property </b></td><td><b>Description</b> </td></tr><tr><td>href </td><td>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. </td></tr></table><br/>The child structures of the <b>tDocPage</b> structure are all <b>tDocTopic</b> structures. <br/> <H2>The tDocTopic Structure</H2> The <b>tDocTopic</b> structure is used to contain the content to be shown. It is created by the <b>Topic</b>, <b>Subtopic</b>, and <b>Code</b> commands. Its properties as are follows: <p/><table> <tr><td><b>Property </b></td><td><b>Description</b> </td></tr><tr><td>content </td><td>This integer property contains the root address of the variable information stream containing the actual content records. </td></tr><tr><td>refType </td><td>This integer property contains a code indicating the type of the content -- topic (1), subtopic (2), or code documentation (3). </td></tr><tr><td>anchor </td><td>This integer property contains the offset in storage of the anchor string to be used in authoring on-page subtopic links. </td></tr><tr><td>name </td><td>This integer property contains the offset in storage of a name to be associated with the topic text. </td></tr></table><br/>The child structures of the <b>tDocTopic</b> structure are all <b>tDocTopic</b> structures containing subtopics. <br/> <H2>The tCodeDoc Structure</H2> The <b>tCodeDoc</b> structure extends the <b>tDocTopic</b> structure to partition the text content it its logical parts. Its additional properties are all line numbers or counts within the text content as follows: <p/><table> <tr><td><b>Property </b></td><td><b>Description</b> </td></tr><tr><td>includename </td><td>Include name </td></tr><tr><td>includedesc </td><td>Include description </td></tr><tr><td>servtype </td><td>Record number of service return type </td></tr><tr><td>nProperty </td><td>Number of service properties </td></tr><tr><td>proptype[DOC_MAX_PROP] </td><td>Record number property type description </td></tr><tr><td>propname[DOC_MAX_PROP] </td><td>Record number of property name </td></tr><tr><td>proplabel[DOC_MAX_PROP] </td><td>Record number of property label </td></tr><tr><td>description </td><td>Record number of description of service </td></tr><tr><td>nDescription </td><td>Number of lines in description </td></tr><tr><td>propdesc[DOC_MAX_PROP] </td><td>Record number of property description </td></tr><tr><td>nPropdesc[DOC_MAX_PROP] </td><td>Number of lines of property description </td></tr><tr><td>returnvalue; </td><td>Record number, return value description </td></tr><tr><td>nReturnvalue; </td><td>Number lines, return value description </td></tr></table><br/><br/> </body> </div></div><div class="cell aside"><div class="innerCell"><ac:macro ac:name="panel"><ac:parameter ac:name="bgColor">CCFFFF</ac:parameter><ac:parameter ac:name="title">Table of Contents</ac:parameter><ac:rich-text-body><p><ac:macro ac:name="toc" /></p></ac:rich-text-body></ac:macro></div></div></div></div> </html>