Front page | perl.perl5.porters |
Postings from July 2022
On Fri, 15 Jul 2022 17:13:25 +0100
"Paul \"LeoNerd\" Evans" <leonerd@leonerd.org.uk> 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
unix-likes.
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)
SYNOPSIS
A test of tables in manpages
TABLES
Basic
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
Boxed
This table should have a box around the outside and also
between all the cells
_______
| a| b|
|__|___|
| c| d|
|__|___|
| e| f|
|__|___|
Formatted
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
AUTHOR
Paul "LeoNerd" Evans
SunOS 5.10 Last change: 1
Thread Previous
|
Thread Next