Bug#953686: Add support for list-table :widths: and :header-rows: to rst2html?

[Petter Reinholdtsen]

Package: python3-docutils
Version: 0.14+dfsg-4

The rst2html tool in python3-docutils do not handle list-table the same
pandoc and xmlto, spesifically it do not understand the :widths: and
:header-rows: statements. I found the format documented in
<URL: https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html >,
and the PDFs I generate look good using these statements, but the HTML
edition generated by rst2html do not.

Here is an RST example:

.. list-table:: **Overordnede krav til arkivstrukturen**
:widths: 1 8 1 4
:header-rows: 1

* - Krav nr.
- Overordnede krav til arkivstrukturen
- Type
- Merknad
* - 2.1.1
- For at en løsning skal kunne godkjennes etter Noark 5 må den
koseptuelle modellen av arkivstrukturen og de funksjonelle
mulighetene den gir, kunne implemenenteres i det aktuelle
systemets (fysiske) datastrukturer.
- O
- Innebærer at det må implementeres slik at data skal kunne
presenteres og hentes ut på den måten.
* - 2.1.2
- Arkivdokumenter skal inngå i en arkivstruktur som minst
inneholder følgende arkivenheter:

*arkiv*, *arkivdel*, *registrering*, *dokumentbeskrivelse* og
*dokumentobjekt*.
- O
-

The generated HTML look like this:

<table border="1" class="docutils">
<caption><strong>Overordnede krav til arkivstrukturen</strong>
:widths: 1 8 1 4
:header-rows: 1</caption>
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr><td>Krav nr.</td>
<td>Overordnede krav til arkivstrukturen</td>
<td>Type</td>
<td>Merknad</td>
</tr>
[...]

I expected the widths to be different and the first line to be handled
as a header.
--
Happy hacking
Petter Reinholdtsen

[Dmitry Shachnev]

Hi Petter!

> [...]
>
> I expected the widths to be different and the first line to be handled
> as a header.

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.

If you indent the table content by one more space, then it works fine:

.. list-table:: **Overordnede krav til arkivstrukturen**
:widths: 1 8 1 4
:header-rows: 1

* - Krav nr.
- Overordnede krav til arkivstrukturen
- Type
- Merknad
* - 2.1.1
- For at en løsning skal kunne godkjennes etter Noark 5 må den
koseptuelle modellen av arkivstrukturen og de funksjonelle
mulighetene den gir, kunne implemenenteres i det aktuelle
systemets (fysiske) datastrukturer.
- O
- Innebærer at det må implementeres slik at data skal kunne
presenteres og hentes ut på den måten.

[...]

[1]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table

--
Dmitry Shachnev

[Petter Reinholdtsen]

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

Anyway, thank you very much for the idea for a workaround.

[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

[Petter Reinholdtsen]

Thank you, Dmitry Shachnev, for the very useful input. Sorry I did not
notice it before now, but it will apply directly to the problem at hand,
which we track in
<URL: https://github.com/arkivverket/noark5-standard/issues/101 >.