Re: Tabs and <formalgroup> content model

Hi,

thanks for your answers and ideas. Much appreciated!

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

That was also one of my doubts. ;)


> It feels more like
> 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.

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


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

Right. After looking at the content model again, I see it's indeed only fo=
r 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 <formalgr=
oup>?


>> 2. Why is <formalpara> not added to the content model? [...]
>
> 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.

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 discov=
ered
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 i=
t
makes sense. Or when it's not. However, this may not be feasible and perha=
ps
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=E2=80=99t uncommon now in technical
> documentation: Gradle uses it for Groovy/Kotlin examples. I=E2=80=99m pr=
etty
> sure I=E2=80=99ve seen it used for JavaScript/Typescript examples. Diffe=
rent
> 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 exampl=
e to the
>> TDG[1]? Or would the ideas above justify to amend the content model? An=
y
>> 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.

That's correct, but I wouldn't expect any fancy grouping in PDF anyway. Fo=
r 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=E2=80=99s not much support for the author. You=E2=80=99d w=
ant 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=E2=80=A6

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. Some=
thing
like this:

  <table tabstyle=3D"tabs">
    <title>Definition of a controller for your data model</title>
    <tgroup cols=3D"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 o=
f
<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 distin=
guish
between a regular table and this tab-styled "table".


> 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 di=
v
> element, but they=E2=80=99re an absolute nightmare in the grammar and ma=
ke 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!


=2D-
Gru=C3=9F/Regards
   Thomas Schraitle