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

Re: Pre-RFC: markdown in pod

Thread Previous | Thread Next
From:
Paul "LeoNerd" Evans
Date:
November 12, 2021 15:29
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
20211112152920.5699d71a@shy.leonerd.org.uk
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.

Even when I'm writing POD I often end up doing `this`.. ohwait I meant
C<this>.

> 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.

Tables++

(really I want tables)

> 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.

Yes, that's always an issue.

On a somewhat-tangential note, I lately have been maintaining a tool
designed to be "a better man(1)", able to view POD, Markdown, nroff
etc... with a real native formatter that understands terminal
bold/underline/italics, colour, etc... 

  https://twitter.com/cpan_pevans/status/1405938689050656774

  https://metacpan.org/dist/App-sdview

As well as display, it also has some code to output to various formats,
so it can act as a decent cross-converter between these formats. If you
are looking for more inspiration on how to handle these things, that
might be another good place to look.

-- 
Paul "LeoNerd" Evans

leonerd@leonerd.org.uk      |  https://metacpan.org/author/PEVANS
http://www.leonerd.org.uk/  |  https://www.tindie.com/stores/leonerd/

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