Subject: Re: Separating architecture-specific instructions from Handbook
Newsgroups: gmane.linux.gentoo.documentation
Date: 2004-03-01 19:37:18 GMT (4 years, 18 weeks, 5 hours and 21 minutes ago)
On Thu, Feb 26, 2004 at 02:36:30PM +0100, Sven Vermeulen wrote: > Okay; I've added this to the GDP TODO list (euh, roadmap). I'll try compile a > list of requirements that need to be met in order for the solution to be > profitable and post it here for feedback purposes. Okay; my initial thoughts on the requirements for a dynamical separation of the architecture-specific instructions (based on the assumption that it is a syntax+stylesheet change): 1) No unnecessary changes to the GuideXML (+ handbook extensions) syntax We should try to limit the changes to the syntax to a minimum. An initial thought was to add an arch-attribute to the section entity. 2) Complete compatibility wrt the current guides The changes should only be needed on the Gentoo Handbook and should not affect the existing guides in any way. 3) Keep the documentation clear if no arch is selected The Gentoo Handbook must remain readable with all the architecture-specific instructions contained within. We may not remove this feature in favor of the other (extend choices, don't replace them). 4) Migrate to extensively use the id-attribute #doc_chapX_sectY should depend on the chosen architecture(s). This makes internal linking more difficult. As a result, many links will probably need to be adjusted to use a self-defined id (like <section id="bootloader">). Support for this is already active (and working) but not many links use it. 5) Propagate changes atomically into the other stylesheets Any change proposed should only be implemented once all existing stylesheets (including the printable ones, Xavier's one-page viewing and plasmaroo's XSL-FO -> PDF) are able to deal with the changes. We should in no way have incompatible stylesheets coexisting. 6) Document changes Something I've forgotten to do with the handbook format was to add information on how the handbook syntax is compared to the GuideXML format (in xml-guide.xml) at the same time (or before) the handbook was official. Such a mistake should not be made now. If a change is made to the XML syntax, the xml-guide.xml must be updated with this change. I believe those are the most pertinent requirements for such a change. Wkr, Sven Vermeulen -- ^__^ And Larry saw that it was Good. (oo) Sven Vermeulen (__) http://www.gentoo.org Documentation & PR