Re: [docbook] How to use classsynopsis and friends

[Thomas Schraitle <tom_schr@web.de>]

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