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@xxxxxxxxxx>: > > > 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/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
