Front page | perl.perl5.porters |
Postings from November 2021
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 doesnt, and theres the whole table issue. But on the very rare occasion Ive wanted a table in documentation Ive 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 Im aware of is that this would require coordination of changes in multiple places, and I dont even know what all of those places are. And there are different markdown formats, so wed 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