Re: [docbook] Re: Equations and figures as descendants of an example

[Erik Leunissen <e.leunissen@hccnet.nl>]

On 10/12/13 18:58, Norman Walsh wrote:
> Erik Leunissen <e.leunissen@hccnet.nl> writes:
> > First off: I feel a bit uncomfortable that I don't quite grasp the
> > reason that you asking these questions. Maybe there is an implicit
> > misunderstanding. I'm going to try to be explicit ...
>
> Sorry. I wasn't trying to make you uncomfortable. I'm absolutely
> not suggesting that you're wrong or that you don't have a good use
> case, it's just not one that I understand yet.

OK.

> > > What's your motivation for putting figures and equations inside an
> > > example?
> >
> > I've got the feeling that asking for a motivation is like turning the
> > world upside down. Have you never seen a theoretical exposition in a
> > textbook that clarifies it's theory with an example, where a figure is
> > used (regardless titles, regardless figure labels)?
>
> I can't think of one where the figure was nested inside the example, but
> I'm not disputing that it's a logical possibility.
>
> > Before I continue, I'd like to check whether there is anything wrong
> > with my understanding. Maybe it's the case that you mean something
> > quite different with an <example> than I do?
>
> Part of our miscommunication may be a question of perspective. I tend
> to think of figure, table, example, and equation as all members of a
> class of thing (which we call "formal" objects because they have a
> title).
>
> So I see "allow figure in example" as naturally leading to "allow
> figure in table" and "allow table in equation". Historically, DocBook
> has not allowed "formal objects" to nest.

Now I see your point, and I do agree that "figure in table" is 
unusual[*], and that "table in equation" is utterly weird.

[*] Though I do have a use case for the informal variant of this. I even 
have it ready implemented in a textbook chapter (in Dutch though).

> However, they aren't really all exactly uniform. For even more distant
> historical reasons, the title on equation is optional. And I can see
> that "example" can easily be taken as broader than figure, table, or
> equation.

I can indeed see a difference w.r.t. perspective becoming clear now:

If docbook collects these elements in the same category of formal 
objects for the only reason that they may carry a title and possibly a 
label, then that is so. And I'm sure that that classification has its 
merits. However, it also makes the apparent uniformity a construed one, 
which ignores/overlooks the nature or functionality of these elements.

Posing the same restrictions w.r.t. their mutual ordering, because of a 
classification that overlooks the natural functionality, is something 
that seems (to me) to have dangerous twist to it.

> That said, this still feels a bit weird to me:
>
> <example>
>    <title>Example of something</title>
>
>    <para>Some prose.</para>
>
>    <figure>
>      <title>Figure title</title>
>      <mediaobject>...</mediaobject>
>    </figure>
> </example>

OK. That's indeed the case that I think is plausible. And maybe the 
<example> is the odd one in the set of [equation, table, figure, ... ]

> I'd still like to better understand what your examples actually look
> like and what your rendering expectations are. Again, not because I
> think they're wrong, just because it would help me understand.

OK. In my teaching experience (I'm a lecturer in environmental 
chemistry), I often see in written texts:

A description of a general, more abstract process, let's say some type 
of chemical reaction (e.g. acid-base reactions). You can write lots of 
interesting things about it and how it works in general. Then you know 
that this abstract story won't cling to your average college student's 
brain because it is too abstract. In order to make it more concrete, you 
add one or two examples or cases where you are specific. You add figures 
and balanced equations for those specific cases to "provide proof".

I trust that there are analogies of these in other than chemical subjects.

As for rendering, I find that difficult to describe. I've seen these 
kind of examples (or cases) in small and larger versions, sometimes a 
few lines, sometimes covering several pages.

They may look as sidebars. In that case, they stand apart from the main 
text as separate "stories", maybe having a greyed/colored backgound, 
maybe a font different from main body, or just a solid border around it 
to make it visually stand apart.

They may also simply look as a sub-division of a section, not 
necessarily numbered/labeled, but separated from the rest of the section 
by a title/bridgehead.

About numbering the "(in)formal objects" inside such an example: that 
depends. If the example is not meant to be read separately but should be 
read along with the main text to clarify it, then I'd just like the 
numbering to continue as if it were part of the main text. Otherwise, 
numbering inside these examples may be unimportant and skipped. I don't 
recall to have ever seen a numbering system that is different from the 
main text.

Well that's an outline. I'm sure I didn't cover all dimensions of 
variability, but I hope that I've started to make more clear what I mean.


Greetings,

Erik Leunissen.


>                                          Be seeing you,
>                                            norm