File: ch03.html

package info (click to toggle)
xae 1.0beta6-5
links: PTS
area: main
in suites: sarge
size: 28,184 kB
ctags: 12,210
sloc: java: 27,149; xml: 20,864; lisp: 12,921; perl: 1,054; sh: 237; makefile: 169
file content (1429 lines) | stat: -rw-r--r-- 34,758 bytes
parent folder | download | duplicates (2)
<HTML
><HEAD
><TITLE
>Parsing DocBook Documents</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.45"><LINK
REL="HOME"
TITLE="DocBook"
HREF="docbook.html"><LINK
REL="UP"
TITLE="Introduction"
HREF="part1.html"><LINK
REL="PREVIOUS"
TITLE="Creating DocBook Documents"
HREF="ch02.html"><LINK
REL="NEXT"
TITLE="Publishing DocBook Documents"
HREF="ch04.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="dbtdg.css"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>DocBook: The Definitive Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="ch02.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="ch04.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="CH-PARSE"
>Chapter 3. Parsing DocBook Documents</A
></H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>3.1. <A
HREF="ch03.html#AEN4107"
>Validating Your Documents</A
></DT
><DT
>3.2. <A
HREF="ch03.html#AEN4220"
>Understanding Parse Errors</A
></DT
></DL
></DIV
><P
><A
NAME="PARSDOCCH4"
></A
>
<A
NAME="DOCDTDPARSCH4"
></A
>

A key feature of <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> and <SPAN
CLASS="ACRONYM"
>XML</SPAN
> markup is that you
<I
CLASS="EMPHASIS"
>validate</I
> it.  The DocBook <SPAN
CLASS="ACRONYM"
>DTD</SPAN
> is a precise description
of valid nesting, the order of elements, and their content.  All
DocBook documents must conform to this description or they are not
DocBook documents (by definition).</P
><P
><A
NAME="AEN4059"
></A
>
<A
NAME="AEN4062"
></A
>

A <I
CLASS="FIRSTTERM"
>validating parser</I
> is a program that can read
the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
> and a particular document and determine whether the exact
nesting and order of elements in the document is valid according to
the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>.</P
><P
><A
NAME="AEN4069"
></A
>

If you are not using a structured editor that can enforce the markup
as you type, validation with an external parser is a particularly
important step in the document creation process.  You cannot expect
to get rational results from subsequent processing (such as document
publishing) if your documents are not valid.</P
><P
><A
NAME="AEN4073"
></A
>
The most popular free <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> parser is <SPAN
CLASS="ACRONYM"
>SP</SPAN
> by James Clark,
available at <A
HREF="http://www.jclark.com/"
TARGET="_top"
>http://www.jclark.com/</A
>.</P
><P
><A
NAME="AEN4080"
></A
>
<A
NAME="AEN4082"
></A
>
<A
NAME="AEN4084"
></A
>
<A
NAME="AEN4087"
></A
>
<A
NAME="AEN4089"
></A
>
<A
NAME="AEN4092"
></A
>

<SPAN
CLASS="ACRONYM"
>SP</SPAN
> includes <I
CLASS="COMMAND"
>nsgmls</I
>, a fast command-line
parser. In the world of free validating <SPAN
CLASS="ACRONYM"
>XML</SPAN
> parsers,
<SPAN
CLASS="ACRONYM"
>IBM</SPAN
> AlphaWorks's <I
CLASS="COMMAND"
>xml4j</I
> and James
Clark's <I
CLASS="COMMAND"
>xp</I
> are popular choices.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="figures/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
><A
NAME="AEN4102"
></A
>

Not all <SPAN
CLASS="ACRONYM"
>XML</SPAN
> parsers are validating, and although a
non-validating parser may have many uses, it cannot ensure that your
documents are valid according to the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN4107"
>3.1. Validating Your Documents</A
></H1
><P
>The exact way in which the parser is executed varies according to
the parser in use, naturally.  For information about your particular
parser, consult the documentation that came with it.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4110"
>3.1.1. Using nsgmls</A
></H2
><P
><A
NAME="AEN4113"
></A
>

The <I
CLASS="COMMAND"
>nsgmls</I
> command from <SPAN
CLASS="ACRONYM"
>SP</SPAN
> is a
validating <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> parser.  The options used in the example below
suppress the normal output (<TT
CLASS="OPTION"
>-s</TT
>), except for error messages,
print the version number (<TT
CLASS="OPTION"
>-v</TT
>), and specify the catalog file
that should be used to map public identifiers to system
identifiers. Printing the version number guarantees that you always
get <I
CLASS="EMPHASIS"
>some</I
> output, so that you know the command ran
successfully:</P
><PRE
CLASS="SCREEN"
>[n:\dbtdg] nsgmls -sv -c \share\sgml\catalog test.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"</PRE
><P
><A
NAME="AEN4124"
></A
>
<A
NAME="AEN4127"
></A
>

Because no error messages were printed, we know our document is valid.
If you're working with a document that you discover has many errors,
the <TT
CLASS="OPTION"
>-f</TT
> option offers a handy way to direct the errors to a file
so they don't all scroll off your screen.</P
><P
><A
NAME="AEN4132"
></A
>
<A
NAME="AEN4135"
></A
>
<A
NAME="AEN4138"
></A
>
<A
NAME="AEN4140"
></A
>

If you want to validate an <SPAN
CLASS="ACRONYM"
>XML</SPAN
> document with <SPAN
CLASS="ACRONYM"
>SP</SPAN
>,
you must make sure that <SPAN
CLASS="ACRONYM"
>SP</SPAN
> uses the correct
declaration.  An <SPAN
CLASS="ACRONYM"
>XML</SPAN
> declaration called <TT
CLASS="FILENAME"
>xml.dcl</TT
> is
included with <SPAN
CLASS="ACRONYM"
>SP</SPAN
>.</P
><P
>The easiest way to make sure that <SPAN
CLASS="ACRONYM"
>SP</SPAN
> uses <TT
CLASS="FILENAME"
>xml.dcl</TT
> is to
include the declaration explicitly on the command line when you run
<I
CLASS="COMMAND"
>nsgmls</I
> (or Jade, or other <SPAN
CLASS="ACRONYM"
>SP</SPAN
> tools):</P
><PRE
CLASS="SCREEN"
>[n:\dbtdg] nsgmls -sv -c \share\sgml\catalog m:\jade\xml.dcl test.xml
m:\jade\nsgmls.exe:I: SP version "1.3.2"</PRE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4155"
>3.1.2. Using xml4j</A
></H2
><P
><A
NAME="AEN4158"
></A
>
<A
NAME="AEN4160"
></A
>

The <SPAN
CLASS="APPLICATION"
>xml4j</SPAN
> distribution includes a sample
program called <I
CLASS="COMMAND"
>XJParse</I
> that you can use to test
the validity of <SPAN
CLASS="ACRONYM"
>XML</SPAN
> documents:</P
><PRE
CLASS="SCREEN"
>[n:\dbtdg] java samples.XJParse.XJParse -d examples\simple.xml
<A
NAME="XJPARSE.INODOT"
><B
>(1)</B
></A
>ent/iso-lat2.ent: 49, 27: Warning: Entity name, "inodot", already defined. This declaration will be ignored.
<A
NAME="XJPARSE.TABLE"
><B
>(2)</B
></A
>calstblx.dtd: 20, 22: Warning: Entity name, "bodyatt", already defined. This declaration will be ignored.
calstblx.dtd: 22, 0: Warning: Entity name, "secur", already defined. This declaration will be ignored.
calstblx.dtd: 44, 48: Warning: Entity name, "tbl.table.name", already defined. This declaration will be ignored.
calstblx.dtd: 47, 78: Warning: Entity name, "tbl.table.mdl", already defined. This declaration will be ignored.
calstblx.dtd: 64, 80: Warning: Entity name, "tbl.entry.mdl", already defined. This declaration will be ignored.
<A
NAME="XJPARSE.OUTPUT"
><B
>(3)</B
></A
>&lt;!DOCTYPE chapter PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN" "n:/share/sgml/Norman_Walsh/db31xml/db3xml.dtd"&#62;
&lt;chapter&#62;&lt;title&#62;Test Chapter&lt;/title&#62;
&lt;para&#62;
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.
&lt;/para&#62;
...</PRE
><DIV
CLASS="CALLOUTLIST"
><DL
COMPACT="COMPACT"
><DT
><A
HREF="ch03.html#XJPARSE.INODOT"
><B
>(1)</B
></A
></DT
><DD
><A
NAME="AEN4172"
></A
>
<A
NAME="AEN4175"
></A
>
<A
NAME="AEN4179"
></A
>
<A
NAME="AEN4183"
></A
>
<A
NAME="AEN4185"
></A
>

You can ignore the warning message about the duplicate character
entity <TT
CLASS="LITERAL"
>inodot</TT
>.  Both the <SPAN
CLASS="ACRONYM"
>ISO</SPAN
>
<SPAN
CLASS="ACRONYM"
>AMS</SPAN
> Ordinary Math character entities and the
<SPAN
CLASS="ACRONYM"
>ISO</SPAN
> Latin 2 character entities define the
<TT
CLASS="LITERAL"
>inodot</TT
> entity.</DD
><DT
><A
HREF="ch03.html#XJPARSE.TABLE"
><B
>(2)</B
></A
></DT
><DD
><A
NAME="AEN4194"
></A
>
<A
NAME="AEN4196"
></A
>

Similarly, duplicate entities associated with the
<TT
CLASS="FILENAME"
>calstblx.mod</TT
> module can be ignored.  The
<TT
CLASS="LITERAL"
>CALS</TT
> Table Model is customized by redefining
parameter entities. It's part of the design of the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
> fragment.</DD
><DT
><A
HREF="ch03.html#XJPARSE.OUTPUT"
><B
>(3)</B
></A
></DT
><DD
><A
NAME="AEN4203"
></A
>

Finally, if there are no errors, <I
CLASS="COMMAND"
>XJParse</I
> prints the 
input document.  This is an indication that the document is valid.</DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4207"
>3.1.3. Using xp</A
></H2
><P
><A
NAME="AEN4210"
></A
>
<A
NAME="AEN4212"
></A
>

The <SPAN
CLASS="APPLICATION"
>xp</SPAN
> distribution includes several sample programs.
One of these programs, <I
CLASS="COMMAND"
>Time</I
>, performs a validating parse
of the document and prints the amount of time required to parse the
<SPAN
CLASS="ACRONYM"
>DTD</SPAN
> and the document.  This program makes an excellent validity
checker:</P
><PRE
CLASS="SCREEN"
>java com.jclark.xml.apps.Time examples\simple.xml
6.639</PRE
><P
>The result states that it took 6.639 seconds to parse the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
> and
the document.  This indicates that the document is valid.  If the
document is invalid, additional error messages are displayed.</P
></DIV
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN4220"
>3.2. Understanding Parse Errors</A
></H1
><P
><A
NAME="ERRORPARSECH4"
></A
>

<A
NAME="AEN4226"
></A
>
<A
NAME="AEN4229"
></A
>

Every parser produces slightly different error messages, but most
indicate exactly (at least technically)<A
NAME="AEN4232"
HREF="#FTN.AEN4232"
>[1]</A
> 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.</P
><P
>&#13;<A
NAME="AEN4235"
></A
>

In the rest of this section, we'll look at a number of common errors
and the messages they produce in <SPAN
CLASS="ACRONYM"
>SP</SPAN
>.  We've
chosen <SPAN
CLASS="ACRONYM"
>SP</SPAN
> for the rest of these examples because
that is the same parser used by Jade, which we'll be discussing
further in <A
HREF="ch04.html"
>Chapter 4</A
>.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4241"
>3.2.1. <SPAN
CLASS="ACRONYM"
>DTD</SPAN
> Cannot Be Found</A
></H2
><P
><A
NAME="AEN4245"
></A
>
<A
NAME="AEN4247"
></A
>
<A
NAME="AEN4250"
></A
>

The telltale sign that SP could not find the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>, or some module of
the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>, is the error message: "cannot generate system identifier
for public text &hellip;".  Generally, the errors that occur after
this are spurious; if SP couldn't find some part of the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>,
it's likely to think that <I
CLASS="EMPHASIS"
>everything</I
> is wrong.</P
><P
>Careful examination of the following document will show that we've
introduced a simple typographic error into the public identifier (the
word <SPAN
CLASS="QUOTE"
>"DocBook"</SPAN
> is misspelled with a lowercase <SPAN
CLASS="QUOTE"
>"b"</SPAN
>):</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//OASIS//DTD Docbook V3.1//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/title&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;para&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;/para&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><P
>SP responds dramatically to this error:</P
><PRE
CLASS="SCREEN"
>[n:\dbtdg]nsgmls -sv -c examples\errs\cat1 examples\errs\nodtd.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:1:57:W: cannot generate system identifier for public text "-//OASIS//DTD Docbook V3.1//EN"
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:1:57:E: reference to entity "CHAPTER" for which no system identifier could be generated
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:1:0: entity was defined here
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:1:57:E: DTD did not contain element declaration for document type name
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:2:8:E: element "CHAPTER" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:2:15:E: element "TITLE" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:3:5:E: element "PARA" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:9:5:E: element "PARA" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:10:15:E: there is no attribute "ROLE"
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:10:19:E: element "EMPHASIS" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:11:9:E: element "EMPHASIS" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:11:24:E: element "EMPHASIS" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:12:18:E: element "SUPERSCRIPT" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:13:16:E: element "SUBSCRIPT" undefined
m:\jade\nsgmls.exe:examples\errs\nodtd.sgm:15:5:E: element "PARA" undefined</PRE
><P
><A
NAME="AEN4265"
></A
>

Other things to look for, if you haven't misspelled the public
identifier, are typos in the catalog or failure to specify a catalog
that resolves the public identifier that can't be found.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4268"
>3.2.2. <SPAN
CLASS="ACRONYM"
>ISO</SPAN
> Entity Set Missing</A
></H2
><P
>&#13;<A
NAME="AEN4272"
></A
>

A missing entity set is another example of either a misspelled public
identifier, or a missing catalog or catalog entry.</P
><P
>In this case, there's nothing wrong with the document, but the catalog
that's been specified is missing the public identifiers for the
<SPAN
CLASS="ACRONYM"
>ISO</SPAN
> entity sets:</P
><PRE
CLASS="SCREEN"
>[n:\dbtdg]nsgmls -sv -c examples\errs\cat2 examples\simple.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:53:65:W: cannot generate system identifier for public text "ISO 8879:1986//ENTITIES Added Math Symbols:Arrow Relations//EN"
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:54:8:E: reference to entity "ISOamsa" for which no system identifier could be generated
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:52:0: entity was defined here
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:60:66:W: cannot generate system identifier for public text "ISO 8879:1986//ENTITIES Added Math Symbols:Binary Operators//EN"
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:61:8:E: reference to entity "ISOamsb" for which no system identifier could be generated
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:59:0: entity was defined here
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:67:60:W: cannot generate system identifier for public text "ISO 8879:1986//ENTITIES Added Math Symbols:Delimiters//EN"
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:68:8:E: reference to entity "ISOamsc" for which no system identifier could be generated
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:66:0: entity was defined here
m:\jade\nsgmls.exe:n:/share/sgml/docbook/3.1/dbcent.mod:74:67:W: cannot generate system identifier for public text "ISO 8879:1986//ENTITIES Added Math Symbols:Negated Relations//EN"
...</PRE
><P
><A
NAME="AEN4279"
></A
>

The <SPAN
CLASS="ACRONYM"
>ISO</SPAN
> entity sets are required by the DocBook
<SPAN
CLASS="ACRONYM"
>DTD</SPAN
>, but they are not distributed with it.  That's because they
aren't maintained by <SPAN
CLASS="ACRONYM"
>OASIS</SPAN
>.<A
NAME="AEN4285"
HREF="#FTN.AEN4285"
>[2]</A
></P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4288"
>3.2.3. Character Data Not Allowed Here</A
></H2
><P
><A
NAME="AEN4291"
></A
>
<A
NAME="AEN4294"
></A
>
<A
NAME="AEN4297"
></A
>

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!</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/title&#62;
&#60;para&#62;
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.
&#60;/para&#62;
You can't put character data here.
&#60;para&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;/para&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><PRE
CLASS="SCREEN"
>[n:\dbtdg] nsgmls -sv -c \share\sgml\catalog examples\errs\badpcdata.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\badpcdata.sgm:9:0:E: character data is not allowed here</PRE
><P
><A
NAME="AEN4304"
></A
>

<A
HREF="chapter.html"
><TT
CLASS="SGMLTAG"
>Chapter</TT
></A
>s aren't allowed to contain character data
directly. Here, a wrapper element, such as <A
HREF="para.html"
><TT
CLASS="SGMLTAG"
>Para</TT
></A
>, is
missing around the sentence between the first two paragraphs.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4309"
>3.2.4. Misspelled Start Tag</A
></H2
><P
><A
NAME="AEN4312"
></A
>

If you spell it wrong, the parser gets confused.</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/title&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;paar&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;/para&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><PRE
CLASS="SCREEN"
>[n:\documents\books\dbtdg]nsgmls -sv -c \share\sgml\catalog examples\errs\misspe
ll.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\misspell.sgm:9:5:E: element "PAAR" undefined
m:\jade\nsgmls.exe:examples\errs\misspell.sgm:14:6:E: end tag for element "PARA" which is not open
m:\jade\nsgmls.exe:examples\errs\misspell.sgm:21:9:E: end tag for "PAAR" omitted, but OMITTAG NO was specified
m:\jade\nsgmls.exe:examples\errs\misspell.sgm:9:0: start tag was here</PRE
><P
>Luckily, these are pretty easy to spot, unless you accidentally spell
the name of another element.  In that case, your error might appear to
be out of context.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4320"
>3.2.5. Misspelled End Tag</A
></H2
><P
><A
NAME="AEN4323"
></A
>

Spelling the end tag wrong is just as confusing.</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/titel&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;para&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;/para&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><PRE
CLASS="SCREEN"
>[n:\dbtdg]nsgmls -sv -c \share\sgml\catalog examples\errs\misspell2.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\misspell2.sgm:2:35:E: end tag for element "TITEL" which is not open
m:\jade\nsgmls.exe:examples\errs\misspell2.sgm:3:5:E: document type does not allow element "PARA" here; missing one of "FOOTNOTE", "MSGTEXT" start-tag
m:\jade\nsgmls.exe:examples\errs\misspell2.sgm:9:5:E: document type does not allow element "PARA" here; missing one of "FOOTNOTE", "MSGTEXT" start-tag
m:\jade\nsgmls.exe:examples\errs\misspell2.sgm:15:5:E: document type does not allow element "PARA" here; missing one of "FOOTNOTE", "MSGTEXT" start-tag
m:\jade\nsgmls.exe:examples\errs\misspell2.sgm:21:9:E: end tag for "TITLE" omitted, but OMITTAG NO was specified
m:\jade\nsgmls.exe:examples\errs\misspell2.sgm:2:9: start tag was here
m:\jade\nsgmls.exe:examples\errs\misspell2.sgm:21:9:E: end tag for "CHAPTER" which is not finished</PRE
><P
>These are pretty easy to spot as well, but look at how confused the
parser became.  From the parser's point of view, failure to close the
open <A
HREF="title.html"
><TT
CLASS="SGMLTAG"
>Title</TT
></A
> element means that all the following elements
appear out of context.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4331"
>3.2.6. Out of Context Start Tag</A
></H2
><P
><A
NAME="AEN4334"
></A
>
<A
NAME="AEN4338"
></A
>

Sometimes the problem isn't spelling, but placing a tag in the wrong
context.  When this happens, the parser tries to figure out what it
can add to your document to make it valid.  Then it proceeds as if it
had seen what was added in order to recover from the error seen, which
can cause future errors.</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/title&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;para&#62;&#60;title&#62;Paragraph With Inlines&#60;/title&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;/para&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><PRE
CLASS="SCREEN"
>[n:\dbtdg]nsgmls -sv -c \share\sgml\catalog examples\errs\badstarttag.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\badstarttag.sgm:9:12:E: document type does not allow element "TITLE" here; missing one of "CALLOUTLIST", "SEGMENTEDLIST", "VARIABLELIST", "CAUTION", "IMPORTANT", "NOTE", "TIP", "WARNING", "BLOCKQUOTE", "EQUATION", "EXAMPLE", "FIGURE", "TABLE" start-tag</PRE
><P
><A
NAME="AEN4345"
></A
>
<A
NAME="AEN4349"
></A
>

In this example, we probably wanted a <A
HREF="formalpara.html"
><TT
CLASS="SGMLTAG"
>FormalPara</TT
></A
>, so that
we could have a title on the paragraph.  But note that the parser
didn't suggest this alternative.  The parser only tries to add
additional elements, rather than rename elements that it's already
seen.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4353"
>3.2.7. Missing End Tag</A
></H2
><P
><A
NAME="AEN4356"
></A
>

Leaving out an end tag is a lot like an out of context start tag.  In
fact, they're really the same error.  The problem is never caused by
the missing end tag per se, rather it's caused by the fact that
something following it is now out of context.</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/title&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;para&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><PRE
CLASS="SCREEN"
>[n:\dbtdg]nsgmls -sv -c \share\sgml\catalog examples\errs\noendtag.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\noendtag.sgm:14:5:E: document type does not allow element "PARA" here; missing one of "FOOTNOTE", "MSGTEXT", "CAUTION", "IMPORTANT", "NOTE", "TIP", "WARNING", "BLOCKQUOTE", "INFORMALEXAMPLE" start-tag
m:\jade\nsgmls.exe:examples\errs\noendtag.sgm:20:9:E: end tag for "PARA" omitted, but OMITTAG NO was specified
m:\jade\nsgmls.exe:examples\errs\noendtag.sgm:9:0: start tag was here</PRE
><P
>In this case, the parser figured out that the best thing it could do
is end the paragraph.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4363"
>3.2.8. Bad Entity Reference</A
></H2
><P
><A
NAME="AEN4366"
></A
>

If you spell an entity name wrong, the parser will catch it.</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/title&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;para&#62;
There's no entity called &#38;xyzzy; defined in this document.
&#60;/para&#62;
&#60;para&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;/para&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><PRE
CLASS="SCREEN"
>[n:\dbtdg]nsgmls -sv -c \share\sgml\catalog examples\errs\badent.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\badent.sgm:10:26:E: general entity "xyzzy" not defined and no default entity</PRE
><P
>More often than not, you'll see this when you misspell a character
entity name.  For example, this happens when you type
<TT
CLASS="LITERAL"
>&amp;ldqou;</TT
> instead of
<TT
CLASS="LITERAL"
>&amp;ldquo;</TT
>.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN4375"
>3.2.9. Invalid 8-Bit Character</A
></H2
><P
><A
NAME="AEN4378"
></A
>
<A
NAME="AEN4382"
></A
>
<A
NAME="AEN4384"
></A
>

In <SPAN
CLASS="ACRONYM"
>XML</SPAN
>, the entire range of Unicode characters is available to you,
but in <SPAN
CLASS="ACRONYM"
>SGML</SPAN
>, the declaration indicates what characters are valid.
The distributed DocBook declaration doesn't allow a bunch of fairly
common 8-bit characters.</P
><PRE
CLASS="PROGRAMLISTING"
>&#60;!DOCTYPE chapter PUBLIC "-//Davenport//DTD DocBook V3.0//EN"&#62;
&#60;chapter&#62;&#60;title&#62;Test Chapter&#60;/title&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;para&#62;
The DocBook declaration in use doesn't allow 8 bit characters
like this.
&#60;/para&#62;
&#60;para&#62;
&#60;emphasis role=bold&#62;This&#60;/emphasis&#62; paragraph contains
&#60;emphasis&#62;some &#60;emphasis&#62;emphasized&#60;/emphasis&#62; text&#60;/emphasis&#62;
and a &#60;superscript&#62;super&#60;/superscript&#62;script
and a &#60;subscript&#62;sub&#60;/subscript&#62;script.
&#60;/para&#62;
&#60;para&#62;
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.
&#60;/para&#62;
&#60;/chapter&#62;
</PRE
><PRE
CLASS="SCREEN"
>[n:\dbtdg]nsgmls -sv -c \share\sgml\catalog examples\errs\badchar.sgm
m:\jade\nsgmls.exe:I: SP version "1.3.2"
m:\jade\nsgmls.exe:examples\errs\badchar.sgm:11:0:E: non SGML character number 147
m:\jade\nsgmls.exe:examples\errs\badchar.sgm:11:5:E: non SGML character number 148</PRE
><P
><A
NAME="AEN4393"
></A
>
<A
NAME="AEN4396"
></A
>

In this example, the Windows code page values for
curly left and right quotes have been used, but they aren't in the
declared character set.  Fix this by converting them to character
entities.</P
><P
><A
NAME="AEN4401"
></A
>

You can also fix them by changing the declaration, but if you do that,
make sure all your interchange partners are aware of, and have a copy of,
the modified declaration. See <A
HREF="appf.html"
>Appendix F</A
>.
<A
NAME="AEN4404"
></A
>&#62;
<A
NAME="AEN4405"
></A
>&#62;
<A
NAME="AEN4406"
></A
>&#62;</P
></DIV
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN4232"
HREF="ch03.html#AEN4232"
>[1]</A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>It is often the case that you can correct an error in the document in
several ways.  The parser suggests one possible fix, but this is not
always the right fix.  For example, the parser 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.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN4285"
HREF="ch03.html#AEN4285"
>[2]</A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>If you need to locate the entity sets, consult <A
HREF="http://www.oasis-open.org/cover/topics.html#entities"
TARGET="_top"
>http://www.oasis-open.org/cover/topics.html#entities</A
>.</P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="ch02.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docbook.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="ch04.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Creating DocBook Documents</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part1.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Publishing DocBook Documents</TD
></TR
></TABLE
></DIV
><P
><A
HREF="ln41.html"
>Copyright</A
> &copy; 1999 O'Reilly &amp; Associates, Inc. All rights reserved.</P
></BODY
></HTML
>