New ENTITY declarations?

[Karsten Wade]

On Sun, 2003-11-30 at 02:04, Dave Pawson wrote:
> At 08:06 29/11/2003, Karsten Wade wrote:
> 
> 
> >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;
> 
> Which is fine if the structure on an authors machine reflects
> that on the fedora build.
> 1. Is that the intention.
> 2. Is that structure documented?
> 
> (That's why I suggested the use of a uri on the redhat site,
> and a local catalog entry to map that to the local instance for
> local use)

[clipped and moved...]

>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.
> 
> 
> Are all authors expected to work with that relative path?

I am suggesting one idea for this, and yes under this idea, all authors
would work with that relative path.  To work on a document, you would
need to check out the common directories module (of at least one top
level directory), and put it in a specific relative path.

This idea is not yet a procedure; we are discussing that.  I actually
like the idea of using a URI, will it work within the entity?  That
seems to fit into the spirit of things. :)  It's structurally different
from a CVS module on a relative path, but it's essentially the same
thing - a remote canonical source you generally only have read access to
and you keep a copy of locally.

Two proposals summarized:

1. CVS Common Directories Module Method

A. CVS module contains common directories of XML entities, could also
include graphics, common content such as legalnotices/other boilerplate,
trademark pages (listing all the trademarks used in all the
documentation), etc.

B. Authors need to place that CVS module (or a symlink to it) on a
relative path of ../ to any module/document they are working on.

C. Guide specific entities can be declared in the parent XML file.

2. Common Entities in DTD (please correct my inaccuracies)

A. Common entities are added to Fedora specific DTD and served from
fedora.redhat.com.

B. Authors calling the DTD gain access to the entities, which are listed
XXXXX (manually on the FDP pages?  extracted via xml-fu from the DTD?)

C. Local copies of the DTD are kept, as is common.

Thoughts?

> 
> >I'm not 100% certain that my syntax is accurate for the XML DTD; it
> >works for SGML.
> 
> Which is fedora working in?
>   I've assumed XML. Is there much SGML legacy?

As Ed said, internal only legacy; I only meant that I grabbed samples
from SGML usage and didn't check them for XML accuracy; they should be
compliant, but YMMV.

- 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         
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --