[doc] Issues in perl man pages

[hmartink]

the manpage-l10n project maintains a large number of translations of
man pages both from a large variety of sources (including perl) as
well for a large variety of target languages.

During their work translators notice different possible issues in the
original (english) man pages. Sometimes this is a straightforward
typo, sometimes a hard to read sentence, sometimes this is a
convention not held up and sometimes we simply do not understand the
original.

We use several distributions as sources and update regularly (at
least every 2 month). This means we are fairly recent (some
distributions like archlinux also update frequently) but might miss
the latest upstream version once in a while, so the error might be
already fixed. We apologize and ask you to close the issue immediately
if this should be the case, but given the huge volume of projects and
the very limited number of volunteers we are not able to double check
each and every issue.

Secondly we translators see the manpages in the neutral po format,
i.e. converted and harmonized, but not the original source (be it man,
groff, xml or other). So we cannot provide a true patch (where
possible), but only an approximation which you need to convert into
your source format.

Finally the issues I'm reporting have accumulated over time and are
not always discovered by me, so sometimes my description of the
problem my be a bit limited - do not hesitate to ask so we can clarify
them.

I'm now reporting the errors for your project. If future reports
should use another channel, please let me know.

Man page: perl.1perl
Issue:    I<perldoc> → B<perldoc>(1)

"The I<perldoc> program gives you access to all the documentation that comes "
"with Perl.  You can get more documentation, tutorials and community support "
"online at E<lt>https://www.perl.org/E<gt>."

"If you're new to Perl, you should start by running CW<\\*(C`perldoc "
"perlintro\\*(C'>, which is a general intro for beginners and provides some "
"background to help you navigate the rest of Perl's extensive documentation.  "
"Run CW<\\*(C`perldoc perldoc\\*(C'> to learn more things you can do with "
"I<perldoc>."
--
Man page: perl.1perl
Issue:    I<man> → B<man>(1)

"On a Unix-like system, these documentation files will usually also be "
"available as manpages for use with the I<man> program."
--
Man page: perl.1perl
Issue 1:  by man → by B<man>(1)
Issue 2:  with perldoc → with B<perldoc>(1)

"Some documentation is not available as man pages, so if a cross-reference is "
"not found by man, try it with perldoc.  Perldoc can also take you directly "
"to documentation for functions (with the B<-f> switch). See "
"CW<\\*(C`perldoc\\ --help\\*(C'> (or CW<\\*(C`perldoc\\ perldoc\\*(C'> or "
"\\&CW<\\*(C`man\\ perldoc\\*(C'>) for other helpful options perldoc has to "
"offer."
--
Man page: perl.1perl
Issue 1:  B<sed> → B<sed>(1)
Issue 2:  \\&B<awk> → \\&B<awk>(1)
Issue 3: B<sh> → B<sh>(1)

"The language is intended to be practical (easy to use, efficient, complete) "
"rather than beautiful (tiny, elegant, minimal).  It combines (in the "
"author's opinion, anyway) some of the best features of B<sed>, \\&B<awk>, "
"and B<sh>, making it familiar and easy to use for Unix users to whip up "
"quick solutions to annoying problems.  Its general-purpose programming "
"facilities support procedural, functional, and object-oriented programming "
"paradigms, making Perl a comfortable language for the long haul on major "
"projects, whatever your bent."
--
Man page: perl.1perl
Issue:    perlport → B<perlport>(1)

"Perl is available for most operating systems, including virtually all Unix-"
"like platforms.  See \"Supported Platforms\" in perlport for a listing."
--
Man page: perl.1perl
Issue:    perlrun → B<perlrun>(1)

"See \"ENVIRONMENT\" in perlrun."
--
Man page: perl.1perl
Issue:    perlvar → B<perlvar>(1)

"\"@INC\" above is a reference to the built-in variable of the same name; see "
"perlvar for more information."
--
Man page: perl.1perl
Issue:    perldiag → B<perldiag>(1)

"See perldiag for explanations of all Perl's diagnostics.  The CW<\\*(C`use "
"diagnostics\\*(C'> pragma automatically turns Perl's normally terse warnings "
"and errors into these longer forms."
--
Man page: perl.1perl
Issue:    perlsec. → B<perlsec>(1).

"Setuid scripts have additional constraints that can produce error messages "
"such as \"Insecure dependency\".  See perlsec."
--
Man page: perl.1perl
Issue 1:  B<atof()> → B<atof>(3)
Issue 2:  B<sprintf()> → B<sprintf>(3)

"Perl is at the mercy of your machine's definitions of various operations "
"such as type casting, B<atof()>, and floating-point output with B<sprintf()>."
--
Man page: perl.1
Issue:    I<man> → B<man>(1)

"On a Unix-like system, these documentation files will usually also be "
"available as manpages for use with the I<man> program."
--
Man page: perlbook.1perl
Issue:    This is outdated, there is already an 7th edition from 2016 and even an 8th edition (?)

"\\& by Randal L. Schwartz, Tom Phoenix, and brian d foy \\& ISBN "
"978-1-4493-0358-7 [6th edition June 2011] \\& ISBN 978-1-4493-0458-4 [ebook] "
"\\& https://www.learning-perl.com/"
--
Man page: perlbook.1perl
Issue:    Sentence starts off strange?

"The tutorial started in the Llama continues in the Alpaca, which introduces "
"the intermediate features of references, data structures, object-oriented "
"programming, and modules:"
--
Man page: perlbook.1perl
Issue:    Dave → David

"\\& by Dave Cross \\& ISBN 1-930110-00-6 [1st edition 2001 & ebook] \\& "
"https://www.manning.com/cross"
--
Man page: perlbook.1perl
Issue:    "last five years" would mean 2019 and later, however, none of the above books fits this, the "newest" is from 10 years ago

"Some of the books we've listed appear almost ancient in internet scale, but "
"we've included those books because they still describe the current way of "
"doing things. Not everything in Perl changes every day.  Many of the "
"beginner-level books, too, go over basic features and techniques that are "
"still valid today. In general though, we try to limit this list to books "
"published in the past five years."

[jkeenan]

Several points:

• When you file a ticket in our GH queue, please only use backticks around code blocks. Please do not use them around regular text, as it then becomes difficult to distinguish between text and code.
• With perhaps a few exceptions, all man pages coming out of the Perl core distribution start as files written in the POD format and stored within the distribution as individual pod/perl*.pod files. Please do not mix inquiries/complaints about more than one man page in a given GitHub issue, but please place all complaints about a single POD file in a single GH issue.

[hmartink]

Thanks for your analysis. for a) If I do not use the backticks, then the text looks "strange", probably github interprets some of the characters as markup. for b) I'll note down that in the future I will use one report per man page. As stated in my introduction, I have no clue at all how the man pages are generated, manpages-l10n receives the man pages "as is" from the various distributions. But I hope that one man page correlates to one pod page.

[Leont]

I think most of your comments boil down to "mention the man section when referring to a man page". For our internal documentation, that's a limitation of our pod2man pipeline and should IMHO not be added manually (because it wouldn't be appropriate for the HTML versions of the documentation). For external commands (man, sed, awk, …) it may make sense to add it manually. I wish we had a proper syntax for this to be honest.

As for perlbook:

Issue: This is outdated, there is already an 7th edition from 2016 and even an 8th edition (?)

Yeah that should be updated.

Issue: Sentence starts off strange?

If you don't know the context then I guess it does, but what it says is correct. It refers to the animals on the front of the books.

Issue: Dave → David

He usually goes by Dave Cross, don't think this really matters.

Issue: "last five years" would mean 2019 and later, however, none of the above books fits this, the "newest" is from 10 years ago

Yeah that should be changed for the reality that very few perl books are still getting published.

[hmartink]

Thanks for the reply. I'll mark those issue which are limitations of the toolchain accordingly. Btw., for the German version I researched the German translation of the books as well. And actually most, if not all of them are out of print, unfortunately.