Re: [docbook] How to use classsynopsis and friends

[Stefan Seefeld <stefan@seefeld.name>]

On 06.10.2015 16:52, maxwell wrote:
> On 2015-10-05 22:48, Stefan Seefeld wrote:
>> 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.)
>
> It's too late now, I'm sure, but as a user of DocBook for purposes
> other than software documentation (we use it for grammars), DocBook
> seems bloated with all these tags for software (the aforementioned
> <classsynopsis> being a perfect example).  In our customization, we
> remove all those tags, and add in the ones we need for literate
> programming and for linguistics, using a namespace prefix for our tags.

...which is the reason the aforementioned API vocabulary is an
extension, using its own namespace. No-one proposes to merge it into
DocBook, so only those who need it will have to deal with it.

>
> It always seemed to me like DocBook could have had a much simpler
> model, by putting the software- and hardware-specific tags into a
> separate namespace.  That would make it easier for other potential
> users to wade through the remaining elements and decide which of them
> they really need.  Obviously that couldn't have happened until DB5,
> and it's probably too late now.  I suppose the next best thing would
> be to compile a list of tags that are core DB (meaning about text in
> general), and/or a list of software- and hardware-specific tags, which
> would make it easier for potential users.

Yes, at this point it's not possible to remove all the original synopsis
elements, so we'll have to live with them. But if users switch to the
API extension (if it turns out to be useful to anyone outside a small
community, that is), these elements may indeed be forgotten as a
historic accident.

        Stefan

-- 

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