Re: [PATCH] Makefile: replace perl/Makefile.PL with simple make rules

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Thu, Nov 30 2017, Jonathan Nieder jotted:

> Hi,
>
> Ævar Arnfjörð Bjarmason wrote:
>
>> Replace the perl/Makefile.PL and the fallback perl/Makefile used under
>> NO_PERL_MAKEMAKER=NoThanks with a much simpler implementation heavily
>> inspired by how the i18n infrastructure's build process works[1].
>
> Yay!  This looks exciting.
>
> One quick comment:
>
> [...]
>>  * We don't build the Git(3) Git::I18N(3) etc. man pages from the
>>    embedded perldoc. I suspect nobody really cares, these are mostly
>>    internal APIs, and if someone's developing against them they likely
>>    know enough to issue a "perldoc" against the installed file to get
>>    the same result.
>>
>>    But this is a change in how Git is installed now on e.g. CentOS &
>>    Debian which carry these manpages. They could be added (via
>>    pod2man) if anyone really cares.
>>
>>    I doubt they will. The reason these were built in the first place
>>    was as a side-effect of how ExtUtils::MakeMaker works.
>
> Debian cares (see
> https://www.debian.org/doc/packaging-manuals/perl-policy/ch-module_packages.html
> for details).
>
> I'll try applying this patch and seeing what happens some time this
> week.

It just says you have to install the manpages in such-and-such a place,
but I don't have any. There, policy issue fixed :)

More seriously, it seems to me that the only reason we have these
manpages in the first place is because of emergent effects. *Maybe* I'm
wrong about someone using Git.pm as an external API, is that the case?

I was assuming this was more of a case where we were manifying the
equivalent of Documentation/technical/api-*.txt and shipping them as
user docs just because that's what EU::MM will do by default, and nobody
thought to stop it.

But sure, if we still want these I can just provide them, here's the
relevant generated perl.mak section:

	POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
	POD2MAN = $(POD2MAN_EXE)
	manifypods : pure_all config  \
		Git.pm \
		Git/I18N.pm \
		Git/SVN/Editor.pm \
		Git/SVN/Fetcher.pm \
		Git/SVN/Memoize/YAML.pm \
		Git/SVN/Prompt.pm \
		Git/SVN/Ra.pm \
		Git/SVN/Utils.pm
		$(NOECHO) $(POD2MAN) --section=$(MAN3EXT) --perm_rw=$(PERM_RW) -u \
		  Git.pm $(INST_MAN3DIR)/Git.$(MAN3EXT) \
		  Git/I18N.pm $(INST_MAN3DIR)/Git::I18N.$(MAN3EXT) \
		  Git/SVN/Editor.pm $(INST_MAN3DIR)/Git::SVN::Editor.$(MAN3EXT) \
		  Git/SVN/Fetcher.pm $(INST_MAN3DIR)/Git::SVN::Fetcher.$(MAN3EXT) \
		  Git/SVN/Memoize/YAML.pm $(INST_MAN3DIR)/Git::SVN::Memoize::YAML.$(MAN3EXT) \
		  Git/SVN/Prompt.pm $(INST_MAN3DIR)/Git::SVN::Prompt.$(MAN3EXT) \
		  Git/SVN/Ra.pm $(INST_MAN3DIR)/Git::SVN::Ra.$(MAN3EXT) \
		  Git/SVN/Utils.pm $(INST_MAN3DIR)/Git::SVN::Utils.$(MAN3EXT)

I.e. we'd just need to create the mandir, then call pod2man.

However, even then we should consider what I've noted above and decide
which modules we really want to be shipping docs for, e.g. Git::I18n is
never going to be used by anyone external, nor is the Git::SVN stuff.

I think the only thing we're talking about shipping manpages for is
*maybe* just Git.pm itself, no?

I don't really care, so if others want to ship them all I'll just hack
it up. This just seemed like a bug to fix while I was at it.