Tabs and <formalgroup> content model

[Thomas Schraitle <tom_schr@web.de>]

Hi DocBook users,

DocBook 5.2 contains the element <formalgroup>[1] which has this content model:

  #
  db.formalgroup =
     ## A group of formal objects, for example subfigures
     element formalgroup {
      db.formalgroup.attlist,
      db.formalgroup.info,
      (db.figure+ | db.table+ | db.example+ | db.equation+)
    }

I'd like to use this element for a "tab structures". An example of a tab
structure can be seen in "Litestar library documentation"[2] (scroll down a
bit, see "Define a Controller for your data model").

I would like to replicate this structure in DocBook. Of course the stylesheets
need to be adapted/customized as well, but that's another issue. I'd like to
focus on the markup only.

The tab structure in Litestar could look like this in DocBook:

  <formalgroup>
    <title>Definition of a controller for your data model</title>
    <example>
      <title>Python 3.8+</title>
      <screen>... Code for 3.8 ...</screen>
    </example>
    <example>
      <title>Python 3.9+</title>
      <screen>... Code for 3.9 ...</screen>
    </example>
  </formalgroup>

Not sure if this is the "right" way to do that in DocBook, but I face some
questions:

1. What if I don't need the formalgroup title?
   I could use <title/>, but that's not the same. Perhaps this goes into
   the direction of a <informalformalgroup> (which doesn't exist).

2. Why is <formalpara> not added to the content model?
   The <formalpara> would be the perfect fit if I just want to add
   a single paragraph. The other elements introduce a different semantic.

3. What about the other informal* elements?
   What if I don't need a title of the objects? In other words, wouldn't
   it make sense to allow the informal* elements as well?
   The stylesheets could create a default name ("Tab X"?) in such a case.

Perhaps the way how I would like to use this element was not intended. :) But
for me, the following sentence in the TDG[1] let me believe this would be the
perfect fit for a tab structure:

  "Placing them in a container allows the processing system to style
  them together or place them as related elements."

I don't think, there is any other DocBook element that has a similar role, is
there?

So... what's the "right" way to do that? Perhaps we could add an example to the
TDG[1]? Or would the ideas above justify to amend the content model? Any
alternative?


What do you think? Thanks! :)


--- References
[1] https://tdg.docbook.org/tdg/5.2/formalgroup
[2] https://docs.litestar.dev/2/#expanded-example


--
GruÃ/Regards
  Thomas Schraitle