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

Pre-RFC: markdown in pod

Thread Next
Neil Bowers
November 12, 2021 13:54
Pre-RFC: markdown in pod
Message ID:
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.

I regularly find myself wanting to write markdown instead of pod, particularly when writing modules. Something like:

=format markdown



## Functions



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.

I think this would provide one less huh?/wtf? barrier to people trying Perl, and would let people use the broad range of markdown tools out there.

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.


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