Re: Tabs and <formalgroup> content model

--=-=-=
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Thomas Schraitle <[email protected]> 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=E2=80=99m not sure formalgroup is really a good fit here. It feels more l=
ike
what=E2=80=99s needed for this sort of thing is an =E2=80=9Calternatives=E2=
=80=9D element and a
wrapper for a series of alternatives.

In addition to the title problem, I wouldn=E2=80=99t 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=E2=80=99t feel like quite the same thing, so I=E2=80=99m 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=E2=80=99t uncommon now in technical
documentation: Gradle uses it for Groovy/Kotlin examples. I=E2=80=99m pretty
sure I=E2=80=99ve 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=E2=80=99s 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=3D"python3.8">from typing import List=E2=80=A6</example>
  <example role=3D"python3.9">from litestar import=E2=80=A6</example>

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

There=E2=80=99s not much support for the author. You=E2=80=99d want some Sc=
hematron 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=E2=80=A6

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

                                        Be seeing you,
                                          norm

=2D-
Norm Tovey-Walsh <[email protected]>
https://norm.tovey-walsh.com/

> Simplification good! Oversimplification bad!--Larry Wall

--=-=-=
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iHUEARYKAB0WIQSEJUqRvjpp8yLt8uKDEiZHbwv9OwUCZcDpBwAKCRCDEiZHbwv9
O14TAPsF2TXvWgM0pBWcauY4jimcTc+e1jJEhN73793uZ2UGYgD/dbVEkgxc/z3q
yxl3UFQkZ7QWmeupMNTzRE0u9W2Pogk=
=yP+m
-----END PGP SIGNATURE-----
--=-=-=--