On Sat, 2004-08-14 at 19:38, Mark Johnson wrote: > FWIW, I have some experience in implementing profiling and would be > happy to offer help as needed. > > From a quick scan of the fedora docs guide, I can't tell if it > mentions conditional sections, but if it does, we ought to rewrite > that section. 'Be happy to file the appropriate bug... > It isn't in there currently. I thought I wrote up the instructions after I figured it out for the Fedora Release Notes, but I can't find them now. So, go ahead and file a bug. I think it would make a great tutorial even if we don't end up using it for your quick start guide. Tammy > In fact, the DocBook TC recently agreed to add another global > attribute 'wordsize', which can be used via profiling to distinguish > 32-bit relevant content from 64-bit content. fedora docs may find > this attribute to be useful. (Caveat: the attribute was added to > DocBook V4.4, which is still in the candidate-release phase.) > > Cheers, > Mark > > > Mark Johnson wrote: > > You're talking about profiling based on attribute values. This is a > > different mechanism than conditional sections in SGML. > > > > I agree that this is the way to go, and has generally become the > > solution for the lack of support for conditional sections in XML. > > > > Just wanted to make it clear that we're no longer talking about > > conditional sections, that's all. Profiling is a different mechanism, > > and therefore shouldn't be referred to as using conditional sections. > > Doing so may confuse the authors, and potential authors. > > > > Thanks for clarifying what you meant. > > > > Cheers, > > Mark > > > > > > > > Tammy Fox wrote: > > > >> On Sat, 2004-08-14 at 17:39, Mark Johnson wrote: > >> > >>> Tammy Fox wrote: > >>> > >>> > >>>> One of the benefits of > >>>> DocBook is that you can use conditionals to create multiple documents > >>>> from the same source (like I was saying with the Installation Guides > >>>> for > >>>> multiple arches in a different thread). > >>> > >>> > >>> Yeah, but not within the docs themselves. With XML the conditionals > >>> have to lie in the 'external subset', like a customization layer for > >>> the DTD. (Unless I'm really confused about XML...) > >>> > >> > >> > >> You can set conditionals within the docs themselves. DocBook XML has > >> what is called profiling. > >> http://www.sagehill.net/docbookxsl/Profiling.html > >> > >> I managed to figure this out for the Fedora Release Notes, and it works > >> to have one master file from which all arch-specific release notes are > >> built. > >> There are built-in tag attributes for which you can assign keywords such > >> as x86 for the arch attribute or linux for the os attribute. > >> > >> Then, when you build the HTML, you tell it which profiles to include. > >> You can even include multiple profiles (unlike DocBook SGML conditional > >> INCLUDE statements). For example: > >> > >> xsltproc -o index.html --nonet --xinclude \ > >> -stringparam "profile.arch" "x86" \ > >> -stringparam "profile.os" "linux" \ > >> main.xsl example.xml > >> > >> As long as you use the built-in profile attributes, no customized DTD is > >> needed. > >> > >> Tammy > >> > >> > >>>> So, instead of creating a > >>>> separate guide with some of the same information, I think we should use > >>>> conditions in the existing source for the Docs Guide and create this > >>>> Quick Start Guide instead, if it is determined that we need another > >>>> one. > >>>> This will make sure the 2 do not get out of sync, which can happen very > >>>> quickly. > >>>> > >>>> Mark, since this is your idea, please share some more details about > >>>> what > >>>> you have in mind. How is it different from the existing guide? > >>> > >>> > >>> It would be a very brief tutorial on how to configure emacs for > >>> user-friendly DocBook XML editing. Naturally, I'd recommend that new > >>> users make use of my psgmlx[1] package for the psgml setup. [May have > >>> to do some tweaking to the package to provide the right stuff in the > >>> "Insert DTD" menu. I'll look inot this. Karsten & I are putting the > >>> package on Savannah 'real soon now'.] > >>> > >>> > >>> > >>>> What problem does it solve? > >>> > >>> > >>> Setting up emacsp/sgml, effectively, w/o having to do any setup. > >>> Truly a quick start to setting up a DocBook authoring environment in > >>> emacs. It's different from what's in the Docs guide in that psgmlx > >>> does all the setup for you, and provides sgml/xml-mode color themes > >>> as well. Put simply, it's aimed at newbie emacs users. > >>> > >>> It could be called a "Quick Start Setup Guide for Authoring DocBook > >>> docs with GNU Emacs", or something along those lines. The title isn't > >>> that important to me so long as it conveys the content of the document. > >>> > >>> [1] http://dulug.duke.edu/~mark/psgmlx > >>> > >>> > >>>> However, I would just like to > >>>> point out that even if you have used DocBook before, things like tag > >>>> usage can be interpreted in different ways, so you still need to read > >>>> the guide to make sure you are following the same rules as everyone > >>>> else > >>>> writing Fedora docs. > >>> > >>> > >>> I agree. Some people do need a sort of 'best practices' or 'our > >>> practices' guide to tag usage, even though the online "DocBook, The > >>> Definitive Guide" is usually sufficient. For example, the use of > >>> 'filename' to tag a package is not at all obvious, as one could also > >>> use 'systemitem', or 'application', or many other things. So, yeah, I > >>> agree that there needs to be some sort of style guide to resolve > >>> ambiguities of these sorts. [FWIW, DocBook V4.4 now has a 'package' > >>> element, but is still only in the candidate release phase.] > >>> > >>> > >>>> I honestly don't think it is that long or verbose. > >>> > >>> > >>> It's long, but given the scope of the document, its length makes > >>> sense. I still am of the opinion that <section> should be recommended > >>> instead of the <sect1> <sect2>, etc. elements, and that the ID naming > >>> convention needs to be overhauled. But, hey, that's just my opinion:) > >>> > >>> Cheers, > >>> Mark > >>> > >>> -- > >>> ---------------------------------------------------------- > >>> Mark Johnson <mjohnson@xxxxxxxxxx> > >>> Red Hat Documentation Group <http://www.redhat.com> > >>> Tel: 919.754.4151 Fax: 919.754.3708 > >>> GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 > >> > >> > >> > >> > > > > > > > -- > ---------------------------------------------------------- > Mark Johnson <mjohnson@xxxxxxxxxx> > Red Hat Documentation Group <http://www.redhat.com> > Tel: 919.754.4151 Fax: 919.754.3708 > GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242
