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
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
