Re: [docbook] How to use classsynopsis and friends

[Stefan Seefeld <stefan@seefeld.name>]

On 06.10.2015 00:35, Aristedes Maniatis wrote:
> On 6/10/2015 1:48pm, Stefan Seefeld wrote:
>> 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.
> I guess I'm just not understanding a fundamental concept in docbook then. I had always assumed docbook was a pure documentation schema and not intended to model real world concepts. When I look at http://www.docbook.org/tdg/en/html/synopsis.html it appears more like a way for a UI designer to model an interface than for a documentation person to describe it to a user. (That is, designed for its structure rather than its ability to generate html/pdf or other output).

Sometimes you want to format code in your documentation. The synopses
elements allow you to do that in a structured way. <synopsis> alone
could be thought of as a specialization of the <code> element, but with
some special semantics attached. The other synopsis elements just
provide some sub-structure for synopsis, as would be useful if the
formatted code was to be pretty-printed (function argument highlighting,
etc.)

I just found that this entire sub-vocabulary was quite incomplete, and
the formatting often even buggy, so I preferred to just use the 'raw'
<synopsis>.
>> 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.)
> 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.

Right.

>  Is the branch something I can easily play with? Or do I need to wait for this to land in 5.2?

That depends on how familiar you are with XML schemas and stylesheets.
(And I also am not sure about the current state; I haven't touched this
in a couple of years.)
The API schema is here:
https://github.com/docbook/xslt10-stylesheets/blob/api/docbook/relaxng/api/src/api.rnc
And the stylesheets here:
https://github.com/docbook/xslt10-stylesheets/tree/api/xsl/api

>
> I've never used an API extension.

(As I mentioned, I'm planning on merging the above into master, adding
some documentation on how to use them. If all goes well, we may even
switch the Boost documentation process to use that. But please don't
hold your breath... :-) )

>> In the meantime, I suggest to use 'synopsis' only.
> Even that seems a little cumbersome. By default all the elements there preserve whitespace, so I'll be struggling a little to render html out of it without overriding all the default html XSLT and removing <pre> and <code> elements from the output.
I'm not sure I understand. <synopsis> is a verbatim environment,
preserving the original formatting (in particular whitespace).

> Perhaps my solution will be to not use <synopsis> itself but instead to use many of its children like <methodname> and <parameter> and <returnvalue>, etc but embedded inside more old fashioned <section>, <para> and <variablelist> elements. That should give me some nice structured output I can target with css, without needing to hack away at the xslt other than some minor things.

You may indeed be misunderstanding the intended use of <synopsis>, as
there is nothing "old-fashioned" about <section> etc.; rather, the two
are supposed to be used in conjunction. You typically embed a <synopsis>
*into* a section.
(See https://github.com/vsip/specs/blob/master/vsipl%2B%2B/signal.xml
for an example, and
http://portals.omg.org/hpec/files/specs/vsiplxx/signal.xhtml and
http://www.omg.org/spec/VSIPL++/1.2/PDF/ for how this may be formatted.)

Regards,
        Stefan

-- 

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