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

Re: process RFC - POD for all RFC documentation

Thread Previous | Thread Next
From:
Nicholas Clark
Date:
June 19, 2021 08:08
Subject:
Re: process RFC - POD for all RFC documentation
Message ID:
20210619080829.GQ16703@etla.org
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

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