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
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
