This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

external entities cannot be valid?


It appears that external parsed entities cannot be
valid XML.  Someone please prove me wrong.

I'm setting up a modular authoring environment
for Docbook XML files.  By modular, I mean writers
work on individual chapter XML files, and these
are rolled up into book XML files.  The external
parsed entity mechanism in SGML/XML was designed for this.
The book element contains the book front and back matter,
and a list of references to external parsed entities for
the chapters.

However, I seem to have run into a great big caveat,
and I'm hoping someone can point me to the error in
my ways.

According to the XML 1.0 specification, an external 
parsed entity cannot include a <!DOCTYPE> declaration.  It
may start with the <?xml ... ?> declaration to indicate it
is XML and its encoding, but the file must match the
production in the spec labeled "extParsedEnt" which does
*not* include the doctype declaration.  Tim Bray's annotation
in the annotated spec confirms this.  I'm sure this was
done to prevent collisions from inserting different DTDs.
But if the DTDs are the same, I would accept having the
doctype declaration in the external entity ignored.  But
that isn't what the spec says, so it isn't how XML tools
work.  For example, Jim Clark's XT fails when I try 
a reference that includes a doctype declaration.

So now I have to choose:

Option A: Leave out the doctype declaration from the
chapter files so the external parsed entity references will
legal and the book file that contains the doctype
declaration will be valid.  However, this means the
chapter files are not valid and cannot be individually
validated by a validating processor or editor.

Option B: Include the doctype declaration in each chapter
file, and then run a program to strip out the declaration
to assemble my valid book instance.  In other words, I
cannot use the  external parsed entity mechanism which
was designed for this purpose.

Option C: Leave out the doctype declaration in each chapter
file, and create wrapper chapter files that contain only
the doctype declaration and an external parsed entity
reference to the chapter content, sort of like a
single-chapter version of the book wrapper.  The writers
would work and validate these wrapper files, and the
book file would share the same external parsed entity.
Unfortunately, each XML editor handles this differently.
Most XML editors don't transparently include the content
for editing, and force the user to open the external entity
in another window, where it may or may not be treated as
valid because it doesn't contain the doctype declaration.

I very much want my writers keeping their chapter documents
valid at all times, by using a validating XML editor.
I want each file validated when it is checked into
revision control to prevent problems with our documentation
builds.

There must be some way to accomplish this, isn't there?

bobs
Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The Santa Cruz Operation, Inc.              fax:   (831) 429-1887
                                            email: bobs@sco.com


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]