PrevWriting Documentation: Procedures and ToolsNext

Checking and Viewing the Documents

There are a couple of KDE-specific tools for manipulating DocBook files, namely meinproc5 and checkXML5. checkXML5 (as the name suggests) is used to check that documents are valid, well-formed XML, and meinproc5 converts DocBook files to HTML. Here's some hints on using each of them:

Using checkXML5

checkXML5 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 checkXML5 again. Often, fixing that one error will get rid of all the other error messages. When running meinproc5, 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 is caused either by an element that has not been closed, or by tags that overlap. The error above was generated by the following markup: 



<sect2>
...
878: running &meinproc5;, the same procedure applies.</para>
879: <para>&checkxml5; 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 meinproc5

The most common way to run meinproc5 is simply as 

meinproc5 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 are placing it on line), use 

meinproc5 --stylesheet stylesheet-name docbook-file

where stylesheet-name is the full path to one of the XSL stylesheets found in the kdoctools git repository 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.