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:
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'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 &meinproc5;, the same procedure applies.</para> 879: <para>&checkxml5; is a simple command with 880: </sect2> ...
<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
- 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
qandaentrywhich is missing the required
questionelement. This was generated by the following input:
<qandaset> <qandaentry><answer><para>An answer </para></answer></qandaentry> </qandaset>
questionelement before the
answerfixes the problem.
An easy mistake to make is to forget to put a
paraelement around text in, for example, a
sect. This will be shown as CDATA in the got section of the error.
The most common way to run meinproc5 is simply as
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),
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-chunk-online.xsl. See the
README file in that directory for more details.