From rwstauner@cpan.org

Make reference to "the bytes pragma" an actual link.
Explicitly word "the utf8 pragma" for consistency.
The *roff implementation (perldoc cli) displayed `you can use the "utf8".`

From rwstauner@cpan.org

From 0e3bac8191fb5a2e358864048fdf79ec0850e07c Mon Sep 17 00:00:00 2001
From: Randy Stauner <rwstauner@cpan.org>
Date: Wed, 18 Mar 2015 19:55:11 -0700
Subject: [PATCH] Present utf8 and bytes pragmas consistently in perlport

---
 pod/perlport.pod | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/pod/perlport.pod b/pod/perlport.pod
index 62443d6..d2c4455 100644
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -682,12 +682,12 @@ about what bytes they are.  Someone might for example be using your
 code under a UTF-8 locale, in which case random native bytes might be
 illegal ("Malformed UTF-8 ...")  This means that for example embedding
 ISO 8859-1 bytes beyond 0x7f into your strings might cause trouble
-later.  If the bytes are native 8-bit bytes, you can use the C<bytes>
-pragma.  If the bytes are in a string (regular expressions being
+later.  If the bytes are native 8-bit bytes, you can use L<< the C<bytes>
+pragma|bytes >>.  If the bytes are in a string (regular expressions being
 curious strings), you can often also use the C<\xHH> or more portably,
 the C<\N{U+HH}> notations instead
 of embedding the bytes as-is.  If you want to write your code in UTF-8,
-you can use L<utf8>.
+you can use L<< the C<utf8> pragma|utf8 >>.
 
 =head2 System Resources
 
-- 
2.2.2

From @jkeenan

On Wed Mar 18 20​:17​:09 2015, rwstauner wrote​:

Make reference to "the bytes pragma" an actual link.
Explicitly word "the utf8 pragma" for consistency.
The *roff implementation (perldoc cli) displayed `you can use the "utf8".`

I'm not sure that the POD formatting for this is correct.

When I search the pod/ directory for instances which match the pattern in the patch, this is what I get​:

#####
$ ack 'L<<.*?C<.*?>.*?\|.*?>>' pod
pod/perlsub.pod
284​:L<< C<import> | perlfunc/use >>, L<< C<unimport> | perlfunc/use >>,
285​:L<< C<INC> | perlfunc/require >>
#####

... which is this part of 'perlsub'

#####
=item documented in L<perlfunc>

L<< C<import> | perlfunc/use >>, L<< C<unimport> | perlfunc/use >>,
L<< C<INC> | perlfunc/require >>
#####

Now, I don't regularly generate or read POD in HTML format. When I do, it's at perldoc.perl.org. When I go to the 'perlsub' page there (http​://perldoc.perl.org/perlsub.html), what I see in my browser (Firefox) is this​:

#####
documented in perlfunc

use, use, require
#####

In other words, the strings 'import', 'unimport' and 'INC' vanish. I don't know whether this is some peculiarity of this web site, or whether the L<<C<something>|podsection/podsubsection>> syntax is simply wrong. Perhaps we only need a single '<' and a single '>' at the ends, rather than doubles.

Any ideas?

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

The RT System itself - Status changed from 'new' to 'open'

From rwstauner@cpan.org

Wow, that (perldoc.perl.org) is bizarre. I've never noticed that before.
I'm not sure what perldoc.perl.org uses for parsing/formatting, but
Pod​::Simple seems to parse the syntax as I understand it​:

https://metacpan.org/pod/perlsub#documented-in-perlfunc
http​://search.cpan.org/~shay/perl-5.20.2/pod/perlsub.pod#documented_in_perlfunc

The double angles on the outside are what enable the single angles on
the inside.
I used the syntax because I found other instances of double brackets
surrounding single brackets elsewhere in perlport.pod so I figured
it's use in core was acceptable.
Additionally it kept the text of `the "bytes" pragma` the same and
merely added the link.

So, anybody know what pod parser perldoc.perl.org uses?

On Thu, Mar 19, 2015 at 5​:49 PM, James E Keenan via RT
<perlbug-followup@​perl.org> wrote​:

On Wed Mar 18 20​:17​:09 2015, rwstauner wrote​:

Make reference to "the bytes pragma" an actual link.
Explicitly word "the utf8 pragma" for consistency.
The *roff implementation (perldoc cli) displayed `you can use the "utf8".`

I'm not sure that the POD formatting for this is correct.

When I search the pod/ directory for instances which match the pattern in the patch, this is what I get​:

#####
$ ack 'L<<.*?C<.*?>.*?\|.*?>>' pod
pod/perlsub.pod
284​:L<< C<import> | perlfunc/use >>, L<< C<unimport> | perlfunc/use >>,
285​:L<< C<INC> | perlfunc/require >>
#####

... which is this part of 'perlsub'

#####
=item documented in L<perlfunc>

L<< C<import> | perlfunc/use >>, L<< C<unimport> | perlfunc/use >>,
L<< C<INC> | perlfunc/require >>
#####

Now, I don't regularly generate or read POD in HTML format. When I do, it's at perldoc.perl.org. When I go to the 'perlsub' page there (http​://perldoc.perl.org/perlsub.html), what I see in my browser (Firefox) is this​:

#####
documented in perlfunc

use, use, require
#####

In other words, the strings 'import', 'unimport' and 'INC' vanish. I don't know whether this is some peculiarity of this web site, or whether the L<<C<something>|podsection/podsubsection>> syntax is simply wrong. Perhaps we only need a single '<' and a single '>' at the ends, rather than doubles.

Any ideas?

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

---
via perlbug​: queue​: perl5 status​: new
https://rt-archive.perl.org/perl5/Ticket/Display.html?id=124115

From @craigberry

On Thu, Mar 19, 2015 at 10​:03 PM, Randy Stauner <rwstauner@​cpan.org> wrote​:

So, anybody know what pod parser perldoc.perl.org uses?

I'm guessing the answer is here​:

https://github.com/jonallen/perldoc.perl.org

but I have not looked carefully.

From rwstauner@cpan.org

Thanks!

Looks like it's using Pod​::POM which has several open rt tickets about
nested angle brackets​:
https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-POM

On Thu, Mar 19, 2015 at 8​:34 PM, Craig A. Berry <craig.a.berry@​gmail.com> wrote​:

On Thu, Mar 19, 2015 at 10​:03 PM, Randy Stauner <rwstauner@​cpan.org> wrote​:

So, anybody know what pod parser perldoc.perl.org uses?

I'm guessing the answer is here​:

https://github.com/jonallen/perldoc.perl.org

but I have not looked carefully.

From rwstauner@cpan.org

In this instance perldoc.perl.org looks like it would display the
change properly
(perhaps because the text and the target are the same module, unlike
in perlsub).
Using the afore-linked github repo, i compared blead perldocs to this
patch, and the relevant changes are

-you can use the <code class="inline"><span
class="w">bytes</span></code> pragma.
+you can use <a href="bytes.html">the bytes pragma</a>

and

-you can use <a href="utf8.html">utf8</a>.</p>
+you can use <a href="utf8.html">the utf8 pragma</a>.</p>

The inline tags (making "bytes" appear in fixed-width) are lost, but
the text is the same and the link is added.
The inline tag stripping is deliberate​:
(https://github.com/jonallen/perldoc.perl.org/blob/master/lib/Perldoc/Convert/html.pm#L258-L259)

  # Naively remove HTML tags from link text (tags screw up formatting...)
  $link =~ s/<.*?>//sg;

For utf8, it merely adds "the" and "pragma". This reads consistently
with "the bytes pragma"
and as I said, the real reason I offered the change was to fix the
*nroff formatting of "you can use the utf8." to add the word
"pragma".

Would anyone prefer it be worded or formatted differently?

On Thu, Mar 19, 2015 at 8​:52 PM, Randy Stauner <rwstauner@​cpan.org> wrote​:

Thanks!

Looks like it's using Pod​::POM which has several open rt tickets about
nested angle brackets​:
https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-POM

On Thu, Mar 19, 2015 at 8​:34 PM, Craig A. Berry <craig.a.berry@​gmail.com> wrote​:

On Thu, Mar 19, 2015 at 10​:03 PM, Randy Stauner <rwstauner@​cpan.org> wrote​:

So, anybody know what pod parser perldoc.perl.org uses?

I'm guessing the answer is here​:

https://github.com/jonallen/perldoc.perl.org

but I have not looked carefully.

From rwstauner@cpan.org

We could also make it simpler by just doing​: "the L< bytes|bytes > pragma".
It would read the same, only the actual module name would be a link,
and there'd be no embedded pod codes,
however there would also be no "code" style for the words.

On Fri, Mar 20, 2015 at 10​:28 PM, Randy Stauner <rwstauner@​cpan.org> wrote​:

In this instance perldoc.perl.org looks like it would display the
change properly
(perhaps because the text and the target are the same module, unlike
in perlsub).
Using the afore-linked github repo, i compared blead perldocs to this
patch, and the relevant changes are

-you can use the <code class="inline"><span
class="w">bytes</span></code> pragma.
+you can use <a href="bytes.html">the bytes pragma</a>

and

-you can use <a href="utf8.html">utf8</a>.</p>
+you can use <a href="utf8.html">the utf8 pragma</a>.</p>

The inline tags (making "bytes" appear in fixed-width) are lost, but
the text is the same and the link is added.
The inline tag stripping is deliberate​:
(https://github.com/jonallen/perldoc.perl.org/blob/master/lib/Perldoc/Convert/html.pm#L258-L259)

 \# Naively remove HTML tags from link text \(tags screw up formatting\.\.\.\)
 $link =~ s/\<\.\*?>//sg;

For utf8, it merely adds "the" and "pragma". This reads consistently
with "the bytes pragma"
and as I said, the real reason I offered the change was to fix the
*nroff formatting of "you can use the utf8." to add the word
"pragma".

Would anyone prefer it be worded or formatted differently?

On Thu, Mar 19, 2015 at 8​:52 PM, Randy Stauner <rwstauner@​cpan.org> wrote​:

Thanks!

Looks like it's using Pod​::POM which has several open rt tickets about
nested angle brackets​:
https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-POM

On Thu, Mar 19, 2015 at 8​:34 PM, Craig A. Berry <craig.a.berry@​gmail.com> wrote​:

On Thu, Mar 19, 2015 at 10​:03 PM, Randy Stauner <rwstauner@​cpan.org> wrote​:

So, anybody know what pod parser perldoc.perl.org uses?

I'm guessing the answer is here​:

https://github.com/jonallen/perldoc.perl.org

but I have not looked carefully.

From @mauke

On Mon Mar 30 07​:12​:59 2015, rwstauner wrote​:

We could also make it simpler by just doing​: "the L< bytes|bytes >
pragma".
It would read the same, only the actual module name would be a link,
and there'd be no embedded pod codes,
however there would also be no "code" style for the words.

I hadn't noticed this ticket before, but I've applied commit 83a46a6 to blead. I believe this obsoletes the ticket and patch (the wording now includes "the utf8 pragma").

From rwstauner@cpan.org

On Sat Jul 30 14​:29​:29 2016, mauke- wrote​:

I hadn't noticed this ticket before, but I've applied commit
83a46a6 to blead. I believe this
obsoletes the ticket and patch (the wording now includes "the utf8
pragma").

LGTM. Thanks!

@mauke - Status changed from 'open' to 'pending release'

From @khwilliamson

Thank you for filing this report. You have helped make Perl better.

With the release today of Perl 5.26.0, this and 210 other issues have been
resolved.

Perl 5.26.0 may be downloaded via​:
https://metacpan.org/release/XSAWYERX/perl-5.26.0

If you find that the problem persists, feel free to reopen this ticket.

@khwilliamson - Status changed from 'pending release' to 'resolved'