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

Pre-RFC: markdown in pod

Thread Next
From:
Neil Bowers
Date:
November 12, 2021 13:54
Subject:
Pre-RFC: markdown in pod
Message ID:
cf486735-dba4-4714-b986-312d0c0a3915@Spark
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

# NAME

...

## Functions

...

=cut

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.

Neil

Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About