Front page | perl.perl5.porters |
Postings from November 2021
Re: Pre-RFC: markdown in pod
From: Oodler 577 via perl5-porters
November 30, 2021 04:15
Re: Pre-RFC: markdown in pod
Message ID: YaWlKFHkgghZbm8Y@odin.sdf-eu.org
* Ricardo Signes <firstname.lastname@example.org> [2021-11-29 21:06:07 -0500]:
> On Mon, Nov 29, 2021, at 12:49 PM, Oodler 577 wrote:
> > * Ricardo Signes <email@example.com> [2021-11-27 14:30:13 -0500]:
> >> But I will say that I think that by far the most tedious thing in Pod is lists, for which I provided myself with a solution in Pod::Elemental::Transformer::List <https://metacpan.org/pod/Pod::Elemental::Transformer::List>, which creates a "=begin :list" region or "=for :list" paragraph, which allows very compact notation for bulleted, definition, or ordered lists that uses Pod sequences instead of Markdown, and so remains very much like all other Pod. Adding support to that to Pod::Simple might be a fair bit simpler than Markdown... but I won't be the one to do it! ?????
> > What's your workflow for rendering this to POD, is it transformed in the source after you've written once (e.g., via an external tool or vim plugin), or does it remain in the source for downstream consumption?
> I use Dist::Zilla, which rewrites the quirky Pod from my git repository's source into standard Pod before building tarballs for the CPAN.
Thank you. Makes perfect sense using this workflow. It also solves the problem
of "where to keep the editable intermediate format".
FWIW (to all), after doing some more "research" on this issue and what's come
before (even looking at tables in *rof), I saw that the there is a necessary
separation between the content and the formatting - in most "early" cases I
saw this was referred to as "typesetting". We might think of it more as ren-
So short of doing *anything* with POD to support what's needed, the idea of
approaching this from a tools and workflow angle seems to be the most exped-
For example, it makes perfect sense to add some shorthand notation that is
meant for author convenience into Dist::Zilla (or similar tool) since it must
live in the precise part of the development workflow for this need. It's also
superior to the idea of having just a utility that can convert some table
syntax into a "neat" ascii table by passing it through an external command
in vim. This necessarily destroys the persistent value of any intermediate
The question then becomes, is Dist::Zilla a good candidate for managing pure
content + hints for tedius POD. This doesn't solve the issue of POD not being
able to handle things like:
* concise lists
It does, however, provide a spot in the workflow for authors to basically use
any means for managing their intermediate format (say on the git repo) into
a standard representation in the distribution of this module (via CPAN).
What this looks like, extending the "concise list" example, is that, e.g.:
* tables can be defined in some intermediate way, but the resulting distribut-
ed "POD" visible via "perldoc" would be a neat ASCII table contained in a
verbatim section. And this preformatted text would be "safe" in all places
the POD would appear.
I don't know what to say about images, but the complicating factors there are:
1. it's not reasonable to "show" pictures at the commandline nor is it a
good idea to carry images in CPAN distros
2. people might have different ideas of what should be shown in the terminal
versus a canonical way to allow the images to be rendered when looking at
the HTML version of the POD in a web browser (or exported to PDF or whatever).
Images are not something I care much about, but for the 2 cases that do seem
interesting and useful to me (lists and tables), this approach seems to be
a good one.
In summary, my overall point is that the way RJBS is handling concises lists
via Dist::Zilla and the workflow it admits is a good example of where any tool-
based solution of this would need to exist.
SDF-EU Public Access UNIX System - http://sdfeu.org
irc.perl.org #openmp #pdl #native