Front page | perl.perl5.porters |
Postings from November 2021
Re: Pre-RFC: markdown in pod
Thread Previous
|
Thread Next
From:
Dan Book
Date:
November 15, 2021 20:20
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
CABMkAVXpZe1oCgQYMhmytqpf_4Wa5FLspWhQpm+xbFrxNNdkSw@mail.gmail.com
On Mon, Nov 15, 2021 at 2:59 PM Nicholas Clark <nick@ccl4.org> wrote:
> On Fri, Nov 12, 2021 at 01:54:02PM +0000, Neil Bowers wrote:
> On Mon, Nov 15, 2021 at 03:45:15PM +0100, Tomasz Konojacki wrote:
> > 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
>
> In core we use Pod to generate man pages, text documentation and HTML.
> We seem to mention `perldoc` [or should I say C<perldoc>? :-)] more than
> the other two.
>
> (If I understand =for correctly) then using exactly the syntax you're
> suggesting would mean that perldoc would render module documentation as a
> blank page.
>
Currently yes, but this doesn't rule out that Pod::Perldoc could be
extended to render markdown sections, nor that metacpan could (the most
commonly viewed HTML rendering). Either way this isn't the job of the pod
*specification* or even Pod::Simple, but of specific pod renderers, unless
we want to extend the specification to support some custom markdown
variant, which is IMO not a good idea.
-Dan
Thread Previous
|
Thread Next