User manual

Introduction

Before the Amsterdam SGML Parser can be used, it must be installed. An executable program generator must be created which parses the input document type definition (DTD).
The executable program generator must be installed in a place on the system that is reachable for the user. generator accepts a DTD. The DTD is parsed and a document parser doc_parser is generated.
A program (shell script) called asp can be made to generate the document parser. Under Unix the file asp looks as follows:

    PWD=`pwd`
    DIR=/Asp/Parser/Src
    
    rm $DIR/document*.g $DIR/DOC/document*.c  $DIR/DOC/document*.o
    if (cd $DIR; GEN/generator $PWD/$1 document 2>$PWD/errors)
    then
        cd $DIR;  make -f Makefile doc_parser
        mv $DIR/DOC/doc_parser $PWD/asp_$1
    else
        echo "DTD $i contains FATAL error, see file: errors"
    fi

The above shell script performs the following functions: It takes as parameter the file ($1) containing the document type definition. It changes to the directory where the sources of the Amsterdam SGML Parser are kept, in this case `/Asp/Parser/Src' and removes previously generated document.g document.c and document.o files. There it calls:

GEN/generator  document

to parse the document type definition in . If the exit status of generator does not equal 0, errors have occurred and the script must be stopped. Otherwise, the document type definition is correct and the script proceeds as follows:

make -f Makefile doc_parser

This creates the document parser in the directory DOC. Now the document parser must be moved because a generation of a new doc_parser overwrites the one already there.

mv DOC/doc_parser asp_

Note that the generated LLgen and C-files are generated in the directories $DIR/DOC and $DIR. This means that only one person at the time can use the asp script. If more users are using asp at the same time, the script should be changed. The generated files must then be generated in separate directories. The compiled files must also be created in separate directories.
For the user everything is simple. To invoke the asp shell script, the user types the command:

asp

and the script automatically returns error reports on standard error output or creates the document parser called asp_ in the user's directory. In the latter case the user can parse a document in file by calling:

asp_ file.doc >complete_file.doc 2>error_output

On the standard output, which is redirected to the file `complete_file.doc', the `complete document' including all start- and end-tags, expanded entities, etc. is written. All error- and warning-messages are written on the standard error output. In the example above the standard error output is redirected to the file `error_output'.
If the `file.doc' parameter is only a minus `-', then the document will be read from standard input. This enables the use of pipes in Unix. This option is also available in the generator.
Before the `file.doc' parameter there are two optional arguments. The first optional argument is `-r ', which specifies the file used by the backend of the document parser. See the chapter `The Backend' for a description of the replacement file.
The second optional argument is `-z ', which specifies the string used in error-messages. Default, the name of the document file parameter `file.doc' is used. This option is useful if the document is read from standard input, or in a batch environment where the docuemnt file always has the same name.
Summarized, a call to a document_parser is of the form:

doc_parser [-r replacement_file] [-z 'text string'] document_file

doc_parser [-r replacement_file] [-z 'text string'] -

where the arguments between square brackets are optional.