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: ```bash 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 ***@***.***> 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 <#4564 (comment)>, 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 🙂

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

[danse]

I haven't been working on pandoc in years and i'm definitely out of training, anyway this is a relatively simple update of an existing patch so here is the new pull request

[BaardBouvet]

I tried the patch, and from what I can tell it produced RST that Pandoc is not able to read back in:

$ cat test.rst 
.. list-table::
  :widths: 50 50
  :header-rows: 1

  * - Left
    - Right
  * - Second
    - row
$ pandoc test.rst --list-table -t rst | ~/.local/bin/pandoc -f rst -t native
[Table ("",[],[]) (Caption Nothing
 [])
 []
 (TableHead ("",[],[])
 [])
 [(TableBody ("",[],[]) (RowHeadColumns 0)
  []
  [Row ("",[],[])
   []])]
 (TableFoot ("",[],[])
 [])]

The format that is output-ed by this patch is:

.. list-table::
   :widths: 36 36
   :header-rows: 1

   - 

      - Left
      - Right
   - 

      - Second
      - row

[petterreinholdtsen]

[Baard H. Rehn Johansen]

I tried the patch, and from what I can tell it produced RST that Pandoc is not able to read back in:

As far as I can tell, not being an RST expert, the input and output seem to be equivalent. At least any :widths with two identical numbers would work the same way, so "1 1", "50 50" and "36 36" are all the same. And the list in list seem to be equivalent too. What specific do you see that is not understood correctly?

…

-- Happy hacking Petter Reinholdtsen

[jgm]

We could easily change the patch to produce the more compact list output (which seems desirable to me).

[BaardBouvet]

[Baard H. Rehn Johansen]
I tried the patch, and from what I can tell it produced RST that Pandoc is not able to read back in:
As far as I can tell, not being an RST expert, the input and output seem to be equivalent. At least any :widths with two identical numbers would work the same way, so "1 1", "50 50" and "36 36" are all the same. And the list in list seem to be equivalent too. What specific do you see that is not understood correctly?
…
-- Happy hacking Petter Reinholdtsen

The native output after parsing doesn't contain any of the text in the input, it's just a blank table. So the format output-ed by the patch is not parsed correctly by pandoc. I'm not an RST guru, so not sure if the output of the patch is wrong or if the RST reader in pandoc is broken (I suspect the latter).

[jgm]

If this reveals a problem with pandoc's RST list parsing, then you might open a new issue for that, using as simple an example as possible (regular list, not list table).

[brogersadobe]

Just to add support to this need: Here at Adobe our rst/sphinx docs use list tables 100% of the time. Pandoc's grid table output is very time consuming to work with. Keep up the good work.

[danse]

hopefully i will get some time to work on this in the next weeks, but i am still blocked by this #4564 (comment) about the feature's design.

personally if i had to convert many documents, the idea of marking every table would sound tedious to me, but i am willing to follow users' consensus and look for another way, since i agree that having a global option is not ideal either. Is it now possible to add attributes to tables, or should this still wait a bit?

[jgm]

Yes, Tables can have attributes added to them now -- in the AST. But many input formats (including Markdown) still don't have a way to add attributes directly to a table.

[jgm]

It would be good to know, from those who use list tables, whether they have a need to have documents containing some list and some non-list tables.

[danse]

I created a new pull request including the required changes. As discussed, a filter will be required in order to render all tables in a document as list tables.

A filter instance is attached here, along with a test.native file you can use to test the filter, just rename the files removing the final .txt extensions that are needed to upload on github. Once you have made the filter executable as described in the docs, you will be able to run pandoc with the filter and get the following output:

$ pandoc test.native -t rst --filter list-tables.hs
   .. list-table::
      :widths: 11 10 12 27
      :header-rows: 1

      - 

         - Centered Header
         - Left Aligned
         - Right Aligned
         - Default aligned
      - 

         - First
         - row
         - 12.0
         - Example of a row that spans multiple lines.
      - 

         - Second
         - row
         - 5.0
         - Here’s another one. Note the blank line between rows.

list-tables.hs.txt
test.native.txt