fedora-entities - a proposal in the flesh

[Karsten Wade]

This one has been on my to-do list for a while ...

http://people.redhat.com/kwade/fedora-docs/common/fedora-entities-en.xml

This works fine in my local tree, but since it includes entities
required by the build scripts, it needs more QA.

See below the Background section for implementation steps.

# Background

If you aren't familiar with the concept here, DocBook entities allow us
to objectify common words and phrases that we want to use regularly, and
be able to easily update from a single location.  Entries look like
this:

<!-- *************** Fedora version numbers *************** -->
<!ENTITY FCVER "2">  <!-- Current release version of main project -->
<!ENTITY TESTVER "test1"> <!-- Current test number of main project -->
<!ENTITY FCTESTVER "3 &TESTVER;">  <!-- Current test version of main
project  -->

In the XML it appears like this:

  The information in this FAQ is specific to &FC; &FCTESTVER;. If you
  are looking for the FAQ for &FC; &FCVER; ...

Which DocBook converts into:

  The information in this FAQ is specific to Fedora Core 3test1. If you
  are looking for the FAQ for Fedora Core 2 ...

# Implementing

To take advantage of this common entities file, we need to do the
following:

1. If the common entities file is ready for submission, get it into CVS
in fedora-docs/common.  I'll be responsible for making this happen, ye
gods willing.

2. Update your XML to use the common file by first removing the local
versions of similar entities (leave in your true local entities), and
adding this line:

<!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../common/fedora-entities-en.xml">
%FEDORA-ENTITIES-EN;

Note the relative path.  Just like the build scripts, you are relying
upon the various build directories in fedora-docs/ being in specific
locations.

The BOOKID entity is still set in each guide locally:

<!ENTITY BOOKID "selinux-faq-1.3 (2004-07-30-T04:20-0800)"> <!-- version
of manual and date -->

I use a LOCALVER entity for the times when my guide is out of sync with
the current FCVER or FCTESTVER in the common entities file.  The
LOCALVER would be used like this:

<!ENTITY LOCALVER "3">  <!-- Set value to your choice, when guide
version is out of sync with FC release, use instead of FEDVER or
FEDTESTVER  -->

  The information in this FAQ is relevant to &FC; &LOCALVER; only and
  not to the current or test release.

3. File bugzilla tickets for all the other guides in CVS that need to be
updated to use the new common entities file.

## 30

- Karsten
-- 
Karsten Wade, RHCE, Tech Writer
this .signature subject to random changes
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115  5F1B D992 0E06 AD0E 0C41