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... --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-h...@lists.oasis-open.org
