Hypertext Documentation

Hypertext Documentation

Ada-ASSURED has an integrated hypertext subsystem. Documentation is provided as a collection of HTML files. The collection consists of:

Ada-ASSURED documentation for each command, transform, and view.
Ada-ASSURED tutorial for an introduction to the editor.
Ada Language Reference Manual (for both Ada 83 and Ada95).
Software Productivity Consortium (SPC) Ada 95 Quality and Style Guidelines for Professional Programmers (which subsumes Ada 83 Guidelines).

This chapter describes how the documentation is integrated into Ada-ASSURED, and how you can integrate your own documentation into the hypertext web:

Section Web Browser Integration
Section Integrating User-defined Hypertext Documentation

Section Hypertext Links contains additional reference material.

Web Browser Integration

Various Ada-ASSURED commands provide indexed entry into the documentation web:

help-for-editor
loads file top.html, which contains a master table of contents for the hypertext documentation.
tutorial
loads file tutorial-top.html, which contains the starting page of a tutorial for Ada-ASSURED.
describe-command(c)
loads file c.html, which describes command c. If c does not uniquely determine one command, a file is loaded containing a link for each matching command. If c is the null string, the file contains links for all commands.
describe-context
loads the Ada LRM section that describes the syntactic category of the current structural selection.
describe-menus
loads a page that provides access to command descriptions structured like the menus.
describe-transform
loads a hypertext file with a link for each enabled transformation.
describe-view
loads a hypertext file with a link view-v.html for each editor view v.

The first such command to be executed launches a standard web browser as a separate process. Integrations with four commonly used web browsers are provided: NCSA Mosaic, Spyglass Enhanced Mosaic, Internet Explorer, and Netscape Navigator. The default browser is Spyglass Enhanced Mosaic, which is delivered with Ada-ASSURED [X] or the current selected default browser for Windows [MS]. After the web browser has been launched, each subsequent documentation request from within Ada-ASSURED sends it a message requesting that a given location (URL) be displayed. In addition to the commands listed above, Ada-ASSURED supports hypertext links in Ada code. Typically, such links appear in comments. Phrases of the following form are interpreted as hypertext links:

[LRM83 num]
A link to section num of the Ada83 LRM.
[LRM95 num]
A link to section num of the Ada95 LRM.
[LRM num]
A link to section num of the appropriate version of the Ada LRM.
[AQ&S num]
A link to section num of the SPC Guidelines.
[Enum]
A link into the appropriate version of the Ada LRM for Ada-ASSURED error number num.
[Vnum]
A link into the SPC Guidelines for Ada-ASSURED violation num.
[Inum]
A link into the SPC Guidelines for Ada-ASSURED indicator num.

When [Enum], [Vnum], or [Inum] does not correspond to a unique section of the LRM or SPC Guidelines, it points to an intermediate file that contains links to all relevant sections. When the version of the Ada LRM is not specified, it depends on which version of Ada-ASSURED (aa83 or aa95) is running.

Integrating User-defined Hypertext Documentation

The web of hypertext documentation distributed with Ada-ASSURED can be augmented with personal or project-specific files. There are several ways to effectively integrate new documentation with existing documentation:

New links can be edited into existing HTML files.
New commands can be defined that provide access to the documentation.
New link formats can be defined for Ada code that provide point-and-click access into the new documentation.

Suppose, for example, that a project's auxiliary documentation appears in a collection of files doc-n.html, where n is a section number, and that the table of contents for the collection is file doc.html.

New links. Command help-for-editor loads file top.html into the web browser. This file contains a master table of contents for the distributed web documentation. A link to the local table of contents file doc.html can be edited into top.html.

New commands. The following simple script defines a new command local-help and adds it to the Help menu. Executing this command loads the local table of contents file doc.html into the web browser:

(define (local-help) (sg:load-html-file docroot "doc.html"))
(sg:add-command "local-help" local-help)
(sg:add-menu "Help" "Local Help" 0 ##\null #\b
 '() "local-help")

This script assumes that the variable docroot is a string that contains the absolute pathname of the directory where doc.html is located.

Alternatively, the following script would define command local-help to take the section number as a parameter:

(define (do-local-help n) 
  (sg:load-html-file docroot (string-append "doc-" n ".html")))
(define (local-help)
  (sg:make-dialog "do-local-help" "Local Documentation" "Section:" ))

New link formats. Each click of Select within the object pane invokes script procedure sg:follow-edge. If the click was in some text delimited by square brackets, then sg:follow-edge is defined to extract the enclosed text and attempt to load a corresponding HTML page into the browser.

Links can be either logical or physical. A logical link contains a textual descriptor that is mapped to a corresponding physical URL. In contrast, a physical link contains the actual URL in the displayed text. Logical links are (a) more readable, and (b) more transportable because the mapping to physical link is soft and can be changed. Physical links are more flexible because any URL between square brackets can be followed.

End users can easily add new forms of logical link. If the new link is not parameterized, just add it to the hash table sg:hypertext-ht, which maps strings to URL's. For example, to add [Local Documentation] as a link to /u/doc/doc.html, execute:

(hash-table-put! sg:hypertext-ht "Local Documentation" "/u/doc/doc.html")

If the new logical link is parameterized, a URL must be constructed from the parameter. Procedure sg:follow-other-link can be redefined or extended for this purpose. For example, to add [Requirement n] as a link to /u/doc/doc-n.html, where parameter n is a section number, just define sg:follow-other-link as follows:

;;; Load doc-n.html for link in format [Requirement n].
(define (sg:follow-other-link s)
  (sg:load-web-page
    (string-append 
      (regexp-replace "Requirement *" s "file:///u/doc/doc-")
      ".html")))