Re: [docbook] How to use classsynopsis and friends

[Aristedes Maniatis <ari@ish.com.au>]

On 6/10/2015 6:26pm, Thomas Schraitle wrote:
> I don't know what the designer had in their mind when they created
> these elements. As far as I know, these elements were already in place
> in version 4.1 and probably below. So DocBook carry these *synopsis
> elements for a long time. Maybe at that time it was completely
> sufficient for describing an API. ;-)
> 
> 
>> > [... "BoostBook" ...]
>> > 
>> > That looks really interesting. I poked around a bit, but in its
>> > currently BoostBook state it looks like too much work to build and
>> > incorporate into our workflow. Is the branch something I can easily
>> > play with? Or do I need to wait for this to land in 5.2?
> If you think this is something that is worth to incorporate into the
> next DocBook version, I would suggest to open a request for enhancement:
> 
>   https://sourceforge.net/p/docbook/rfes/new/

Thanks Thomas. And thanks to everyone else who responded.

Perhaps docbook 6.0 is a good time to remove some of these old elements from the specifications. But I don't really have a request for enhancement. Overall my experience with docbook has been good, tempered only with a lack of good examples.

Yes, there is reasonable technical documentation. But not much of the "best practices" kind of stuff. 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.

Since most users will get through with about 20% of the docbook elements, it would be great to have guidance on which 20% that is. Yes, I know it might differ for different purposes, but as I discovered for <sect1> and now with <classsynopsis>, there is a whole lot of docbook which is best avoided unless you have really specialised needs. I started with my team using almost every element from docbook and quickly realised that was the way to madness.

Anyhow, that's my 5 cents as a relative newcomer to docbook.

Thanks
Ari



-- 
-------------------------->
Aristedes Maniatis
ish
http://www.ish.com.au
Level 1, 30 Wilson Street Newtown 2042 Australia
phone +61 2 9550 5001   fax +61 2 9550 4001
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A

Attachment: signature.asc
Description: OpenPGP digital signature