docutils-users

[Docutils-users] table notes

[Alan G I. <ai...@am...>]

In academe, tables often include table notes.
Is there currently an accepted way to produce
table notes in reST?  If not, might a :note:
option (or equivalent) be added to tables?
(Multiple notes should be possible.)

Thank you,
Alan Isaac

[Docutils-users] table notes

[Alan I. <ala...@gm...>]

In published work, tables and figures often require
explanatory notes.

In rst there appears to be an odd difference in structure between
tables and figures.  A figure is understood to have three possible
types of content, and image, a caption, and what is called a "legend"
(which can hold explanatory notes).

A table does not do this, but it could.
Might this be considered as a possible enhancement?

Thanks, Alan Isaac

Re: [Docutils-users] table notes

[David G. <go...@py...>]

That's what the "table" directive is for:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#table

David Goodger
<https://david.goodger.org>

On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
>
> In published work, tables and figures often require
> explanatory notes.
>
> In rst there appears to be an odd difference in structure between
> tables and figures.  A figure is understood to have three possible
> types of content, and image, a caption, and what is called a "legend"
> (which can hold explanatory notes).
>
> A table does not do this, but it could.
> Might this be considered as a possible enhancement?
>
> Thanks, Alan Isaac
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] table notes

[Alan I. <ala...@gm...>]

I'm looking at the documentation at
http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
On my reading, it does not allow for the equivalent of the "legend"
content in a figure.  What am I overlooking?

Thanks, Alan Isaac


On 5/16/2019 4:37 PM, David Goodger wrote:
> That's what the "table" directive is for:
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> 
> David Goodger
> <https://david.goodger.org>
> 
> On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
>>
>> In published work, tables and figures often require
>> explanatory notes.
>>
>> In rst there appears to be an odd difference in structure between
>> tables and figures.  A figure is understood to have three possible
>> types of content, and image, a caption, and what is called a "legend"
>> (which can hold explanatory notes).
>>
>> A table does not do this, but it could.
>> Might this be considered as a possible enhancement?
>>
>> Thanks, Alan Isaac
>>
>>
>> _______________________________________________
>> Docutils-users mailing list
>> Doc...@li...
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>>
>> Please use "Reply All" to reply to the list.

Re: [Docutils-users] table notes

[David G. <go...@py...>]

The table directive as implemented doesn't allow for a legend, just a
title. I can't think of why a table would need a legend, and I've
never seen one in the wild.

Note: figures have captions (below), tables have titles (above).
They're not the same thing, and shouldn't be conflated.

David Goodger
<https://david.goodger.org>

On Thu, 16 May 2019 at 16:59, Alan Isaac <ala...@gm...> wrote:
>
> I'm looking at the documentation at
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> On my reading, it does not allow for the equivalent of the "legend"
> content in a figure.  What am I overlooking?
>
> Thanks, Alan Isaac
>
>
> On 5/16/2019 4:37 PM, David Goodger wrote:
> > That's what the "table" directive is for:
> > http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> >
> > David Goodger
> > <https://david.goodger.org>
> >
> > On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
> >>
> >> In published work, tables and figures often require
> >> explanatory notes.
> >>
> >> In rst there appears to be an odd difference in structure between
> >> tables and figures.  A figure is understood to have three possible
> >> types of content, and image, a caption, and what is called a "legend"
> >> (which can hold explanatory notes).
> >>
> >> A table does not do this, but it could.
> >> Might this be considered as a possible enhancement?
> >>
> >> Thanks, Alan Isaac
> >>
> >>
> >> _______________________________________________
> >> Docutils-users mailing list
> >> Doc...@li...
> >> https://lists.sourceforge.net/lists/listinfo/docutils-users
> >>
> >> Please use "Reply All" to reply to the list.
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] table notes

[Alan I. <ala...@gm...>]

I will try to keep it in mind when talking about reST,
but I find your distinction between titles and captions to be
unfamiliar.  E.g., the following usage is more familiar to me:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption

However, in this query my interest is (as in the Subject) how
to handle table notes.  My observation is that just as figures
allow figure notes (as part of the "legend" content), a table could
similarly allow table notes.  These are a *very* often needed feature
-- so much so, that tables without notes are often unacceptable.
I've attached an "in the wild" example.  My query is whether
docutils could consider accommodating such optional content
for tables, paralleling the feature in figures.

Cheers, Alan


On 5/16/2019 10:09 PM, David Goodger wrote:
> The table directive as implemented doesn't allow for a legend, just a
> title. I can't think of why a table would need a legend, and I've
> never seen one in the wild.
> 
> Note: figures have captions (below), tables have titles (above).
> They're not the same thing, and shouldn't be conflated.
> 
> David Goodger
> <https://david.goodger.org>
> 
> On Thu, 16 May 2019 at 16:59, Alan Isaac <ala...@gm...> wrote:
>>
>> I'm looking at the documentation at
>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
>> On my reading, it does not allow for the equivalent of the "legend"
>> content in a figure.  What am I overlooking?
>>
>> Thanks, Alan Isaac
>>
>>
>> On 5/16/2019 4:37 PM, David Goodger wrote:
>>> That's what the "table" directive is for:
>>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
>>>
>>> David Goodger
>>> <https://david.goodger.org>
>>>
>>> On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
>>>>
>>>> In published work, tables and figures often require
>>>> explanatory notes.
>>>>
>>>> In rst there appears to be an odd difference in structure between
>>>> tables and figures.  A figure is understood to have three possible
>>>> types of content, and image, a caption, and what is called a "legend"
>>>> (which can hold explanatory notes).
>>>>
>>>> A table does not do this, but it could.
>>>> Might this be considered as a possible enhancement?
>>>>
>>>> Thanks, Alan Isaac
>>>>
>>>>
>>>> _______________________________________________
>>>> Docutils-users mailing list
>>>> Doc...@li...
>>>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>>>>
>>>> Please use "Reply All" to reply to the list.
>>
>>
>>
>> _______________________________________________
>> Docutils-users mailing list
>> Doc...@li...
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>>
>> Please use "Reply All" to reply to the list.

Re: [Docutils-users] table notes

[David G. <go...@py...>]

My distinction between titles and captions comes straight from `The
Chicago Manual of Style`: tables have titles above, figures have
captions below. The HTML <caption> tag seems to be the result of
conflation, shown in the first link you provided:

    The HTML Table Caption element (<caption>) specifies the caption
(or title) of a table

For table notes, I suggest simply adding them into the table itself.
This can be done now.

It's *possible* that Docutils could accommodate "table notes" [1]_,
but it would require specification (e.g. are they repeated when a
table is broken across pages, like a header? are they always at the
bottom of tables, even very long ones? etc.) and, of course,
implementation. I personally remain unconvinced.

.. [1] But **not** a table legend; that still makes no sense to me.

David Goodger
<https://david.goodger.org>

On Fri, 17 May 2019 at 08:38, Alan Isaac <ala...@gm...> wrote:
>
> I will try to keep it in mind when talking about reST,
> but I find your distinction between titles and captions to be
> unfamiliar.  E.g., the following usage is more familiar to me:
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption
>
> However, in this query my interest is (as in the Subject) how
> to handle table notes.  My observation is that just as figures
> allow figure notes (as part of the "legend" content), a table could
> similarly allow table notes.  These are a *very* often needed feature
> -- so much so, that tables without notes are often unacceptable.
> I've attached an "in the wild" example.  My query is whether
> docutils could consider accommodating such optional content
> for tables, paralleling the feature in figures.
>
> Cheers, Alan
>
>
> On 5/16/2019 10:09 PM, David Goodger wrote:
> > The table directive as implemented doesn't allow for a legend, just a
> > title. I can't think of why a table would need a legend, and I've
> > never seen one in the wild.
> >
> > Note: figures have captions (below), tables have titles (above).
> > They're not the same thing, and shouldn't be conflated.
> >
> > David Goodger
> > <https://david.goodger.org>
> >
> > On Thu, 16 May 2019 at 16:59, Alan Isaac <ala...@gm...> wrote:
> >>
> >> I'm looking at the documentation at
> >> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> >> On my reading, it does not allow for the equivalent of the "legend"
> >> content in a figure.  What am I overlooking?
> >>
> >> Thanks, Alan Isaac
> >>
> >>
> >> On 5/16/2019 4:37 PM, David Goodger wrote:
> >>> That's what the "table" directive is for:
> >>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> >>>
> >>> David Goodger
> >>> <https://david.goodger.org>
> >>>
> >>> On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
> >>>>
> >>>> In published work, tables and figures often require
> >>>> explanatory notes.
> >>>>
> >>>> In rst there appears to be an odd difference in structure between
> >>>> tables and figures.  A figure is understood to have three possible
> >>>> types of content, and image, a caption, and what is called a "legend"
> >>>> (which can hold explanatory notes).
> >>>>
> >>>> A table does not do this, but it could.
> >>>> Might this be considered as a possible enhancement?
> >>>>
> >>>> Thanks, Alan Isaac
> >>>>
> >>>>
> >>>> _______________________________________________
> >>>> Docutils-users mailing list
> >>>> Doc...@li...
> >>>> https://lists.sourceforge.net/lists/listinfo/docutils-users
> >>>>
> >>>> Please use "Reply All" to reply to the list.
> >>
> >>
> >>
> >> _______________________________________________
> >> Docutils-users mailing list
> >> Doc...@li...
> >> https://lists.sourceforge.net/lists/listinfo/docutils-users
> >>
> >> Please use "Reply All" to reply to the list.
>

Re: [Docutils-users] table notes

[Alan I. <ala...@gm...>]

On 5/17/2019 10:49 AM, David Goodger wrote:
> .. [1] But **not** a table legend; that still makes no sense to me.


I was certainly not suggesting such a terminology.
My point is rather that what reST refers to as a
figure "legend" is in fact a rather multi-use
container.  In fact, I do not think I have ever
used it to hold a legend; instead, I use it to
hold figure notes.  I would hazard that my usage
is the most common, since legend information is
very often part of the figure (in one way or another).
Example attached (from Jones 2015).

That said, tables often contain meaningful markers
or colors, whose meaning needs to be explicated in
the notes.  (E.g., markers of statistical significance
levels.)  This is quite similar to a figure legend.

Alan

Re: [Docutils-users] table notes

[Alan I. <ala...@gm...>]

Thinking this through a bit more, I realize I have a more fundamental
design question.  As I struggle with the `table` directive, it seems
that it behaves quite a bit differently than I would like, and that
would I would find more useful would be something like the following:
a table directive that is basically a container with a class, except
that it accepts a title as an argument.

With this perspective, I would then like to be able to
add arbitrary content in the container.  One type of
content would be a normal reST table.  Another type
of content would be a `note` directive.  Etc.  This
gets closer to the idea that a "table" environment is
just a (usually numbered) environment that contains content
that should be kept together (e.g., tabular content,
source notes, other notes, etc).  This notion of a table
environment would be close to the LaTeX approach.

Additionally, from this perpsective, the `csv-table` directive
has conflated two things: the desire for a "table environment",
and the desire to input tabular data in a certain format.

Cheers, Alan