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

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next
From:
Tomasz Konojacki
Date:
November 15, 2021 14:45
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
20211115154511.6275.5C4F47F8@xenu.pl
On Fri, 12 Nov 2021 13:54:02 +0000
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.
> 
> Neil

As the others have already said, =for already exists. However, it's
mainly used for small, isolated fragments of the documentation, *not* to
write everything using a different markup language.

In my opinion, allowing to write a whole documentation in Markdown would
be too drastic of a change and I don't support it. Also, keep in mind
that Markdown isn't really standarized and there are several competing
syntaxes for e.g. tables. If we allowed "=for markdown", we would have
to write a complete specification for our Markdown dialect.

I think we should fix POD instead. There are two big problems with it:
the lack of images and the lack of tables. Both are fixable. I will
probably submit pre-RFCs soon.


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