Front page | perl.perl5.porters |
Postings from November 2021
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. -DanThread Previous | Thread Next