OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Always use most specific markup?

Lasse Kliemann wrote:
> Should one always use the most specific markup available?

Well, it depends ;-)
The question can be broaden: should one use inline markup at all?

It depends whether you plan to make use of that meta-information or not.
The question should be:
- Do I need to differentiate the rendering of a file name and a command
in the output documents?
- Do I need to be able to scan for all file names used in the document?
- Do others that will further use the document need that information?
- etc.

The risk with DocBook is one can be tempted to markup every word, just
because there is an element that may fit it. It can make writing a pain,
and maintaining the stylesheets too.
The answer to those questions is specific for each of us, IMHO.

If the simplified DocBook project has been unmaintained, I guess this is
because DocBook 5 makes it so easy to create its own simplified DocBook
(see http://norman.walsh.name/2005/11/05/dbtiny).

However the Publishing subcommittee may bring more answers.



>  For 
> example, sometimes it may be conceivable to use 'systemitem' 
> instead of 'filename', 'envar', or 'function'.
> Sometimes, even, there is no more specific markup available than 
> 'systemitem'. When I write a document where I am forced to use 
> 'systemitem' in many places (since there is nothing more specific 
> available), it might seem unproportional to be so very specific 
> as 'filename', 'envar', etc. in other places, unless it is clear 
> that this specific markup serves a purpose.
> The Simplified Docbook Project looked as if it could offer some 
> guidance concerning such questions, but unfortunately it seems to 
> be no longer maintained. It would in general be good to have more 
> documentation and public discussion on how to use Docbook markup 
> appropriately for different purposes. Maybe we can spur some 
> development in that direction.

fn;quoted-printable:Camille B=C3=A9gnis
adr:;;139 rue Philippe de Girard;Pertuis;;84120;France

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]