[Python-modules-team] Bug#953686: Add support for list-table :widths: and :header-rows: to rst2html?

[Dmitry Shachnev]

On Wed, Jun 03, 2020 at 07:45:06AM +0200, Petter Reinholdtsen wrote:
> [Dmitry Shachnev]
> > I think the problem here is the indentation. The example in documentation [1]
> > has the same indent level for directive options and for the content.
>
> Aha.  But as far as I can tell from the specification in 
> <URL: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists >
> and
> <URL: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives >
> there is no requirement on how much indentation is used for directive
> options, but perhaps I am reading it wrong.  Do you know why the
> rst2html tool believe there is, while pandoc and xmlto do not?  Perhaps
> they all should be made to agree on the syntax...

The specification also says [1]:

| Several constructs begin with a marker, and the body of the construct
| **must** be indented relative to the marker.

(emphasis mine)

| For constructs using simple markers (bullet lists, enumerated lists,
| footnotes, citations, hyperlink targets, directives, and comments), the
| level of indentation of the body is determined by the position of the
| first line of text, which begins on the same line as the marker.

If I read it correctly, this means that if your directive starts with
".. list-table::", the content should be aligned under the "l" letter,
i.e. indented with three spaces.

The directives syntax section [2] also has the following diagram:

+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block                         |
        |                               |
        +-------------------------------+

which confirms my hypothesis. By chance, your table indented with two spaces
does not cause syntax errors, but you should not rely on that.

In any case, docutils/rst2html is the reference implementation, so I would
say a valid markup is markup that is correctly parsed by docutils.

Please close this bug if you agree with me.

[1]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#indentation
[2]: https://docutils.sourceforge.io/docs/ref/rst/directives.html

--
Dmitry Shachnev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://alioth-lists.debian.net/pipermail/python-modules-team/attachments/20200603/366a5f19/attachment.sig>