Every validator produces slightly different error messages, but most indicate exactly (at least technically[2]) what is wrong and where the error occurred. With a little experience, this information is all you’ll need to quickly identify what’s wrong.
In the rest of this section, we’ll look at a number of common errors and the messages they produce in MSV. We’ve chosen MSV because it generally produces informative error messages.
Out-of-context character data is frequently caused by a missing start tag, but sometimes it’s just the result of typing in the wrong place!
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>Test Chapter</title> <para> This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. </para> You can't put character data here. <para> <emphasis role="bold">This</emphasis> paragraph contains <emphasis>some <emphasis>emphasized</emphasis> text</emphasis> and a <superscript>super</superscript>script and a <subscript>sub</subscript>script. </para> <para> This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. </para> </chapter>
java -jar msv.jar docbook.rng badpcdata.xml start parsing a grammar. warnings are found. use -warning switch to see all warnings. validating badpcdata.xml Error at line:10, column:7 of badpcdata.xml unexpected character literal
You can’t put character data directly in a
chapter. Here, a wrapper element, such as
para, is missing around the sentence between the
first two paragraphs.
If you spell a start tag incorrectly, or use the wrong namespace, the parser will get confused:
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>Test Chapter</title> <para> This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. </para> <paar> <emphasis role="bold">This</emphasis> paragraph contains <emphasis>some <emphasis>emphasized</emphasis> text</emphasis> and a <superscript>super</superscript>script and a <subscript>sub</subscript>script. </para> <para> This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. </para> </chapter>
java -jar msv.jar docbook.rng misspell.xml start parsing a grammar. warnings are found. use -warning switch to see all warnings. validating misspell.xml Error at line:9, column:7 of misspell.xml tag name "paar" is not allowed. Possible tag names are: <address>,<anchor>, <annotation>,<bibliography>,<bibliolist>,<blockquote>,<bridgehead>, <calloutlist>,<caution>,<classsynopsis>,<cmdsynopsis>, <constraintdef>,<constructorsynopsis>,<destructorsynopsis>,<epigraph>, <equation>,<example>,<fieldsynopsis>,<figure>,<formalpara>, <funcsynopsis>,<glossary>,<glosslist>,<important>,<index>, <indexterm>,<informalequation>,<informalexample>,<informalfigure>, <informaltable>,<itemizedlist>,<literallayout>,<mediaobject>, <methodsynopsis>,<msgset>,<note>,<orderedlist>,<para>, <procedure>,<productionset>,<programlisting>,<programlistingco>, <qandaset>,<refentry>,<remark>,<revhistory>,<screen>,<screenco>, <screenshot>,<section>,<section>,<segmentedlist>,<sidebar>, <simpara>,<simplelist>,<simplesect>,<synopsis>,<table>,<task>, <tip>,<toc>,<variablelist>,<warning>
Luckily, these are usually easy to spot, unless you accidentally spell the name of another element. In that case, your error might appear to be out of context.
Sometimes the problem isn’t spelling, but rather placing a tag in the wrong context. When this happens, the validator tries to figure out what it can add to your document to make it valid. Then it tries to recover by continuing as if it had seen what it just added. Of course, this may cause future errors:
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"> <title>Test Chapter</title> <para> This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. </para> <para><title>Paragraph With Inlines</title> <emphasis role="bold">This</emphasis> paragraph contains <emphasis>some <emphasis>emphasized</emphasis> text</emphasis> and a <superscript>super</superscript>script and a <subscript>sub</subscript>script. </para> <para> This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. This is a paragraph in the test chapter. It is unremarkable in every regard. </para> </chapter>
$ java -jar msv.jar docbook.rng context.xml start parsing a grammar. warnings are found. use -warning switch to see all warnings. validating context.xml Error at line:9, column:14 of context.xml tag name "title" is not allowed. Possible tag names are: <abbrev>,<accel>, <acronym>,<address>,…,<varname>,<warning>,<wordasword>,<xref>
In this example, we probably wanted a
formalpara so that we could have a title on the
paragraph. But note that the validator didn’t suggest this alternative.
The validator only tries to add additional elements, rather than rename
elements that it’s already seen.
[2] It is often the case that you can correct an error in the document in several ways. The validator suggests one possible fix, but this is not always the right fix. For example, the validator may suggest that you can correct out-of-context data by adding another element, when in fact it’s “obvious” to human eyes that the problem is a missing end tag.