Re: [docbook-tc] Building the DocBook TDG 5.2 book

[Bob Stayton <bobs@sagehill.net>]

Hi Norm,

The formalgroup element was very specifically designed to support subfigures 1a, 1b, etc., and the same for other formal numbered elements like equations, examples and tables. It allows for autonumbering by the stylesheet, titles and captions for each, as well as automatically generated xrefs to specific subfigures. We noted that TeX supports subfigures. This is a common use case in technical documentation, and we could see no way to easily support it otherwise. We did not consider any general wrapper during this discussion.

Bob Stayton
Sagehill Enterprises
bobs@sagehill.net

On 3/7/2019 5:59 AM, Norman Walsh wrote:

Hi folks,

In the course of building TDG 5.2, Iâve noticed some more 5.2 schema
changes. Please accept these comments from the peanut gallery in the
friendly spirit that theyâre intended.

Apologies that I havenât gone back to find the appropriate minutes.
Telling me to piss off and find them is perfectly reasonable if thatâs
where the answers are.

With that preamble out of the way, two observations.

1. I think âbuildtargetâ is awfully specialized to be raised to the
level of its own inline. There are lots of things relegated to a class
value on âsystemitemâ that strike me as equally common: filesystem,
macro, server, â

How did âbuildtargetâ justify its own inline? Is it time to give up on
any sense of limiting the number of elements and just raise all the
systemitem classes up?

2. I can imagine the justifications for âformalgroupâ, but thatâs so
far down the slippery slope towards a generic wrapper I feel like Iâm
in a toboggan. I canât imagine a rationale for âformalgroupâ that
doesnât apply equally to âinformalgroupâ. And at that point, it might
as well just be âgroupâ. You know someoneâs going to ask to group two
paragraphs or a paragraph and figure or a list and a procedure next.

Why is the attribute named âfgstyleâ and not just âstyleâ? DocBook
tries to avoid cryptic names for the most part.

                                        Be seeing you,
                                          norm

P.S. Hi Sabine! Lovely to see you back in DocBook land!