\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename DosfopManual.info
@settitle DOSFOP Manual
@c %**end of header
@ifclear html
@macro DOSFOP
@sc{Dosfop}
@end macro
@macro OPAL
@sc{Opal}
@end macro
@end ifclear
@ifset html
@macro DOSFOP
DOSFOP
@end macro
@macro OPAL
OPAL
@sc{Opal}
@end macro

@end ifset
@macro CITEM{entry}
@item \entry\
@cindex @code{\entry\}

@end macro
@macro CITEMX{entry}
@itemx \entry\
@cindex @code{\entry\}

@end macro
@macro FITEM{entry}
@item \entry\
@cindex @code{\entry\}

@end macro
@macro FITEMX{entry}
@itemx \entry\
@cindex @code{\entry\}

@end macro
@macro CODEINDEX{entry}
@cindex @code{\entry\}

@end macro
@set VERSION 1.92g
@ifinfo
This is the manual for the @DOSFOP{} literate programming tool, 
version @value{VERSION}.

Copyright @copyright{} 1997, 1998, 1999 Klaus Didrich
@end ifinfo
@finalout
@titlepage
@title DOSFOP Manual
@subtitle Literate Programming of @sc{Opal} programs
@author Klaus Didrich
Copyright @copyright{} 1997, 1998, 1999
@end titlepage

@ifinfo
@node Top, Introduction, (dir), (dir)
@top DOSFOP Manual

DOSFOP is a literate programming tool for @sc{Opal}.
@end ifinfo

@menu
* Introduction::                
* Using DOSFOP::                
* Texinfo Environment of DOSFOP::  
* The Files DOSFOP Uses::       
* The Programs DOSFOP Uses::    
* Tips and Tricks::             
* Texinfo for Experienced TeX Users::  
* Useful Texinfo Commands::     
* Changes::                     
* Index::                       

 --- The Detailed Node Listing ---

Introduction

* Architecture of DOSFOP::      
* History of DOSFOP::           

Using @DOSFOP{}

* Writing Documentation::       
* The Graphical User Interface::  
* DOSFOP without Windows::      
* DOSFOP and ocs::              
* DOSFOP and oasys::            
* DOSFOP and Non-OPAL Programs::  
* Incrementally Generating Documentation::  

Writing Documentation

* Project and Subsystem Surveys::  
* Structure Surveys::           
* Source Code Documentation::   

The Graphical User Interface

* Global Configuration::        
* Project Browser::             

Global Configuration

* Administrative Data::         
* Global Options::              

Project Browser

* Structures::                  
* Subsystems::                  
* Filebrowser::                 

The Texinfo Environment for @DOSFOP{}

* TeX macros::                  
* Texinfo setup::               
* Predefined Macros ::          
* Switches::                    
* Conditionally Visible Text::  

The Files @DOSFOP{} Uses

* TeX and Texinfo Related Files::  
* TeX Styles::                  
* Files in the Project Data Base::  
* Other Files ::                

The Programs @DOSFOP{} Uses

* DOSFOP Programs::             
* Graphical User Interface ::   
* Programs for Producing DVI Files::  
* Programs for Producing Info Hypertext::  
* Programs for Producing HTML Hypertext::  
* External Interpreters::       

Tips and Tricks

* Coloured Source Code::        
* Highlight Warnings::          
* No Indentation of Source Code::  
* Indentation of Documentation::  
* Obey Line Breaks in Documentation::  
* Add New Indices::             
* Find Unfinished Source Code::  
* Hide Source Code::            
* Javadoc::                     

Useful Texinfo Commands

* Environments::                
* Font Modification::           
* Formatting Commands::         
* Cross References::            
* Miscellaneous::               
@end menu

@node Introduction, Using DOSFOP, Top, Top
@chapter Introduction

@DOSFOP{}, the documentation system for @OPAL{} projects, is a
@emph{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:
@itemize @bullet{}
@item 
Provide @emph{hierarchic documentation} for hierarchic software.
@item
Use information that is @emph{already contained} in the source code.
@item
Provide documentation on @emph{paper and} as @emph{hypertext}.
@item
Take the @emph{programmer's individuality} into account.
@item
@emph{Low barrier} for initial use.
@item
@emph{Compatibility with undocumented code.}
@end itemize

@cindex TAPSOFT
@cindex technical report
The tool was presented at the tool session at TAPSOFT'97 @*
(see
@url{http://uebb.cs.tu-berlin.de/papers/published/DocumentationToolOpal.html}),
and a  technical report is available
(see @url{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
@value{VERSION} (for changes from older versions, see @ref{Changes}).
@menu
* Architecture of DOSFOP::      
* History of DOSFOP::           
@end menu

@node Architecture of DOSFOP, History of DOSFOP, Introduction, Introduction
@section @DOSFOP{}'s Architecture

@DOSFOP{} takes input from three different sources:
@itemize @bullet
@item
The @emph{global configuration}, which contains administrative data and
global options for customizing the documentation.
@item
The @emph{project data base}, in which the structure of an @OPAL{} project
is recorded.
@item
The source code, which contains documentation in the form of special marked
comments. @DOSFOP{} requires access to the abstract syntax in order to
properly generate documentation. As a consequence, the structures to be
documented must have been context-checked!
@end itemize

@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 @sc{dvi} files for printed output, to @sc{info}
files for the GNU info help system and to @sc{html} files for web
browsers. 

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

@node History of DOSFOP,  , Architecture of DOSFOP, Introduction
@section @DOSFOP{}'s History

A first prototype of the system was developed by Torsten
Klein as his @emph{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 @sc{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 @value{VERSION}.

@node Using DOSFOP, Texinfo Environment of DOSFOP, Introduction, Top
@chapter Using @DOSFOP{}

@menu
* Writing Documentation::       
* The Graphical User Interface::  
* DOSFOP without Windows::      
* DOSFOP and ocs::              
* DOSFOP and oasys::            
* DOSFOP and Non-OPAL Programs::  
* Incrementally Generating Documentation::  
@end menu

@cindex environment variables
@cindex @code{DOSFOP} (environment variable)
Dosfop needs no adjustment of environment variables. The variable
@code{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.

@table @code
@item DOSFOP
The @code{DOSFOP} subdirectory is used to store intermediate output and
administrative data.
@item doc
@cindex @code{doc} directory
@cindex generated documentation
@cindex @file{index.html}
The @code{doc} subdirectory contains the generated documentation. If the
user does not change the default, the (root) output files are called
@file{doc/out.dvi}, @file{doc/out.info} and @file{doc/out.html} for
@sc{dvi}, @sc{info} and @sc{html} format, respectively. There is always an
additional top-level @sc{html} file @file{index.html}.
Note that there may
be more than one file for @sc{info} and @sc{html} format.
@xref{Administrative Data} to change the name of the generated file.
@end table

@node Writing Documentation, The Graphical User Interface, Using DOSFOP, Using DOSFOP
@section Writing Documentation

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

@cindex Texinfo
@cindex GNU utilities
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 
(@pxref{Texinfo for Experienced TeX Users}). 

@ifhtml
A <a href="file:/usr/gnu/html/texinfo/texinfo_toc.html">hypertext
documentation of Texinfo</a> is locally available at TU Berlin.
@end ifhtml

@menu
* Project and Subsystem Surveys::  
* Structure Surveys::           
* Source Code Documentation::   
@end menu

@node Project and Subsystem Surveys, Structure Surveys, Writing Documentation, Writing Documentation
@subsection Project and Subsystem Surveys

@cindex survey of project
@cindex survey of subsystem
@cindex project, survey of
@cindex subsystem, survey of
@cindex introduction to project
@cindex introduction to subsystem
@cindex project, introduction to
@cindex subsystem, introduction to
@CODEINDEX Survey.texi
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 @file{Survey.texi} at
toplevel or the path to the subsystem respectively.

@node Structure Surveys, Source Code Documentation, Project and Subsystem Surveys, Writing Documentation
@subsection Structure Surveys

@cindex survey of structure
@cindex structure, survey of
@cindex @code{SIGNATURE} keyword
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 @code{SIGNATURE}.

@node Source Code Documentation,  , Structure Surveys, Writing Documentation
@subsection Source-Code Documentation

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

@cindex types of documentation
There are five types of source-code documentation available.

@table @b
@item Ordinary documentation
@cindex ordinary documentation
Ordinary documentation is any documentation that does not belong to
  the remaining four categories.  Ordinary documentation may contain arbitrary
  Texinfo text.

Example:
@example
-- %This function computes the length of a sequence.
@end example

@item Tagged documentation
@cindex tagged documentation
@cindex level documentation (= tagged doc.)
Tagged documentation (also called @emph{level documentation}) is ordinary
documentation with an additional tag. This tag appears in curly brackets
immediately after the initial per cent sign.

Example:
@example
/* %@{optimize@} This function needs further attention 
   if used with bigger arguments.
*/
@end example

@cindex ribbon
The name ``level documentation'' originates in the intention to provide
documentation for different `levels' of users. In @sc{GRASP} the same
concept is called @emph{ribbon}.@*

As a default, tags are ignored (i.e. tagged documentation is treated like
ordinary documentation). You may configure globally or for subsystems
(@pxref{Global Options}) that the level mechanism is turned on. In this
case, you must provide a set of tags that are included. @*

@cindex @code{@@BEGINDOCtag} (macro)
@cindex @code{@@ENDDOCtag} (macro)
@cindex @code{@@BEGINDOCoptimize} (macro)
@cindex @code{@@ENDDOCoptimize} (macro)
If level handling is turned on, documentation tagged with @var{tag} is
enclosed in a pair of macro calls, @code{@@BEGINDOCtag} and
@code{@@ENDDOCtag}. @strong{These macros must be defined by the user!} 
Macros for the above example might be:

@example
@@macro BEGINDOCoptimize
@@strong@{optimize:@}@@i@{
@@end macro
@@macro ENDDOCoptimize
@}
@@end macro
@end example

which would generate the following documentation:@*

@strong{optimize:}@i{
This function needs further attention 
if used with bigger arguments.
}@*@*

@item Documentation sectioning
@cindex documentation sectioning
@cindex documentation headers
@cindex headers, additional h. in documentation
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 (@samp{$}) 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:
@example
-- %$$Accessing elements of a sequence$
@end example

@cindex levels of sectioning
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.

@item Hidden documentation
@cindex hidden documentation
@cindex ignored 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:
@example
-- %- Check below carefully for typos!
@end example

@item Property references
@cindex property references
@cindex law
Property references consist of the name of a law enclosed in square
brackets. The reference is replaced by the law itself.@*

@cindex property parts and property references
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:
@example
FUN ++ : seq ** seq -> seq
-- %[++_assoc]
@end example

@end table

@node The Graphical User Interface, DOSFOP without Windows, Writing Documentation, Using DOSFOP
@section The Graphical User Interface

@cindex @DOSFOP{} main window
@cindex main window (of @DOSFOP{})
@CODEINDEX dosfop
The graphical user interface is invoked by the command @code{dosfop}. The
@DOSFOP{} main window provides buttons to start other programs needed for
producing documentation.

The components:

@table @b
@item File (menu)
@cindex @DOSFOP{} execution window
@cindex execution window (of @DOSFOP{})
Close the @DOSFOP{} main window and the @DOSFOP{} execution window.
@item Help (menu)
Provide global or context-sensitive help.
@item DOSFOP: documenting @var{project} (title)
The @var{project} is the title given in the global configuration.
@item Global configuration
@cindex Global Configuration (button)
Edit administrative data and global switches. @xref{Global Configuration}.
@item Project browser
@cindex Project Browser (button)
Enter structures and subsystems of the project. Local configuration of
subsystems and structures. @xref{Project Browser}.
@item Check configuration consistency
@cindex Check Configuration Consistency (button)
Check whether the source code and abstract syntax (interopal) files are
present. Result is presented in the @DOSFOP{} execution window.
@item Start DOSFOP
@cindex Start DOSFOP (button)
@cindex intermediate Texinfo output
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.
@item convert to DVI
@itemx convert to Info
@itemx convert to HTML
@cindex convert to DVI (button)
@cindex convert to Info (button)
@cindex convert to HTML (button)
@cindex @sc{dvi} files, constructing
@cindex @sc{html} files, constructing
@cindex @sc{info} files, constructing
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.
@item DVI previewer
@itemx Info hypertext reader
@itemx HTML viewer
@cindex DVI previewer (button)
@cindex Info hypertext reader (button)
@cindex HTML viewer (button)
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:
@cindex @code{XDVI} (environment variable)
@cindex @code{INFO} (environment variable)
@cindex @code{WWWBROWSER} (environment variable)
@table @code
@item XDVI
The name of a previewer for @sc{dvi} files.
@item INFO
The name of a previewer for @sc{info} files.
@item WWWBROWSER
The name of a browser for @sc{html} files.
@end table

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).

@end table
@menu
* Global Configuration::        
* Project Browser::             
@end menu

@node Global Configuration, Project Browser, The Graphical User Interface, The Graphical User Interface
@subsection Global Configuration

@cindex global configuration
@cindex administrative data
@cindex global options
@cindex customizing the documentation
@cindex configurator
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.

@emph{Changes are only effected after the settings have been saved.}

@menu
* Administrative Data::         
* Global Options::              
@end menu

@node Administrative Data, Global Options, Global Configuration, Global Configuration
@subsubsection Administrative Data

@cindex administrative data
@table @b
@item 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.
@item Help (menu)
Invoke a window with global or context-sensitive help.
@item Root-location of the Project
@cindex Root-location of the Project (option)
@cindex toplevel
This is the location where @DOSFOP{} looks for structures at the
`top level'. 
@item Intermediate code output file
@cindex Intermediate code output file (option)
@cindex intermediate Texinfo output
@cindex @code{doc} directory
This is the name of the file where @DOSFOP{} stores the intermediate
Texinfo output. The default is @var{root-location}@code{/DOSFOP/out.texi}.
You may change @code{out} in order to change the name of the generated files
in the @code{doc} directory (@pxref{Using DOSFOP}).

Note that this file contains the surveys and the structure of the
docuemntation only. Documentation of structures is located in their
associated @file{OCS} subdirectory.

@item Top structure name
@cindex Top Structure Name (option)
@cindex top structure
@cindex * (as special top structure)
@cindex import relation
@cindex library structures
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 @code{*} to indicate that @emph{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). 
@item Name of the project
@itemx Authors' names
@itemx Date of creation
@cindex Name of the Project (option)
@cindex Authors'Names (option)
@cindex Date of Creation (option)
@cindex title page
These entries are used for the title page. The name of the project also
appears in the @DOSFOP{} main window.
@item Display all options
@cindex Display All Options (button)
Display switches for global options (@pxref{Global Options}).
@end table

@node Global Options,  , Administrative Data, Global Configuration
@subsubsection Global Options

@cindex global options
@cindex configuration of subsystem
@cindex configuration of structure
@cindex individual configuration of subsystem
@cindex individual configuration of structure
Options marked with @emph{SUB} can be configured individually for
subsystems, those marked @emph{STR} can be configured individually for
structures.

@table @b
@item Survey (SUB)
@cindex Survey (button)
@cindex survey
@cindex introduction
@CODEINDEX Survey.texi
Introduction to the documentation (or the subsystem).
Note that this information is ignored, if a file @file{Survey.texi} exists
at the time the documentation is generated. In this case, the survey is
included from that file.
@item Macros
This feature has been made obsolete by the introduction of macros into
Texinfo.
@item Level mechanism (SUB, STR)
@cindex tagged documentation
@cindex level documentation (= tagged doc.)
@cindex level handling
@cindex edit list of tags
@cindex @code{@@BEGINDOCtag} (macro)
@cindex @code{@@ENDDOCtag} (macro)
Treatment of tagged or level documentation (@pxref{Source Code
Documentation}). 
@table @i
@item No Level Handling
Tagged documentation is treated as ordinary documentation.
@item 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
@code{BEGINDOCtag} and @code{ENDDOCtag} (@pxref{Source Code Documentation}).
@end table
@item Functionality index
@cindex Functionality Index (option)
@cindex Function Index
@cindex Function Index By Domain
@cindex Function Index By Codomain
@cindex Sort Index
@cindex Property Index
@cindex properties
@cindex laws
@cindex free type declaration
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:
@table @i
@item Function Index
@itemx Function Index By Domain
@itemx Function Index By Codomain
Functions declared in structures of the project sorted alphabetically, by
types in their domain and their codomain, respectively.
@item Sort Index
Sorts declared in structures of the project.
@item Property Index
Algebraic properties (laws and free type declarations) from structures of the
project.
@end table
@item Application Index
This switch controls two indices:
@table @i
@item
@cindex Application index (option)
@cindex Application index
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. @xref{Files in the Project Data
Base}, for what @DOSFOP{} considers to be a library file.
@item Definition index
@cindex Definition index
Index to the places where functions are defined. Verbosity is the same as
with the functionality index.
@end table
@item Concept index
@cindex Concept Index (option)
@CODEINDEX @@cindex
Insert a concept index. The user must define entries by adding
@code{@@cindex entry} lines in the documentation.
@item Structure index
@cindex Structure Index (option)
Alphabetic index of all structures (without libraries).
@item Subsystem inclusion
@cindex Subsystem Inclusion (option)
Include only top-level structures or top-level structures and all subsystems.
@item Library inclusion
@cindex Library Inclusion (option)
@cindex library
Include the library files referenced from other files in the generated
documentation. 
@item Property inclusion (SUB, STR)
@cindex Property Inclusion (option)
@cindex external property part
@cindex internal property part
@cindex property parts
Also include external and (if ``include only interfaces'' -- see below -- is
off) internal property parts of structures. 
@item Include only interfaces (SUB, STR)
@cindex Include only Interfaces (option)
If on, include only signature and (if ``property  inclusion'' -- see above
-- is on) external property parts of structures,
@item Hierarchy visualization (SUB)
@cindex Hierarchy Visualization (option)
@cindex graphic visualization of dependencies
@cindex visualization of dependencies
@cindex dependencies between subsystems and/or structures
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.
@item Sort structures (SUB)
@cindex Sort Structures (option)
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.
@item Import referencing (SUB, STR)
@cindex Import Referencing (option)
Include links to imported structures, with or without library structures.
@item Used function tables (SUB, STR)
@cindex Used Function Tables (option)
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.
@item Basic language
@cindex Basic Language (option)
Generate English or German section names.
@item Start new pages (SUB, STR)
@cindex Start New Pages (option)
@cindex new pages
Start new pages where necessary.
@item Drop empty lines (SUB, STR)
@cindex Drop Empty Lines (option)
@cindex empty lines
Remove empty lines between documentation and source code.
@item Structure in single node
@cindex Structure in single node (option)
@cindex single node
This option has (almost) no effect on printed output. For @sc{info} and
@sc{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.
@end table

@node Project Browser,  , Global Configuration, The Graphical User Interface
@subsection Project Browser

@cindex project browser
@cindex project data base
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.

@emph{Changes to the project data base are immediately effective.}

@menu
* Structures::                  
* Subsystems::                  
* Filebrowser::                 
@end menu

@node Structures, Subsystems, Project Browser, Project Browser
@subsubsection Structures

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

@table @b
@item Delete
@cindex Delete (button)
@cindex deletion of structures
The marked structure is deleted.
@item Insert
@cindex Insert (button)
@cindex insertion of structures
@cindex filebrowser
You may insert a new structure name, either by typing it in or by using the
file browser (@pxref{Filebrowser}). Click on @code{Exit} when all structures
have been entered.
@item Rename
@cindex Rename (button)
@cindex renaming of structures
The marked structure may be given a new name.
@item Config global
@itemx Config
@cindex Config Global (button)
@cindex Config (button)
@cindex configuration of structure
Configure each structure of the subsystem or the marked structure
individually. @xref{Global Options}, for the available options.
@end table

@node Subsystems, Filebrowser, Structures, Project Browser
@subsubsection Subsystems

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

@table @b
@item Level up
@cindex Level Up (button)
This button -- immediately above the list -- 
takes you to the parent subsystem. It is not displayed at the top level.
@item Delete 
@cindex Delete (button)
@cindex deletion of subsystems
Delete the marked subsystem.
@item Insert
@cindex Insert (button)
@cindex insertion of subsystems
@cindex filebrowser
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
(@pxref{Filebrowser}) 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.
@item Rename
@cindex Rename (button)
@cindex renaming of subsystems
Rename the marked subsystem. (You cannot change the path.)
@item Move 
@cindex Move (button)
@cindex moving of subsystems
Move the marked subsystem. After clicking on the move button, click on the
structure before which the marked structure is to be inserted.
@item Config
@cindex Config (button)
@cindex configuration of subsystem
@cindex change path of subsystem
@cindex path of subsystem, changing
Edit options for the marked subsystem. @xref{Global Options}, for the
available options. Additionally, the path to the subsystem may be changed.
@end table

@node Filebrowser,  , Subsystems, Project Browser
@subsubsection File Browser

@cindex filebrowser
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.

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

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

@node  DOSFOP without Windows, DOSFOP and ocs, The Graphical User Interface, Using DOSFOP
@section @DOSFOP{} without Windows

@cindex graphic user interface, without
@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. 

@CODEINDEX pureDosfop
The program is called @code{pureDosfop}. The following options are available:
@table @i
@item -addonly
@CODEINDEX only
This switch is followed by names of structures which are added to the
@file{DOSFOP/only} file. (@pxref{Incrementally Generating Documentation})
@item -cc
@cindex Check Configuration Consistency (button)
Identical to the button 'Check Configuration Consistency'.
@item -clearonly
Remove the @file{DOSFOP/only} file. (@pxref{Incrementally Generating Documentation})
@item -config
@CODEINDEX config
Construct the file @file{config} from its parts. Must be used if the
configuration has been changed manually. (See also @ref{Files in the Project
Data Base}.)
@item -configascii
@itemx -configbin
@CODEINDEX config.bin
@cindex binary configuration
@DOSFOP{} can read the configuration either in ASCII (readable) format or in
binary format (which is stored in @file{DOSFOP/config.bin}. If both files
exist, @DOSFOP{} reads in the newer one and writes a new binary
configuration.

The switch @code{-configascii} removes the binary configuration. The switch
@code{-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. 
@item -dosfop
@cindex intermediate Texinfo output
Construct the intermediate Texinfo output.
@item -dvi
@itemx -info
@itemx -html
@cindex @sc{dvi} files, constructing
@cindex @sc{html} files, constructing
@cindex @sc{info} files, constructing
Construct the @sc{dvi} file (@sc{info} file, @sc{html} files) from the
intermediate Texinfo output.
@item -qhtml
@cindex @sc{html} files, constructing quickly
@CODEINDEX only
Construct the @sc{html} files from the intermediate Texinfo output, using
only structures in @file{DOSFOP/only}. This is faster but may result in
dangling links and incomplete indices.
@item -usage
A short usage message.
@end table

Calling @code{pureDosfop} with no option is identical to calling
@code{pureDosfop -dosfop}.

@node DOSFOP and ocs, DOSFOP and oasys, DOSFOP without Windows, Using DOSFOP
@section @DOSFOP{} and @sc{ocs}

@cindex @sc{ocs}
@sc{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 @code{dosfop} program.

@cindex @code{PROJECTROOT} (environment variable)
The @sc{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
@code{PROJECTROOT} must be defined, which contains the absolute path to the
top level directory. 

@itemize @bullet
@CITEM doc
Generate @sc{html} documentation for the current project. 
@CITEM dvi
Generate @sc{dvi} documentation for the current project.
@end itemize

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

@cindex memory overflow
@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.

@itemize @bullet
@CITEM thisdoc
Write the structures of the current subsystem to @file{DOSFOP/only} and
generate documentation for these structures.
@CITEM thisdocall
Perform @code{thisdoc} for current system and all subsystems.
@end itemize

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


@node DOSFOP and oasys, DOSFOP and Non-OPAL Programs, DOSFOP and ocs, Using DOSFOP
@section @DOSFOP{} and @sc{oasys}

@cindex @sc{oasys}
@CODEINDEX dfo.tcl
@CODEINDEX .oasysrc
If @sc{oasys} is used, the usage of @DOSFOP{} is made much simpler. 
Simply execute the line
@example
@var{<DOSFOP path>}/tcl4/dfo.tcl
@end example
from the @sc{oasys} command line or include this line in your
@file{.oasysrc} file. You need not change your @code{PATH} variable.
The @DOSFOP{} distribution is searched for as follows:
@enumerate
@cindex @code{DOSFOP} (environment variable)
@item
If the environment variable @code{DOSFOP} is set, its contents are used.
@item
@cindex @code{OCSDIR} (environment variable)
If the environment variable @code{OCSDIR} is set, @DOSFOP{} is sought under
@file{$OCSDIR/dosfop}.
@item 

If neither @code{DOSFOP} nor @code{OCSDIR} are defined,
@file{/usr/ocs/dosfop} is used.
@end enumerate

@CODEINDEX doc-dvi
@CODEINDEX doc-info
@CODEINDEX doc-html
@CODEINDEX doc-help
@cindex @sc{dvi} files, constructing
@cindex @sc{html} files, constructing
@cindex @sc{info} files, constructing
@cindex intermediate Texinfo output
Within @sc{oasys}, four additional commands are available:
@table @code
@item doc-dvi
@itemx doc-info
@itemx doc-html
These commands construct the @DOSFOP{} data base from the @sc{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.
@item doc-help
Provide a brief introduction to these commands.
@end table


@node DOSFOP and Non-OPAL Programs, Incrementally Generating Documentation, DOSFOP and oasys, Using DOSFOP
@section @DOSFOP{} and Non-@OPAL{} Programs

@cindex non @OPAL{} source code
@CODEINDEX dosfop.filetypes
@DOSFOP{} can incorporate non-@OPAL{} sources. To use this feature, create a
file @file{dosfop.filetypes} in the @code{DOSFOP} directory with the
following content:

@itemize @bullet
@item
Empty lines and lines starting with @code{#} are treated as comments.
@item
Other lines
must contain six components separated by colons. Empty components must be
indicated by one space. The six components have the following semantics:

@table @b
@item Suffix 
Any file with this suffix will be regarded as a foreign file.
@item Implementation suffix
Suffix of the corresponding implementation file. Empty if no implementation
exists. 
@item Line comment starter
Empty if no line comments are available.
@item Nested comment starter
Empty if no nested comments are available. Subsequent documentation from
line comments is then merged.
@item Nested comment ender
Empty if no nested comments are available.
@item Documentation designator
String which distinguishes documentation from comments. 
@end table
@end itemize

The file @file{dosfop.filetypes} is searched in the given order and before
an @OPAL{} signature file is searched.

Example file:
@example
# 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: :(*:*): :
@end example

Note that scanning still obeys the @OPAL{} rules. For example, @code{/*} is
not regarded as a valid comment starter for @samp{.h} or @samp{.c} files if
followed by a special character. In particular, @code{/*******/} is
@emph{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 @var{path}
into a subdirectory @var{path}@file{/OCS}. You must ensure that this
directory exists.

@cindex import references for non @OPAL{} sources
@cindex indices for non @OPAL{} sources
@DOSFOP{} can incorporate import references and indices generated by other
programs: 

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

@CODEINDEX foo.index
@CODEINDEX DOSFOP/foo.index
The index entries have to be given in file @file{DOSFOP/foo.index}.
Every line has the following format
@example
@var{<line number>}:@var{<index generating command>}:@var{<index entry>}
@end example

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

The files @file{DOSFOP/foo.@{deps,index@}} are not mandatory.

@node Incrementally Generating Documentation,  , DOSFOP and Non-OPAL Programs, Using DOSFOP
@section Incrementally Generating Documentation

@DOSFOP{} can generate documentation incrementally. To use this feature,
create a file @file{only} in the @file{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 @file{DOSFOP/only} exists, @DOSFOP{} will generate the
@file{DOSFOP/out.texi} file and the documentation files for the structures
named in the @file{only} file.

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

@node Texinfo Environment of DOSFOP, The Files DOSFOP Uses, Using DOSFOP, Top
@chapter The Texinfo Environment for @DOSFOP{}

@cindex Texinfo environment

@menu
* TeX macros::                  
* Texinfo setup::               
* Predefined Macros ::          
* Switches::                    
* Conditionally Visible Text::  
@end menu

@node TeX macros, Texinfo setup, Texinfo Environment of DOSFOP, Texinfo Environment of DOSFOP
@section @TeX{} macros

@cindex @TeX{} macros
@cindex macro packages
@CODEINDEX dosfopLatin1.sty
@CODEINDEX psfig.tex
@CODEINDEX pstricks.tex
@CODEINDEX pst-node.tex
@cindex latin1 character set
@cindex ISO-8859-1 character set
The following macro packages are available for use in printed manuals:
@table @b
@item dosfopLatin1.sty
Characters from the ISO-8859-1 (latin1) character set can be used directly
for @sc{dvi}, for @sc{info} and for @sc{html} files.
@item psfig.tex
Macros to include postscript figures.
@item pstricks.tex
The pstricks macro package is included.
@item pst-node.tex
Macros to draw nodes in graphics for the @code{pstricks} package.
@end table

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

@node  Texinfo setup, Predefined Macros , TeX macros, Texinfo Environment of DOSFOP
@section Texinfo setup

@CODEINDEX @@setchapternewpage
@CODEINDEX @@finalout
The following switches are set:
@example
@@setchapternewpage off
@@finalout
@end example

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

@CODEINDEX @@dfStarLine
The variable @code{@@dfStarLine} is used. Further variables will all use the
prefix @samp{df}. 

@node  Predefined Macros , Switches, Texinfo setup, Texinfo Environment of DOSFOP
@section Predefined Macros 

@cindex @code{@@Sign} (macro)
@cindex @code{@@Impl} (macro)
@cindex @code{@@Extp} (macro)
@cindex @code{@@Intp} (macro)
@cindex @code{@@LibSign} (macro)
@cindex @code{@@LibExtp} (macro)
@cindex @code{@@ref} 
@cindex @code{@@xref}  
@CODEINDEX @@pxref
The following macros may be used to reference structure parts in
@code{@@ref}, @code{@@xref} or @code{@@pxref} commands:
@table @code
@item @@Sign@{@var{structure name}@}
@item @@Impl@{@var{structure name}@}
@item @@Extp@{@var{structure name}@}
@item @@Intp@{@var{structure name}@}
@item @@LibSign@{@var{structure name}@}
@item @@LibExtp@{@var{structure name}@}
@end table

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

@node Switches, Conditionally Visible Text, Predefined Macros , Texinfo Environment of DOSFOP
@section Switches

Some options are translated to variables:
@table @code
@item html
@CODEINDEX html
Set iff @sc{HTML} output is produced. (@pxref{Conditionally Visible Text})
@item colon
@CODEINDEX colon
Set to @samp{:} if @sc{dvi} or @sc{html} output is produced; set to
@samp{;} if @sc{info} is produced. This is used to overcome difficulties
with info's inability to include colons in entries.
@item structureindexflag
@CODEINDEX structureindexflag
@cindex Structure Index
Set iff a structure index is part of the generated documentation.
@item dfDomainIndexFlag
@CODEINDEX dfDomainIndexFlag
@cindex Function Index by Domain
Set iff a function index by domain is part of the generated documentation.
@item dfCodomainIndexFlag
@CODEINDEX dfCodomainIndexFlag
@cindex Function Index by Codomain
Set iff a function index by codomain is part of the generated documentation.
@item dfEnglish
@CODEINDEX dfEnglish
Set iff the chosen language is English.
@item dfGerman
@CODEINDEX dfGerman
Set iff the chosen language is german.
@item dfSingleNode
@CODEINDEX dfSingleNode
Set iff all parts of a structure are to be part of a single node.
@item dfProjectName
@CODEINDEX dfProjectName
Set to the project title.
@item dfAuthors
@CODEINDEX dfAuthors
Set to the authors' names.
@item dfDate
@CODEINDEX dfDate
Set to the date.
@item dfSorttop_down
@itemx dfSortbottom_up
@itemx dfSortalphabetically
@itemx dfSortuser_defined
@itemx dfSortoff
@CODEINDEX dfSorttop_down
@CODEINDEX dfSortbottom_up
@CODEINDEX dfSortalphabetically
@CODEINDEX dfSortuser_defined
@CODEINDEX dfSortoff
Set iff the respective option for sorting structures has been chosen.
@end table

@node Conditionally Visible Text,  , Switches, Texinfo Environment of DOSFOP
@section Conditionally Visible Text

@cindex 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 @sc{html}. 

This is possible with the following Texinfo environments:
@table @code
@item @@iftex
@itemx @@end iftex
@CODEINDEX @@iftex
@CODEINDEX @@ifclear html
Text in this environment is processed by Texinfo and then passed on to
@TeX{} and @sc{html}. If this text is not passed to @sc{html}, you may use
@TeX{} commands, except that you must replace the @samp{\} with an
@samp{@@}.@* If you want to exclude @sc{html}, enclose this environment in the
environment 
@code{@@ifclear html}/@code{@@end ifclear}.
@item @@tex
@itemx @@end tex
@CODEINDEX @@tex
@cindex plain @TeX{}
Text in this environment is passed directly on to @TeX{}, so you may enter
plain @TeX{} here.
@item @@ifset html
@itemx @@end ifset
@CODEINDEX @@ifset html
Text in this environment is processed by Texinfo and then passed on to
@sc{html}.
@item @@ifinfo
@itemx @@end ifinfo
@CODEINDEX @@ifinfo
Text in this environment appears only in the @sc{info} output.
@item @@ifhtml
@itemx @@end ifhtml
@CODEINDEX @@ifhtml
@cindex @sc{html} tags
Text in this environment is passed directly on to @sc{html}; you may thus
enter @sc{html} tags here.
@end table

@subsection Macros and Conditions

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

@CODEINDEX @@ifset html
@CODEINDEX @@ifclear html
@example
@@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
@end example

@node The Files DOSFOP Uses, The Programs DOSFOP Uses, Texinfo Environment of DOSFOP, Top
@chapter The Files @DOSFOP{} Uses

@menu
* TeX and Texinfo Related Files::  
* TeX Styles::                  
* Files in the Project Data Base::  
* Other Files ::                
@end menu

@node TeX and Texinfo Related Files, TeX Styles, The Files DOSFOP Uses, The Files DOSFOP Uses
@section TeX- and Texinfo-Related Files

These files are located in the directory @var{<@DOSFOP{} path>}@file{/tex}.

The following files may be modified by the user by placing a copy in the
local @file{DOSFOP} directory.

@table @file
@item dosfopPrelude.tex
@CODEINDEX dosfopPrelude.tex
@CODEINDEX texinfo.tex
@TeX{} commands which must be carried out, before @file{texinfo.tex} is
included (which resets some category codes).
@item dosfopPrelude.texi
@CODEINDEX dosfopPrelude.texi
Texinfo commands to set up variables, indices and the like.
Some files are included from other packages.
@item dosfop.macros
@CODEINDEX dosfop.macros
@cindex macro definitions
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 :
@table @code
@item @@BEGINOPAL@{@}
@itemx @@ENDOPAL@{@}
@cindex @code{@@BEGINOPAL} (macro)
@cindex @code{@@ENDOPAL} (macro)
@CODEINDEX @@example
Every piece of @OPAL{} source code is surrounded by a call to these
macros. The default is @code{@@example}/@code{@@end example}.
@item @@BEGINDOC@{@}
@itemx @@ENDDOC@{@}
@cindex @code{@@BEGINDOC} (macro)
@cindex @code{@@ENDDOC} (macro)
@CODEINDEX dfStarLine
Every piece of documentation --- with the exception of the surveys --- is
enclosed in a call to these macros. The default is @code{@@value@{dfStarLine@}}
for both, which will put a line consisting of 70 @samp{*} around
documentation in @sc{info} output. No effect on @sc{dvi} or @sc{html}
output.
@item @@BEGINOVW@{@}
@itemx @@ENDOVW@{@}
@CODEINDEX @@BEGINOVW
@CODEINDEX @@ENDOVW
Every survey (project, subsystem, structure survey) is enclosed in these
macros. They are empty by default.
@item @@FINALIZEDOC@{@}
@cindex @code{@@FINALIZEDOC} (macro)
@CODEINDEX @@contents
This macro is called at the very end of the documentation. The default
definition is @code{@@contents}.
@end table
@end table

@node TeX Styles, Files in the Project Data Base, TeX and Texinfo Related Files, The Files DOSFOP Uses
@section @TeX{} Styles

These files are included to make the @DOSFOP{} distribution self-contained.
@table @code
@item dosfopLatin1.sty
@CODEINDEX 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.
@item psfig.sty
@itemx psfig.tex (1.9)
@itemx pst-node.tex (0.93a)
@itemx pstricks.con (0.93a)
@itemx pstricks.sty
@itemx pstricks.tex (0.93a)
@CODEINDEX psfig.sty
@CODEINDEX psfig.tex
@CODEINDEX pst-node.tex
@CODEINDEX pstricks.con
@CODEINDEX pstricks.sty
@CODEINDEX pstricks.tex
Some files from the @code{pstricks} package.
@item texinfo.tex (2.185)
@CODEINDEX texinfo.tex
A very recent version of the Texinfo macro package; @DOSFOP{} will not
produce correct @sc{dvi} output if older versions are used.
@end table

@node Files in the Project Data Base, Other Files , TeX Styles, The Files DOSFOP Uses
@section Files in the Project Data Base

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

@table @file
@item config
@CODEINDEX config
@CODEINDEX pureDosfop
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 @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 @code{pureDosfop
-config} (@pxref{DOSFOP without Windows}).
@item Toplevel.config
@CODEINDEX Toplevel.config
Contains the administrative data and the global option settings.
@item @var{subsystem name}.config
@CODEINDEX @i{subsystem name}.config
Contains administrative data and option settings for the specific subsystem.
@item @var{subsystem name}.names
@CODEINDEX @i{subsystem name}.names
Contains the names of the subsystems of subsystem @var{subsystem
name}. (Spaces have already been replaced by underscores).
@item @var{structure name}.config
@CODEINDEX @i{structure name}.config
Contains the local option settings for this structure.
@item Library.config
@CODEINDEX Library.config
@cindex library structures
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
@var{@DOSFOP{}-path}@code{/defaults/Library.config}, but you may copy it
to the local @code{DOSFOP} directory and modify it.
@end table

Backup files are given the extension @samp{.old}.

@node Other Files ,  , Files in the Project Data Base, The Files DOSFOP Uses
@section Other Files 

There are some other files located in the @code{DOSFOP} directory.

@table @file
@item dosfop.switches
@CODEINDEX dosfop.switches
Constructed every time the translation to Texinfo is started. This file
contains variable settings which change according to the global option
settings. @xref{Switches}, for an explanation of the switches.
@item diagnostics
@CODEINDEX diagnostics
This file contains all warnings encountered during the translation to
intermediate output.
@item lastChange
@CODEINDEX lastChange
This file is @samp{touch}ed every time the global configuration changes.
@item options.data
@CODEINDEX options.data
@cindex X defaults
This file contains X defaults for the graphical appearance of the windows of
the graphical user interface.
@end table

@node The Programs DOSFOP Uses, Tips and Tricks, The Files DOSFOP Uses, Top
@chapter The Programs @DOSFOP{} Uses

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

@menu
* DOSFOP Programs::             
* Graphical User Interface ::   
* Programs for Producing DVI Files::  
* Programs for Producing Info Hypertext::  
* Programs for Producing HTML Hypertext::  
* External Interpreters::       
@end menu

@node DOSFOP Programs, Graphical User Interface , The Programs DOSFOP Uses, The Programs DOSFOP Uses
@section @DOSFOP{} Programs

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

@table @code
@CITEM 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.
@CITEM dosfopTranslator
This program reads the project data
base and the global configuration found in the @code{DOSFOP} subdirectory
and produces the Texinfo intermediate output. @*
It is called with the top-level directory as the current directory and without
arguments. 
@CITEM 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.
@end table

@node  Graphical User Interface , Programs for Producing DVI Files, DOSFOP Programs, The Programs DOSFOP Uses
@section Graphical User Interface 

@cindex graphical user interface
@cindex @sc{Tcl/Tk}
The @sc{Tcl/Tk} programs are located in the directory @code{@var{<DOSFOP
path>}/tcl}. 

The files ending in @samp{.tcl} are read by the main programs; the other
programs are started as separate processes. 

@table @code
@CITEM browse
@cindex project browser
Call the project browser.
@CITEM dosfop
@cindex @DOSFOP{} main window
@cindex main window (of @DOSFOP{})
Open the @DOSFOP{} main window.
@CITEM globalConfig
@cindex global options
Edit the global options.
@CITEM pureDosfop
Call @DOSFOP{} without using windows.
@CITEM structureConfig
@cindex configuration of structure
Edit the local options of a structure, whose name must be given as a parameter.
@CITEM subsystemConfig
@cindex configuration of subsystem
Edit the local options of a subsystem, whose name must be given as a parameter.
@end table

@node  Programs for Producing DVI Files, Programs for Producing Info Hypertext, Graphical User Interface , The Programs DOSFOP Uses
@section Programs for Producing @sc{dvi} Files

@table @code
@CITEM dosfopMacroExpander
@CODEINDEX makeinfo
This program is used instead of @code{makeinfo} for the expansion of
macros (@pxref{External Interpreters}).
@CITEM dosfopTexindex
@CODEINDEX texindex
This program is needed as an wrapper ofthe @code{texindex} program. The
generated indices need to be processed before and after the call to
@code{texindex} (see the following entry).
@CITEM fixtexindexpre
@CITEMX fixtexindexpost
The generated indices have some flaws and bugs which are corrected by these
two scripts. @*
@emph{fixtexindexpre} removes @code{\penalty 10000} from the index entries
and corrects name entris starting with a backslash.@*
@emph{fixtexindexpost} disables hyphenation of the function arrow and
corrects the initial letter of names starting with underscore.
@item texi2dvi --verbose @var{<intermediate Texinfo file>}
@CODEINDEX texi2dvi
This program controls the production of a @sc{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 @code{texi2dvi}:
@table @code
@item TEXINDEX dosfopTexindex
@cindex @code{TEXINDEX} (environment variable)
-- to replace the standard @code{texindex} program with the @DOSFOP{}
version.
@item TEXINPUTS .:@var{<DOSFOP path>}/tex:@var{<old value of TEXINPUTS>}
@cindex @code{TEXINPUTS} (environment variable)
-- to ensure that files included by the generated Texinfo file are found at
the proper places.
@item MAKEINFO dosfopMacroExpander
@cindex @code{MAKEINFO} (environment variable)
-- to replace @code{makeinfo} as the macro-processing program.
@end table
Before @code{texi2dvi} is called, the current directory is changed to the
@code{DOSFOP} directory.
@CITEM texindex
This program is needed to process the indices for @sc{dvi} output.
@end table

@node Programs for Producing Info Hypertext, Programs for Producing HTML Hypertext, Programs for Producing DVI Files, The Programs DOSFOP Uses
@section Programs for Producing @sc{info} Hypertext

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

@table @code
@CITEM dosfopMacroExpander 
@CODEINDEX makeinfo
This program is used instead of @code{makeinfo} for the expansion of
macros (@pxref{External Interpreters}). @*
The program is called with these parameters:
@example
dosfopMacroExpander --verbose -I @var{<DOSFOP subdirectory>}
                    -I @var{<DOSFOP path>}/tex 
                    -E @var{<intermediate Texinfo file>}.new 
                    @var{<intermediate Texinfo file>}
@end example
@CITEM makeinfo
The @code{makeinfo} program generates the @sc{info} file. It is known to
have difficulties with long Texinfo files.@*
It is called with the following parameters:
@example
makeinfo --verbose --no-validate --no-warn -I DOSFOP 
         -I @var{<DOSFOP path>}/tex 
         @var{<intermediate Texinfo file>} 
         -o @var{<info output file>}
@end example
@end table

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

@node Programs for Producing HTML Hypertext, External Interpreters, Programs for Producing Info Hypertext, The Programs DOSFOP Uses
@section Programs for Producing @sc{html} Hypertext

@table @code
@CITEM dosfopMacroExpander 
@CODEINDEX makeinfo
This program is used instead of @code{makeinfo} for the expansion of
macros. (@pxref{External Interpreters}). @*
The program is called with these parameters:
@example
dosfopMacroExpander --verbose -I @var{<DOSFOP subdirectory>}
                    -I @var{<DOSFOP path>}/tex 
                    -E @var{<intermediate Texinfo file>}.new 
                    @var{<intermediate Texinfo file>}
@end example
@CITEM 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 @sc{info} file, better presentation of indices and some
other more minor adjustments).@*
The program is called with these parameters:
@example
texi2html -toc_name @var{<Table of Contents string>} 
                    -I ../DOSFOP -I @var{<DOSFOP path>}/tex 
                    -split_node -menu -verbose 
                    @var{<intermediate Texinfo file>}
@end example
The @var{<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.
@end table

@node External Interpreters,  , Programs for Producing HTML Hypertext, The Programs DOSFOP Uses
@section 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 @code{dosfopMacroExpander} here, because there is no better place for
this. 

@table @code
@CITEM sh
The @code{sh} interpreter is used for @code{texi2dvi} and
@code{dosfopTexindex}.
@CITEM perl
@cindex @code{PERL} (environment variable)
Perl is used for @code{dosfopMacroExpander}, @code{fixtexindexpre},
@code{fixtexindexpost} and @code{texi2html}. These programs run both under
Perl 4 and Perl 5. The location of perl is read from the environment
variable @code{PERL} which is set by @code{dosfop} and @code{pureDosfop}.
@item wish
@CODEINDEX wish
@cindex @sc{Tcl/Tk}
@cindex @code{WISH} (environment variable)
@sc{Tcl/Tk} Version 4.1 (or newer) is used for the graphical user interface
and the integration of @DOSFOP{} and @sc{oasys}. The location of wish is
read from the environment variable @code{WISH} which is set by @code{dosfop}
and @code{pureDosfop}. 
@CITEM dosfopMacroExpander
@CODEINDEX @@TeX
@CODEINDEX @@AA
@CODEINDEX @@AE
@cindex macro calls
@cindex macro names
The macros, which were introduced into the latest Texindex edition (version
3.9, October 1996) are expanded by a call to the @code{makeinfo}
program. Unfortunately, the macro expansion in @code{makeinfo} is not bug
free, so I decided to re-implement a separate program for macro
expansion. This implementation has some restrictions:
@itemize @minus{}
@item
Macro names must start with an uppercase letter.
@item
Parameters may not contain other macro calls or commands (except for special
macro invocation, where the argument is the rest of the entire line).
@item
No macro calls may occur in lines in which the Texinfo commands
@code{@@TeX@{@}}, @code{@@AA} or @code{@@AE} are used.
@end itemize
@end table

@node Tips and Tricks, Texinfo for Experienced TeX Users, The Programs DOSFOP Uses, Top
@appendix Tips and Tricks

@CODEINDEX dosfop.macros
@CODEINDEX dosfopPrelude.texi
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) @file{dosfop.macros} and/or @file{dosfopPrelude.texi} from
@file{@var{<DOSFOP path>}/tex} and modify
them.

@cindex trouble-shooting
@strong{Trouble-shooting:}
@table @emph
@item Commands are not processed and appear verbatim in the generated documentation.
Some commands are allowed only at the beginning of a line, @emph{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.
@end table

@menu
* Coloured Source Code::        
* Highlight Warnings::          
* No Indentation of Source Code::  
* Indentation of Documentation::  
* Obey Line Breaks in Documentation::  
* Add New Indices::             
* Find Unfinished Source Code::  
* Hide Source Code::            
* Javadoc::                     
@end menu

@node Coloured Source Code, Highlight Warnings, Tips and Tricks, Tips and Tricks
@section Coloured Source Code

@cindex colouring text
@cindex @code{@@BEGINOPAL} (macro)
@cindex @code{@@ENDOPAL} (macro)
To make your source code appear in a different colour in @sc{html}
hypertext, use these definitions:
@example
@@macro BEGINOPAL
@@ifhtml
<font color="8B000">
@@end ifhtml
@@example
@@end macro

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

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

@node Highlight Warnings, No Indentation of Source Code, Coloured Source Code, Tips and Tricks
@section Highlight Warnings

@cindex @code{@@BEGINDOCwarning} (macro)
@cindex @code{@@ENDDOCwarning} (macro)
@CODEINDEX @@cartouche

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

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

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

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

@cindex tagged documentation
@cindex level documentation (= tagged doc.)
The documentation must then be @emph{tagged} with the tag @samp{warning}:
@example
-- %@{warning@} This function is completely untested!
@end example

resulting in:
@example
@ifhtml
<font color="FF0000"><blink>
@end ifhtml
@cartouche
This function is completely untested!
@end cartouche
@ifhtml
</blink></font>
@end ifhtml
@end example

@node No Indentation of Source Code, Indentation of Documentation, Highlight Warnings, Tips and Tricks
@section No Indentation of Source Code

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

@example
@@macro BEGINOPAL
@@t@{
@@format
@@end macro

@@macro ENDOPAL

@@end format
@}
@@end macro
@end example

@node Indentation of Documentation, Obey Line Breaks in Documentation, No Indentation of Source Code, Tips and Tricks
@section Indentation of Documentation

@cindex indentation
@cindex @code{@@BEGINOPAL} (macro)
@cindex @code{@@ENDOPAL} (macro)
@cindex @code{@@BEGINDOC} (macro)
@cindex @code{@@ENDDOC} (macro)
Normally, source code is indented and documentation is not. To
reverse the default, redefine @code{@@BEGINOPAL}, @code{@@ENDOPAL},
@code{@@BEGINDOC} and @code{@@ENDDOC}:

@example
@@macro BEGINOPAL
@@t@{
@@format
@@end macro

@@macro ENDOPAL
@@end format
@}
@@end macro

@@macro BEGINDOC
@@quotation
@@end macro

@@macro ENDDOC
@@end quotation
@@end macro
@end example

@node Obey Line Breaks in Documentation, Add New Indices, Indentation of Documentation, Tips and Tricks
@section Obey Line Breaks in Documentation

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

@example
@@macro BEGINDOC
@@format
@@end macro

@@macro ENDDOC
@@end format
@@end macro
@end example

@node Add New Indices, Find Unfinished Source Code, Obey Line Breaks in Documentation, Tips and Tricks
@section Add New Indices

@cindex new indices
@cindex xy index
@cindex @code{@@FINALIZEDOC} (macro)
@CODEINDEX @@defcodeindex
@CODEINDEX @@defindex
@CODEINDEX @@xyindex
If you want to add an @samp{xy} index, you must edit two files:

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

@@contents
@@end macro
@end example
@end table

You may now use the command @code{@@xyindex} to include entries:
@example
-- %@@xyindex An XY index entry
@end example


@node Find Unfinished Source Code, Hide Source Code, Add New Indices, Tips and Tricks
@section Find Unfinished Source Code

@cindex unfinished source code
@cindex To-Do Index
@cindex @code{@@FINALIZEDOC} (macro)
@CODEINDEX @@defcodeindex
@CODEINDEX @@tdindex
@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 @ref{Add New Indices}, to add a new
`To Do' index:

@table @file
@FITEM dosfopPrelude.texi
Add the line
@example
@@defcodeindex td
@end example
@FITEM dosfop.macros
Change the @code{@@FINALIZEDOC} macro to insert your index at the end:
@example
@@macro FINALIZEDOC
@@node To Do, Texinfo for Experienced TeX Users, XY Index, Top
@@chapter To Do
@@printindex td

@@contents
@@end macro
@end example
@end table

The code then looks like this:
@example
/* %This function sorts its argument.
@@tdindex FUN sort implemented inefficiently
*/
FUN sort: seq[mytype] -> seq[mytype]
@end example

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


@node Hide Source Code, Javadoc, Find Unfinished Source Code, Tips and Tricks
@section Hide Source Code

@cindex hide source code
@cindex exclude source code
@cindex ignore source code
@CODEINDEX @@ignore
You can exclude source code from the generated documentation with the help
of the @code{@@ignore} environment:

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

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

@node  Javadoc,  , Hide Source Code, Tips and Tricks
@section Javadoc

@CODEINDEX javadoc
@DOSFOP{} cannot process the special tags recognized by @code{javadoc}. But
if you are willing to sacrifice @sc{dvi} and
@sc{info} output, @DOSFOP{} can also process files documented in
@sc{javadoc} style.

@cindex @code{@@BEGINDOC} (macro)
@cindex @code{@@ENDDOC} (macro)
The following definitions allow @sc{html} documentation:
@example
@@macro BEGINDOC
@@ifhtml
@@end macro

@@macro ENDDOC
@@end ifhtml
@@end macro
@end example

@CODEINDEX dosfop.filetypes
To allow inclusion of @sc{java} files, create a file @file{dosfop.filetypes}
in the @code{DOSFOP} directory, which consists of this line:
@example
.java: : :/**:*/: :
@end example
This will tell @DOSFOP{} how to process @samp{.java} files: nested comments
starting with @code{/**} and ending with @code{*/} are documentation,
everything else is source code.


@node Texinfo for Experienced TeX Users, Useful Texinfo Commands, Tips and Tricks, Top
@appendix 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:
@table @b
@item Escaping by @@
@cindex escaping by @@
The escape character is the at sign (@samp{@@}). The backslash character
(@samp{\}) need not be escaped. The only characters that must be escaped are
the at sign (write @code{@@@@}) and the curly brackets (write @code{@@@{} and
@code{@@@}} resp.).
@item Environments
@cindex environments
An environment @code{env} is begun with @code{@@env} and terminated with
@code{@@end env}. Both commands must appear on a line of their own and may
not be preceded by spaces or tabs.
@item Commands that occupy an entire line
@cindex 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.
@item Itemize lists
@cindex itemize lists
@CODEINDEX @@bullet
@CODEINDEX @@minus
@CODEINDEX @@itemize
@CODEINDEX @@item
There are two traps for @TeX{} users with itemize lists:
@enumerate
@item
The command to begin an environment has an additional argument for the
command generating the mark
(most often @code{@@bullet} or @code{@@minus}).
@item
The @code{@@item} command must appear on a line of its own and may
not be preceded by spaces or tabs.
@end enumerate
An itemize list might look like this:
@example
@@itemize @@bullet
@@item
Text for first item.
@@item
Text for second item.
@@item 
@dots{}
@@end itemize
@end example
@end table


@node Useful Texinfo Commands, Changes, Texinfo for Experienced TeX Users, Top
@appendix 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 @emph{very} quick introduction, you need to learn only the following
commands:

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

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

@ifhtml
<p>
If you view this locally at TU Berlin, the following links take you to the
relevant chapters of the Texinfo Manual:
<ul>
<li><a href="file:/usr/gnu/html/texinfo/texinfo_9.html#SEC91">Cross
References</a>
<li><a href="file:/usr/gnu/html/texinfo/texinfo_10.html#SEC103">Marking
Words and Phrases</a>
<li><a href="file:/usr/gnu/html/texinfo/texinfo_11.html#SEC120">Quotations
and Examples</a>
<li><a href="file:/usr/gnu/html/texinfo/texinfo_12.html#SEC132">Making Lists
and Tables</a>
<li><a href="file:/usr/gnu/html/texinfo/texinfo_14.html#SEC149">Special
Insertions</a>
<li><a href="file:/usr/gnu/html/texinfo/texinfo_16.html#SEC175">Making and
Preventing Breaks</a> 
<li><a
href="file:/usr/gnu/html/texinfo/texinfo_18.html#SEC196">Footnotes</a>
<li><a href="file:/usr/gnu/html/texinfo/texinfo_24.html#SEC234">@-Command
List</a>
</ul>

<p>
@end ifhtml

@menu
* Environments::                
* Font Modification::           
* Formatting Commands::         
* Cross References::            
* Miscellaneous::               
@end menu

@node Environments, Font Modification, Useful Texinfo Commands, Useful Texinfo Commands
@section Environments

@cindex environments    
The following list contains the commands needed to begin an
environment. Environments are ended by the command @code{@@end
@var{environment}}.

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

@table @code
@CITEM @@enumerate
@CODEINDEX @@item
Begin a numbered list. Use a separate @code{@@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.
@CITEM @@itemize @var{mark-gen-char-or-command}
@CODEINDEX @@item
@CODEINDEX @@bullet
@CODEINDEX @@minus
Produce a sequence of indented paragraphs with a mark inside the left
margin at the beginning of each paragraph. Use a separate @code{@@item} line
at the beginning of each entry. The beginning command takes an argument
which is used to generate the initial mark. Most often, @code{@@bullet} or
@code{@@minus} are used. 
@CITEM @@table @var{formatting-command}
@CODEINDEX @@item
@CODEINDEX @@itemx
Begin a two-column table. Use @code{@@item @var{first-column}} for each
entry. First-column entries are printed in the font given in
@var{formatting-command}. @* 
If you want to group several entries, use @code{@@itemx} instead of
@code{@@item} for the second and following entries. Add the explanation
after the last @code{@@itemx} line.
@end table


@node  Font Modification, Formatting Commands, Environments, Useful Texinfo Commands
@section Font Modification

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

@node Formatting Commands, Cross References, Font Modification, Useful Texinfo Commands
@section Formatting Commands

@cindex paragraphs, formatting of
@cindex non @OPAL{} source code
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 @ref{DOSFOP and
Non-OPAL Programs}.)

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

@node  Cross References, Miscellaneous, Formatting Commands, Useful Texinfo Commands
@section Cross References

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

@table @code
@CITEM @@ref@{node name@}
Generate a reference to the named node.
@CITEM @@xref@{node name@}
Produce an initial @samp{See} followed by a reference to the named node.
@CITEM @@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 @samp{see} followed by a
reference to the named node.
@end table

@node Miscellaneous,  , Cross References, Useful Texinfo Commands
@section Miscellaneous

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


@node Changes, Index, Useful Texinfo Commands, Top
@appendix Changes

@DOSFOP{} 1.92g has the following differences to version 1.92f:
@itemize @bullet
@item
In the @file{doc} directory, an additional top-level @sc{html} file
@file{index.html} is created.
@item
Bug fix: Earlier versions were unable to handle the region variant of
InterOpal positions, which are generated by ocs 2.3c and newer.
@end itemize

@DOSFOP{} 1.92f has the following differences to version 1.92d:
@itemize @bullet
@item 
Output of superfluous empty lines has been reduced.
@item
Indices in @sc{html} output use @code{<TABLE>} and colours.
Functionality in indices now printed in italics.
@item
If a subsystem (or toplevel) contains a file @file{Survey.texi}, this file
is included instead of the survey in the configuration.
@item 
Defaults have been slightly changed. Coloured source code (as given in
@ref{Coloured Source Code}) is no used by default.
@item
@sc{ocs} has now support for building documentation.
@end itemize

@DOSFOP{} 1.92d has the follwoing differences to version 1.92c:
@itemize @bullet
@item
Definition of @code{DOSFOP} and extension of @code{PATH} is no longer
necessary.
@item 
The initial @sc{html} file is called @file{doc/out.html}.
@item
The previewers for @sc{dvi}, @sc{info} and @sc{html} files can be configured
by setting the variables @code{XDVI}, @code{INFO} and @code{WWWBROWSER}
respectively. 
@item 
Locations and some names of @sc{Tcl/Tk} scripts have changed.
@item
Location of @code{perl} and @code{wish} are not hard-wired into the code,
but read from the variables @code{PERL} and @code{WISH} respectively.
@end itemize


@DOSFOP{} 1.92c has the following differences with respect to version 1.90h:
@itemize @bullet
@item
For every structure @code{S}, a Texinfo file @code{OCS/S.doc.texi} is
created.  
@item 
Incremental generation of documentation is supported, @xref{Incrementally
Generating Documentation}.
@item
Some bugfixes, especially index generation.
@item 
The generated @sc{html} files uses frames. Default output has changed to
@file{doc/out.html}. 
@end itemize

@node  Index,  , Changes, Top
@unnumbered Index
@printindex cp

@contents

@bye
@c Local Variables:
@c compile-command: "texi2html manual.texi" 
@c End:
