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:21
Subject:
Re: Pre-RFC: markdown in pod
Message ID:
CABMkAVXeUz3pmRUfkOOxZ9hrq19TNc0facmx0O3=zw0e2Ye0gA@mail.gmail.com
On Mon, Nov 15, 2021 at 3:20 PM Dan Book <grinnz@gmail.com> wrote:
> 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.
>
Forgot to mention: this has precedent of a sort as metacpan currently
renders (stripped) =for html sections, while non-HTML renderers of course
ignore them.
-Dan
Thread Previous
|
Thread Next