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

(correction) Re: process RFC - POD for all RFC documentation

Thread Next
From:
mah.kitteh via perl5-porters
Date:
June 19, 2021 10:38
Subject:
(correction) Re: process RFC - POD for all RFC documentation
Message ID:
lpZBmaCwpw2Kr_ANVQa1lzDMNgob9zAu3FCOOpPyMmSy2S-pT3D21sfiqRmMN-ySNyhMOJopWisDrTI2wHq-_0WqpQ3sVFrF1X9N_LPJSwU=@protonmail.ch
s/TSP/TPF/

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

On Saturday, June 19th, 2021 at 5:34 AM, oodler@cpan.org <mah.kitteh@protonmail.ch> wrote:

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


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About