Re: more defined process

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux