Unnecessary doc entities abound?

[Paul W. Frields]

A while back, we created the ability for document modules to carry their
own specific XML entities.  An editor who needs to use entities that are
specific to a document makes a per-document entities XML file, and
defines it in the module's Makefile with the ${DOC_ENTITIES} variable.
For instance, a tutorial about the program
"Supercalifragilisticexpialidocious" could have a defined general entity
MYNAME that allowed the author the ability to shorthand the program
name:

  <para>This paragraph has something very
    vital to say about &MYNAME;.</para>

This cuts down on typographical errors, and also ensures that if
"Supercalifragilisticexpialidocious" changes its name to "Foobarific"
later, the author or editor need only change the name in one place to
have it propagate through the document.

We used to ask for all documents to carry this file and to always define
the following entities:

  &DOCNAME; (the document module name)
  &DOCVER; (the document version, repeated from rpm-info.xml)
  &DOCDATE; (the document date, repeated from rpm-info.xml)
  &DOCID; (the document ID, which is really:
           "&DOCNAME;-&DOCVER; (&DOCDATE;)" -- or for example:
           "foobarific-guide-0.5 (2007-05-20)")

Other than the &DOCNAME; entity, these elements appear in rpm-info.xml,
which is a required file.  Even the &DOCNAME; is of questionable value,
since we already have the document title (e.g. "Foobarific Guide") in
rpm-info.xml.  The reason we created these elements originally was -- we
(I?) thought -- that we could use them to populate commonly included
snippets from the "docs-common" module.

This is incorrect.  The XML standard does not allow for this willy-nilly
inclusion from different directory namespaces.  We could build a lot of
crazy infrastructure to allow us to copy or link these included
snippets, but in the long run, it's simply ugly hackery and makes our
toolchain more fragile and less maintainable.

So my proposal (sorry, long time to get to the punch line):  We drop the
requirement for these document entities.  Document metadata then only
needs to be updated once by an author or editor making a change -- in
the rpm-info.xml file only.

This is a minor change and should not affect any current functionality
in the toolchain.  No documents should be attempting to use the snippets
as they currently exist.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20070706/b27f944f/attachment.sig>