Side-by-side objects, such as tables, figures, subtables, subfigures

[Chris Hughes]

I have a feature that allows each of the following in both LaTeX and html:

• multiple figures side by side
• multiple tables side by side
• figures and tables side by side
• subfigures (e.g Figure 1(a), (b), (c), etc)
• subtables (e.g Table 1(a), (b), (c), etc)

Some sample screenshots (LaTeX first, then html):

As I say, the feature allows Figures and Tables to be next to each other, together with subfigures, and subtables.

The XML for the above tables is

<multobjects type="table" TeXFloatOptions="!hbt">
              <div width="50%">
                <table xml:id="exp-tab-salary">
                  <caption/>
                  <coltypes>
                    <col align="decimal" format="2.0"/>
                    <col align="decimal" format="10.0"/>
                  </coltypes>
                  <thead>
                    <row><entry><m>d</m> (days worked)</entry><entry><m>p</m> (cents)</entry></row>
                  </thead>
                  <tbody>
                    <row><entry>1</entry><entry>2</entry></row>
                    <row><entry>2</entry><entry>4</entry></row>
                    <row><entry>3</entry><entry>8</entry></row>
                    <row><entry>4</entry><entry>16</entry></row>
                    <row><entry>5</entry><entry>32</entry></row>
                    <row><entry>10</entry><entry>1024</entry></row>
                    <row><entry>30</entry><entry>1073741824</entry></row>
                  </tbody>
                </table>
              </div>
              <div width="50%">
                <table xml:id="exp-tab-salaryalt">
                  <caption />
                  <coltypes>
                    <col align="decimal" format="2.0"/>
                    <col align="left"/>
                  </coltypes>
                  <thead>
                    <row><entry><m>d</m> (days worked)</entry> <entry><m>p</m> (cents)</entry></row>
                  </thead>
                  <tbody>
                    <row><entry>1</entry> <entry><m>2</m>                  </entry></row>
                    <row><entry>2</entry> <entry><m>2^2</m>                </entry></row>
                    <row><entry>3</entry> <entry><m>2^3</m>                </entry></row>
                    <row><entry>4</entry> <entry><m>2^4</m>                </entry></row>
                    <row><entry>5</entry> <entry><m>2^5</m>                </entry></row>
                    <row><entry>10</entry> <entry><m>2^{10}</m>             </entry></row>
                    <row><entry>30</entry> <entry><m>2^{30}</m>             </entry></row>
                  </tbody>
                </table>
              </div>
            </multobjects>

For the moment, please ignore the coltypes as they are part of another discussion; instead, please concentrate on the multobjects tag, and the use of a div tag together with an associate width to specify how wide each 'sub' object should be.

The LaTeX code uses the minipage environment, and the subcaption package with associated subfigure and subtable environments (for Figures 1(a), (b), etc). The hmtl code uses div boxes, together with a check on the parent object, multobjects type to style the caption.

Rob said that it's generally a good idea to post these kinds of things here in the support forum so that the syntax can be hashed out and stewed over for a bit before submitting a pull request. So.... please do let me know if you have any questions about this; I'll be happy to post more sample code, or chat about any potential issues.

[Rob Beezer]

Thanks, Chris. This has been on my mental wish-list for some time, and I know
David Farmer has some definite ideas, so I hope he weighs-in when he can.
Comments, in no particular order.

1. I like the outer wrapper ("multobjects") and the wrapper around each item
("div"). Seems the most natural way to do it, though see thought below.

2. Does the "type" mean you have a bunch of tables, or the whole thing is a
table? Of course, you can discover the tables within through XSL.

3. I have never liked LaTeX's floats. Especially when they all get queued up
for the end of a chapter because one big one gums up the system. I invariably
need to go in by hand. I think that LaTeX output is always going to need
hand-tuning for page-breaks (even absent floats) if you are going for
high-quality output (like a printed book). You'll notice I use the LaTeX
"float" package and just place figures and tables "here". The idea being you
will eventually adjust location to get whatever quality of placement on the
printed page that you want. Eventually, I may add the capability for latex
"hints", like a hard page-break, but I'd like to hold off as long as possible.

So I'm not wild about "TeXFloatOptions." As much as possible, I want to avoid
output-specific items in the source. An author (or future implementer) should
not need to understand "!hbt" and/or there should be some natural analog
behavior for HTML (or some other output format). Generally right now ties go to
HTML, since I think that is more important than print going forward.

4. Could we have a hierarchy of uses/fine-tuning? I'd like simple uses to
always be easy, with optional flexibility as situations demand.

* Default: Several items, all in one row, equally spaced. Simple
outer-wrapper to collect them. Boom. Easy.

* Bigger layouts: eg, rows="2", cols="3" on outer-wrapper would get you a 2
x 3 equally spaced grid of 6 objects. (if total < rows*columns, code could
space out last row differently? Or leave blank entries?) I have some private
code for laying out "arrays" of combinatorial designs that I can send you and it
might help with implementation.

* Each object could admit a width="60%" (or width="60") to override equal
spacing when desired.

5. Names. I'd like names to be natural to an author who does not know TeX or
HTML. For example, I know what a "div" is, but could not tell you what it is
short for. I've used short items from HTML that are natural abbreviations, eg.
p, ol, ul, and other very short abbreviations for common items, eg m, me, c.
Otherwise I'd prefer to spell out entire words rather than recall half-way
abbreviations. So - could "multobjects" become something like "displaygroup"?
Could "div" become something less HTML-ish? "type" (above) is always an easy
choice, but not very informative (eg, I can not tell from the example what the
purpose is).

6. Inner-wrapper. Do you think an inner-wrapper on each item is redundant?
Just allow tables, images, and whatever else piled-up inside, and add attributes
like "width" to them for use only inside a grouping? Do you have more ideas for
attributes on the "div"?

7. Captions. Will the whole group admit a caption of its own, while each
sub-item has its caption rendered as a sub-caption? This is the kind of thing
I'd love to see - just drop a bunch of existing individual tables into a simple
outer-wrapper and get the behavior you expect without adjusting the individual
tables.

Please include both simple and advanced (stress-test) examples into the
sample-article (but maybe mostly with images, since tables may change/evolve).

This will be a great contribution and I am looking forward to having it. Thanks
for taking it on.

Rob

On 02/08/2015 05:58 AM, Chris Hughes wrote:
>
> I have a feature that allows each of the following in both LaTeX and html:
>

> * multiple figures side by side
> * multiple tables side by side
> * figures and tables side by side
> * subfigures (e.g Figure 1(a), (b), (c), etc)
> * subtables (e.g Table 1(a), (b), (c), etc)

>
> Some sample screenshots (LaTeX first, then html):
>

> <https://lh5.googleusercontent.com/-W0IMAJOfEFg/VNdpCMI92kI/AAAAAAAADoU/pC5n6jHNp7g/s1600/Screenshot%2Bfrom%2B2015-02-08%2B13%3A46%3A36.png>
>
> <https://lh4.googleusercontent.com/-soioMAo_WAU/VNdpNIq4YkI/AAAAAAAADoc/MqwqBjHgHHU/s1600/Screenshot%2Bfrom%2B2015-02-08%2B13%3A46%3A59.png>

> For the moment, please ignore the *coltypes* as they are part of another
> discussion; instead, please concentrate on the *multobjects* tag, and the use of
> a *div* tag together with an associate *width* to specify how wide each 'sub'
> object should be.
>
> The LaTeX code uses the *minipage* environment, and the *subcaption* package
> with associated *subfigure* and *subtable* environments (for Figures 1(a), (b),
> etc). The hmtl code uses *div* boxes, together with a check on the parent
> object, *multobjects* type to style the caption.

>
> Rob said that it's generally a good idea to post these kinds of things here in
> the support forum so that the syntax can be hashed out and stewed over for a bit
> before submitting a pull request. So.... please do let me know if you have any
> questions about this; I'll be happy to post more sample code, or chat about any
> potential issues.
>

> --
> You received this message because you are subscribed to the Google Groups
> "MathBook XML Support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to mathbook-xml-sup...@googlegroups.com
> <mailto:mathbook-xml-sup...@googlegroups.com>.
> For more options, visit https://groups.google.com/d/optout.

[David Farmer]

Great topic, especially if you add text/paragraph as one of the options.

It is reasonably common to have 2 or three things side-by-side in a
book. Both having and not having a caption is common (not having a
caption would be more common if people put more thought into the
presentation. See Tufte's "Beautiful Evidence".)

Here are three pages of a book of mine, in which there appears
2 images, or text and image, or three images side-by-side:

http://aimath.org/~farmer/print/side-by-side.pdf

Those examples show that you need a way to position the objects
vertically within their block, and also that you need to control
the width of the object, the spacing between objects, and
the margins.

In my examples where I have text next to an image, I want the text
to be centered vertically with respect to the image,
and I wanted a fair amount of space between the text and the
image. I can imagine reasonable defaults, but the author needs
to be able to do some visual tweaking.

If the discussion is really about things being "next to each other",
as opposed to a 2-dimensional grid of objects, then I think the tag
"multobjects" should be changed to a term reflecting that
the objects are side-by-side. It would also be good to have
something more semantic than "div" to wrap each object.
(I do think it is a good idea to specifically support side-by-side
objects, and not treat is as a grid that happens to only have one row.)

The cases of two things or three things side-by-side are the most common.
Writing p for text, t for table, and i for image, I definitely have
used all of the following:

pp (same content in two languages, for example)
pt
pi
ip
ii
ipi
iii

I could imagine other combinations. I have seen 4 or more things
next to each other, but only in the case where each is an image.

Just to give something for people to shoot down, here is an attempt
at the markup for the first thing on the PDF at the link above:

<sidebyside type="pi" leftmargin="0" rightmargin="5%">
<div width="31%" valign="middle">
<p>First glue the top edge to the bottom to make a cylinder.</p>
</div>
<div width="29%" />
<div width="40%">
[whatever markup is needed for that image]
</div>
</sidebyside>

(I wrote a lot of comments about the various decisions I made when
writing that example, and the alternatives I considered. Then I deleted
them because I think it would be more helpful if a few people did
their own examples before trying to settle on the proper markup.
I still don't like "div" for the components but couldn't think of an
alternative.)

On Sun, 8 Feb 2015, Chris Hughes wrote:

>
>
> I have a feature that allows each of the following in both LaTeX and html:
>

> * multiple figures side by side
> * multiple tables side by side
> * figures and tables side by side
> * subfigures (e.g Figure 1(a), (b), (c), etc)
> * subtables (e.g Table 1(a), (b), (c), etc)

>
> Some sample screenshots (LaTeX first, then html):
>

> [Screenshot%2Bfrom%2B2015-02-08%2B13%3A46%3A36.png]
>
> [Screenshot%2Bfrom%2B2015-02-08%2B13%3A46%3A59.png]

> --
> You received this message because you are subscribed to the Google Groups "MathBook XML Support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to

> mathbook-xml-sup...@googlegroups.com.

[Robert Beezer]

Let's try to imagine David's example without any div's.

1. Drop the "type" and let XSL discover it.
2. Left margin on outer level, rightmargin's on each item.
3. Repurpose "paragraph" environment to allow several paragraphs in text.
4. I've shown a title, which changes David's content, just for illustration.  Optional.
5. Dropped % on widths, margins (unsure about this one).
   

<sidebyside leftmargin="0">
   <paragraph width="31" valign="middle" rightmargin="29">
      <title>First Step</title>
      <p>Glue the top edge to the bottom to make a cylinder.</p>
      <p>Maybe my text has a second paragaph, so we use "paragraph" enclosure.</p>
      <p>Title is optional.</p>
   </paragraph>
   <image width="40" rightmargin="5">
      [image source, description, etc, here]
   </image>
</sidebyside>

[Chris Hughes]

Thanks for the follow-ups Rob and David, I'm excited that there is enthusiasm for this feature :)

To address/answer/comment on some of the questions/comments made so far:

2.  Does the "type"  mean you have a bunch of tables, or the whole thing is a table?  Of course, you can discover the tables within through XSL.

This illustrates the outer 'wrapper' for the main object. For example, imagine that you have the following arrangement:

**************      **************
**************      **************

**************      **************

    (a)                     (b)

           Figure 3.5

The type tells you that it the wrapper is a Figure. In the case where we have a Figure and a Table next to each other, the type is not relevant.

3.  I have never liked LaTeX's floats....

I'm happy to remove any reference to floats; it's something that OpenMathDocs (our project that uses MathBook) will have to address at a later stage, but we're nowhere near that point yet, so consider TeXFloatOptions removed :)

4.  Could we have a hierarchy of uses/fine-tuning?  I'd like simple uses to always be easy, with optional flexibility as situations demand.

Yes, I think I can work with this idea, and I'm happy to (try to) implement rows=*** and columns=###.

5/6.  Inner-wrapper.  Do you think an inner-wrapper on each item is redundant? Just allow tables, images, and whatever else piled-up inside, and add attributes like "width" to them for use only inside a grouping?  Do you have more ideas for attributes on the "div"?

That had actually occurred to me as well; I'm happy to ditch the inner-wrapping div and simply allow tables, images, and anything else to have an optional width that comes into play within the displaygroup.

7.  Captions.  Will the whole group admit a caption of its own, while each sub-item has its caption rendered as a sub-caption?  This is the kind of thing I'd love to see - just drop a bunch of existing individual tables into a simple outer-wrapper and get the behavior you expect without adjusting the individual tables.

Either or both is fine; each sub-item is allowed its own caption, and a global caption is also allowed (see my mock-up above with Figure 3.5). I didn't illustrate it in my example above, but there's an optional attribute called children that can be subfigure or subtable; in the case of subfigure all figure blocks are interpreted as subfigures, and similarly for subtables.

It is reasonably common to have 2 or three things side-by-side in a
book.  Both having and not having a caption is common (not having a
caption would be more common if people put more thought into the
presentation.  See Tufte's "Beautiful Evidence".)

Good point, thanks for the reference.
 

Here are three pages of a book of mine, in which there appears
2 images, or text and image, or three images side-by-side:

http://aimath.org/~farmer/print/side-by-side.pdf

Those examples show that you need a way to position the objects
vertically within their block, and also that you need to control
the width of the object, the spacing between objects, and
the margins.

This is a good example, thanks for providing the link. I'm reasonably sure that I can implement both of these in LaTeX and in html.

 

The cases of two things or three things side-by-side are the most common.
Writing p for text, t for table, and i for image, I definitely have
used all of the following:

pp     (same content in two languages, for example)
pt
pi
ip
ii
ipi
iii

I can see that this has value, and is very similar to the mark-up used to specify LaTeX columns. However, with the discussion above, I don't think it would be necessary.

How about mark-up such as the following:

<displaygroup>

    <figure width=50%>
    ....

    </figure>

    <table width=50%>
     ...
    </table>

</displaygroup>

and

<displaygroup>

    <p width=50% valign="middle">
    ....

    </p>

    <table width=50%>
     ...
    </table>

</displaygroup>

and

<displaygroup children="subfigure">

    <figure>
    ....

    </figure>

    <figure>
     ...

    </figure>

    <figure>
    ....

    </figure>

</displaygroup>

Thanks again; I'm curious to hear all thoughts and feedback and am excited to get this going :)

[Robert Beezer]

Dear Chris,

That all sounds very good.  I did not give a lot of thought to "displaygroup" so if you like something else, give it a try.

How about instead of "@type", you just wrap the group in a "figure" if that is what is needed?

<figure>
  <caption>A nice figure</caption>
  <displaygroup children="subfigure">
  ....
  </displaygroup>
</figure>

No need to reinvent (duplicate) code for wrapping "things" as figures, unless I am missing an implementation detail.  I see the value/need for "children" and I think that will work well.  This way you can get all three combinations easily:

figure, subfigure
figure, no subfigure
no figure, no subfigure
(four: no figure, with subfigure is wrong and maybe should get flagged with "xsl:message")

XSL should be able to look up from the "displaygroup" to see if there is an enclosing figure if the implementation requires that.  (I don't know the subfigure package.)

A lone "p" should be fine, but we will need to group multiple "p"'s somehow if they are a unit.  I think "paragraph" will work well as it allows an inline title, and it could be realized as a caption, I suppose (or a "caption" could be employed/recognized in this situation).

I really like David's suggestion of "sidebyside", even the name.  You could start with that and generalize, or maybe it is well worth implementing as a special case of  rows="1"  under the hood and away from view.

Thanks,
Rob

[David Farmer]

How would you do a 3 by 2 grid of figures, where each figure is
the graph of a hyperbolic trig function, each little graph has
a caption, and the whole group has a caption?

How about two graphs, one above the other, with a caption
"The top is the graph of y=f(x), and the bottom is the
graph of $y=f'(x)$."

I realize that the above are not examples of side-by-side,
but I think there are some principles that apply in both cases.

[Robert Beezer]

On Sunday, February 8, 2015 at 5:52:17 PM UTC-8, farmer wrote:

How would you do a 3 by 2 grid of figures, where each figure is
the graph of a hyperbolic trig function, each little graph has
a caption, and the whole group has a caption?

I'd go:

<figure>
    <caption>The Hyperbolic Functions</caption>
    <displaygroup rows="3" cols="2" children="subfigure">
        <figure>
            <caption><m>y=\cosh(x)</m></caption>
            <image source="cosh.svg" />
        </figure>        
        <figure>
            <caption><m>y=\sinh(x)</m></caption>
            <image source="sinh.svg" />
        </figure>        
        <figure>
            <caption><m>y=\tanh(x)</m></caption>
            <image source="tanh.svg" />
        </figure>        
        <figure>
            <caption><m>y=\sech(x)</m></caption>
            <image source="sech.svg" />
        </figure>        
        <figure>
            <caption><m>y=\csch(x)</m></caption>
            <image source="csch.svg" />
        </figure>        
        <figure>
            <caption><m>y=\coth(x)</m></caption>
            <image source="coth.svg" />
        </figure>
    </displaygroup>
</figure>

As written you'd get some nice (uniform) spacing.  Tweaks would be provided/allowed as percentages.

[Alex Jordan]

Just in case the inner wrapper ends up needing to stay, how about calling it a tile?

mathbook-xml-support+unsub...@googlegroups.com.

[David Farmer]

About floats:

There are (at least) two bad consequences of LaTeX's excessive use of
"floats" for figures.

First, no real book ever has a float. Graphics and tables are placed in
specific locations as chosen by the person doing the layout. Chris'
inclusion of TeXFloatOptions="!hbt" as a parameter makes sense for
the sake of completeness, but we want authors to put their images
and tables exactly where they want them to go. The default should be
"I really really mean that I want this exactly here". There can be an
option for the author to write float="!hbt" for a particular figure
or as a global option, if that is really their wish. (Note that there
is nothing specifically LaTeX about floats.)

What is the benefit of floats? They prevent large blocks of vertical
white space in the PDF version. If seeing that blank space in the
early drafts of your document causes you that much anguish, then go
ahead and use floats. But go back later and make a conscious choice
of where everything goes, rewriting or rearranging as necessary.
(Note: only do this at the end, because small local changes can have
global consequences on the layout.)

The second bad consequence is the impression that it is a good idea
to put a caption on every figure. Yes, if the figure is likely to
float away from its desired location then you need a caption. But
ideally the words and images work together to create a unified narrative.
(I don't claim that my own work is stellar, but that principle is
illustrated in the 3 page PDF in my earlier posting.)

I'll again recommend the master, Edward Tufte, who has written some
great books that merit careful study. His book "Beautiful Evidence"
is about how to integrate words and images on the page. The principles
apply whether the page is paper or web.

To tie this email to the current thread, let me suggest that we
need both <sidebyside> and <displaygroup>, even though it seems
like sidebyside is just a one-row displaygroup. One way they
could differ is that sidebyside is unambiguously part of the
current narrative, and it is impossible to float it. Also,
the defaults for centering and margins could be different, and reflect
the fact that sidebyside is likely to have different content in
its parts, while displaygroup is likely to just be a bunch of
images.

On Sun, 8 Feb 2015, Robert Beezer wrote:

> Let's try to imagine David's example without any div's.
>

> 1. Drop the "type" and let XSL discover it.
> 2. Left margin on outer level, rightmargin's on each item.
> 3. Repurpose "paragraph" environment to allow several paragraphs in text.
> 4. I've shown a title, which changes David's content, just for illustration.  Optional.
> 5. Dropped % on widths, margins (unsure about this one).

>
> <sidebyside leftmargin="0">
>    <paragraph width="31" valign="middle" rightmargin="29">
>       <title>First Step</title>
>       <p>Glue the top edge to the bottom to make a cylinder.</p>
>       <p>Maybe my text has a second paragaph, so we use "paragraph" enclosure.</p>
>       <p>Title is optional.</p>
>    </paragraph>
>    <image width="40" rightmargin="5">
>       [image source, description, etc, here]
>    </image>
> </sidebyside>
>
>
>
> On Sunday, February 8, 2015 at 10:36:20 AM UTC-8, farmer wrote:
> <sidebyside type="pi" leftmargin="0" rightmargin="5%">
>     <div width="31%" valign="middle">
>        <p>First glue the top edge to the bottom to make a cylinder.</p>
>     </div>
>     <div width="29%" />
>     <div width="40%">
>        [whatever markup is needed for that image]
>     </div>
> </sidebyside>
>

[Chris Hughes]

Thanks for all of the feedback, it's nice to see such interest in this.

It seems that floats in LaTex are quite a hot topic in this group! I don't want my feature to be dragged down by them, so for the moment, let's assume that this feature will inherit the same behaviour as the current figures and tables. 

My working version doesn't have rows and cols, but I'm happy to try to implement it. The working version allows per-figure captions and global over-arching captions. 

I'll get working on it, and try my best to incorporate all the suggestions here.

[Rob Beezer]

Well said.

The LaTeX "float" package add the "H" specifier, which means "HERE!" as in "I
really really mean that I want this exactly here". That is the currrent default
(and only possibility) in MBX's LaTeX output for tables and figures.

> To tie this email to the current thread, let me suggest that we
> need both <sidebyside> and <displaygroup>, even though it seems

I agree, for much the reasons you describe.

Rob