7:21 p.m.
Do we need a block of additional ENTITY declarations as a standard in
the templates, or are they up to the tutorial authors to use? I have
been removing the existing block of Red Hat-specific declarations, and
replacing them with more Fedora-specific ones, such as:
<!ENTITY FEDORA "The Fedora Project">
<!ENTITY FEDORA-URL "<ulink
url='http://fedora.redhat.com/'>http://fedora.redhat.com/</...
<!ENTITY DISTRO "Fedora Core">
<!ENTITY DOCS "The Fedora Documentation Project">
<!ENTITY DOCS-URL "<ulink
url='http://fedora.redhat.com/projects/docs/'>http://fedora.re...
I don't see a need to standardize just for the sake of it; if this is
something that authors are expected to do for themselves, that's ducky
by me. I just don't want to step on any toes since I'm new to this part.
:-)
--
Paul W. Frields, RHCE
6:55 a.m.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Wednesday 26 November 2003 23:21, Paul W. Frields wrote:
I don't see a need to standardize just for the sake of it; if
this is
something that authors are expected to do for themselves, that's ducky
by me. I just don't want to step on any toes since I'm new to this part.
I think is a nice idea. Not just for the sake of it, but because I think it
will be useful.
Writers will end up doing similar things, using similar entities, so I think
establishing a standard to all docs would be a Good Thing, since it would
spare the writers the time to do it again and again to every doc.
My 2 cents, though.
- --
Luiz Rocha <lsdr(a)lsdr.net>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)
iD8DBQE/xfRkN2+4JlrxCYYRAkgaAKCWYB1oBA4JtT7MO0NWfhxtYbg3jACfZ4sa
fLyU9M70dUAZyixtkqN5yQ4=
=U5SC
-----END PGP SIGNATURE-----
2:06 a.m.
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/</...
...
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(a)redhat.com : http://rhea.redhat.com/ : c: +1.831.818.9995
Red Hat Applications : WAF, CMS, Portal Server
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
4:04 a.m.
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)
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?
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.
Are all authors expected to work with that relative path?
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'. ;)
No problems with that... so long as all understand it..
and its documented :-)
<snip/>
hth - Karsten
Very much so Karsten.
Very clear.
.... Is this to be marked up and added to the documentation howto :-)
regards DaveP
10:24 a.m.
>>>> "Dave" == Dave Pawson
<dpawson(a)nildram.co.uk> writes:
Dave> Which is fedora working in? I've assumed XML. Is there much SGML
Dave> legacy?
The Fedora Project documentation is meant to be in XML. There is a
*massive* amount of SGML legacy on the internal side (in fact the only
documentation not produced in DocBook/SGML format are the RHEL release
notes). Long-term, we'll likely move to DocBook/XML internally, but this
is probably not too interesting to y'all... :-)
Ed
--
Ed Bailey Red Hat, Inc. http://www.redhat.com/
2:10 p.m.
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(a)redhat.com : http://rhea.redhat.com/ : c: +1.831.818.9995
Red Hat Applications : WAF, CMS, Portal Server
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
12:42 p.m.
At 20:10 01/12/2003, Karsten Wade wrote:
>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.
The downside of which is that it may not suite all our
disk setup's.
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?
Yes, since its the parser that expands the entity.
... Any reason to use an entity though?
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.
Rationale (for some),
We may not always be connected to the net.
Hence, for example,
<!--This group handles all docbook items. -->
<!-- Use formal public identifiers in preference to SYSTEM identifiers -->
<group
prefer="public"
xml:base="/sgml/nw/" >
<!-- docbook 4.2 -->
<public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
uri="docbook/docbookx.dtd"/>
<uri name="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
uri="docbook/docbookx.dtd"/>
Is a snippet of my docbook stuff.
The Edited text refers to the web,
the catalog maps it to /sgml/nw/docbook/docbookx.dtd
(Similar, using Oasis catalog, for emacs use)
2. Common Entities in DTD (please correct my inaccuracies)
Depends on the design modularity you want/need.
Some things (names etc) will be very stable.
Versions may change fairly quickly.
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?)
Don't care? If they nest nicely they'll all be accessible,
either from the redhat site, or locally when mapped.
Two (local) usages,
Within the editor for use (not always needed, but useful)
Externally, when validating, say with nsgmls,
there the catalog is needed, so perhaps some documentation
on using Daniel Vaillard's software as a parser?
I know he supports catalogs.
C. Local copies of the DTD are kept, as is common.
Thoughts?
I like it. Its flexible. redhat.com has the masters,
they are available over the net if needed,
I can copy them to my hard drive if needed.
I think that meets most needs.
regards DaveP
10:21 a.m.
>>>> "Paul" == Paul W Frields
<paul(a)frields.com> writes:
...
Paul> <!ENTITY FEDORA "The Fedora Project">
Paul> <!ENTITY FEDORA-URL "<ulink
url='http://fedora.redhat.com/'>http://fedora.redhat.com/</...
Paul> <!ENTITY DISTRO "Fedora Core">
Paul> <!ENTITY DOCS "The Fedora Documentation Project">
Paul> <!ENTITY DOCS-URL "<ulink
url='http://fedora.redhat.com/projects/docs/'>http://fedora.re...
I'll let Karsten's fine response speak for me on the whole, however, I
would like to note that you seem to be mixing metaphors a bit here. For
example, you call the overall project FEDORA, but the Fedora Core
distribution is DISTRO. It might be a bit nicer to have something like:
<!ENTITY NAME "Fedora">
<!ENTITY PROJ "The &NAME; Project">
<!ENTITY PROJ-URL "<ulink
url='http://fedora.redhat.com/'>http://fedora.redhat.com/</...
<!ENTITY DISTRO "&NAME; Core">
<!ENTITY DOCS-PROJ "The &NAME; Documentation Project">
<!ENTITY DOCS-PROJ-URL "<ulink
url='http://fedora.redhat.com/projects/docs/'>http://fedora.re...
Just a thought,
Ed
--
Ed Bailey Red Hat, Inc. http://www.redhat.com/
7448
days inactive
7453
days old
8 comments
5 participants
participants (5)
-
Dave Pawson -
Edward C. Bailey -
Karsten Wade -
Luiz Rocha -
Paul W. Frields