docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] Docutils docs as a single HTML or PDF?

[Guenter M. <mi...@us...>]

On 2019-09-01, Libor Jelinek wrote:
> Hello,
> before manually collecting all documents... How to read Docutils
> documentation as a single HTML or PDF that I will easily print, or save and
> read offline?

Unfortunately, there is no such meta file.

There were attempts to create a Sphinx version of the Docutils
documentation. This would provide for a cross-linked set of HTML
documents as well as a single PDF (via LaTeX). I don't know of a finished
such project, though.

Günter

Re: [Docutils-users] Writing Custom Directives, Expand Using Dynamic Data?

[Guenter M. <mi...@us...>]

On 2019-09-01, Kent Borg wrote:

> So, since that previous e-mail, I went off and, with some help, did what 
> I described, and we are very close to declaring Phase I a victory. Phase 
> II will be putting this to practical work.

> Let me give you a report on how things have gone:

...

> Building tables programmatically with ASCII art---um, no, correction: 
> utf-8 art!---

?? https://sourceforge.net/p/docutils/feature-requests/6/

> is a bit ugly. 
> And building tables by creating the right 
> doctree nodes directly is not exactly well documented. At the moment we 
> are doing some of each and we will need to rationalize that.

Did you try list tables or CSV tables? Depending on your needs these may
facilitate your task a lot.

http://docutils.sourceforge.net/docs/ref/rst/directives.html#tables

Günter

Re: [Docutils-users] Writing Custom Directives, Expand Using Dynamic Data?

[Kent B. <ken...@bo...>]

Hey, I got an answer! I didn't see it until now--this list does not have 
much traffic...

So, since that previous e-mail, I went off and, with some help, did what 
I described, and we are very close to declaring Phase I a victory. Phase 
II will be putting this to practical work.

Let me give you a report on how things have gone:

  * First looked at sample code in the docutils tree for how to process
    RST data programmaticly, from inside another Python program, and the
    resulting code has worked with few ongoing changes needed.

  * Have written quite a few custom directives. I am usually not a fan
    of being too object oriented, but with inheritance patterns I set up
    it is possible for me to create new custom directive for a new
    dynamically generated table in just a few lines of code. Or for a
    new dynamically generated graphic in just a few lines of code.

  * Have done a couple custom roles for cases where we needed syntax
    that could occur without breaking off into a new paragraph.

  * Pending nodes are our friends! We can drop them in the doctree as we
    go, then traverse them later, giving each a chance to convert itself
    into appropriate static data.

  * The API going into this code is roughly three calls:

     1. Instantiate the thing, passing in the name of a starting RST
        file (in other words, initialize a context for everything else
        that happens);
     2. Make a call asking what dynamic data is needed, passing in an
        initially empty dictionary, get back a list of missing data,
        fetch what is missing, update the dictionary, call
        again...repeat until there is no more missing data;
     3. With the now-complete dictionary of dynamic data make a render
        call, listing the needed output format(s), and get back the
        results, make more render calls on the same context if desired.

    The code on the RST side is kept completely ignorant of where the
    dynamic data actually comes from, and the code doing the data fetch
    is kept completely ignorant of all details of what RST looks like or
    might mean. This was important, not necessarily obvious it was
    needed, and not trivial to do.

  * Not everything can be done as a pending node, some things need to
    happen at parse time.

    This was a problem! We aren't changing RST syntax, we mostly have no
    gripes with what the parser does and had no interest in rewriting or
    otherwise messing with it, but when the parser hits one of our
    custom directives or custom roles and that code immediately needs
    some external data, there is no provision to communicate those needs
    up the call chain. So we go around the call chain: We run the parser
    as its own thread and when our code needs to communicate with the
    outside world it does so over a pair of Python queues, one for
    communicating out what dynamic data is needed, the other for getting
    back in the requested stuff. When it has what it needs, it acts
    accordingly, and the parsing continues per normal until some other
    directive or role needs additional data at parse time. This is
    admittedly a hack, but I think a reasonable one.

The state machine code that implements the three-call API, initializes 
things, fires up the second thread, etc., is not simple, but its 
responsibilities are otherwise very limited, so it has been stable for 
some time, we don't need to mess with it much. That file is less than 
500-lines long, and that's with a lot of comments. Not bad.

Building tables programmatically with ASCII art---um, no, correction: 
utf-8 art!---is a bit ugly. And building tables by creating the right 
doctree nodes directly is not exactly well documented. At the moment we 
are doing some of each and we will need to rationalize that.

We have a couple custom directives that we don't use from our RST files 
at all, rather they are instantiated programmatically by custom roles, 
to set up pending operations.

It all works pretty well. We are at the point that we /can/ get the code 
to do what we want (sometimes after some exploring when we want 
something new), now we mostly have to make sure it /does/ do what we 
want. We are dealing with content issues now, which was the whole point.

The hardest parts were two:

 1. Figuring what custom directives and roles would accomplish what we
    needed while still being sensible RST. There was a risk of inventing
    a whole new, completely obscure, domain-specific, programming
    language here. I needed to avoid that. Our source documents need to
    be something that normal people who know how to write, can write.
 2. Segregating concerns wherever we could, and keeping the
    implementation as architecturally clean as possible. I have left out
    a lot here, there are other system concerns that had to be accounted
    for yet still chased away and not allowed to creep into and
    complexify this into never working.

It is hard to make something simple. I think we have done a pretty 
decent job.


-kb

[Docutils-users] Docutils docs as a single HTML or PDF?

[Libor J. <lje...@vi...>]

Hello,
before manually collecting all documents... How to read Docutils
documentation as a single HTML or PDF that I will easily print, or save and
read offline?

Libor

Re: [Docutils-users] 0.15.1.post1 packaging/versioning problem

[engelbert g. <eng...@gm...>]

post is (in my understanding) if no code changed.

so an upgrade from -0.15.1 to 0.15.1.post1 would not be necessary

to a system (e.g. pip) would not read the "post" word but only count parts
in the version
0.15.1 is the same as 0.15.1-post1 and both are smaller than 0.15.1.post1

whl-packages of version 0.15.1.post1 have to be changed
if the "-" ist used (0.15.1-post1) then the whl-file can be simply renamed.

then i will pack 0.15.2 soon

On Fri, 26 Jul 2019 at 13:02, Guenter Milde via Docutils-users <
doc...@li...> wrote:

> On 2019-07-25, Andrew Jaffe wrote:
>
> > Hi,
>
> > There’s a problem with the latest release version — even if you install
> > the `post1` version, it doesn’t register and still shows a need to
> > upgrade. Happens with `pip`/`pip2`/`pip3`.
>
>
> > ~$ pip list --outdated
> > Package  Version Latest       Type
> > -------- ------- ------------ -----
> > docutils 0.15.1  0.15.1.post1 sdist
>
> > ~$ pip install --upgrade docutils
> > Collecting docutils
> > Installing collected packages: docutils
> >   Found existing installation: docutils 0.15.1
> >     Uninstalling docutils-0.15.1:
> >       Successfully uninstalled docutils-0.15.1
> > Successfully installed docutils-0.15.1
>
> > ~$ pip list --outdated
> > Package  Version Latest       Type
> > -------- ------- ------------ -----
> > docutils 0.15.1  0.15.1.post1 sdist
>
> I suppose this is because the tar archive should have been named
> "docutils-0.15.1.tar.gz" instead of docutils-0.15.1-post1.tar.gz
> (the post1 is only for sub-sub micro releases).
>


> To fix the version issues and the test failures reported by Dmitry,
> I suggest a 0.15.2 release with
>
> * docutils-0.15.2.tar.gz
> * docutils-0.15.2-py2-none-any.whl
> * docutils-0.15.2-py3-none-any.whl
>
> (even if no change to 0.15 is required for py3).
>
> Günter
>
>
>
> _______________________________________________
> 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] 0.15.1.post1 packaging/versioning problem

[Guenter M. <mi...@us...>]

On 2019-07-25, Andrew Jaffe wrote:

> Hi, 

> There’s a problem with the latest release version — even if you install
> the `post1` version, it doesn’t register and still shows a need to
> upgrade. Happens with `pip`/`pip2`/`pip3`.


> ~$ pip list --outdated 
> Package  Version Latest       Type 
> -------- ------- ------------ -----
> docutils 0.15.1  0.15.1.post1 sdist

> ~$ pip install --upgrade docutils
> Collecting docutils
> Installing collected packages: docutils
>   Found existing installation: docutils 0.15.1
>     Uninstalling docutils-0.15.1:
>       Successfully uninstalled docutils-0.15.1
> Successfully installed docutils-0.15.1

> ~$ pip list --outdated 
> Package  Version Latest       Type 
> -------- ------- ------------ -----
> docutils 0.15.1  0.15.1.post1 sdist

I suppose this is because the tar archive should have been named
"docutils-0.15.1.tar.gz" instead of docutils-0.15.1-post1.tar.gz
(the post1 is only for sub-sub micro releases).

To fix the version issues and the test failures reported by Dmitry,
I suggest a 0.15.2 release with 

* docutils-0.15.2.tar.gz
* docutils-0.15.2-py2-none-any.whl 
* docutils-0.15.2-py3-none-any.whl

(even if no change to 0.15 is required for py3).

Günter

[Docutils-users] 0.15.1.post1 packaging/versioning problem

[Andrew J. <a.h...@gm...>]

Hi, 

There’s a problem with the latest release version — even if you install the `post1` version, it doesn’t register and still shows a need to upgrade. Happens with `pip`/`pip2`/`pip3`.


~$ pip list --outdated 
Package  Version Latest       Type 
-------- ------- ------------ -----
docutils 0.15.1  0.15.1.post1 sdist

~$ pip install --upgrade docutils
Collecting docutils
Installing collected packages: docutils
  Found existing installation: docutils 0.15.1
    Uninstalling docutils-0.15.1:
      Successfully uninstalled docutils-0.15.1
Successfully installed docutils-0.15.1

~$ pip list --outdated 
Package  Version Latest       Type 
-------- ------- ------------ -----
docutils 0.15.1  0.15.1.post1 sdist

[Docutils-users] Release 0.15.1 for python2

[engelbert g. <eng...@gm...>]

Bugfix release for bugs #366 circular import.

Only necessary for python2

all the best

Re: [Docutils-users] [Doc-SIG] docutils release 0.15

[Roger G. <rga...@ga...>]

On 21 July 2019 10:39:58 BST, engelbert gruber <eng...@gm...> wrote:
>Note
> Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to
>3.5

Is there a problem with 3.6, 3.7 and 3.8 betas? Or is this an oversight in the announcement text



-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

[Docutils-users] docutils release 0.15

[engelbert g. <eng...@gm...>]

Note
   Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to
3.5

* reStructuredText:

  - Allow embedded colons in field list field names (before, tokens like
    ``:this:example:`` were considered ordinary text).

  - Fixed a bug with the "trim" options of the "unicode" directive.

* languages: Added Korean (ko) mappings and latin.

* Several fixes to keep mor information on source in parsed elements,
  isolate documents roles from other documents parsed, smartquotes,
  table gets width and latex table multicolumn cells, ...

all the best
 engelbert

Re: [Docutils-users] Writing Custom Directives, Expand Using Dynamic Data?

[Guenter M. <mi...@us...>]

Dear Kent,

On 2019-05-22, Kent Borg wrote:
> Hello,

> I am looking at using reStructuredText in the following custom way:

>   - Write documents using conventional rst for static data,

>   - And define my own custom directives and roles for dynamic data,

>   - Programmatically process my hybrid static/dynamic documents, 
> substituting/expanding my custom directives into static data,

>   - Likely write my own "writer"--or two or three--for custom output 
> formats, though that will come later.

> I don't see a lot of documentation on this kind of work. Looking about I 
> made it as far as core.publish_programmatically() and that looks 
> promising, plus the documentation there says that if I think I want to 
> use this code I should ask on the list first.

> So, two questions:

> 1) And I crazy?

Ambitious.

Docutils is designed with this use-case in mind, so it is not too hard to
achieve. However, there is no user manual for this task, so you will need
to read and understand the source code.


> 2) How should I go about this?

I suggest starting with a custom `front end tool`__ that imports and
enhances the parser prior to the call to publish_cmdline().

__ http://docutils.sourceforge.net/docs/api/cmdline-tool.html

An example for this approach is http://docutils.sourceforge.net/sandbox/jensj/latex_math/tools/rst2latexmath.py
from the times Docutils did not have native math support.


* Get a general understanding of rST and Docutils.

* Look for examples in the sandbox or other extensions__.

  __ http://docutils.sourceforge.net/docs/user/links.html#extensions


* Look for examples for directives and roles in docutils/parsers/rst/

* Eventually study examples for "transforms" (working on the generated
  document tree Python object) in docutils/transforms


Start with a simple example and come back to the list if there are
specific questions.

Good luck,

Günter

Re: [Docutils-users] width vs csv-table

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

Apologies, I shd have updated before reporting.  It's fixed in latest Subversion (8256).
(Unfortunately I did not check the revision I was updating from so I cannot report that.)

Alan


On 6/11/2019 3:44 AM, Guenter Milde via Docutils-users wrote:
> On 2019-06-10, Alan Isaac wrote:
>> If I understand the documentation, the following should work::
> 
>>     .. csv-table:: Test
>>        :width: 50%
> 
>>        test01
>>        test02
> 
>> The html5 write produces no content for this.
>> If I remove the `width` specification, the output is as expected.
> 
> I cannot reproduce. Here, with
> `rst2html5 --link-stylesheet example.txt` I get the expected:
> 
> <!DOCTYPE html>
> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
> <head>
> <meta charset="utf-8"/>
> <meta name="generator" content="Docutils 0.15b.dev: http://docutils.sourceforge.net/" />
> <title>widetable.rst</title>
> <link rel="stylesheet" href="<path-to>/docutils/writers/html5_polyglot/minimal.css" type="text/css" />
> <link rel="stylesheet" href="<path-to>/docutils/writers/html5_polyglot/plain.css" type="text/css" />
> </head>
> <body>
> <div class="document">
> 
> 
> <table style="width: 50%">
> <caption>Test</caption>
> <colgroup>
> <col style="width: 100%" />
> </colgroup>
> <tbody>
> <tr><td><p>test01</p></td>
> </tr>
> <tr><td><p>test02</p></td>
> </tr>
> </tbody>
> </table>
> </div>
> </body>
> </html>
> 
> 
> Günter
> 
> 
> 
> _______________________________________________
> 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] width vs csv-table

[Guenter M. <mi...@us...>]

On 2019-06-10, Alan Isaac wrote:
> If I understand the documentation, the following should work::

>    .. csv-table:: Test
>       :width: 50%

>       test01
>       test02

> The html5 write produces no content for this.
> If I remove the `width` specification, the output is as expected.

I cannot reproduce. Here, with
`rst2html5 --link-stylesheet example.txt` I get the expected:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="utf-8"/>
<meta name="generator" content="Docutils 0.15b.dev: http://docutils.sourceforge.net/" />
<title>widetable.rst</title>
<link rel="stylesheet" href="<path-to>/docutils/writers/html5_polyglot/minimal.css" type="text/css" />
<link rel="stylesheet" href="<path-to>/docutils/writers/html5_polyglot/plain.css" type="text/css" />
</head>
<body>
<div class="document">


<table style="width: 50%">
<caption>Test</caption>
<colgroup>
<col style="width: 100%" />
</colgroup>
<tbody>
<tr><td><p>test01</p></td>
</tr>
<tr><td><p>test02</p></td>
</tr>
</tbody>
</table>
</div>
</body>
</html>


Günter 

Re: [Docutils-users] transition inside container

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

Transitions are structural elements, along with sections & sidebars.
Containers are body elements, which cannot contain structural
elements. See docs/ref/docutils.dtd for complete technical details.

You could simulate a transition with an empty paragraph (escaped space: "\ ").

Compared to Docutils, HTML has a much more permissive, anything-goes,
way-too-loose document model.

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

On Mon, 10 Jun 2019 at 12:26, Alan Isaac <ala...@gm...> wrote:
>
> I want to indicate a thematic transition inside a containter.
>
> It seems that transitions (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#transitions)
> are not allowed inside containers.  Why is that?  (E.g., an HR element can certainly go inside a DIV element
> in an HTML document.)
>
> Thank you,
> 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] width vs csv-table

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

If I understand the documentation, the following should work::

   .. csv-table:: Test
      :width: 50%

      test01
      test02

The html5 write produces no content for this.
If I remove the `width` specification, the output is as expected.

Alan Isaac

[Docutils-users] transition inside container

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

I want to indicate a thematic transition inside a containter.

It seems that transitions (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#transitions)
are not allowed inside containers.  Why is that?  (E.g., an HR element can certainly go inside a DIV element
in an HTML document.)

Thank you,
Alan Isaac

[Docutils-users] Writing Custom Directives, Expand Using Dynamic Data?

[Kent B. <ken...@bo...>]

Hello,

I am looking at using reStructuredText in the following custom way:

  - Write documents using conventional rst for static data,

  - And define my own custom directives and roles for dynamic data,

  - Programmatically process my hybrid static/dynamic documents, 
substituting/expanding my custom directives into static data,

  - Likely write my own "writer"--or two or three--for custom output 
formats, though that will come later.

I don't see a lot of documentation on this kind of work. Looking about I 
made it as far as core.publish_programmatically() and that looks 
promising, plus the documentation there says that if I think I want to 
use this code I should ask on the list first.

So, two questions:

1) And I crazy?

2) How should I go about this?


Thanks,

-kb

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

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

[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...>]

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...>]

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'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] query about admonition classes convention

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

I am wondering why "admonition" is prepended to the title
for the class attribute, given that "admonition" is one
of the classes.  If this is to accommodate another write,
shouldn't that be handled by a multiple-class to single
identifier convention?

Also, has the current convention always applied?
It took me by surprise, possibly due to forgetfulness.

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.