Front page | perl.perl5.porters |
Postings from November 2021
Re: Pre-RFC: markdown in pod
Thread Previous
|
Thread Next
From:
William Lindley
Date:
November 18, 2021 15:54
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
7dea3652-83af-7331-bad9-efebded5064b@wlindley.com
On 11/18/21 3:23 AM, Shlomi Fish wrote:
> Quoting my page at
> https://www.shlomifish.org/philosophy/computers/web/choice-of-docs-formats/ :
> Why the Markdown Dialects Should be Avoided as much as Possible [ #markdowns ]...
>
> So I am opposed for making one of the markdowns an integral part of POD. "Only
> dead fish go with the flow".
I agree it is better to partly solve known problems rather than create
new ones.
POD's strength lies in its being a self-contained all-text format,
easily viewable, editable, and maintainable with git or other version
control systems.
In contrast, inserting in-line hrefs to external resources is
problematic, not only because they cannot easily be viewed off-line, but
because there is no guarantee of synchronization between versions of the
documentation and the separate resource. External binary resources in
particular, even if meticulously mirrored, cannot easily be checked to
see what changed over time in a version-control system.
1. Images:
The problem of mixing images and diagrams with documentation were mostly
solved long ago, albeit in a somewhat different age, by NetPBM and by
troff-accompanying tools like pic or the modern pikchr.
NetPBM, http://netpbm.sourceforge.net/ , includes the definition of
image formats pbm, pgm, and ppm for binary, grayscale, and color images
stored in a plain text format (for these purposes we dismiss the 'raw'
binary varieties). Such images, though loquacious in their storage,
would be embedded directly into a POD file (perhaps as addenda),
satisfying the requirement to be self-contained, human-readable, and
easily trackable through git et al.
Pikchr (https://pikchr.org/home/doc/trunk/homepage.md) can produce
charts (such as bit-fields or Perl Reference pointers) and diagrams
(e.g., state, flow, or network communication protocol) in a pleasing
vector format easily comprehended on screen or paper, and whose
originals are maintainable in a text format; for example as in
https://metacpan.org/dist/perl/view/pod/perlreftut.pod#Solution the
"%table" diagram, in Pikchr, would be written:
move down 5mm
line 0mm "%table" above
B1: box "Germany" height 7mm width 2cm
box width 5mm height 7mm with .w at last box.e
dot at last box.center
arrow right
box "Frankfurt" fit with .w at last arrow.e
box "Berlin" fit with .w at last box.e
B2: box "Finland" height 7mm width 2cm with .n at B1.s
box width 5mm height 7mm with .w at last box.e
dot at last box.center
arrow right
box "Helsinki" fit with .w at last arrow.e
B3: box "USA" height 7mm width 2cm with .n at B2.s
box width 5mm height 7mm with .w at last box.e
dot at last box.center
arrow right
box "Chicago" fit with .w at last arrow.e
box "Washington" fit with .w at last box.e
box "New York" fit with .w at last box.e
You may see the end result, as SVG or PNG, by pasting the above at
https://pikchr.org/home/pikchrshow
Regrettably that does not produce ASCII style output, but Emacs at least
can display SVG inline while viewing or editing text. Perhaps other
terminal pagers (like Less) comprehend inline svg? Vector formats surely
would be preferable than bitmaps for most things Perl documentation
would encompass. In any case, the PNG is easily convertible, even
scriptable as part of the cpan upload process, with the pngtopbm program
of NetPBM and then embedded into the POD alongside the text definition
as above.
2. Tables.
Emacs Org-mode has a built-in ASCII-mode table editor, producing very
much in the vein of Markdown; see
https://orgmode.org/manual/Built_002din-Table-Editor.html the following
page to which,
https://orgmode.org/manual/Column-Width-and-Alignment.html explains how
columns may have width and left/right/center alignment defined. While
that is somewhat Emacs-specific, it is highly convenient to have the
table realigned each time you hit TAB while editing the table right in
the editor: What you see is truly what you get.
Perhaps other editors have similar features which POD editors could
leverage, if the new specification resembles something already existing.
Conclusion.
It would be regrettable to define yet another syntax for images,
diagrams, and tables when long-standing, well-used solutions already
exist, especially when they are already compatible with Perl's and
CPAN's existing workflows.
\\/
William Lindley
Shelbyville, KY
Thread Previous
|
Thread Next