develooper Front page | perl.perl5.porters | Postings from July 2022

Re: Pre-RFC: tables in Pod

Thread Previous | Thread Next
Paul "LeoNerd" Evans
July 15, 2022 16:13
Re: Pre-RFC: tables in Pod
Message ID:
** TL;DR: All: Please test the attached nroff file to see if it
**   correctly renders tables on your obscure systems.

On Tue, 16 Nov 2021 02:42:02 +0100
Tomasz Konojacki <> wrote:

> Tables are one of the most frequently requested features for Pod. 

This thread has stalled a bit, but we keep mentioning it at the PSC
meetings so now's a good opportunity to resurrect it a bit.

The overall feeling is that while we're not *opposed* to the idea of
table support in Pod, it seems there isn't a huge amount of forward
momentum so far. Beyond defining the formatting spec of what it should
look like in the Pod itself, there needs to be support by the actual
processors to output it.

And here's where it may become a problem. Of the various core-shipped
or easily-available processors, there are converters to

  Manpages (i.e. nroff)
  Plain text

and probably several others. If we're going to declare tables-in-POD as
a supported feature, it must perform reasonably well in all of these
outputs at least.

Of these, only HTML natively has its own concept of "tables" that can
be used. PDF rendering can presumably put text in a tabular layout and
draw some gridlines. Plaintext can just do its own thing (with Unicode
linedrawing if necessary).

The two problematic ones are Markdown and nroff. Neither of these
formats *technically* support tables, though both have fairly common
extensions to basically add the idea.

Perhaps other people can comment about Markdown, but here I'd like to
draw attention to nroff. Since many people's main interaction with Pod
embedded in Perl modules is via the `man` command, if nroff (i.e. the
rendering engine behind `man`) can't be relied on to cope with tables,
then realistically there isn't much point in us supporting them in Pod.

I don't know how prevalent actual support for tbl macros is across
nroff systems - for this I need everyone else's help.

The attached file contains tbl-extended nroff markup, which hopefully
should render in some text-like form. Please test if it does so; if
successful it should look something like the following:

$ man ./test-tables.1 | cat
TEST TABLES(1ex)                                       TEST TABLES(1ex)

       A test of tables in manpages

       Basic use of the .TS macro showing column alignment

           Left         Centre          Right
       This column    This column     This column
       should be       should be        should be
       left-aligned     centred     right-aligned

       This  table  should  have a box around the outside and also
       between all the cells

       │a │ b │
       │c │ d │
       │e │ f │
       Cell contents can be formatted; either by default applied to the
       whole cell, or by using the usual font selection escapes inside

       Headings                           Here
       ^-- enboldened             headings --^
       Cells can also   contain formatted text

       Paul "LeoNerd" Evans

Please everyone, go test that on a variety of obscure systems and report
back what does/doesn't work. If this all works fine on a variety of
different systems then maybe we have a chance at moving this forward.
If most nroff systems (as used by `man`) don't handle tables, then
realistically I don't see a point in us adopting it.


Paul "LeoNerd" Evans      |  |

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About