Tabs and <formalgroup> content model

Thomas Schraitle <[email protected]> Mon, 5 Feb 2024 13:01:59 +0100
Newsgroups gmane.text.docbook.misc
Message-ID <[email protected]>
Hi DocBook users,

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

   #
   db.formalgroup =3D
      ## 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 stylesh=
eets
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 t=
o the
TDG[1]? Or would the ideas above justify to amend the content model? Any
alternative?


What do you think? Thanks! :)


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


=2D-
Gru=C3=9F/Regards
   Thomas Schraitle