[doc] Issue in perl5124delta.1perl

[hmartink]

Dear Perl maintainer,
the manpage-l10n project[1] 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
your 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 issues for your project. If future reports
should use another channel, please let me know.

[1] https://manpages-l10n-team.pages.debian.net/manpages-l10n/

Btw. I noticed that you said that missing perl-internal links are a
limitation of your toolchain, because in HTML it does not look right.
Is this still the case? Then I will not report this in the future,
but I think in HTML it is quite sensible, as this can then be turned
into proper hyperlinks within the Perl documentation, giving a nice
reading experience.

PS. I left of the triple backticks as requested, hopefully this
remains readible.

Man page: perl5124delta.1perl
Issue 1: perl5123delta → B(1perl)
Issue 2: perl5120delta → B(1perl)

"If you are upgrading from an earlier release such as 5.12.2, first read "
"perl5123delta, which describes differences between 5.12.2 and 5.12.3. The "
"major changes made in 5.12.0 are described in perl5120delta."

--
Man page: perl5124delta.1perl
Issue: Module::CoreList → BModule::CoreList(3perl)

"Module::CoreList has been upgraded from version 2.43 to 2.50."

Man page: perl5124delta.1perl
Issue: perlfunc → B(1)

"Updated the documentation for B<rand()> in perlfunc to note that it is not "
"cryptographically secure."

Man page: perl5124delta.1perl
Issue: B → B(1)

"If you believe you have an unreported bug, please run the B program "
"included with your release. Be sure to trim your bug down to a tiny but "
"sufficient test case. Your bug report, along with the output of "
"CW<\(C`perl -V\(C'>, will be sent off to perlbug@perl.org to be analysed "
"by the Perl porting team."

Man page: perl5124delta.1perl
Issue: who be able → who will be able

"If the bug you are reporting has security implications, which make it "
"inappropriate to send to a publicly archived mailing list, then please send "
"it to perl5-security-report@perl.org. This points to a closed subscription "
"unarchived mailing list, which includes all the core committers, who be able "
"to help assess the impact of issues, figure out a resolution, and help co-"
"ordinate the release of patches to mitigate or fix the problem across all "
"platforms on which Perl is supported. Please only use this address for "
"security issues in the Perl core, not for modules independently distributed "
"on CPAN."

[book]

Hi,

First of all, the wall of text in what looks like an automated message is a little bit off-putting.

Btw. I noticed that you said that missing perl-internal links are a
limitation of your toolchain, because in HTML it does not look right.
Is this still the case? Then I will not report this in the future,
but I think in HTML it is quite sensible, as this can then be turned
into proper hyperlinks within the Perl documentation, giving a nice
reading experience.

The Perl documentation is written in the POD format, and links are formatted using L<> formatting code. Links to the internal documentation are supported.

The format of your report is sadly a bit hard to read, and I couldn't make sense of some of the issues described in it, e.g.:

Man page: perl5124delta.1perl
Issue: Module::CoreList → BModule::CoreList(3perl)

I picked the few fixes I could from your report, and applied them as 85ee741.

Thanks! If someone from your team could collaborate with the Perl team to find a nicer report format, I believe this would be beneficial for everyone.

[hmartink]

First of all, the wall of text in what looks like an automated message is a little bit off-putting.

This is my usual introduction, so you know the background. In the future, do you want me to provide it only on the first report, and then just refer to it on subsequent reports?

Btw. I noticed that you said that missing perl-internal links are a
limitation of your toolchain, because in HTML it does not look right.
Is this still the case? Then I will not report this in the future,
but I think in HTML it is quite sensible, as this can then be turned
into proper hyperlinks within the Perl documentation, giving a nice
reading experience.

The Perl documentation is written in the POD format, and links are formatted using L<> formatting code. Links to the internal documentation are supported.

Ok, so I will continue to report them, thanks for the clarification.

The format of your report is sadly a bit hard to read, and I couldn't make sense of some of the issues described in it, e.g.:

Man page: perl5124delta.1perl
Issue: Module::CoreList → BModule::CoreList(3perl)

This means, that "Module::CoreList" should be replaced by the proper man pages reference, which is formatted in bold and the section is appended in parenthesis.

If you have any other question, simply ask, the style of the translators is often brief.

I picked the few fixes I could from your report, and applied them as 85ee741.

Thanks! If someone from your team could collaborate with the Perl team to find a nicer report format, I believe this would be beneficial for everyone.

Thank you very much.

As requested last time, I reported each man page in a dedicated report, hope this helps resolving them as well.

[book]

This means, that "Module::CoreList" should be replaced by the proper man pages reference, which is formatted in bold and the section is appended in parenthesis.

I believe this is a job for the POD formatter. Not sure if there's anything we can do about that in the documentation source.

As requested last time, I reported each man page in a dedicated report, hope this helps resolving them as well.

OK, I might have missed some previous history, I'll look at your previous reports.

[hmartink]

Hello Book,

This means, that "Module::CoreList" should be replaced by the proper man pages reference, which is formatted in bold and the section is appended in parenthesis.

I believe this is a job for the POD formatter. Not sure if there's anything we can do about that in the documentation source.

I can only report what the translators found. If you tell me you cannot fix it, then I'll mark this accordingly. Should I do this or do you want to check first?

As requested last time, I reported each man page in a dedicated report, hope this helps resolving them as well.

OK, I might have missed some previous history, I'll look at your previous reports.

No problem, in #23934 also the history was not known and I was requested to contact perl-porters (which I will do).

[Leont]

The format of your report is sadly a bit hard to read, and I couldn't make sense of some of the issues described in it, e.g.:

Yeah, same.

This means, that "Module::CoreList" should be replaced by the proper man pages reference, which is formatted in bold and the section is appended in parenthesis.

This sounds like most of your bug reports should be replaced by a single bug report to podlators (specifically the Pod::Man module in it), to make it generate links to modules differently.

[hmartink]

If you tell me which issues I should ignore, I can do so. However, I don't have the ressource to figure out why an issue exists and how and where it could be fixed.

(And apologies for the formatting, I was requested in last years bug report not to use backticks to make it easier to read).

[guest20]

The request was to not put your whole report in backticks, not to never use back ticks.

The point is that regular old english text does not need to be wrapped in a code tag.

[hmartink]

Sorry for the late reply.

Thanks for the clarification. However, we translators use the entire UTF-8 code range, and never provide code (unless in examples), so the concept of "old english text" does not make sense (anymore). For us, every character should be treated verbatim, hence I'm almost always use the backticks to ensure the characters are shown as is.

[hmartink]

This means, that "Module::CoreList" should be replaced by the proper man pages reference, which is formatted in bold and the section is appended in parenthesis.

This sounds like most of your bug reports should be replaced by a single bug report to podlators (specifically the Pod::Man module in it), to make it generate links to modules differently.

We have man pages from over 100 upstreams, with a wide variety of documentation tool chains. I don't have the knowledge and ressources to trace each and everyone.

What I can do is to ignore certain issues, e.g. these kind of internal man page links, if you don't have the ressources (or desire) to report them to the respective tool. Simply tell me so (e.g. in the threads on perl-porters, I started last week).

[guest20]

Sorry for the late reply.

lmao, there are bugs in this tracker that are 20 years old. We can wait a week.

"old english text"

Sorry, I didn't mean "text from ye olde english", or "text in an old encoding like ascii or latin-1". I just mean "regular old" (as in "plan") "english text" (as in "prose"), that is the text that's not verbatim data or examples of code / terminal sessions etc.

The point of this distinction is mainly to stop github's markdown and auto-linking from interpreting your data as html, formatting instructions or links to other issues, but it's also helpful for readers when you start using bits of code inside your sentences

Here are examples from this github issue/email:

Your intro "Dear Perl maintainer," is "prose"

Your explanation about the nature of your project is "prose"

Your field labels are prose, but the issue descriptions are data:

Issue 1: perl5123delta → B(1perl)
Issue 2: perl5120delta → B(1perl)

The text below the "issue" names is"prose" in the context of an issue, so they get the verbatim markers:

"If you are upgrading from an earlier release such as 5.12.2, first read "
"perl5123delta, which describes differences between 5.12.2 and 5.12.3. The "
"major changes made in 5.12.0 are described in perl5120delta."

For us, every character should be treated verbatim

This is 100% true for code written in perl too, single characters make a big difference in this language.