more defined process

Mark Johnson mjohnson at redhat.com
Sat Aug 14 23:38:06 UTC 2004


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...

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