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
signature.asc
Description: OpenPGP digital signature
