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

Re: process RFC - POD for all RFC documentation

Thread Previous | Thread Next
From:
mah.kitteh via perl5-porters
Date:
June 19, 2021 10:35
Subject:
Re: process RFC - POD for all RFC documentation
Message ID:
PnBnpnWnvZZeQqsqbB4RTx0-QpUS5vtctDmoHuEVzckCbDCovS9ZUlz5e2wBEQlWgr1H6k1jmBaMuqZDh2hpZBVV7rAUX4BMc81oy6swnaI=@protonmail.ch
In order to stay focused on "perl" the default should be POD as the "source". I don't know what the affinity for markdown is, but any talk about _not_ use POD particularly when it comes to converting to other formats is a huge distraction and waste of effort. For example, while I have a strong interest in helping with POD tooling written _in_ Perl; I have zero interest in other formats. MD just happens to be the "other" format. Frankly, if I had my druthers I'd push latex all day long. So it has nothing to do with the superior capabilities of POD, just that it's already a capability.

I have no idea what the future holds, but I say we align with TSP's documentation group and defer to their opinion. Based on what jmac said at the converence, it's POD; but this has to do with perldocs. Maybe the PSC has already consulted him/TPF Docs Team; but this might be the more prudent route regardles of my personal opinion.

To summarize, let's not create work for ourselves that doesn't need to exist. This is true in all cases, but especially in this one where we have a clear and efficient path.

Cheers,
Brett
‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

On Saturday, June 19th, 2021 at 4:58 AM, Nicholas Clark <nick@ccl4.org> wrote:

> On Sat, Jun 19, 2021 at 10:27:19AM +0100, Paul "LeoNerd" Evans wrote:
>
> > On Sat, 19 Jun 2021 08:08:29 +0000
> >
> > Nicholas Clark nick@ccl4.org wrote:
> >
> > > A tool to convert 90% of Markdown to Pod (and warn about the bits
> > >
> > > that need some manual fixup) would be really useful. Does one exist
> > >
> > > on CPAN already?
> >
> > I would suggest pandoc, except it doesn't support POD.
> >
> > But by happy coincidence, yesterday I began writing myself a
> >
> > "better man" [1] that can render POD and nroff (i.e. what man uses) to
> >
> > the terminal. I'm intending to add Markdown/ReST and other such
> >
> > formats, and also give it multiple outputs - maybe cross-conversion
> >
> > would be on theme there.
>
> Ooh interesting.
>
> Given the context I should stress "my personal opinion, and not something
>
> the current PSC has thought about" was that in the general case
>
> 1.  We need to convert our documents to HTML, plain text and man pages
> 2.  Pod can do this
> 3.  I have no idea about tooling to convert Markdown to man pages
>
>     so if "we" wanted to offer Markdown as an equal first class documentation
>
>     alternative generally, "we" need to be able to convert Markdown to man
>
>     pages, and I had no idea if that's already been done, and I didn't go
>
>     investigate.
>
>     But I don't have time to look into this, and won't once I've escaped the
>
>     PSC. There's a bunch of other Real Life (TM) stuff that needs doing and
>
>     had been on hold.
>
> > I did have a look around CPAN for some sort of Markdown parser, and I
> >
> > can find loads of duplicate modules on a theme of "convert Markdown
> >
> > to HTML" in one atomic lump, I can't find an abstract SAX or DOM-alike
> >
> > Markdown parser, in the same style as something like Pod::Simple or
> >
> > Parse::Man::DOM.
> >
> > Does anyone know of one, or should I write it? I kindof feel that
> >
> > "Writing your own Markdown parser" is only one level away from writing
> >
> > your own crypto. :/
>
> Good question, and I don't know.
>
> My impertinent thought is "Please don't spread yourself too thin"
>
> But really "It's your own time. Do what you find fun and productive"
>
> Nicholas Clark

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