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

[Norm Tovey-Walsh <ndw@nwalsh.com>]

Thomas Schraitle <tom_schr@web.de> writes:
> 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).

Iâm not sure formalgroup is really a good fit here. It feels more like
whatâs needed for this sort of thing is an âalternativesâ element and a
wrapper for a series of alternatives.

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.

> 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.

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.

> 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.

The more arbitrary the content, the harder it becomes to work out the
semantics in the general 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?

No, not really.

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.

> 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.

You could make this work:

  <para>Define a controller for your data model:</para>

  <example role="python3.8">from typing import Listâ</example>
  <example role="python3.9">from litestar importâ</example>

  <para>When instantiating your app, import your controller into your
  applicationâs entry-point and pass it to Litestar:

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â

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.

                                        Be seeing you,
                                          norm

--
Norm Tovey-Walsh <ndw@nwalsh.com>
https://norm.tovey-walsh.com/

> Simplification good! Oversimplification bad!--Larry Wall

Attachment: signature.asc
Description: PGP signature