DOSFOP Manual

Literate Programming of OPAL programs

Klaus Didrich


Copyright © 1997, 1998, 1999

Introduction

DOSFOP, the documentation system for OPAL projects, is a literate programming tool, i.e. documentation and program code are kept in the same file. Documentation is integrated into OPAL source code by means of special marked comments.

The DOSFOP approach tries to make documentation more acceptable to programmers by adhering to the following principles:

The tool was presented at the tool session at TAPSOFT'97
(see http://uebb.cs.tu-berlin.de/papers/published/DocumentationToolOpal.html), and a technical report is available (see http://uebb.cs.tu-berlin.de/papers/published/TR96-4.html) which describes the DOSFOP approach to software documentation.

This manual contains technical details for the use of DOSFOP, version 1.92g (for changes from older versions, see Changes).

DOSFOP's Architecture

DOSFOP takes input from three different sources:

DOSFOP does not directly produce documentation, rather it generates an intermediate output file in the Texinfo language. This intermediate output can then be converted to DVI files for printed output, to INFO files for the GNU info help system and to HTML files for web browsers.

Before documentation can be produced, the user must set up the global configuration (see Global Configuration) and the project data base (see Project Browser).

DOSFOP's History

A first prototype of the system was developed by Torsten Klein as his Studienarbeit -- undergraduate dissertation -- and was further enhanced by user-friendly features as part of his master's thesis, both of which were supervised by the author of this manual.

The system was developed in OPAL itself, with the exception of the graphical user interface, which was developed in TCL/TK.

Since the completion of Torsten Klein's master's thesis, the DOSFOP system has been maintained and developed by Klaus Didrich.

The current version is 1.92g.

Using DOSFOP

Dosfop needs no adjustment of environment variables. The variable DOSFOP, which was mandatory in former versions, may be set to point to a non-standard DOSFOP installation, if necessary.

DOSFOP requires two directories, both of which are initialized automatically.

DOSFOP
The DOSFOP subdirectory is used to store intermediate output and administrative data.
doc
The doc subdirectory contains the generated documentation. If the user does not change the default, the (root) output files are called `doc/out.dvi', `doc/out.info' and `doc/out.html' for DVI, INFO and HTML format, respectively. There is always an additional top-level HTML file `index.html'. Note that there may be more than one file for INFO and HTML format. See Administrative Data to change the name of the generated file.

Writing Documentation

Documentation is incorporated in OPAL source code in the form of special comments. Every comment that starts with a per cent sign (`%') is treated as documentation. All other comments are treated as source code.

The documentation is written in Texinfo, the same language used for documentation of GNU utilities. Those who know TeX but not Texinfo should refer to the Appendix (see Texinfo for Experienced TeX Users).

A hypertext documentation of Texinfo is locally available at TU Berlin.

Project and Subsystem Surveys

There are two ways to include a survey of a project or a subsystem. Either insert the survey into the documentation by configuring or create a file `Survey.texi' at toplevel or the path to the subsystem respectively.

Structure Surveys

The first documentation of an OPAL signature part is considered to contain an overview of the structure's contents, provided it appears before the initial keyword SIGNATURE.

Source-Code Documentation

Every comment that starts with a per cent sign(`%') is treated as documentation. This applies to line comments and nested comments.

There are five types of source-code documentation available.

Ordinary documentation
Ordinary documentation is any documentation that does not belong to the remaining four categories. Ordinary documentation may contain arbitrary Texinfo text. Example:
-- %This function computes the length of a sequence.
Tagged documentation
Tagged documentation (also called level documentation) is ordinary documentation with an additional tag. This tag appears in curly brackets immediately after the initial per cent sign. Example:
/* %{optimize} This function needs further attention 
   if used with bigger arguments.
*/
The name "level documentation" originates in the intention to provide documentation for different `levels' of users. In GRASP the same concept is called ribbon.
As a default, tags are ignored (i.e. tagged documentation is treated like ordinary documentation). You may configure globally or for subsystems (see Global Options) that the level mechanism is turned on. In this case, you must provide a set of tags that are included.
If level handling is turned on, documentation tagged with tag is enclosed in a pair of macro calls, @BEGINDOCtag and @ENDDOCtag. These macros must be defined by the user! Macros for the above example might be:
@macro BEGINDOCoptimize
@strong{optimize:}@i{
@end macro
@macro ENDDOCoptimize
}
@end macro
which would generate the following documentation:
optimize: This function needs further attention if used with bigger arguments.

Documentation sectioning
In addition to the structuring provided by DOSFOP, it is useful to insert additional headings into the source code. Headings are marked by between one and four dollar signs (`$') after the initial per cent sign. The number of dollar signs indicates the sectioning level relative to the structure heading. The heading must be closed by a single dollar sign.
Example:
-- %$$Accessing elements of a sequence$
Note that the total number of sectioning levels required by the documentation may be less than that provided by the formatting tool. The characters used for the heading must be suitable for several tools and may therefore not contain punctuation.
Hidden documentation
Hidden documentation is marked by a minus sign after the initial per cent sign. Unlike OPAL comments, hidden documentation does not appear at all in the generated documentation.
Example:
-- %- Check below carefully for typos!
Property references
Property references consist of the name of a law enclosed in square brackets. The reference is replaced by the law itself.
The point is that property references may occur in the signature and implementation parts of a structure, and that they are treated correctly even if the property parts are not included in the generated documentation.
Example:
FUN ++ : seq ** seq -> seq
-- %[++_assoc]

The Graphical User Interface

The graphical user interface is invoked by the command dosfop. The DOSFOP main window provides buttons to start other programs needed for producing documentation.

The components:

File (menu)
Close the DOSFOP main window and the DOSFOP execution window.
Help (menu)
Provide global or context-sensitive help.
DOSFOP: documenting project (title)
The project is the title given in the global configuration.
Global configuration
Edit administrative data and global switches. See Global Configuration.
Project browser
Enter structures and subsystems of the project. Local configuration of subsystems and structures. See Project Browser.
Check configuration consistency
Check whether the source code and abstract syntax (interopal) files are present. Result is presented in the DOSFOP execution window.
Start DOSFOP
Start generation of intermediate Texinfo documentation. Progress is presented in the DOSFOP execution window. Errors and warnings encountered during the translation are repeated at the end.
This button does not invoke the consistency check any more.
convert to DVI
convert to Info
convert to HTML
Start conversion of the intermediate Texinfo documentation into the respective format. Progress is presented in the DOSFOP execution window. These buttons are disabled if no intermediate documentation is present. They turn red if the intermediate documentation is newer than the output available in the respective format.
DVI previewer
Info hypertext reader
HTML viewer
Invoke a (pre)viewer for the respective format. These buttons are disabled if the documentation is not available in the appropriate format. There are three environment variables which may be set if the default is not convenient:
XDVI
The name of a previewer for DVI files.
INFO
The name of a previewer for INFO files.
WWWBROWSER
The name of a browser for HTML files.
ALl of these are called with file name to be displayed as their argument. Note that all should open a separate window and should consist of a single name (no arguments).

Global Configuration

Global Configuration consists of administrative data and global options for customizing the documentation. On the first call, only the administrative data is displayed; on pressing a button, all the switches are displayed. The configurator is an independent process and is not closed when the DOSFOP main window is exited.

Changes are only effected after the settings have been saved.

Administrative Data

File (menu)
Three options for saving the changes and exiting the configurator, for saving the changes, or for discarding the changes and exiting the configurator.
Help (menu)
Invoke a window with global or context-sensitive help.
Root-location of the Project
This is the location where DOSFOP looks for structures at the `top level'.
Intermediate code output file
This is the name of the file where DOSFOP stores the intermediate Texinfo output. The default is root-location/DOSFOP/out.texi. You may change out in order to change the name of the generated files in the doc directory (see Using DOSFOP). Note that this file contains the surveys and the structure of the docuemntation only. Documentation of structures is located in their associated `OCS' subdirectory.
Top structure name
The name of the top structure of the project, which must be located at the Root-location (see above). DOSFOP will include all structures which are directly or transitively imported by the top structure in the documentation.
You may use the special name * to indicate that all structures contained in the project data base should be included. Note that this set must be closed under the import relation (with the exception of library structures).
Name of the project
Authors' names
Date of creation
These entries are used for the title page. The name of the project also appears in the DOSFOP main window.
Display all options
Display switches for global options (see Global Options).

Global Options

Options marked with SUB can be configured individually for subsystems, those marked STR can be configured individually for structures.

Survey (SUB)
Introduction to the documentation (or the subsystem). Note that this information is ignored, if a file `Survey.texi' exists at the time the documentation is generated. In this case, the survey is included from that file.
Macros
This feature has been made obsolete by the introduction of macros into Texinfo.
Level mechanism (SUB, STR)
Treatment of tagged or level documentation (see Source-Code Documentation).
No Level Handling
Tagged documentation is treated as ordinary documentation.
Modify Levels
You may edit a list of tags. Tagged documentation is only included if its tag is an element of this list. Note that you must provide macros BEGINDOCtag and ENDDOCtag (see Source-Code Documentation).
Functionality index
Generate a functionality index. Identifiers can be annotated with the instantiation, with the instantiation and the origin, or with all components.
In fact, this switch controls several indices:
Function Index
Function Index By Domain
Function Index By Codomain
Functions declared in structures of the project sorted alphabetically, by types in their domain and their codomain, respectively.
Sort Index
Sorts declared in structures of the project.
Property Index
Algebraic properties (laws and free type declarations) from structures of the project.
Application Index
This switch controls two indices:
Index to the places where functions are applied. Verbosity is the same as with the functionality index. You may additionally decide to index applications of library functions. See Files in the Project Data Base, for what DOSFOP considers to be a library file.
Definition index
Index to the places where functions are defined. Verbosity is the same as with the functionality index.
Concept index
Insert a concept index. The user must define entries by adding @cindex entry lines in the documentation.
Structure index
Alphabetic index of all structures (without libraries).
Subsystem inclusion
Include only top-level structures or top-level structures and all subsystems.
Library inclusion
Include the library files referenced from other files in the generated documentation.
Property inclusion (SUB, STR)
Also include external and (if "include only interfaces" -- see below -- is off) internal property parts of structures.
Include only interfaces (SUB, STR)
If on, include only signature and (if "property inclusion" -- see above -- is on) external property parts of structures,
Hierarchy visualization (SUB)
Include graphic visualization of dependencies between subsystems and/or structures of a subsystem.
This option is mainly for use in printed documentation, but works for all three output formats.
Sort structures (SUB)
Structures cannot be sorted by the user. DOSFOP can sort the structures according to their dependencies, top-down or bottom-up, alphabetically, or not at all.
Import referencing (SUB, STR)
Include links to imported structures, with or without library structures.
Used function tables (SUB, STR)
At the end of a section, include a table for every function defined in that section which lists the function it references. For the verbosity, see above: functionality index.
Basic language
Generate English or German section names.
Start new pages (SUB, STR)
Start new pages where necessary.
Drop empty lines (SUB, STR)
Remove empty lines between documentation and source code.
Structure in single node
This option has (almost) no effect on printed output. For INFO and HTML output, all parts and the overview are put into a single node. This is useful when most structures are not documented as a few less mouse clikcs are needed to access information.

Project Browser

The project browser is used to edit the project data base, that is, the information as to which structures are part of the project and how are they grouped into subsystems. The project browser always starts at `top level'. It is a separate process and not closed when the DOSFOP main window is closed.

Changes to the project data base are immediately effective.

Structures

The left-hand side contains a list of the structures of the project that are located in the current subsystem.

Delete
The marked structure is deleted.
Insert
You may insert a new structure name, either by typing it in or by using the file browser (see File Browser). Click on Exit when all structures have been entered.
Rename
The marked structure may be given a new name.
Config global
Config
Configure each structure of the subsystem or the marked structure individually. See Global Options, for the available options.

Subsystems

The right-hand side contains a list of the subsystems of the current subsystem.

Level up
This button -- immediately above the list -- takes you to the parent subsystem. It is not displayed at the top level.
Delete
Delete the marked subsystem.
Insert
Insert a new subsystem. The name of the new subsystem (to be used in headings) and its path are required. You may again use the file browser (see File Browser) to facilitate your work.
After clicking insert, move the mouse to the list of subsystems and click on the subsystem before which the new subsystem is to be inserted.
Rename
Rename the marked subsystem. (You cannot change the path.)
Move
Move the marked subsystem. After clicking on the move button, click on the structure before which the marked structure is to be inserted.
Config
Edit options for the marked subsystem. See Global Options, for the available options. Additionally, the path to the subsystem may be changed.

File Browser

The file browser can be invoked when inserting either structures or subsystems. It is again a separate process which must be terminated explicitly. You need (and should) not have more than one file browser open at one time.

You can change the current directory by double-clicking on the directory name in the list.

Insertion of structures is done by double-clicking on the file name. In the case of OPAL files, the extension (`.sign', `.impl', `.extp', `.intp') is removed from the file name. All other file names are left as they are. (see DOSFOP and Non-OPAL Programs). The file is immediately inserted into the structures of the current subsystem.

Insertion of subsystems is done by double-clicking on the directory name above the list widget. You must then provide a name for the subsystem and insert it yourself.

DOSFOP without Windows

DOSFOP can also be invoked without the graphic user interface. This may come in handy if neither the project data base nor the global options have been changed.

The program is called pureDosfop. The following options are available:

-addonly
This switch is followed by names of structures which are added to the `DOSFOP/only' file. (see Incrementally Generating Documentation)
-cc
Identical to the button 'Check Configuration Consistency'.
-clearonly
Remove the `DOSFOP/only' file. (see Incrementally Generating Documentation)
-config
Construct the file `config' from its parts. Must be used if the configuration has been changed manually. (See also Files in the Project Data Base.)
-configascii
-configbin
DOSFOP can read the configuration either in ASCII (readable) format or in binary format (which is stored in `DOSFOP/config.bin'. If both files exist, DOSFOP reads in the newer one and writes a new binary configuration. The switch -configascii removes the binary configuration. The switch -configbin switch creates a dummy binary configuration and causes DOSFOP to create a real one in the next run. The binary configuration can be quite large.
-dosfop
Construct the intermediate Texinfo output.
-dvi
-info
-html
Construct the DVI file (INFO file, HTML files) from the intermediate Texinfo output.
-qhtml
Construct the HTML files from the intermediate Texinfo output, using only structures in `DOSFOP/only'. This is faster but may result in dangling links and incomplete indices.
-usage
A short usage message.

Calling pureDosfop with no option is identical to calling pureDosfop -dosfop.

DOSFOP and OCS

OCS has been extended by some targets which allow the automatic generation of documentation of an OPAL project. The configuration may afterwards be edited with the standard dosfop program.

The MAKE mechanism is not well suited for DOSFOP, we had to compromise. For one, documentation is always generated anew and not if the respective source code has changed. Second, an environment variable PROJECTROOT must be defined, which contains the absolute path to the top level directory.

Incremental generation of documentation (see Incrementally Generating Documentation) is supported. If the environment variable PROJECTROOT is defined, every time a structure is compiled its name is added to the `DOSFOP/only' file. A call `ocs doc' or `ocs dvi' will then only generate new documentation for the changed files. The `DOSFOP/only' file is always removed afterwards.

DOSFOP often uses a large amount of resources (even for nowadays' computers), and it may happen that documentation cannot be generated at once. The following targets help in these cases.

The calls `ocs doc' and `ocs thisdocall' have similar effects. The latter one calls dosfop for every subsystem and may not correctly compute the hierarchy visualization correctly. On the other hand, it often works, where `ocs doc' fails for lack of resources.

DOSFOP and OASYS

If OASYS is used, the usage of DOSFOP is made much simpler. Simply execute the line

<DOSFOP path>/tcl4/dfo.tcl

from the OASYS command line or include this line in your `.oasysrc' file. You need not change your PATH variable. The DOSFOP distribution is searched for as follows:

  1. If the environment variable DOSFOP is set, its contents are used.
  2. If the environment variable OCSDIR is set, DOSFOP is sought under `$OCSDIR/dosfop'.
  3. If neither DOSFOP nor OCSDIR are defined, `/usr/ocs/dosfop' is used.

Within OASYS, four additional commands are available:

doc-dvi
doc-info
doc-html
These commands construct the DOSFOP data base from the OASYS data base, invoke the DOSFOP translation to construct the intermediate Texinfo output, and finally convert Texinfo to the desired output format. Only the necessary steps are performed.
doc-help
Provide a brief introduction to these commands.

DOSFOP and Non-OPAL Programs

DOSFOP can incorporate non-OPAL sources. To use this feature, create a file `dosfop.filetypes' in the DOSFOP directory with the following content:

The file `dosfop.filetypes' is searched in the given order and before an OPAL signature file is searched.

Example file:

# almost standard OPAL (note leading space for documentation designator!)
.sign:.impl:--:/*:*/: %:
# C files (assuming .h to be the interface for .c)
# empty documentation designator -> all comments are documentation
.h:.c: :/*:*/: :
# Tcl files
.tcl: :#: : : :
# SysDefs file
SysDefs: :#: : : :
# Modula-2 files
.md:.mi: :(*:*): :

Note that scanning still obeys the OPAL rules. For example, /* is not regarded as a valid comment starter for `.h' or `.c' files if followed by a special character. In particular, /*******/ is not recognized as a comment.

Other problems might occur if string constants are denoted differently than in OPAL, but so far we have had no problems in this regard.

You should make sure that DOSFOP does not search for structure parts that do not exist (property inclusion should be off; only interfaces should be off if no implementation exists). `Check Consistency' has not been adapted yet and will complain if you include foreign structures.

DOSFOP puts the intermediate output for structure located at path into a subdirectory path`/OCS'. You must ensure that this directory exists.

DOSFOP can incorporate import references and indices generated by other programs:

For file `foo', the imported structures are contained in `DOSFOP/foo.deps' (`foo' includes the suffix), each line containing one structure name.

The index entries have to be given in file `DOSFOP/foo.index'. Every line has the following format

<line number>:<index generating command>:<index entry>

Line numbers start with zero! The command for generating the index entry could for example be @findex or @pindex. The index entry may contain other colons. Escaping of Texinfo special characters is done by DOSFOP.

The files `DOSFOP/foo.{deps,index}' are not mandatory.

Incrementally Generating Documentation

DOSFOP can generate documentation incrementally. To use this feature, create a file `only' in the `DOSFOP' subdirectory which contains the names of structures (one in each line), for which documentation shall be generated. The same name may occur several times in the file.

If the file `DOSFOP/only' exists, DOSFOP will generate the `DOSFOP/out.texi' file and the documentation files for the structures named in the `only' file.

There is a switch -qhtml for the program pureDosfop. The generation of HTML files will in this case cover the main file, the indices and the files associated with structures referred to in `only'. Note that this may produce dangling links and incomplete indices.

The Texinfo Environment for DOSFOP

TeX macros

The following macro packages are available for use in printed manuals:

dosfopLatin1.sty
Characters from the ISO-8859-1 (latin1) character set can be used directly for DVI, for INFO and for HTML files.
psfig.tex
Macros to include postscript figures.
pstricks.tex
The pstricks macro package is included.
pst-node.tex
Macros to draw nodes in graphics for the pstricks package.

Some other macros are defined for the construction of used function tables and the table of contents. Indentation and skip between paragraphs are defined.

Texinfo setup

The following switches are set:

@setchapternewpage off
@finalout

These indices are used by DOSFOP: st, ap, cd, dm, pr. The predefined indices are also reserved for use by DOSFOP. Indices starting with the letters `x', `y' and `z' will not be used by DOSFOP.

The variable @dfStarLine is used. Further variables will all use the prefix `df'.

Predefined Macros

The following macros may be used to reference structure parts in @ref, @xref or @pxref commands:

@Sign{structure name}
@Impl{structure name}
@Extp{structure name}
@Intp{structure name}
@LibSign{structure name}
@LibExtp{structure name}

For other predefined macros which are not designed to be used in documentation, see TeX- and Texinfo-Related Files.

Switches

Some options are translated to variables:

html
Set iff HTML output is produced. (see Conditionally Visible Text)
colon
Set to `:' if DVI or HTML output is produced; set to `;' if INFO is produced. This is used to overcome difficulties with info's inability to include colons in entries.
structureindexflag
Set iff a structure index is part of the generated documentation.
dfDomainIndexFlag
Set iff a function index by domain is part of the generated documentation.
dfCodomainIndexFlag
Set iff a function index by codomain is part of the generated documentation.
dfEnglish
Set iff the chosen language is English.
dfGerman
Set iff the chosen language is german.
dfSingleNode
Set iff all parts of a structure are to be part of a single node.
dfProjectName
Set to the project title.
dfAuthors
Set to the authors' names.
dfDate
Set to the date.
dfSorttop_down
dfSortbottom_up
dfSortalphabetically
dfSortuser_defined
dfSortoff
Set iff the respective option for sorting structures has been chosen.

Conditionally Visible Text

While most text shall be used for all three output formats, sometimes it is desirable to include text in only one of the formats, or even to pass text untouched by Texinfo directly to TeX or HTML.

This is possible with the following Texinfo environments:

@iftex
@end iftex
Text in this environment is processed by Texinfo and then passed on to TeX and HTML. If this text is not passed to HTML, you may use TeX commands, except that you must replace the `\' with an `@'.
If you want to exclude HTML, enclose this environment in the environment @ifclear html/@end ifclear.
@tex
@end tex
Text in this environment is passed directly on to TeX, so you may enter plain TeX here.
@ifset html
@end ifset
Text in this environment is processed by Texinfo and then passed on to HTML.
@ifinfo
@end ifinfo
Text in this environment appears only in the INFO output.
@ifhtml
@end ifhtml
Text in this environment is passed directly on to HTML; you may thus enter HTML tags here.

Macros and Conditions

Instead of putting the condition inside the macro, one should define the macros conditionally:

@ifset html
@macro TEXT
This text shows up in HTML.
@end macro
@end ifset
@ifclear html
@macro TEXT
This text shows up in TeX and Info.
@end macro
@end ifclear

The Files DOSFOP Uses

TeX- and Texinfo-Related Files

These files are located in the directory <DOSFOP path>`/tex'.

The following files may be modified by the user by placing a copy in the local `DOSFOP' directory.

`dosfopPrelude.tex'
TeX commands which must be carried out, before `texinfo.tex' is included (which resets some category codes).
`dosfopPrelude.texi'
Texinfo commands to set up variables, indices and the like. Some files are included from other packages.
`dosfop.macros'
Texinfo macro definitions. Many of the macros contained here are used to generate headings and node names. You may change these freely (for example, for a new language), but should ensure that all parameters are used when constructing node names, otherwise the uniqueness of node names is no longer guaranteed. The following macros are of particular interest :
@BEGINOPAL{}
@ENDOPAL{}
Every piece of OPAL source code is surrounded by a call to these macros. The default is @example/@end example.
@BEGINDOC{}
@ENDDOC{}
Every piece of documentation -- with the exception of the surveys -- is enclosed in a call to these macros. The default is @value{dfStarLine} for both, which will put a line consisting of 70 `*' around documentation in INFO output. No effect on DVI or HTML output.
@BEGINOVW{}
@ENDOVW{}
Every survey (project, subsystem, structure survey) is enclosed in these macros. They are empty by default.
@FINALIZEDOC{}
This macro is called at the very end of the documentation. The default definition is @contents.

TeX Styles

These files are included to make the DOSFOP distribution self-contained.

dosfopLatin1.sty
This style file defines TeX commands to allow usage of characters from the ISO-8859-1 (latin1) character set. These are no longer strictly necessary anymore, because Texinfo provides commands for these characters now.
psfig.sty
psfig.tex (1.9)
pst-node.tex (0.93a)
pstricks.con (0.93a)
pstricks.sty
pstricks.tex (0.93a)
Some files from the pstricks package.
texinfo.tex (2.185)
A very recent version of the Texinfo macro package; DOSFOP will not produce correct DVI output if older versions are used.

Files in the Project Data Base

The project data base and the global and local options are stored in files in the DOSFOP directory. They may be edited by the user.

`config'
This file contains the entire project data base and the option settings. It is read in by the DOSFOP translation program and is not affected by changes to other files.
Note that the file `config' is frequently rebuilt from the parts. It is therefore not advisable to edit this file --- a better option is to edit one of the parts and call pureDosfop -config (see DOSFOP without Windows).
`Toplevel.config'
Contains the administrative data and the global option settings.
`subsystem name.config'
Contains administrative data and option settings for the specific subsystem.
`subsystem name.names'
Contains the names of the subsystems of subsystem subsystem name. (Spaces have already been replaced by underscores).
`structure name.config'
Contains the local option settings for this structure.
`Library.config'
Contains the subsystem structure of what DOSFOP considers the `library'. Every structure in this file is considered to be a library structure. This file is normally read from DOSFOP-path/defaults/Library.config, but you may copy it to the local DOSFOP directory and modify it.

Backup files are given the extension `.old'.

Other Files

There are some other files located in the DOSFOP directory.

`dosfop.switches'
Constructed every time the translation to Texinfo is started. This file contains variable settings which change according to the global option settings. See Switches, for an explanation of the switches.
`diagnostics'
This file contains all warnings encountered during the translation to intermediate output.
`lastChange'
This file is `touch'ed every time the global configuration changes.
`options.data'
This file contains X defaults for the graphical appearance of the windows of the graphical user interface.

The Programs DOSFOP Uses

Most programs named in this section are located in <DOSFOP path>/bin, if not otherwise stated.

DOSFOP Programs

These are the core programs of DOSFOP, all written in OPAL.

checkConsistency
This programs verifies the existence of all source-code files and associated interopal files.
It is called with one argument: the top-level directory.
dosfopTranslator
This program reads the project data base and the global configuration found in the DOSFOP subdirectory and produces the Texinfo intermediate output.
It is called with the top-level directory as the current directory and without arguments.
getsetting
It extracts the local settings for a structure or a subsystem.
It is called with two arguments: the name of the subsystem or the structure and the top-level directory as the second argument.

Graphical User Interface

The TCL/TK programs are located in the directory <DOSFOP path>/tcl.

The files ending in `.tcl' are read by the main programs; the other programs are started as separate processes.

browse
Call the project browser.
dosfop
Open the DOSFOP main window.
globalConfig
Edit the global options.
pureDosfop
Call DOSFOP without using windows.
structureConfig
Edit the local options of a structure, whose name must be given as a parameter.
subsystemConfig
Edit the local options of a subsystem, whose name must be given as a parameter.

Programs for Producing DVI Files

dosfopMacroExpander
This program is used instead of makeinfo for the expansion of macros (see External Interpreters).
dosfopTexindex
This program is needed as an wrapper ofthe texindex program. The generated indices need to be processed before and after the call to texindex (see the following entry).
fixtexindexpre
fixtexindexpost
The generated indices have some flaws and bugs which are corrected by these two scripts.
fixtexindexpre removes \penalty 10000 from the index entries and corrects name entris starting with a backslash.
fixtexindexpost disables hyphenation of the function arrow and corrects the initial letter of names starting with underscore.
texi2dvi --verbose <intermediate Texinfo file>
This program controls the production of a DVI file from a Texinfo file. Note that we need Version 1.11 or newer (the Texinfo 3.9 distribution contains Version 1.10). Three environment variables are set before the call to texi2dvi:
TEXINDEX dosfopTexindex
-- to replace the standard texindex program with the DOSFOP version.
TEXINPUTS .:<DOSFOP path>/tex:<old value of TEXINPUTS>
-- to ensure that files included by the generated Texinfo file are found at the proper places.
MAKEINFO dosfopMacroExpander
-- to replace makeinfo as the macro-processing program.
Before texi2dvi is called, the current directory is changed to the DOSFOP directory.
texindex
This program is needed to process the indices for DVI output.

Programs for Producing INFO Hypertext

Formerly, the INFO format was the only supported hypertext output. Nowadays, INFO output is rarely used; you can achieve a similar effect with an ASCII web browser like lynx. Support for INFO output may not be available in future versions of DOSFOP.

dosfopMacroExpander
This program is used instead of makeinfo for the expansion of macros (see External Interpreters).
The program is called with these parameters:
dosfopMacroExpander --verbose -I <DOSFOP subdirectory>
                    -I <DOSFOP path>/tex 
                    -E <intermediate Texinfo file>.new 
                    <intermediate Texinfo file>
makeinfo
The makeinfo program generates the INFO file. It is known to have difficulties with long Texinfo files.
It is called with the following parameters:
makeinfo --verbose --no-validate --no-warn -I DOSFOP 
         -I <DOSFOP path>/tex 
         <intermediate Texinfo file> 
         -o <info output file>

The program is called with the top-level directory as the current directory.

Programs for Producing HTML Hypertext

dosfopMacroExpander
This program is used instead of makeinfo for the expansion of macros. (see External Interpreters).
The program is called with these parameters:
dosfopMacroExpander --verbose -I <DOSFOP subdirectory>
                    -I <DOSFOP path>/tex 
                    -E <intermediate Texinfo file>.new 
                    <intermediate Texinfo file>
texi2html
This program was originally written by Lionel Cons at CERN and has been adapted to the special needs of generating documentation (copying the links from the INFO file, better presentation of indices and some other more minor adjustments).
The program is called with these parameters:
texi2html -toc_name <Table of Contents string> 
                    -I ../DOSFOP -I <DOSFOP path>/tex 
                    -split_node -menu -verbose 
                    <intermediate Texinfo file>
The <Table of Contents string> is a language-dependent string used for links to the top node. The program is called with the top-level directory as the current directory.

External Interpreters

While the translation to the intermediate Texinfo file does not rely on external interpreters, some of the programs which form the environment do. These interpreters are listed here. We also include the description of the dosfopMacroExpander here, because there is no better place for this.

sh
The sh interpreter is used for texi2dvi and dosfopTexindex.
perl
Perl is used for dosfopMacroExpander, fixtexindexpre, fixtexindexpost and texi2html. These programs run both under Perl 4 and Perl 5. The location of perl is read from the environment variable PERL which is set by dosfop and pureDosfop.
wish
TCL/TK Version 4.1 (or newer) is used for the graphical user interface and the integration of DOSFOP and OASYS. The location of wish is read from the environment variable WISH which is set by dosfop and pureDosfop.
dosfopMacroExpander
The macros, which were introduced into the latest Texindex edition (version 3.9, October 1996) are expanded by a call to the makeinfo program. Unfortunately, the macro expansion in makeinfo is not bug free, so I decided to re-implement a separate program for macro expansion. This implementation has some restrictions:

Tips and Tricks

This appendix contains some tips and tricks for achieving certain effects through sophisticated usage of Texinfo and the possibilities for (re)defining macros. In most cases you will need to copy the file(s) `dosfop.macros' and/or `dosfopPrelude.texi' from `<DOSFOP path>/tex' and modify them.

Trouble-shooting:

Commands are not processed and appear verbatim in the generated documentation.
Some commands are allowed only at the beginning of a line, not even spaces or tabs may occur before them. If this happens to commands introduced by a macro, start the macro with an empty line.

Coloured Source Code

To make your source code appear in a different colour in HTML hypertext, use these definitions:

@macro BEGINOPAL
@ifhtml
<font color="8B000">
@end ifhtml
@example
@end macro

@macro ENDOPAL
@end example
@ifhtml
</font>
@end ifhtml
@end macro

Similarly, bychanging the macro pairs @BEGINDOC/@ENDDOC and/or @BEGINOVW/@ENDOVW, you can give a different colour to documentation and/or overviews.

Highlight Warnings

If you want to make warnings stand out, try these definitions:

@macro BEGINDOCwarning
@ifhtml
<font color="FF0000"><blink>
@end ifhtml
@cartouche
@end macro

@macro ENDDOCwarning
@end cartouche
@ifhtml
</blink></font>
@end ifhtml
@end macro

This will result in a box with rounded corners around the documentation in the printed manual (@cartouche) and make the warning blink and appear in red in the HTML hypertext.

The documentation must then be tagged with the tag `warning':

-- %{warning} This function is completely untested!

resulting in:


This function is completely untested!

No Indentation of Source Code

By default, source code is put into an @example environment, which indents it. To remove the indentation, redefine @BEGINOPAL and @ENDOPAL:

@macro BEGINOPAL
@t{
@format
@end macro

@macro ENDOPAL

@end format
}
@end macro

Indentation of Documentation

Normally, source code is indented and documentation is not. To reverse the default, redefine @BEGINOPAL, @ENDOPAL, @BEGINDOC and @ENDDOC:

@macro BEGINOPAL
@t{
@format
@end macro

@macro ENDOPAL
@end format
}
@end macro

@macro BEGINDOC
@quotation
@end macro

@macro ENDDOC
@end quotation
@end macro

Obey Line Breaks in Documentation

When you process ASCII-style comments (perhaps when using DOSFOP for non-OPAL sources, see DOSFOP and Non-OPAL Programs), you might want to retain the line breaks. This is achieved by these definitions:

@macro BEGINDOC
@format
@end macro

@macro ENDDOC
@end format
@end macro

Add New Indices

If you want to add an `xy' index, you must edit two files:

`dosfopPrelude.texi'
Add the line
@defcodeindex xy
Use @defindex if entries are to appear in Roman and not fixed-width font.
`dosfop.macros'
Change the @FINALIZEDOC macro to insert your index at the end:
@macro FINALIZEDOC
@node XY Index, To Do, Tips And Tricks, Top
@chapter XY Index
@printindex xy

@contents
@end macro

You may now use the command @xyindex to include entries:

-- %@xyindex An XY index entry

Find Unfinished Source Code

DOSFOP can help you keep track of all the places in your code you think need a second look.

We just use the technique presented in Add New Indices, to add a new `To Do' index:

`dosfopPrelude.texi'
Add the line
@defcodeindex td
`dosfop.macros'
Change the @FINALIZEDOC macro to insert your index at the end:
@macro FINALIZEDOC
@node To Do, Texinfo for Experienced TeX Users, XY Index, Top
@chapter To Do
@printindex td

@contents
@end macro

The code then looks like this:

/* %This function sorts its argument.
@tdindex FUN sort implemented inefficiently
*/
FUN sort: seq[mytype] -> seq[mytype]

If you want to highlight these parts of the documentation, too, see Highlight Warnings.

Hide Source Code

You can exclude source code from the generated documentation with the help of the @ignore environment:

-- %@ignore
...
... lots of hidden functions
...
-- %@end ignore

Do not forget the @end ignore line! Otherwise no more documentation will be generated after the initial @ignore.

Javadoc

DOSFOP cannot process the special tags recognized by javadoc. But if you are willing to sacrifice DVI and INFO output, DOSFOP can also process files documented in JAVADOC style.

The following definitions allow HTML documentation:

@macro BEGINDOC
@ifhtml
@end macro

@macro ENDDOC
@end ifhtml
@end macro

To allow inclusion of JAVA files, create a file `dosfop.filetypes' in the DOSFOP directory, which consists of this line:

.java: : :/**:*/: :

This will tell DOSFOP how to process `.java' files: nested comments starting with /** and ending with */ are documentation, everything else is source code.

Texinfo for Experienced TeX Users

Experienced TeX users should not have much difficulty writing Texinfo. The look and feel of Texinfo is similar to a special LaTeX style.

The following differences are the most important:

Escaping by @
The escape character is the at sign (`@'). The backslash character (`\') need not be escaped. The only characters that must be escaped are the at sign (write @@) and the curly brackets (write @{ and @} resp.).
Environments
An environment env is begun with @env and terminated with @end env. Both commands must appear on a line of their own and may not be preceded by spaces or tabs.
Commands that occupy an entire line
Most commands are followed by an argument list in braces, as in TeX. But there is a set of commands that occupy an entire line. These commands must be written at the beginning of a line (no spaces or tabs allowed). They take the rest of the line as their single argument.
Itemize lists
There are two traps for TeX users with itemize lists:
  1. The command to begin an environment has an additional argument for the command generating the mark (most often @bullet or @minus).
  2. The @item command must appear on a line of its own and may not be preceded by spaces or tabs.
An itemize list might look like this:
@itemize @bullet
@item
Text for first item.
@item
Text for second item.
@item 
...
@end itemize

Useful Texinfo Commands

Texinfo is a language which combines commands for setting up hyperlinks, for chapter structuring and for text formatting. Fortunately, the user of DOSFOP is only concerned with the text-formatting parts.

For a very quick introduction, you need to learn only the following commands:

@@
@{
@}
The characters `@', `{' and `}' must be written with an initial at sign (`@'). All other characters can be used as they are.
@code{text}
Use @code to mark references to identifiers from the source code.
@emph{text}
Use @emph to highlight (emphasize) text.
@ref{@Overview{structure name}}
Use @ref{@Overview{structure name}} to create a hyperlink to structure structure name.

A full description is given in the Texinfo manual. The most important Texinfo commands are briefly described in this appendix.

If you view this locally at TU Berlin, the following links take you to the relevant chapters of the Texinfo Manual:

Environments

The following list contains the commands needed to begin an environment. Environments are ended by the command @end environment.

These commands must be on a line of their own and may not be preceded by spaces or tabs.

@enumerate
Begin a numbered list. Use a separate @item line at the beginning of each entry. You may give the beginning command a number or a letter, which is then used for the first entry.
@itemize mark-gen-char-or-command
Produce a sequence of indented paragraphs with a mark inside the left margin at the beginning of each paragraph. Use a separate @item line at the beginning of each entry. The beginning command takes an argument which is used to generate the initial mark. Most often, @bullet or @minus are used.
@table formatting-command
Begin a two-column table. Use @item first-column for each entry. First-column entries are printed in the font given in formatting-command.
If you want to group several entries, use @itemx instead of @item for the second and following entries. Add the explanation after the last @itemx line.

Font Modification

@asis{text}
No font modification (useful for two-column tables, see Environments).
@b{text}
Use bold font.
@code{text}
Highlight text that is an expression, a syntactically complete token of a program, or a program name.
@emph{text}
Highlight (emphasize) text.
@i{text}
Print text in italic font.
@r{text}
Print text in roman font.
@sc{text}
Set text in a printed output in the small caps font.
@t{text}
Print text in a fixed-width, typewriter-like font.

Formatting Commands

Paragraphs are separated by an empty line. In the generated documentation, every comment that contains documentation is given a separate paragraph. (One exception: In non-OPAL source code which does not have nested comments, subsequent line comments are merged. See DOSFOP and Non-OPAL Programs.)

@*
Force a line break.
@-
Mark possible hyphenation for printed output.
@noindent
Do not indent the following paragraph.
@page
Start a new page in a printed manual.

Cross References

Text may contain cross references to other `nodes'. DOSFOP provides the commands @Overview{structure name}, @Sign{structure name}, @Impl{structure name}, @Extp{structure name}, @Intp{structure name} to reference the overview, signature part, implementation part, external property part, internal property part respectively. Use @LibSign{structure name} @LibExtp{structure name} to refer to library structures.

@ref{node name}
Generate a reference to the named node.
@xref{node name}
Produce an initial `See' followed by a reference to the named node.
@pxref{node name}
Use it only inside parentheses and do not type a comma or period after the command's closing bracket. Produces an initial `see' followed by a reference to the named node.

Miscellaneous

@c comment
@comment comment
Begin a comment in Texinfo. The rest of the line does not appear in the generated documentation.
@cindex entry
Add entry to the index of concepts. You may switch on the concept index in the global options (see Global Options).
@email{mail address}
Indicate an electronic mail address. In HTML this produces a hyperlink.
@footnote{text of footnote}
Enter a footnote.
@url{URL}
Highlight text that is a uniform resource locator for the World Wide Web. In HTML this produces a hyperlink.

Changes

DOSFOP 1.92g has the following differences to version 1.92f:

DOSFOP 1.92f has the following differences to version 1.92d:

DOSFOP 1.92d has the follwoing differences to version 1.92c:

DOSFOP 1.92c has the following differences with respect to version 1.90h:

Index

347 entries

[ * ] [ . ] [ @ ] [ a ] [ b ] [ c ] [ d ] [ e ] [ f ] [ g ] [ h ] [ i ] [ j ] [ l ] [ m ] [ n ] [ o ] [ p ] [ r ] [ s ] [ t ] [ u ] [ v ] [ w ] [ x ]

*

* (as special top structure)

.

.oasysrc

@

@*
@-
@AA
@AE
@asis{text}
@BEGINDOC (macro) : [1], [2], [3], [4]
@BEGINDOCoptimize (macro)
@BEGINDOCtag (macro) : [1], [2]
@BEGINDOCwarning (macro)
@BEGINOPAL (macro) : [1], [2], [3], [4]
@BEGINOVW
@bullet : [1], [2]
@b{text}
@c comment
@cartouche
@cindex
@cindex entry
@code{text}
@comment comment
@contents
@defcodeindex : [1], [2]
@defindex
@dfStarLine
@email{mail address}
@emph{text}
@ENDDOC (macro) : [1], [2], [3], [4]
@ENDDOCoptimize (macro)
@ENDDOCtag (macro) : [1], [2]
@ENDDOCwarning (macro)
@ENDOPAL (macro) : [1], [2], [3], [4]
@ENDOVW
@enumerate
@example
@Extp (macro)
@FINALIZEDOC (macro) : [1], [2], [3]
@finalout
@findex
@footnote{text of footnote}
@ifclear html : [1], [2]
@ifhtml
@ifinfo
@ifset html : [1], [2]
@iftex
@ignore
@Impl (macro)
@Intp (macro)
@item : [1], [2], [3], [4]
@itemize
@itemize mark-gen-char-or-command
@itemx
@i{text}
@LibExtp (macro)
@LibSign (macro)
@minus : [1], [2]
@noindent
@page
@pindex
@pxref
@pxref{node name}
@ref
@ref{node name}
@r{text}
@sc{text}
@setchapternewpage
@Sign (macro)
@table formatting-command
@tdindex
@TeX
@tex
@t{text}
@url{URL}
@xref
@xref{node name}
@xyindex

a

administrative data : [1], [2]
Application index
Application index (option)
Authors'Names (option)

b

Basic Language (option)
binary configuration
browse

c

change path of subsystem
Check Configuration Consistency (button) : [1], [2]
checkConsistency
colon
colouring text
commands that occupy an entire line
Concept Index (option)
conditionally defined macros
conditionally visible text
config : [1], [2]
Config (button) : [1], [2]
Config Global (button)
config.bin
configuration of structure : [1], [2], [3]
configuration of subsystem : [1], [2], [3]
configurator
convert to DVI (button)
convert to HTML (button)
convert to Info (button)
customizing the documentation

d

Date of Creation (option)
Definition index
Delete (button) : [1], [2]
deletion of structures
deletion of subsystems
dependencies between subsystems and/or structures
dfAuthors
dfCodomainIndexFlag
dfDate
dfDomainIndexFlag
dfEnglish
dfGerman
dfo.tcl
dfProjectName
dfSingleNode
dfSortalphabetically
dfSortbottom_up
dfSortoff
dfSorttop_down
dfSortuser_defined
dfStarLine
diagnostics
Display All Options (button)
doc
doc directory : [1], [2]
doc-dvi
doc-help
doc-html
doc-info
documentation headers
documentation sectioning
dosfop : [1], [2]
DOSFOP (environment variable) : [1], [2]
DOSFOP execution window
DOSFOP main window : [1], [2]
dosfop.filetypes : [1], [2]
dosfop.macros : [1], [2], [3], [4]
dosfop.switches
DOSFOP/foo.deps
DOSFOP/foo.index
dosfopLatin1.sty : [1], [2]
dosfopMacroExpander : [1], [2]
dosfopMacroExpander : [1], [2]
dosfopPrelude.tex
dosfopPrelude.texi : [1], [2], [3], [4]
dosfopTexindex
dosfopTranslator
Drop Empty Lines (option)
dvi
DVI files, constructing : [1], [2], [3]
DVI previewer (button)

e

edit list of tags
empty lines
environment variables
environments : [1], [2]
escaping by @
exclude source code
execution window (of DOSFOP)
external property part

f

filebrowser : [1], [2], [3]
fixtexindexpost
fixtexindexpre
foo.deps
foo.index
free type declaration
Function Index
Function Index By Codomain
Function Index by Codomain
Function Index by Domain
Function Index By Domain
Functionality Index (option)

g

generated documentation
getsetting
global configuration
Global Configuration (button)
global options : [1], [2], [3], [4]
globalConfig
GNU utilities
graphic user interface, without
graphic visualization of dependencies
graphical user interface

h

headers, additional h. in documentation
hidden documentation
hide source code
Hierarchy Visualization (option)
html
HTML files, constructing : [1], [2], [3]
HTML files, constructing quickly
HTML tags
HTML viewer (button)
hyphenation

i

ignore source code
ignored documentation
import references for non OPAL sources
Import Referencing (option)
import relation
Include only Interfaces (option)
indentation : [1], [2]
`index.html'
indices for non OPAL sources
indices used by DOSFOP
individual configuration of structure
individual configuration of subsystem
INFO (environment variable)
INFO files, constructing : [1], [2], [3]
Info hypertext reader (button)
Insert (button) : [1], [2]
insertion of structures : [1], [2]
insertion of subsystems : [1], [2]
Intermediate code output file (option)
intermediate Texinfo output : [1], [2], [3], [4]
internal property part
introduction
introduction to project
introduction to subsystem
ISO-8859-1 character set
itemize lists

j

javadoc

l

lastChange
latin1 character set
law
laws
level documentation (= tagged doc.) : [1], [2], [3]
level handling
Level Up (button)
levels of sectioning
library
Library Inclusion (option)
library structures : [1], [2]
Library.config
line breaks
line numbers
local options
lynx

m

macro calls
macro definitions
macro names
macro packages
main window (of DOSFOP) : [1], [2]
makeinfo : [1], [2], [3], [4]
MAKEINFO (environment variable)
memory overflow
Move (button)
moving of subsystems

n

Name of the Project (option)
new indices
new page
new pages
non OPAL source code : [1], [2]

o

OASYS
OCS
OCSDIR (environment variable)
only : [1], [2], [3]
options.data
ordinary documentation

p

paragraphs, formatting of
path of subsystem, changing
perl
PERL (environment variable)
plain TeX
predefined indices
project browser : [1], [2]
Project Browser (button)
project data base : [1], [2]
project, introduction to
project, survey of
PROJECTROOT (environment variable)
properties
Property Inclusion (option)
Property Index
property parts
property parts and property references
property references
psfig.sty
psfig.tex : [1], [2]
pst-node.tex : [1], [2]
pstricks.con
pstricks.sty
pstricks.tex : [1], [2]
pureDosfop : [1], [2], [3]

r

Rename (button) : [1], [2]
renaming of structures
renaming of subsystems
ribbon
Root-location of the Project (option)

s

sh
SIGNATURE keyword
single node
Sort Index
Sort Structures (option)
Start DOSFOP (button)
Start New Pages (option)
Structure in single node (option)
Structure Index
Structure Index (option)
structure name.config
structure, survey of
structureConfig
structureindexflag
Subsystem Inclusion (option)
subsystem name.config
subsystem name.names
subsystem, introduction to
subsystem, survey of
subsystemConfig
survey
Survey (button)
survey of project
survey of structure
survey of subsystem
Survey.texi : [1], [2]

t

tagged documentation : [1], [2], [3]
TAPSOFT
TCL/TK : [1], [2]
technical report
TeX macros
texi2dvi
texi2html
texindex : [1], [2]
TEXINDEX (environment variable)
Texinfo
Texinfo environment
Texinfo special characters
texinfo.tex : [1], [2]
TEXINPUTS (environment variable)
thisdoc
thisdocall
title page
To-Do Index
top structure
Top Structure Name (option)
toplevel
Toplevel.config
trouble-shooting
types of documentation

u

unfinished source code
Used Function Tables (option)

v

visualization of dependencies

w

wish
WISH (environment variable)
WWWBROWSER (environment variable)

x

X defaults
XDVI (environment variable)
xy index


This document was generated 5 June 2001 (14:13:50) using the texi2html translator version 1.51-kd-pl15.