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

[Thomas Schraitle <tom_schr@web.de>]

Hi,

thanks for your answers and ideas. Much appreciated!

On 05.02.24 14:31, Norm Tovey-Walsh wrote:
> [...]
> Iâm not sure formalgroup is really a good fit here.

That was also one of my doubts. ;)


> It feels more like
> whatâs needed for this sort of thing is an âalternativesâ element and a
> wrapper for a series of alternatives.

Probably. Maybe for this special use case, <formalgroup> isn't the right element.


> In addition to the title problem, I wouldnât be surprised if you
> discovered you wanted to have different kinds of things in different
> tabs. You might even be eluding to that in your introduction of
> formalpara to the mix. Note that formalgroup is a group of one type.

Right. After looking at the content model again, I see it's indeed only for one
type.

Hmn, apart from layout issues and simplification, is there a reason why it's
not allowed, let's say, add a <figure> and an <example> inside a <formalgroup>?


> > 2. Why is <formalpara> not added to the content model? [...]
>
> I think that might be an oversight, but a group of formal paragraphs
> doesnât feel like quite the same thing, so Iâm not sure.

I was also unsure about this, but I thought I just ask. :)

Maybe formalpara isn't a good fit anyway as it's quite limited. It allows only
a title and _one_ paragraph. Apart from the semantic discrepancies, maybe it's
not worth the trouble.


> > 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.
>
> The use case was to create a group of formal items: for example, a
> figure on a page that contains four subfigures. If you want to group
> informal things together, you can usually just put them all in one
> container: an informalfigure containing four mediaobjects, for example.

I think I have an idea now how <formalgroup> should be used. I just discovered
this element some time ago, but didn't have a use case for that.

Nevertheless, it would be helpful if we had an example of how this element
should be used. Or maybe some further explanations on use cases and when it
makes sense. Or when it's not. However, this may not be feasible and perhaps
too specific for a reference.


> The more arbitrary the content, the harder it becomes to work out the
> semantics in the general case.

Yes, that's something that I was afraid of too.


> [...]
> The tabbed view you propose isnât uncommon now in technical
> documentation: Gradle uses it for Groovy/Kotlin examples. Iâm pretty
> sure Iâve seen it used for JavaScript/Typescript examples. Different
> versions of Python seems perfectly reasonable.

Right, I've seen it in several places now.

Maybe it's not so a question of markup than more a question of layout.


> > 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?
>
> Itâs an interesting question. What would you do to present the
> alternatives in a dead tree version of the document? Two obvious
> possibilities are a Python 3.8 version of the document, and a Python 3.9
> version, with no attempt to present the alternatives side by side. The
> other possibility is to present them sequentially. In neither case is
> the grouping doing you any favors.

That's correct, but I wouldn't expect any fancy grouping in PDF anyway. For me,
it would be totally acceptable to have it presented sequentially. Only for HTML
it would make sense to group them in a more tab style layout.


> [...] > Thereâs not much support for the author. Youâd want some Schematron to
> make sure the adjacent examples were arranged in a way that your
> stylesheets expect. Of course, in some editing environments, those
> Schematron rules would *be* support for the author, soâ

Schematron would be one solution, but as we use XSLT 1.0 only.

After thinking about it... maybe an alternative could be to have a table. It's
certainly not ideal, as it's more layout-driven than semantic-driven. Something
like this:

 <table tabstyle="tabs">
   <title>Definition of a controller for your data model</title>
   <tgroup cols="2">
     <tbody>
       <row>
         <entry>
           <example>
             <title>Python 3.8+</title>
             <screen>... Code for 3.8 ...</screen>
           </example>
         </entry>
         <entry>
           <example>
             <title>Python 3.9+</title>
             <screen>... Code for 3.9 ...</screen>
           </example>
         </entry>
       </row>
     </tbody>
   </tgroup>
 </table>

That would allow more variations and is not limited to the content model of
<formalgroup>.

With the help of a custom XSLT, CSS, and JavaScript, it could certainly be
rendered in a tab style layout.

Perhaps one downside could be, that the FO/HTML stylesheets need to distinguish
between a regular table and this tab-styled "table".


> This reminds me of the periodic discussions weâve had about a âdivâ
> element: something that can wrap arbitrary content so that you can group
> it. Itâs not hard to find use cases that would benefit from a div
> element, but theyâre an absolute nightmare in the grammar and make all
> kinds of processing more complicated.

I could certainly imagine use cases for a <div>, but as you said, it would be a
nightmare. :)


Thanks for the discussion and ideas!


--
GruÃ/Regards
  Thomas Schraitle