install-guide/en

[Paul W. Frields]

On Wed, 2006-03-01 at 02:06 +0000, Stuart Ellis wrote:
> On Wed, 2006-03-01 at 09:52 +0800, Yuan Yijun wrote:
> > 2006/3/1, elliss Stuart Ellis <fedora-docs-commits at redhat.com>:
> > > Author: elliss
> > >
> > > Update of /cvs/docs/install-guide/en
> > >
> > > - Updated files with entity declarations to work with XIncludes.
> > 
> > Thank you! I will notify my dear IG-zh_CN contributer Xiaofan.Yang who
> > is working on this ASAP :)
> 
> OK. Just to be clear - it won't successfully build yet, although this
> reduces the number of errors a bit :). I discussed this with Paul on IRC
> this evening, and there is a bit more to be done to get all of the
> entities that we use working with XIncludes.

Something interesting that other people might benefit from as well if
they're working on larger docs... Now that we're doing XInclude, recall
that each individual XML file is validated before it's included in the
larger "infoset."  That means that each file must, on its own, be valid
DocBook XML.

There are a couple things you can do to help your document validate, and
which also help you out:

1.  Make sure the root-level element in the <!DOCTYPE> declaration
matches that in your file.  For the parent file, this might be "book" or
"article," but for the other XML files, it will almost certainly be
different, probably "preface," "section," or "glossary."  If you do this
correctly, you will find that Emacs, Vim and other good document editors
will have a much easier time dealing with automatic tagging and so
forth.  (In other words, you're not cheating or fooling the system any
longer, you're working the system correctly.)

2.  If you use an entity in an XML file, that entity must be present in
that document's DTD, either because you've included it manually with a
declaration, or because it exists in the global entities file in
docs-common/common/entities.  If you XInclude another level, or even if
you include some XML snippet through a parsed entity like
&BUG-REPORTING;, the requirement doesn't change.  That snippet can't
include any entities the XIncluded file doesn't understand.

This presents a bit of a problem because, for example, the
&BUG-REPORTING; file "bugreporting-en.xml" has a reference to the parsed
entity &DOCID; in it.  That's well and good, but the
"fedora-install-guide-intro.xml" file has no knowledge of the &DOCID;
entity, which is *only* declared in the top-level
"fedora-install-guide.xml" file.  So the only alternative right now is
to put copies in both files, which sucks from a maintenance point of
view.

That's why I just made a suggestion that we incorporate a slight
improvement to the current entity generation scheme, where a local
entities file is automatically merged with the common entities file from
docs-common, to generate a complete set of entities for each document at
build time.  Since the local entities can simply follow the DTD Tommy
hsa so helpfully provided, merging should be a snap, the XML for the
entities fits right into the translation schema we already use, and Life
Will Be Good.

Stay tuned for more.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20060228/da08c04c/attachment.bin