develooper Front page | perl.perl5.porters | Postings from November 2021

Pre-RFC: tables in Pod

Thread Next
From:
Tomasz Konojacki
Date:
November 16, 2021 01:42
Subject:
Pre-RFC: tables in Pod
Message ID:
20211116024159.2D63.5C4F47F8@xenu.pl
Tables are one of the most frequently requested features for Pod. 

There's some prior art in PseudoPod[1] and Pod6[2], but I dislike them
both. PseudoPod's table syntax is way too verbose, while Pod6 is too
complicated and whitespace sensitive.

I came up the following syntax:

=begin table

table specification

=end table

The table specification syntax is based on GitHub Markdown with some
extensions (most notably rowspan and colspan). Please read its
documentation first:

https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables

Using Pod formatting codes (e.g. B<foo>) is allowed inside tables.

Since this is just an elevator pitch, instead of writing a full
specification, I will just show a few examples:

------------------------------------------------------------------------

Basic table. Leading and terminating pipes are optional.

Input:

| foo | bar | baz |
| oof | rab | zab |

Output:

+-----------------+
| foo | bar | baz |
+-----------------+
| oof | rab | zab |
+------------------

------------------------------------------------------------------------

Table with headers. The "header2" column is right-aligned. In GitHub
headers are required, in this specification they will be optional (as
you've seen in the previous example).

Input:

| header1 | header2 | header3 |
| ---     | ---:    | ---     |
| abc     | def     | ghi     |

Output (it's hard to show in plain text, but the first row will be
rendered as <thead> in HTML):

+-----------------------------+
| header1 | header2 | header3 |
+-----------------------------+
| abc     |     def | ghi     |
+-----------------------------+

------------------------------------------------------------------------

"-" merges with the previous cell horizontally (cellspan); "^",
vertically (rowspan). They can be escaped with E<> or a backslash.
GitHub Markdown doesn't have this feature.

Input:

| foo | -   | baz |
| ^   | -   | zab |

Output:

+-----------------+
| foo       | baz |
+           +-----+
|           | zab |
+------------------

------------------------------------------------------------------------

[1] - https://metacpan.org/dist/Pod-PseudoPod/view/lib/Pod/PseudoPod/Tutorial.pod#Tables
[2] - https://docs.raku.org/language/tables

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About