Mailing List Archive

On 2023-08-22 7:17 a.m., Paul Marquess wrote:
>
> Happened to notice that https://github.com/Dual-Life/Devel-PPPort
> displays a markdown version of its POD when you navigate to it on
> GitHub. Digging a bit deeper I see that does that by strong a
> README.md file in the .github directory – somehow GitHub spots it and
> uses it for the module landing page. Quite a neat approach because the
> .github directory doesn’t end up in the CPAN bundle. Also means that
> the plain-vanilla text README isn’t touched.
>
> Before I jump in with both feet and replicate this, do we have any
> guidance on the general approach? Also is there any tooling to
> automate the process? (Not that it’s a big deal to create it).
>
I use Pod::Markdown.

I run it manually, because I don't want a 1:1 between the POD
documentation and the README.md anyway, but it'd be trivial to automate
if you wanted to.

- R

On 22.08.23 15:17, Paul Marquess wrote:
> Happened to notice that https://github.com/Dual-Life/Devel-PPPort
> <https://github.com/Dual-Life/Devel-PPPort> displays a markdown version
> of its POD when you navigate to it on GitHub. Digging a bit deeper I see
> that does that by strong a README.md file in the .github directory –
> somehow GitHub spots it and uses it for the module landing page. Quite a
> neat approach because the .github directory doesn’t end up in the CPAN
> bundle. Also means that the plain-vanilla text README isn’t touched.
>
> Before I jump in with both feet and replicate this, do we have any
> guidance on the general approach? Also is there any tooling to automate
> the process? (Not that it’s a big deal to create it).

The .github/README thing is documented at
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.
I quite like it.

Here's some ad-hoc tooling I made myself (probably not entirely
appropriate for core): https://github.com/mauke/Function-Parameters

Both README and .github/README.md are autogenerated from the main module
POD. This happens via a hook into the Makefile.PL/make process.

https://github.com/mauke/Function-Parameters/blob/main/Makefile.PL is
boilerplate that loads the module-specific ExtUtil::MakeMaker settings
from
https://github.com/mauke/Function-Parameters/blob/main/Makefile_PL_settings.plx
and, in maintainer mode, runs the code in
https://github.com/mauke/Function-Parameters/blob/main/maint/eumm-fixup.pl.

The latter adds rules to the generated Makefile that automatically
recreate README (on 'make dist') and .github/README.md (on 'make' in
general) using the scripts in
https://github.com/mauke/Function-Parameters/blob/main/maint/pod2readme.pl
and
https://github.com/mauke/Function-Parameters/blob/main/maint/pod2markdown.pl.

The latter is relatively straightforward Pod::Markdown, but with a few
tweaks:

- It processes "github-markdown" sections, so I can put something like
"=for github-markdown " in my POD and use it to
render custom badges, but only on Github.
- For L<Module> links, it normally links to metacpan.org. But if the
target is a L<perl...> page, I have it link to perldoc.perl.org instead,
because metacpan doesn't know about generated perldoc pages such as perlapi.
- It understands "=for highlighter language=foo" sections and uses
them for syntax highlighting (by rendering all following verbatim
paragraphs as "```foo ... ```" fenced code blocks).
- It works around a Markdown syntax issue with list items that start
with a code block.

(In comparison, pod2readme.pl is very simple: It takes a few selected
POD sections and renders them as plain text.)

On Tue, Aug 22, 2023 at 01:17:51PM +0000, Paul Marquess wrote:
>
> Before I jump in with both feet and replicate this, do we have any
> guidance on the general approach? Also is there any tooling to
> automate the process? (Not that it's a big deal to create it).

Not sure if you meant "replicate this [in the perl5 repository]", but
just in case, this already exists:
https://github.com/Perl/perl5/tree/blead/.github

See also 42557cf44325545afd1c1455ebfeecbc2d23157c.

--
Philippe Bruhat (BooK)

Mankind is the story of the same mistakes in different places.
(Moral from Groo #1 (Image))

> From: Ryan Thompson i@ry.ca <mailto:i@ry.ca>

…

> Before I jump in with both feet and replicate this, do we have any guidance on the general approach? Also is there any tooling to automate the process? (Not that it’s a big deal to create it).

>

> I use Pod::Markdown.



So do I



> I run it manually, because I don't want a 1:1 between the POD documentation and the README.md anyway



I know that I’ll forget to refresh the README.md file so I want it fully automatic. Will also get it to merge the GigHub badges into the file when I’m at it.



> but it'd be trivial to automate if you wanted to.



Yeah, not a lot too it



Paul

On Tue, Aug 22, 2023 at 6:18?AM Paul Marquess <paul.marquess@outlook.com>
wrote:

> Happened to notice that https://github.com/Dual-Life/Devel-PPPort
> displays a markdown version of its POD when you navigate to it on GitHub.
> Digging a bit deeper I see that does that by strong a README.md file in the
> .github directory – somehow GitHub spots it and uses it for the module
> landing page. Quite a neat approach because the .github directory doesn’t
> end up in the CPAN bundle. Also means that the plain-vanilla text README
> isn’t touched.
>
>
>
> Before I jump in with both feet and replicate this, do we have any
> guidance on the general approach? Also is there any tooling to automate the
> process? (Not that it’s a big deal to create it).
>

As others have said, Pod::Markdown exists. Also, github understands pod
itself, so you needn't even convert your pod files to markdown if you don't
want to. For my distributions, I use Dist::Zilla::Plugin::ReadmeFromPod to
generate a README.pod in the root of the repository (but NOT in the shipped
distribution - because PAUSE will want to index it). This is then displayed
on the main page of the repository as its manpage, which is convenient for
non-perlish users who expect to find documentation in github rather than on
metacpan.

On Tue, Aug 22, 2023 at 6:36?PM Karen Etheridge <perl@froods.org> wrote:
>
> As others have said, Pod::Markdown exists. Also, github understands pod itself, so you needn't even convert your pod files to markdown if you don't want to. For my distributions, I use Dist::Zilla::Plugin::ReadmeFromPod to generate a README.pod in the root of the repository (but NOT in the shipped distribution - because PAUSE will want to index it). This is then displayed on the main page of the repository as its manpage, which is convenient for non-perlish users who expect to find documentation in github rather than on metacpan.

This doesn't work anymore.

https://github.com/github/markup/issues/1715

On Tue, Aug 22, 2023 at 9:45?AM Graham Knop <haarg@haarg.org> wrote:

> This doesn't work anymore.
> https://github.com/github/markup/issues/1715
>

Oh no! This appears to be a very new breakage, so hopefully it is fixed
soon as well. I do not like the idea of having to go through hundreds of
distributions to change README.pod files to README.md.

> From: Lukas Mai <lukasmai.403@gmail.com> On Behalf Of Lukas Mai

...
>
> The .github/README thing is documented at https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.
> I quite like it.

Ta

> Here's some ad-hoc tooling I made myself (probably not entirely appropriate for core): https://github.com/mauke/Function-Parameters
>
> Both README and .github/README.md are autogenerated from the main module POD. This happens via a hook into the Makefile.PL/make process.
>
> https://github.com/mauke/Function-Parameters/blob/main/Makefile.PL is boilerplate that loads the module-specific ExtUtil::MakeMaker settings from https://github.com/mauke/Function-Parameters/blob/main/Makefile_PL_settings.plx
> and, in maintainer mode, runs the code in https://github.com/mauke/Function-Parameters/blob/main/maint/eumm-fixup.pl.
>
> The latter adds rules to the generated Makefile that automatically recreate README (on 'make dist') and .github/README.md (on 'make' in
> general) using the scripts in
> https://github.com/mauke/Function-Parameters/blob/main/maint/pod2readme.pl
> and
> https://github.com/mauke/Function-Parameters/blob/main/maint/pod2markdown.pl.
>
> The latter is relatively straightforward Pod::Markdown, but with a few
> tweaks:
>
> - It processes "github-markdown" sections, so I can put something like "=for github-markdown " in my POD and use it to render custom badges, but only on Github.
> - For L<Module> links, it normally links to metacpan.org. But if the target is a L<perl...> page, I have it link to perldoc.perl.org instead, because metacpan doesn't know about generated perldoc pages such as perlapi.
> - It understands "=for highlighter language=foo" sections and uses them for syntax highlighting (by rendering all following verbatim paragraphs as "```foo ... ```" fenced code blocks).
> - It works around a Markdown syntax issue with list items that start with a code block.
>
> (In comparison, pod2readme.pl is very simple: It takes a few selected POD sections and renders them as plain text.)

Thanks, will take a look

Paul