For what I want, I already switched to Markdown wholesale everywhere I had
previously been using POD as a general documentation format.
I found them reasonably comparable but that Markdown was a lot less verbose.
Certain things Markdown seemed to fall short of POD such as the cleanliness of
navigation links. And I'm speaking of standard Markdown that works everywhere
not extensions that only work in some places.
I'm currently naive as to what if any support there is in Perl or its toolchain
for Markdown now, but I feel it would be valuable if Markdown was supported by
both or especially the toolchain as an official alternative to POD.
The simpler scenario is that Markdown files could be supported in the same way
as standalone POD-only .pod files are supported now, and the toolchain would
handle either in the same way.
A more complicated scenario would be somehow supporting embedding Markdown
inside Perl source files .pl, .pm etc if that is useful. This would be required
for it to be an eventual full replacement for POD everywhere if one wanted to do
that.
However, while embedding POD in Perl source files is a very useful feature in
principle and I can see benefits of it, particularly for interleaving docs with
what routines etc they document, I found in practice that when I wrote POD it
actually worked best for me to have it in wholly separate files.
See
https://metacpan.org/dist/Set-Relation for an example of my preferred POD
practice, where Perl source files don't have any POD in them, the POD is separate.
A key reason I find separate files are better is that the optimal structure for
documentation is not the same order as the optimal structure for code, and
separate files means each can be optimized for its purpose without being forced
to align with each other because routine docs must be beside the routines they
describe and so on.
And so, at least for people that follow my recommended practice of docs being in
separate files, the much simpler support for standalone Markdown files without
embedding it in Perl files would be sufficient.
-- Darren Duncan
On 2023-09-23 1:11 p.m., Paul "LeoNerd" Evans wrote:
> On Sat, 23 Sep 2023 10:02:18 -0700
> Scott Baker <scott@perturb.org> wrote:
>
>> I'm curious how "switch to Markdown" would even work?
>
> It prettymuch wouldn't. There's too many moving parts everywhere.
>
> But we discussed it anyway just to come to that conclusion, and be
> prepared to explain it to the folks that inevitably will say "drop POD
> in favour of Markdown rather than keep stealing its features".
>