There are a couple of TDE-specific tools for manipulating DocBook files, namely meinproc and checkXML. checkXML (as the name suggests) is used to check that documents are valid, well-formed XML, and meinproc converts DocBook files to HTML. Here's some hints on using each of them:
checkXML is a simple command with only one argument: the file to check. However, the output can be a bit daunting, since one small mistake can cause a cascade of errors. The trick is to look at the first error, fix that error, save the file, and run checkXML again. Often, fixing that one error will get rid of all the other error messages. When running meinproc, the same procedure applies.
Most errors in DocBook sources fall into one of a few categories. Here are descriptions of some of the most common errors and their solutions:
index.docbook:880: parser error : Opening and ending tag mismatch: para
line 879 and sect2
</sect2>
^
This is possibly the most common type of error. It's caused either by an element that hasn't been closed, or by tags that overlap. The error above was generated by the following markup:
<sect2>
...
878: running &meinproc;, the same procedure applies.</para>
879: <para>&checkxml; is a simple command with
880: </sect2>
...
The <para>
tag on line 879 has
not been closed before the </sect2>
on
line 880, causing the error. The simple fix in this case is to add a </para>
before the closing </sect2>
.
index.docbook:932: element qandaentry: validity error : Element qandaentry content
does not follow the DTD, expecting (blockinfo? , revhistory? , question , answer*), got (answer)
</para></answer></qandaentry>
^
This error is caused by an element in the document not matching the requirements of the DocBook DTD (Document Type Definition). The DTD specifies what each element must contain. This list is shown after expecting in the error message. This so-called “content model” is quite difficult to understand at first: refer to the Duck Book and the section “Understanding Content Models” for full information.
The text after got shows the content actually found in the document.
In the example above, we have a qandaentry
which is missing the required question
element. This
was generated by the following input:
<qandaset>
<qandaentry><answer><para>An answer
</para></answer></qandaentry>
</qandaset>
Adding a question
element before the
answer
fixes the problem.
An easy mistake to make is to forget to put a
para
element around text in, for example, a
listitem
or a
sect
. This will be shown
as CDATA in the got
section of the error.n
The most common way to run meinproc is simply as
meinproc docbook-file
where
docbook-file
is usually
index.docbook
. This command creates HTML pages
from the DocBook file. Note that these pages are only viewable in
TDE-based browsers (like Konqueror). If you need to view the HTML
output in another browser (for example, if you're placing it on line),
use
meinproc --stylesheet
stylesheet-name
docbook-file
where
stylesheet-name
is the
full path to one of the XSL stylesheets in $TDEDIR
/share/apps/ksgmltools/customization
.
To produce output suitable for the web, you can use
tde-web.xsl
or
tde-chunk-online.xsl
. See the
README
file in that directory for more details.
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team