new programming synopsisinfo elements

[Bob Stayton <bobs@sagehill.net>]

Following up on one of my action items, we were wondering why the proposal for new programming elements contains individual *info elements like namespacesynopsisinfo instead of just info. It turns out they were patterning their new elements on the existing classsynopsis and classsynopsisinfo elements (and the similar funcsynopsisinfo).

The existing classsynopsisinfo element literally contains info itself *and* a whole bunch of other inlines or a textobject. See the reference page:

https://tdg.docbook.org/tdg/5.1/classsynopsisinfo.html

TDG says "Unlike the other info elements, classsynopsisinfo is not a container for meta-information. Instead, classsynopsisinfo is a verbatim environment for adding additional information to a class synopsis. Processing expectations: This element is displayed âverbatimâ; whitespace and line breaks within this element are significant."

No examples were given. But it also includes info if you also want metadata.

So these elements are additional information that displays after the actual synopsis statement in the output, so they are not like other info metadata.

Of course, funcsynopsisinfo and classsynopsisinfo have identical content models, as should all the new ones. It would be better if we just added a generic synopsisinfo element that we can use for all the new ones, and leave the old classsynopsisinfo and funcsynopsisinfo for backwards compatibility. That is a bit asymetric, but what else would work?

-- 
Bob Stayton
Sagehill Enterprises
bobs@sagehill.net