more defined process
Tammy Fox
tfox at redhat.com
Sat Aug 14 23:58:51 UTC 2004
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 at redhat.com>
> >>> 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 at redhat.com>
> 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
More information about the fedora-docs-list
mailing list