OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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.


What's your motivation for putting figures and equations inside an

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

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

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:

   <title>Example of something</title>

   <para>Some prose.</para>

     <title>Figure title</title>

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.


Erik Leunissen.

                                         Be seeing you,

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]