perl5
perl5 copied to clipboard
Perl
Convert .github/README.md to POD
Rename and convert README from Markdown to POD
POD is Perl native markup, Markdown is foreign to Perl.
Why not to respect and use POD where ever possible when GitHub renders POD too? 🙂
GitHub formats POD README's as good as Markdown, so I see no reason to favor Markdown to POD here.
Simply converted all # to =head1 and ``` lines to (4 spaces) to match the code examples.
The latter creates headings, the former formats text verbatim.
The main benefit of doing this is it enables us to easily do things like add links to L<perlintro>.
Why not to respect and use POD where ever possible when GitHub renders POD too? 🙂
GitHub formats POD README's as good as Markdown, so I see no reason to favor Markdown to POD here.
A saner approach (in my opinion) is to first decide what content is useful/what content to add and then pick the format that suits best. Does POD rendering in GitHub work? Yes. Does POD support everything that GitHub's markdown supports? No.[^1]
The main benefit of doing this is it enables us to easily do things like add links to
L<perlintro>.
Which will create a link to https://metacpan.org/pod/perlintro Does that work? Of course it does. Would it be better if it linked to the perlintro that is in git? IMO it would.
[^1]: One example: tables. (I'm not saying the .github/README should/will include tables; Maybe it makes sense for something to add a table, maybe not.)
I think we shouldn't adopt another language even if it can be better in some areas (and worse in others), and instead encourage POD to implement modern things such as table support by using it in GitHub as well, leveraging GitHub's POD recognition.
For instance, as a raw example, even if GitHub does Python indexing to easily jump into function definitions in it's editor, it doesn't mean we should write some parts in it as we already have a programming language that works enough for us (let's make GitHub does the same for Perl code too instead by keeping to it).
@bram-perl there is (or maybe was) a hidden standard for creating a table that things like pod2html would respect.
I wonder if this just means we should add a few things to pod?
FWIW, I think debating some of the thing being debated here would be better debated on the list and not as part of PR commentary. I think it comes down to a policy decision: Will we, while hosted on github, make maximum use of githubs documentation features, and assuming we do, how we will balance that against the existing documentation corpus.
IMO even if reasonable people might disagree on some of these points we can make a collective decision that gives some clear guidance on what the community wants to do.
For instance my personal view is we should make the maximum use of github features provided those changes can be isolated from our existing infra, and provided the github specific stuff doesnt supplant it. Eg, the "correct" place to document something should always be in the standard docs, but it should ok to have gtihub specific docs which might enhance that documentation, provided we dont end up with too much double entry. Others seem feel otherwise. Lets discuss this on porters list, not in PR responses.
@bram-perl there is (or maybe was) a hidden standard for creating a table that things like pod2html would respect.
I wonder if this just means we should add a few things to pod?
FWIW, I think debating some of the thing being debated here would be better debated on the list and not as part of PR commentary. I think it comes down to a policy decision: Will we, while hosted on github, make maximum use of githubs documentation features, and assuming we do, how we will balance that against the existing documentation corpus.
IMO even if reasonable people might disagree on some of these points we can make a collective decision that gives some clear guidance on what the community wants to do.
For instance my personal view is we should make the maximum use of github features provided those changes can be isolated from our existing infra, and provided the github specific stuff doesnt supplant it. Eg, the "correct" place to document something should always be in the standard docs, but it should ok to have gtihub specific docs which might enhance that documentation, provided we dont end up with too much double entry. Others seem feel otherwise. Lets discuss this on porters list, not in PR responses.
I agree about not including policy discussions in PR's, and I think we need creating GitHub Discussions in the perl/perl5 repository for debates (be it existing alongside the p5p list), because the porters list is not as convenient as GitHub, and also having everything in one place is useful for interlinking.
That said, I stop my lengthy discussion thereby 🙂
