develooper Front page | perl.perl5.porters | Postings from November 2021

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next
Paul "LeoNerd" Evans
November 12, 2021 15:29
Re: Pre-RFC: markdown in pod
Message ID:
On Fri, 12 Nov 2021 13:54:02 +0000
Neil Bowers <> wrote:

> Markdown has long since won the battle of simple text-based
> documentation formats. People, not just developers, are used to
> writing it in lots of different places. Odds are that developers
> trying out Perl, coming from other language experience, will be
> familiar with markdown, and pod will just seem weird.

Even when I'm writing POD I often end up doing `this`.. ohwait I meant

> There are some things that pod provides that markdown doesn’t, and
> there’s the whole table issue. But on the very rare occasion I’ve
> wanted a table in documentation I’ve used a manually formatted ASCII
> table. And most modules have fairly simple documentation, in terms of
> the pod syntax currently used.


(really I want tables)

> The biggest problem I’m aware of is that this would require
> coordination of changes in multiple places, and I don’t even know
> what all of those places are.

> And there are different markdown formats, so we’d have to pick one.

Yes, that's always an issue.

On a somewhat-tangential note, I lately have been maintaining a tool
designed to be "a better man(1)", able to view POD, Markdown, nroff
etc... with a real native formatter that understands terminal
bold/underline/italics, colour, etc...

As well as display, it also has some code to output to various formats,
so it can act as a decent cross-converter between these formats. If you
are looking for more inspiration on how to handle these things, that
might be another good place to look.

Paul "LeoNerd" Evans      |  |

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About