RE: [docbook] How to use classsynopsis and friends

["Emery, Norma (HGR)" <nemery@whitehangar.net>]

This has been an interesting discussion to follow. 
I'd like to add that I love Docbook's simplicity, flexibility, and reliability.
I don't use all of the elements in Docbook but I may find a use for some of them so I can't think of a compelling reason to remove elements. 
As you point out below:
	"It is always a good idea to go through of all DocBook elements and think about what is useful or not."
So I'm content to have Docbook stay as is and just use the subset of elements I need. It's still good to know there are other elements that might prove useful to me in the future.
Thanks to all of you who develop and support Docbook.


 

-----Original Message-----
From: Thomas Schraitle [mailto:tom_schr@web.de] 
Sent: Thursday, October 08, 2015 2:56 AM
To: docbook@lists.oasis-open.org
Subject: Re: [docbook] How to use classsynopsis and friends

Hi,

On Thu, 8 Oct 2015 17:16:39 +1100
Aristedes Maniatis <ari@ish.com.au> wrote:

> [...]
> Thanks Thomas. And thanks to everyone else who responded.

You're welcome. :)


> [...] Overall my experience with docbook has been good, tempered only 
> with a lack of good examples.

You can find some examples in the following link, although they are created as test files:
https://github.com/docbook/xslt10-stylesheets/tree/master/testdocs/tests


 
> Yes, there is reasonable technical documentation. But not much of the 
> "best practices" kind of stuff.

I guess it has something to do that DocBook supports different use cases. As such, it has a broad spectrum how to markup your text.

I tried to collect some of these "best practices" that I've learned over the years in my cookbook (see link below).


> I'd like some more "structure your
> document like this unless you know what you are doing" sort of thing.
> When does it make sense to use <simplelist> instead of <itemizedlist>? 
> Or why would I want a <segmentedlist> instead of <variablelist>? Or 
> what's the point of <sectx> instead of nested <section>s.

You can find some of your questions answered in my cookbook:

  http://doccookbook.sf.net/html/en/dbc.markup.html

Regarding the simplelist vs. itemizedlist: yes, it may be confusing, but in most cases you can use itemizedlist and don't care about simplelist.

According to the TDG, "ironically, the processing expectations of a simplelist are quite complex." You can render your simplelist inline, in a row- or column-major table.

 
> [...] there is a whole
> lot of docbook which is best avoided unless you have really 
> specialised needs.

That is true.

It is always a good idea to go through of all DocBook elements and think about what is useful or not. You can also use the simplified version of DocBook which is a subset of the complete schema. That may make it easier for you and your team.

Another alternative would be to create your own DocBook schema. With the help of RELAX NG, this is really easy now! Especially if you want to remove elements, this can be done in a simple line.


> [...]


--
Gruß/Regards,
    Thomas Schraitle

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-help@lists.oasis-open.org