Clean pod2man-generated manpages after formula build

[alebcay]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?

---

As noted in Homebrew/homebrew-core#191352 (comment), one factor which hinders :all bottles from being built is that Perl documentation generation via pod2man embeds some version information about the version of perl and tools used.

--- /a/strip-nondeterminism/1.14.0/libexec/man/man3/Getopt::Long::Parser.3pm
+++ /b/strip-nondeterminism/1.14.0/libexec/man/man3/Getopt::Long::Parser.3pm
@@ -1,8 +1,8 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
+.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
 ..
@@ -67,15 +67,15 @@
 .        \}
 .    \}
 .\}
 .rr rF
 .\" ========================================================================
 .\"
 .IX Title "Getopt::Long::Parser 3"
-.TH Getopt::Long::Parser 3 "2024-05-24" "perl v5.34.1" "User Contributed Perl Documentation"
+.TH Getopt::Long::Parser 3 "2024-05-24" "perl v5.30.3" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
 Getopt::Long::Parser \- Getopt::Long object\-oriented interface
 .SH "SYNOPSIS"

This change introduces logic to search for and replace/adjust the following occurrences in manpages:

• By default, the perl version is inserted in the footer. Search for this and replace it with an empty string.
• The version of Pod::Man and Pod::Simple are inserted in a comment in the resulting *roff output. Find/replace the generated line in the output to remove those occurrences.

Alternatives

• Introduce a shim around pod2man to try to catch/fix these cases on each invocation of pod2man, rather than doing a sweep at the end
• Introduce a new DSL that performs the same/similar transformations on a provided file (or all files in a formula's man directory), e.g. clean_pod2man_outputs! or something like that, which would need to be called explicitly, for use in individual formulae which need it.

[MikeMcQuaid]

Seems reasonable, thanks!

Introduce a new DSL that performs the same/similar transformations on a provided file (or all files in a formula's man directory), e.g. clean_pod2man_outputs! or something like that, which would need to be called explicitly.

I'd actually probably favour doing this unconditional as part of Keg relocation logic?

[alebcay]

I'd actually probably favour doing this unconditional as part of Keg relocation logic?

Fair, that makes sense. One less DSL block/method to worry about that way. If the change is made in the keg relocation logic, then this shim is not needed (it wasn't clear to me from your comment which of these - unconditional logic addition vs new shim - is preferred).

[MikeMcQuaid]

If the change is made in the keg relocation logic, then this shim is not needed (it wasn't clear to me from your comment which of these - unconditional logic addition vs new shim - is preferred).

I'd probably prefer the unconditional logic but don't feel strongly if you hate it!

[alebcay]

I ended up adding the logic at the end of build rather than at keg relocation, since the transformation should only run when building from source, not always when an installation occurs (e.g. pouring from bottle won't need this).

One other consideration: this currently runs on all formulae which put the perl version in the footer, including perl itself (and its many manpages). Not sure if there should be a bypass mechanism of some kind (DSL or list in code) to avoid the transformation for some specific formulae where the original behavior may be preferred.

[MikeMcQuaid]

Great work, thanks!