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 used to manipulate an AlcoveBook document are:
alcovebook2pdf, to convert them into PDF (via pdfLaTeX), with clickable table of contents and cross-references. This is the primary format for all Alcôve outgoing documentations ;
alcovebook2ps, to convert them into PostScript (via LaTeX) ;
alcovebook2html, to convert them into a set of HTML files.
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.
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.
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.
you used &plop; in your document, without defining &plop; - or you made a typo
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.
textual content is not authorized in a given context
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.