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

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next
Dan Book
November 13, 2021 15:54
Re: Pre-RFC: markdown in pod
Message ID:
On Fri, Nov 12, 2021 at 8:54 AM 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.
> 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.

I would echo other comments in saying that the ability to notate this is
already present, and add that it should not be the job of Pod parsers to
parse markdown - the Pod spec is intentionally simple. So in my view the
bigger question is: what toolchain do you propose should handle displaying
Pod and markdown within the same file? I don't have a good answer for this.


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