rST writer: add option for list tables, closes #4564

[danse]

I moved some code from the body of blockToRST to a gridTableRST function which exposes the same interface as listTable.

I wrote mapTable and joinTable thinking that they could end up to the Shared module some day. They are straightforward but i think that using them makes the code more readable.

I also fixed the help string for the reference-links option.

[jgm]

This changes the public-facing API, and these changes should be carefully described. As a result of the API change, this PR would require at least a bump to 2.3.

[danse]

This is a non-breaking change, so according to the versioning policy it must affect only C in A.B.C, if i understand correctly.

When you say carefully described you mean a line for the changelog and the release notes, or a paragraph somewhere in the manual?

[danse]

Note that, differently from what is discussed in #4564, list tables are not the default option, here. I figured it's better to introduce it as a new option for now, it will be easy to change the default behaviour later if we will want to

[jgm]

Francesco Occhipinti <[email protected]> writes:

This is a non-breaking change, so according to the [versioning policy](https://pvp.haskell.org/) it must affect only C in A.B.C, if i understand correctly.

That's correct.

When you say _carefully described_ you mean a line for the changelog and the release notes, or a paragraph somewhere in the manual?

The commit message should precisely describe the API change and signal that it's an API change. That way I can put this in the changelog when it's time to do a release. The API isn't described in the manual, so no changes are needed there.

[danse]

i edited the commit message and force-pushed. while writing it occurred to me that, being an option that only involves one format, maybe it could be exposed as an extension in order not to pollute the space of global options. it could be used with -t rst+list-tables. i cannot assess the possibility of list tables to be adopted for other markup languages

[kaushalmodi]

@danse Seeing that you are tweaking the table option in RST writer, would you have time to implement exporting of simple_table too? (#4750)

Thanks!

[danse]

hi @kaushalmodi, the simple table syntax alternative doesn't seem to add much value in terms of maintainability in comparison with other styles, at least in my opinion. Anyway i will submit the idea to my team and check whether is there any interest, thanks

[kaushalmodi]

@danse As the original issue mentions, it adds value to my use case of converting Org mode documentation to RST format, which the Nim language doc generator requires (and the RST parser in Nim accepts only simple table syntax). Thanks for considering this request.

---

Update: Also, may be continue the conversation about simple tables in #4750 so that this thread doesn't get off-topic.

[jgm]

I like the idea of making this an extension. The main difficult I see is that, in this case, we'd want the extension to have different defaults for reading and writing, and that isn't currently possible. That is, the default should be to properly detect list tables when reading RST, but I don't think the default should be to emit list tables when writing RST. Perhaps it could be documented that the extension only affects the writer (and only RST and maybe muse). That would be a bit unusual, but we may already have other extensions like that. Francesco Occhipinti <[email protected]> writes:

…

i edited the commit message and force-pushed. while writing it occurred to me that, being an option that only involves one format, maybe it could be exposed as an extension in order not to pollute the space of global options. it could be used with `-t rst+list-tables`. i cannot assess the possibility of list tables to be adopted for other markup languages

[danse]

so if i understand correctly, extensions are expected to affect reading and writing. is there a place where we keep a glossary? it would be great for refining these concepts. about list tables, if they are one of the allowed syntaxes, then we want them to pass through the parser anyway. i guess that this principle applies to all readers

[kwshaw1]

Is this a functional solution yet? Can I get a version of Pandoc that generates list tables instead of grid tables when converting to RST?

[danse]

Hi @kwshaw1, this solution worked and was merged in this fork, which hasn't been updated in a while

[petterreinholdtsen]

I would love to see list-table write support in pandoc. Need it for a Norwegian national standard. Any hope to have support for it in an official pandoc version any time soon?

[krzychb]

@danse another happy pandoc user here 👍
Grid tables, especially when big and in big quantity are far less convenient to use than the list tables.
Adding to several good comments in #4564, unlike for the grid tables, I like the list tables for their flexibility when it comes to text translation and editing.
Our life will be even better having the list table support in pandoc ❤️
Thank you for this great conversion tool.

[danse]

Superseeded by a corresponding updated pull request