Idxmx : creating indexes for mx document

epsffit.mx version 2.4

Peter Boncz

19 April 1999





1 introduction

The Mx documentation tool has been developed to improve the quality of program documentation. In particular, all program modules are written as if they form part of a final, and completely documented system.That is, the source code can be elicitated in the native language, motivating its design, assumptions, and behavior. Using a text formatter enables the programmer to express more clearly the program properties. Just consider a pictorial presentation of the program structure or an assertion on a set of variables, typeset in a mathematical style. The result is a more readable document where the actual program code plays the role of an illustration of the more global system objectives and design boundaries. The programmer works with Mx files rather than program source files. Therefore, the programmer uses special Mx-directives, to separate the code sections from the documentation sections. The overhead involved in writing a program as a Mx-document is kept minimal. Likewise, the overhead incurred on the edit-compile-debug cycle is kept at a minimum. For example, for C-based code fragments Mx generates compiler directives that enables you to debug the system in terms of Mx-documents, rather than the C-source files extracted. Using Mx during the whole software development cycle leads to a product where the documentation is in sink with the program itself. Moreover, the physical adjanceny of documentation containing rationale and assumptions stimulates the delivery of better quality code, because discrepancies in design and coding are more easily recognized.




2 Mx facilities

An Mx document consists of text blocks separated by directives. The Mx program uses these directives to separate code from documentary comments. Following, the Mx program can be run in two different modes: source extraction mode and document mode. In code extraction mode it will gather all the code blocks from the Mx document and redirects them to a source file. The default name for this file is derived by the basename of the Mx document file and the specific code directive, which precedes the code block. The code directive depends therefore on the programming language used. Currently the languages C, C++, Java, Prolog, Qnap, Yacc and Lex are supported. The program development cycle is improved by breaking a large program into well-delineated modules. In particular, when modules can be compiled on an individual basis such modularization pays off. To accomodate this approach, the basename for source files can be changed in the Mx document using a directive. Again, line directives are added to the source file, which refer to the position of the code block in the original Mx document. In document extraction mode, a file for a document formatting program is generated. This file contains both the documentary comments and the program source fragments. Currently the LaTeX and ``troff -ms'' formatting programs are supported. When you use Mx-directives only then you can decide on the formatter during document generation. At places one might wish to use specific features of the underlying formatters. Such use is supported by an escape mechanism, which allows you to enter text to be interpreted by the text processor only. This way you can easily add figures and tables to your document. The only exception to this rule is the support for typesetting characters in bold, italics, or in code font which are supported by inline Mx macros. In document mode, Mx creates a table of contents containing a reference to all sections and subsections of the document. The user can also create up to 9 reference tables, which are appended to the document and which could document more specific indices. The indices are sorted alphabetically on their entries. In document mode, Mx supports multilevel hiding of text. Large parts of programs are generally not interesting enough to include them in a final document. By running Mx with different hiding levels, one can produce documents in several gradations of detail, from manager style to system programmer style. Some comments on the code will never be included in the final document. Moreover, an archiving option is available to retain the early attempts, valuable remarks on buggy code, etc., within the Mx document by marking them as being archived. Two kind of directives influence both the code extraction and the document extraction mode. They are parametrized text macros and conditional statements. The macros calls are expanded for code extraction, but not for document extraction. In a document, the macro calls are annotated with a reference to the sextion and subsection, where the macro is defined. Conditional statements are used to define different versions of the code or commentary. For instance, if the code must be written for two different compilers, it is possible to include two different versions within a single document and distinguish between them using a conditional statement. The condition is triggered by the existence of a macro definition. Simple macros can also be defined on the command line of the Mx program.


2.1 Command line options


Usage: Mx <flags> <file>.mx.
        -t              Produce LaTeX document (default).
        -c              Extract code.
        -R<dir>         Set target directory to <dir>).
        -S<style>       Set LaTeX documentstyle to 'style'.
        -s              Produce nroff -ms document.
        -1              Single column (default) .
        -2              Double column.
        -H<n>           Set hide level to 'n' (-H0 default).
        -d              Produce a draft document.
        -x <extension>          Extract <extension> labelled code.
        -w              Extract HTML code.
        -D<id>          Define macro 'id'.
        -T<string>      Define default hide text <string>.
        -u              Extract a part of document.
        -n <Title>              Explicitly define the name of title.
        -a <Author>             Explicitly define the author name.
        -v <Version>            Explicitly define the version.


2.2 Code Extraction

For code extraction Mx is called with the following arguments:
Mx -c{file} {-D<macro>}+  <file>.mx 
The -c option sets Mx in code extraction mode. If a <file> argument is given, Mx will only extract the code blocks, which are directed to a file with the same basename. By default Mx extracts all the code files. The -D <macro> option is used for defining body-less macros. If used in combination with the conditional statements, a single Mx document can produce different document and code versions. The sample Mx file illustrates the use of code directives, conditional statements and the definition of the base name for the code file.
meaning
test This defines the base name for the file to which the following code is copied
i This directive introduces a POOL implementation unit
ifdef SOLARIS a:= Deep_copy(D).new it a conditional statement on OS Type
else a:= b!deep_copy();
endif
++
Code Extraction's directives


2.3 Document extraction

For document extraction Mx is called with the following arguments:
Mx [-t -s -w -u -n -a -v] -S<StyleFileName>  [-1 -2] -H<n> -D<macro>}+  <file>.mx 
The options enclosed in ``['' and ``]'' are mutual exclusive and all flags are optional. By default, Mx generates a Latex document in single column style.

2.3.1 Troff or Latex
The options -s and -t select between extracting espectively a document in ``troff -ms'' format and in \LaTeX format. The default format is LaTeX. To accomodate local style conventions, the -S<file> option can be used to use an alternative LaTeX style file. Mx produces a document either in single column format, using the -1 option or in double column format with the -2 option. Single column format is the default.

2.3.2 HTML documents
The -w option selects the HTML document extraction. This produces a single .html document with the basename of the Mx-file. To format the document nicely, this extraction mode uses Netscape extensions to HTML, like tables, colors and background. Since many code uses @T LaTeX blocks for documentation, the extraction performs an on-the-fly, opportunistic, LaTeX-to-HTML translation. This translation works for all LaTeX commands, and also bibliographies and EPFS imagery (.bib/.eps files expected in the "." directory). Beware: LaTeX command definitions with \def and \newcommand are not supported, though. This process will produce one single -- unstructured -- file. Internal URL links are generated only for:
Note that any type of code (such as an URL) can be included in HTML using the "@[<sgml-text>@" macro. It will be extracted "as is" in HTML extraction mode. This facility is exploited by the special utilities WWWidx and WWWlink to interlink Mx documents into a source code web.

2.3.3 Hiden Level
The -H option is used to set the text hiding level to <n>. In Mx document, a level text block is bracketed by @{ and @}. These 'hide' brackets can be nested. If Mx is called with option -H1, then all text enclosed within @{ and @} is replaced by the hide text. Hide level 2 (-H2) will replace all text within @{ @{ <text> @} @} by the hide text. Again the -D<macro> option defines body-less macros. This option is useful in combination with the conditional statement directives. (@ifdef <macro>, @else and @endif. )

2.3.4 Partial document extraction
The -u option is used to extract part of document. Part of document which to be extracted must start with @U and end with @u directives. For example,
* Section Contents of section. U This part will be extracted with argument -u u if -u is not given and @U @u appears is in mx file, mx will extract this block too. This directive is useful for creating document for specific purpose such as user's document.




3 Mx-file structure

The Mx file is a text file interspersed with code and text directives. Typically a Mx document consists of a prologue, which defines the title, author, version and date of the document , a body, which contains code fragments and commentaries, organized into sections, subsections and (numbered) paragraphs, and an epilogue. The epilogue is generated by the Mx program and contains the macro- and user defined indices. A table of contents is added by Mx to the prologue, listing all the sections and subsections. A sample Mx-document is shown in the following:
meaning
t THE TITLE Defines the document title.
a THE AUTHOR Defines the author
v 1.00 Defines the version number
d 1/1/90 Defines the date
f Defines the basename for the code files
* Section A section
...contents... contents
h precedes h file
+ Subsection A subsection
...
c precedes c implementation code
int test;
... C Code ...
++
mx-file structure




4 Code directives

The code directives, summarized in Table , all start at the beginning of a line. The text following a code directive uptil another Mx directive is copied after macro expansion, to a file basename.suffix. The default for basename is the basename of the supplied Mx file. This default can be changed using the @f <file basename> directive. This command changes the basename to <new file basename>. The suffix is implied by the code directive used.




5 Layout directives

All layout directives must directly follow a newline. The layout directives influence the outlook of the document. In the prologue of the Mx file the information for the title page is defined. In the body of the Mx file sections, subsections, and subsubsections can be defined. Both the title and author must be specified to generate a title page and a table of contents. If not, no title page and table of contents are generated. The following table summarizes the layout directives.
Meanings
t +