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: 1Thread Previous | Thread Next