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

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next
From:
Dan Book
Date:
November 13, 2021 15:54
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
CABMkAVUR=2bUxxA+EcMqRx8103eQv9Q7m+N_GF-_khM2jHfMyw@mail.gmail.com
On Fri, Nov 12, 2021 at 8:54 AM 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
>
> 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.

-Dan

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