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

Re: Pre-RFC: tables in Pod

Thread Previous | Thread Next
Tomasz Konojacki
July 15, 2022 19:47
Re: Pre-RFC: tables in Pod
Message ID:
On Fri, 15 Jul 2022 17:13:25 +0100
"Paul \"LeoNerd\" Evans" <> wrote:

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

To be honest, I got burned out on this because my feeling was that PSC
isn't interested in this feature, as evidenced by bizarre arguments
against it such as "only 0.09% CPAN distributions are using a feature
that isn't officially supported, doesn't fully work and isn't even
really documented".

> 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
>   HTML
>   Markdown
>   Manpages (i.e. nroff)
>   PDF
>   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 only Pod to PDF processor I'm aware of is Pod::Pdf, which had the
last release in 2000 and I doubt it's being widely used. 

> 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,

There isn't one Markdown, so Pod to Markdown translator would need an
option to specify the desired flavour. I image most people are
interested in GitHub Markdown. Also, falling back to plain-text tables
is always an option.

> 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 two most popular manpage renderers are groff (usually on Linux) and
mandoc (BSDs). groff always comes with the tbl preprocessor and
automatically invokes it when needed, whereas in mandoc support for tbl
directives is built-in. That pretty much covers all the modern

On most legacy unixes it will be probably necessary to manually
preprocess the output with tbl. For example, on an old version of
Solaris 10:

$ tbl man1/a.1 > man1/b.1
$ man -M . b
Reformatting page.  Please Wait... done
Misc. Reference Manual Pages                     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 cells.
     Headings                           Here
     ^-- enboldened             headings --^
     Cells can also   contain formatted text
     Paul "LeoNerd" Evans
SunOS 5.10                Last change:                          1

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