Re: [docbook] How to use classsynopsis and friends

[Stefan Seefeld <stefan@seefeld.name>]

Hi Aristedes,

On 05.10.2015 22:39, Aristedes Maniatis wrote:
> I'm confused about the purpose of classsynopsis, methodsynopsis and all the related elements. The documentation acknowledges that they are a mixture of modelling and documentation. But I'm hitting my head against a wall trying to use them for either.
>
> As a model, they are clearly lacking many concepts inherent to something like javadoc. But that's OK, because I don't want a 1:1 mapping back to my code... I just want a nice way to output documentation. In my case, I'm modifying groovydoc output to spit out docbook instead of html, which gives me more options to tie into an existing docbook documentation workflow.
>
> But as a documentation structure classsynopsis is also very lacking. It cannot contain common structural elements like <para> or <variablelist> so I'm very limited in formatting documentation elements. My docs contain lists, ulinks, xref and code samples (<programlisting>).
>
> Should I just discard classsynopsis and friends as a well intentioned but ultimately dead-end bit of docbook, and go back to boring old sections, lists and other structures which are more expressive but have no semantic concepts of parameters, return types and more? Or am I missing the point of some other way to handle this?
>
> By Google I've found zero examples of other people using classsynopsis.

I once ran into similar questions...I believe the goal for all those
*synopsis elements is to act as a refinement for the synopsis element,
i.e. to let you create a synopsis with substructure. These elements are
*not* meant to be mixed with text.

However, like you, I also came to the conclusion that they are very
limited, so I abandoned their use in my own documentation. However,
there was a project as part of Boost (http://boost.org) to augment
DocBook with a more complete vocabulary for API documentation, which
ultimately became "BoostBook"
(http://www.boost.org/doc/libs/1_59_0/doc/html/boostbook.html).
This has been ported back to DocBook 5 as an "API" extension, but at
this point is still only available in a branch. (I intend to merge it to
master soon.)

In the meantime, I suggest to use 'synopsis' only.

Regards,
        Stefan

-- 

      ...ich hab' noch einen Koffer in Berlin...