PrevWriting Documentation: Procedures and ToolsNext

Checking and Viewing the Documents

There are a couple of KDE-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:

Using checkXML

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:

Opening and ending tag mismatch

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>.

Element does not follow the DTD

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 sectn. This will be shown as CDATA in the got section of the error.

Using meinproc

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 KDE-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 $KDEDIR/share/apps/ksgmltools/customization. To produce output suitable for the web, you can use kde-web.xsl or kde-chunk-online.xsl. See the README file in that directory for more details.