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

Re: Pre-RFC: tables in Pod

Thread Previous | Thread Next
From:
Neil Bowers
Date:
June 20, 2022 18:22
Subject:
Re: Pre-RFC: tables in Pod
Message ID:
36fcc925-21cc-43d8-8e19-22c1b44b1e21@Spark
> Despite being poorly documented and not working in non-HTML renderers,
> plenty of distributions use the "=begin HTML" hack for tables

I found 42 distributions, which represents 0.09% of CPAN distributions.
Some of them aren’t using tables to present tabular data (for example Image::CairoSVG uses it to format captions below images: https://metacpan.org/pod/Image::CairoSVG#BUGS)

Roughly a quarter of those I classified as abuses of tables. For example https://metacpan.org/pod/Devel::PDB

But at least half of them are things best presented as tables.

If table formatting were provided in pod, then we’d want a decent percentage of people to change over to using pod tables. If they look at pod tables and decide to stick with HTML tables, then what’s the point?


> Competing markup formats often include tables. Vanilla Markdown
> doesn't have tables, but there are countless extensions that add them.
> That indicates it's a pretty popular feature.

For general document formatting systems, tables are a necessity. I’m a big fan of tables – I maintain one of the CPAN modules for rendering text tables.

I’m concerned that getting tables "right" across all the ways and places pod is rendered is non trivial, and that it won’t be widely used, and will also be abused.


I asked:
>> Would cell contents be auto wrapped, or would every cell be treated as nowrap?
You replied:
> I think that should be left to the renderer.

I disagree. This would leave people unsure as to what they can put in tables, and whether they can expect them to come out right.

If this progresses further, I think we should enumerate the different ways/places that people look at pod, and how tables are expected to work/render in each of those places. E.g. perldoc, metacpan, perldoc.org, man, and ... ?


Neil

Thread Previous | 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