New ENTITY declarations?

Karsten Wade kwade at redhat.com
Sat Nov 29 08:06:47 UTC 2003


On Thu, 2003-11-27 at 11:00, Dave Pawson wrote:
> At 01:21 27/11/2003, you wrote:
> >Do we need a block of additional ENTITY declarations as a standard in
> >the templates,
> 
> Yes please. Save's typing!

Agreed, entities are a must.  They promote consistency and give you a
single location to change a name/term/application/etc. without manual
search and replace.

Quick summary of the ideas below before I get into the details,
especially as this is a request for the project lead (Tammy Fox) to
notice:

* Have a common entities file for all documentation, fedora-entities.xml
* Have a common XML directory for all doxen, fedora-common-xml/
* fedora-entities.xml has useful and specific entities created for all
to use
* Individual dox have unique and local entities declared in the parent
XML file

> They need adding to the DTD/schema IMHO.

We use a common set available to all document writers, following the
format of fedora-entities.sgml.  The contents of that file would be
pulled into the parent XML like:

<!-- ****** Bring in Fedora Project standard entities ***** -->
<!ENTITY % FEDORA-ENTITIES SYSTEM
"../fedora-common-xml/fedora-entities.xml">
%FEDORA-ENTITIES;

I'm not 100% certain that my syntax is accurate for the XML DTD; it
works for SGML.  Let us know if there any differences.  Following is an
example scheme based on what we are using at Red Hat.

The target file in the common directory is called via a relative path,
i.e. it's always in an expected location of off the Fedora docs cvsroot,
../fedora-common-xml/fedora-entities.xml.

This means fedora-common-xml/ is a module in CVS that you need to
check-out in order to build your docs (if you call anything from there,
of course), and which makes it easy to distribute changes globally, i.e.
if Fedora Core becomes F3d0ra C0r3, then we only need to 'cd
fedora-common-xml/ && cvs up'. ;)

fedora-entities.xml would have a number of lines, grouped logically with
comment block headers:

<!ENTITY FEDORA "The Fedora Project">
<!ENTITY FEDORA-URL "<ulink
url='http://fedora.redhat.com/'>http://fedora.redhat.com/</ulink>">
...

Also useful are 

The parent XML file can then have localized content such as a series of
repetitious items related to that particular document.  I'd much rather
write &X; than "X window system" over and over and over.

Another good thing to have in the parent XML file is anything related to
version and release, e.g.:

<!ENTITY BOOKDATE "2003-11-26T16:20" -- Date of document -->
<!ENTITY FEDVER "1.0">
<!ENTITY APACHEVER "2.0.47-10">
...

If you want separate files for either chapters or sections, you can then
have:

<!ENTITY INTRO SYSTEM "intro.xml">
<!ENTITY OVERVIEW SYSTEM "overview.xml">
...

This is helpful when people are working on different <section>s of an
overall document; the parent document just looks like:

<article>
  <articleinfo>
    <title>Article Title</title>
    ...
  </articleinfo>

  &INTRO;
  &OVERVIEW;
  ...
</article>

Everyone works on his/her own own file e.g. overview.xml, without
stepping on the toes of other authors; it's easy to <!-- comment out -->
a particular &SECTION; which is having build problems, etc.

> Surely there are a group from redhat that can be adopted and added to?

I honestly don't think they'd be helpful; they're very specific to Red
Hat products, services and versions.  Here are some ideas I got from
looking through which may be applicable (the suffix convention used here
is of X meaning a short version of a name, XS meaning shortest
possible):

<!ENTITY FED "Fedora">
<!ENTITY FC "&FED; Core">
<!ENTITY FCX "FC" -- Fedora Core abbrev -->
<!ENTITY FP "&FED; Project">
<!ENTITY FPX "FP" -- Fedora Project abbrev -->
<!ENTITY FDP "&FED; Documentation Project">
<!ENTITY FDPX "&FED; Docs">
<!ENTITY FDPXS  "FDP" -- Fedora Doc Project abbrev -->
<!ENTITY SECTTR "Security Tutorial">
<!ENTITY INSTTTR "Installation Tutorial">
<!ENTITY ANACONTTR "Anaconda Tutorial">

Because of the number of smaller tutorials possible, a common set would
have longer abbreviations like SECTTR instead of e.g. ST if you only had
a handful of tutorials, or even SG if you have a single Security Guide.

It's nice to break down to the smallest possible elements as well as
often used elements, which build on each other:

<!ENTITY SECTTRX "SecHOWTO">
<!ENTITY FDPXSECTTRX "&FDPX; SECTTRX">

This let's you build:

...
<title>&FDP; &SECTTR;</title>
<subtitle>/aka/ &FDPXSECTTRX; for &FC; &FEDVER;</title>
...

This creates a document with the title

...
Fedora Documentation Project Security Tutorial
/aka/ FDP SecHOWTO for Fedora Core 1.0
...

Whoops, we want "SecHOWTO" to become "SecHowTo"?  Just go back to the
fedora-entities.xml and change it ... you get the idea. :)

hth - Karsten
-- 
Karsten Wade   :      Tech Writer, RHCE     :  o: +1.831.466.9664
kwade at redhat.com : http://rhea.redhat.com/ :   c: +1.831.818.9995
         Red Hat Applications : WAF, CMS, Portal Server         
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --





More information about the fedora-docs-list mailing list