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