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@xxxxxxxxxx : http://rhea.redhat.com/ : c: +1.831.818.9995 Red Hat Applications : WAF, CMS, Portal Server -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
