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

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next
From:
Felipe Gasper
Date:
November 12, 2021 14:04
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
3AF83D4C-B3C1-4160-9251-3B6448176D2A@felipegasper.com


> On Nov 12, 2021, at 08:54, Neil Bowers <neilb@neilb.org> 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

This already works, right? What kind of support do you envision?

Markdown targets HTML, not text. I’ve had difficulty before in finding Markdown-to-text renderers; that said, I guess folks who want to read Markdown as text can probably just read the MD source code without too much difficulty.

Native RST support might also be nice if the desire is to *replace* POD.

Generally I find folks inadvertently misuse POD by thinking indentation is structural (as it is in RST and Markdown) and by ignoring the need for extra newlines to delimit sections. I do agree that, for neophytes, POD is a bit of a shin-bumper. I’m not sure how MD would be a replacement for it, though; that seems more of a job for RST.

-F
Thread Previous | 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