Pandoc: Option to use list-tables in rST writer.

[NickVolynkin]

It would be great if pandoc could write list-tables instead of the usual grid-like tables.

The grid-like rST tables have several faults that list-tables do not have:

• Hard to add formatted content, such as code blocks.
• Hard to edit, as you have to keep all the 'border' characters on their places.
• Hard to swap content between cells in a row. Well, unless you have mastered an editor with block operations.

I've searched through pandoc -h, tests and source code but could not find anything related. If there's a filter that can do it, please drop a link. 😄

[qingpeng]

This will be very helpful!

[danse]

how do you imagine the user interface for this? an extension for the writer?

[NickVolynkin]

@danse maybe as a command line option for the writer:

pandoc -f html -t rst --list-tables test.html -o result.rst

Although, in my opinion the list-table syntax is so much better than the grid-table, that is should be the default option. I've added a bug report that can be solved by switching to list-tables.

[jgm]

A global option like that works if you want all the tables to be
list-tables. But I can imagine someone preferring grid tables
for readability in simple cases, but wanting list tables for
some special cases.

@danse maybe as a command line option for the writer:

pandoc -f html -t rst --list-tables test.html -o result.rst

[NickVolynkin]

@jgm in my company it's a question of documentation style guide. We have to choose one syntax option and stick to it. We chose list-tables for many reasons.

Same with headers: rST allows using any character for any header level, but when you see a header, you should know the level without reading the whole document. So we chose =-~^, just like in Pandoc.

Indeed, people may want to use both styles. Maybe the answer is to use grid-tables in simple cases and switch to list-tables if table contains lists, code blocks, URL's, long words or any other complex things. Then a global option could be used to enforce always using one of the syntaxes. I can help with gathering a set of examples of such things.

Another option could be to mark tables with special classes in native representation. Then someone using Pandoc to write rST would implement their own logic to make a decision about each table, then add a marker class and pass the sources to Pandoc.

[danse]

honestly i am curious about the motivations you mention in favour of
list-tables. we did stumble upon some problems with complex content in grid
tables, and the solution we adopted is to apply --wrap none to tables,
which leads to documents that are less readable.

if list tables prove to be a better solution also for my team, i could
start working on the code for rendering them while we refine ideas about
the interface.

if you think that there is a criteria pandoc could apply, like the presence
of a style in cell contents, then your examples are definitely helpful to
design this automation better.

if i understand correctly, we don't know how to enable the users to specify
the rendering style by table. i'd say that having a writer option would
already be an improvement in pandoc. that could be a first step while we
discuss further.

On 11 May 2018 at 06:45, Nick Volynkin [e-mail] wrote:

@jgm https://github.com/jgm in my company it's a question of
documentation style guide. We have to choose one syntax option and stick to
it. We chose list-tables for many reasons.

Same with headers: rST allows using any character for any header level,
but when you see a header, you should know the level without reading the
whole document. So we chose =-~^, just like in Pandoc
https://github.com/jgm/pandoc/blob/8b01f03eaa0c73259ed7a6d73c649cac65edcddc/src/Text/Pandoc/Writers/RST.hs#L252
.

Indeed, people may want to use both styles. Maybe the answer is to use
grid-tables in simple cases and switch to list-tables if table contains
lists, code blocks, URL's, long words or any other complex things. Then a
global option could be used to enforce always using one of the syntaxes. I
can help with gathering a set of examples of such things.

Another option could be to mark tables with special classes in native
representation. Then someone using Pandoc to write rST would implement
their own logic to make a decision about each table, then add a marker
class and pass the sources to Pandoc.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/jgm/pandoc/issues/4564#issuecomment-388258308, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AA2Er_BMBIIjDwW5-Lx81GOFqm40JQNyks5txRdagaJpZM4TbWQl
.

[NickVolynkin]

honestly i am curious about the motivations you mention in favour of list-tables.

@danse First, some insight into how I'm using Pandoc. We have lots of documentation in a legacy authoring system. Tens of guides, many languages. All these docs will be converted from HTML to rST/Sphinx projects. New sources should be consisent in style and syntax, because we will update and improve them a lot. So we've defined a single true way for doing anything that has more than one option. For tables we chose the list-table syntax. Here's why:

• List-tables have familiar syntax. A list-table is almost the same as a nested list in rST or Markdown, but with a .. list-table:: directive added. Having experience with YAML also helps work with list-tables.
• List-tables have the stub-columns and header-rows parameters that grid-tables don't. Sometimes we have tables with several header rows.
• It's much easier to edit list-tables. Adding, moving and deleting rows and cells is basically just copying and pasting blocks of lines. To add formatted content from elsewhere you just paste and indent it.
• In grid-tables, on the contrary, you have to block-select text all the time. Any time you add a single character, you have to remove one or several spaces to keep table "walls" in place. That's a lot of extra meaningless work to do.
• On the other hand, small grid-tables with plain text are easier to read in source code. Maybe they are better in code comments that go to autogenerated docs.
• Also, there are csv-tables. Can't contain any complex formatting, but perfect for showing program-generated content. If I'll ever have to show test results or performance metrics in Sphinx, I'll use csv-tables.

[danse]

Thanks, that seems to be plenty of reasons. The rST documentation about list tables is very concise so it's not clear to me how to structure a list table containing nested markup like in the case of code with long lines. Does anybody have an example of a complex list table? It would help to assess how this option would affect the users

[NickVolynkin]

@danse here's an example of a list-table with paragraphs, block and inline code from our docs.

[danse]

This test derived from your complex table example succeeds with the code in that branch. While i'm working on improvements i could use some directions from the future users of this feature.

Indentation levels are chosen in order to follow those currently used for bullet lists, in order to reuse the code. Do we have any good reason to do differently?

It is not clear to me how to precisely find the options supported by a directive. Looking at the docutils code it seems like the supported options are name, class, widths, stub-columns and header-rows. Here is the doc about class and name.

I assume that widths are the desired widths ... with sizes expressed in proportions of the column width of the document? I assume that header-rows is just an integer specifying how many of the rows are headers, and in the case of pandoc documents i think that this number can either be 0 or 1. I am not sure about stub-columns.

Any pointer to better doc is appreciated, if i won't find anything better i could look at the docutils code. Currently i think that i will produce header-rows (0 or 1) and widths when the case. Please let me know in case i forgot anything that could be important

[danse]

This might be too technical for some readers but it makes sense to write it here: in the RST writer i see that class and name are written for elements that have Attr in their native representation. Table does not have Attr so i would not add class and name

[danse]

alright, pull request #4780 is finally adding this feature :slightly_smiling_face:

[petterreinholdtsen]

Hi. I have a national standard document I would like to convert to RST with list-table. Is there any hope to have an official pandoc version with this support? I tried unsuccessfully to build the code from the above mentioned pull request, without success (some version skew, not sure what was wrong), and thus hope an official pandoc version will be released with thus support, so I can pick it up via Debian. :)

[jgm]

The main thing blocking this is figuring out a good way to trigger the table style. I'd prefer not to have a command-line option that just affects rst rendering, and affects it globally. Better to be able to mark up tables individually. However, currently, there's no way to put attributes on tables. This should change soon, hopefully, and then we'll have a way to

mark tables with special classes in native representation

[petterreinholdtsen]

[John MacFarlane]

The main thing blocking this is figuring out a good way to trigger the
table style. I'd prefer not to have a command-line option that just
affects rst rendering, and affects it globally. Better to be able to
mark up tables individually. However, currently, there's no way to put
attributes on tables. This should change soon, hopefully, and then
we'll have a way to

For my use case, one time conversion for future maintenance using RST, a
global flag work just fine. :)

--
Happy hacking
Petter Reinholdtsen

[tpatnoe]

I too would love to see this feature. The only solution I have now is to also install rstdoc with pip install rstdoc and use the rstlisttable after converting to RST with pandoc.