Re: [docbook] Tabs and <formalgroup> content model

[Dave Pawson <dave.pawson@gmail.com>]

On Mon, 5 Feb 2024 at 12:02, Thomas Schraitle <tom_schr@web.de> wrote:
>
> 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+)
>      }

From Norms comments, " ## A group of formal objects, for example subfigures"
seems a bit off (my view), rather than 'formal objects' (I've a job
relating to that),
how about 'related' or 'closely related' then figures / subfigures
matches (to me).

regards


>
> 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: docbook-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-help@lists.oasis-open.org
>


-- 
Dave Pawson
XSLT XSL-FO FAQ.
Docbook FAQ.