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’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 <[email protected]>
https://norm.tovey-walsh.com/
> Simplification good! Oversimplification bad!--Larry Wall
signature.asc
Description: PGP signature
