Mailing List Archive

process RFC - POD for all RFC documentation
I didn't see where this was discussed nor is it in the git repo, anywhere.

But I think it's to our benefit to encourage POD for the RFCs. I am also thinking of the dog fooding POD rendering tools here, which is something I know some of us are interested in helping to improve. It's also internally inconsistent, and we should seek to eliminate these kinds of inconsistencies whenever possible.

This is not a small thing, so I ask that this be encouraged if not outright required. I am happy to issue a PR "fixing" the current set of documents that are in markdown if this is accepted somehow.

Cheers,
Brett
Re: process RFC - POD for all RFC documentation [ In reply to ]
On Thu, 17 Jun 2021 12:30:17 +0000
"mah.kitteh via perl5-porters" <perl5-porters@perl.org> wrote:

> But I think it's to our benefit to encourage POD for the RFCs.

I suspect the main reason is that github doesn't render .pod files, but
it does render .md

--
Paul "LeoNerd" Evans

leonerd@leonerd.org.uk | https://metacpan.org/author/PEVANS
http://www.leonerd.org.uk/ | https://www.tindie.com/stores/leonerd/
Re: process RFC - POD for all RFC documentation [ In reply to ]
On Thu, 17 Jun 2021 at 22:07, Paul "LeoNerd" Evans <leonerd@leonerd.org.uk>
wrote:

> On Thu, 17 Jun 2021 12:30:17 +0000
> "mah.kitteh via perl5-porters" <perl5-porters@perl.org> wrote:
>
> > But I think it's to our benefit to encourage POD for the RFCs.
>
> I suspect the main reason is that github doesn't render .pod files, but
> it does render .md
>

github renders pod files very well, so that can't be the reason. Github
even links L<> to metacpan. You have to call the file <name>.pod to get
that though.
Re: process RFC - POD for all RFC documentation [ In reply to ]
??????? Original Message ???????
On Thursday, June 17th, 2021 at 8:18 AM, Ben Bullock <benkasminbullock@gmail.com> wrote:

> On Thu, 17 Jun 2021 at 22:07, Paul "LeoNerd" Evans <leonerd@leonerd.org.uk> wrote:
>
>> On Thu, 17 Jun 2021 12:30:17 +0000
>> "mah.kitteh via perl5-porters" <perl5-porters@perl.org> wrote:
>>
>>> But I think it's to our benefit to encourage POD for the RFCs.
>>
>> I suspect the main reason is that github doesn't render .pod files, but
>> it does render .md
>
> github renders pod files very well, so that can't be the reason. Github even links L<> to metacpan. You have to call the file <name>.pod to get that though.

Correct, I failed to mention this so thank you. I have projects on GH that are also 100% POD, so it works there as well.

Brett

>
Re: process RFC - POD for all RFC documentation [ In reply to ]
On Thu, Jun 17, 2021 at 12:30:17PM +0000, mah.kitteh via perl5-porters wrote:
> I didn't see where this was discussed nor is it in the git repo, anywhere.

You're right, it's not in the repo. I thought that it was, but actually it
was only in the first mail that I sent. I wrote:


2) Format - PSC had thought Markdown, as many places can render it.

However,

a) github itself can render Pod. Is it the only git hosting service that can?
b) I've already found that my local markdown renderer and github disagree
about nested lists, which is annoying - how many other bugs will I hit?
c) Pod doesn't do tables, but plain markdown doesn't either.
github extended markdown with tables, but
i) How many other markdown implementations follow them?
ii) Are there alternative competing "table" dialects of Markdown?
d) I'm missing =cut


=cut :-)

Since then I've done some more homework on tables.

Original markdown - no tables
commonmark - no tables
[several other variants, no tables]
"GitHub flavoured markdown" - simple tables
"GitLib flavoured markdown" - simple tables (same syntax)
BitBucket markdown - simple tables, misses one feature of the previous two

(I'm still wondering whether "GitLab XXX" is just "GitHub XXX" with the old
label ground off and a new one glued on)

So, in theory, you *could* define a variant as "commonmark + tables" without
all the extra features of "GitHub" or "GitLab" but it's https://xkcd.com/927/
again. (And it amuses me that how the mouse-over text on that has dated...)


Right now, Markdown gets you tables and images, but you loose on definition
lists, which what we're doing turns out to actually be important - at
least it seems to be for what I'm finding I need to write.

(And the Markdown tables don't let you put column headers on the left to
"fake it")

Markdown images are really simple:

![alt text](/url "title")

There had been a suggestion to add images to Pod (which there is agreement
for) but the specific proposal lacked the simplicity of the Markdown
approach. And that's where it stalled. Restarting this with a plan inspired
by what Markdown does would be really useful.

(Heck in writing this I see that Markdown is more complex than I remembered
- it can do *both* alt-text and title)


There's internal discussion on this. I think that I've summarised it
accurately. I don't think that it's going to resolve until after the Term
Election.


> But I think it's to our benefit to encourage POD for the RFCs. I am also thinking of the dog fooding POD rendering tools here, which is something I know some of us are interested in helping to improve. It's also internally inconsistent, and we should seek to eliminate these kinds of inconsistencies whenever possible.

Yes, I agree with this. But we end up needing to use Markdown for the
"published" content for the repository (specifically, tables for the
various RFCs in various states), and having it render as the front page
README.md, so I sort of disagree too.

It's messy. I want it all, and I can't quite see how.

> This is not a small thing, so I ask that this be encouraged if not outright required. I am happy to issue a PR "fixing" the current set of documents that are in markdown if this is accepted somehow.

Thanks for the offer. In theory, this is useful. But experience I've seen
with semi-mechanical formatting changes such as these is that

1) of course they conflict with just about every other change
2) there's often a sweet spot in the sequencing of dealing with other changes,
where it makes sense to do them (to minimise future conflicts)

(or you arrange your workflow to engineer this sweet spot)

and so usually this is easiest

1) with a (conceptual) "lock" held on the repository
2) you don't know when you're going to get there (until you do)
3) at which point you want it done straight away


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?

Nicholas Clark
Re: process RFC - POD for all RFC documentation [ In reply to ]
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.

A quick screenshot:

https://twitter.com/cpan_pevans/status/1405938689050656774

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. :/


[1]: No Abba song jokes please; we're British.

--
Paul "LeoNerd" Evans

leonerd@leonerd.org.uk | https://metacpan.org/author/PEVANS
http://www.leonerd.org.uk/ | https://www.tindie.com/stores/leonerd/
Re: process RFC - POD for all RFC documentation [ In reply to ]
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
Re: process RFC - POD for all RFC documentation [ In reply to ]
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
Re: process RFC - POD for all RFC documentation [ In reply to ]
> But I think it's to our benefit to encourage POD for the RFCs.

I think we should stick to markdown for the RFCs.

The rest of the world uses markdown, and people who come to Perl will be used to markdown, not pod.

We need to embrace markdown, and address any issues in our markdown tools. This makes many other existing markdown tools available to us.

Plus, on a personal note, I much prefer writing markdown to pod.

Neil