Re: [docbook] How to use classsynopsis and friends

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

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).


> 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. Is the branch something I can easily play with? Or do I need to wait for this to land in 5.2?

I've never used an API extension.


> 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.

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.

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