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.