Manipulation of an AlcoveBook document

The transformation

SGML documents can be validated in order to check the conformity of their syntax and of their structure with the DTD describing it. Validation begins by parsing the document and then continues by verifying the validity of documents in their context. Thus, when an element is in a bad context, an error is produced.

Validation is always done as a part of the document parsing, but it can be requested manually, using the following command: nsgmls -s file.sgml.

When the validation is over, documents are ready to be formatted, that is to say, to be transformed in a printable or displayable form. This formatting implies transforming the document into another form using a stylesheet. Stylesheets are written in a language that describes the transformation of its structure to a presentation. DSSSL the stylesheet description language used here for AlcoveBook.

Tools for transformation

Tools used to manipulate an AlcoveBook document are:

All of those tools use the same syntax for their arguments. That is to say: alcovebook2x file.sgml. The default stylesheet is inferred from the role attribute of your article, but it is possible to use another stylesheet using the -s style option. Thus, to format a random AlcoveBook document as a technical proposal would be, just use alcovebook2ps -s proposal doc.sgml.

Common transformation errors

This section describes the most common errors occuring during the transformation of the document. You will notice that error messages include a line number, and something which looks like a column number, but which is indeed the number of characters since the beginning of the line, which will not match if you used tabs to indent your text.

end tag for "SECTION" which is not finished

this error is caused by a closing element used while the opening element has not been provided. It can also be caused by a mandatory element in section which is not present. In this example of a section, it may be because your section has no content and no subsection.

general entity "plop" not defined and no default entity

you used &plop; in your document, without defining &plop; - or you made a typo

end tag for "COMPUTEROUTPUT" omitted, but its declaration does not permit this

the opening computeroutput has been used but has not been closed. In AlcoveBook, only empty elements (eg. xref, imagedata) allow the closing tag to be omitted.

character data is not allowed here

textual content is not authorized in a given context

Using Make

Note that providing a Makefile for your documents is mandatory for all documents put in the Alcôve CVS repository. We suggest that you use the following Makefile to compile your document. You will note that all of the job is done by including a file (alcove/commun/make/alcovebook) that contains make rules. Always include it using its relative path so that it can work in cvs workspaces.

Example 14. Makefile example

ALCOVEBOOK_STYLE = alcovebook-intro.en
include ../../../commun/make/alcovebook