perlfunc overhaul

- remove trailing whitespace
- consistently refer to builtins as C<foo>, not foo() or C<foo()>
- hyperlink each C<foo> builtin to its section in perlfunc
- replace some occurrences of -w with a reference to the warnings pragma
- refer to listy comma as "list concatenation" because that's what it
  does
- consistently hyperlink references to external programs (L<touch(1)>),
  system calls (L<fork(2)>), and library functions (L<fdopen(3)>)
- hyperlink variables to their section in perlvar
- hyperlink the names of modules/pragmas
- hyperlink names of functions provided by modules (where possible)
- consistently use "pragmas", not "pragmata" (there were only two of
  those)
- use the same wording for all conditional builtins / features
- -T and -B are file tests, not switches
- remove "see L</open>" (regarding the ':encoding' layer) from
  description of binmode because I don't see why it was there
- refer to variables as C<$foo>, not $foo
- hyperlink some error messages to perldiag
- remove & from subroutine calls
- grammar: write "if X, Y" with a comma and "Y if X" without
- use 'my' in examples when introducing new variables
- 'while (', not 'while('
- don't capitalize the next word after a semicolon
- consistently start error messages (die/warn) with "Can't" (not
  "can't", "Cannot", or "cannot")
- replace bareword filehandles by normal variables in examples
- add missing ')'
- fix module names: IPC::SysV::Msg -> IPC::Msg, IPC::SysV::Semaphore ->
  IPC::Semaphore
- 'open': replace note about binmode with equivalent paragraph from
  'binmode' (the one in 'open' claimed unix systems don't need binmode,
  which is not true with encodings)
- 'open': delete overly clever example of generating filehandle names in
  a recursive function (this is a non-issue with lexical filehandles)
- 'open': instead of running 'perl -V' and looking for the useperlio
  line, you can just run 'perl -V:useperlio'
- 'open': mention shell feature of 'yourscript.pl <( other command )',
  which makes the only remaining use of 2-arg open redundant
- 'open': sysopen uses different modes than open; they're not "subtly
  different" and there's no "may" about it
- 'open': use $fh->autoflush(1) instead of select/$| dance (especially
  since the example already loads IO::Handle for no reason)
- 'printf': remove garbled text ("Look for this throught pod")
- change "use locale 'not_characters'" to the correct "use locale
  ':not_characters'"
- (hopefully) fix inconsistent use of "real filehandle"; use "bareword
  filehandle" instead to distinguish from scalar variables / globrefs
- ":encoding" is a layer, not a pragma
- 'readline': actually use readline in examples
- ?...? is no longer valid; use m?...? instead
- 'sort': whether the algorithm is stable has no effect on runtime
  complexity, so "That algorithm was not stable, so I<could> go
  quadratic" is nonsense
- 'sort': declaring $a/$b as lexicals is an error regardless of strict
- 'sysopen': as far as I can tell the note about depending on fdopen()
  is only true for non-PerlIO builds
- 'use': add an example of what 'use Module VERSION' expands to
- add 'select FILEHANDLE' to filehandle related functions

Also touch ext/Pod-Functions/Functions_pm.PL to make it parse
L<C<foo>|...> in the overview paragraphs.

And teach t/porting/podcheck.t about a ton of man pages and some
external modules.

2 files changed, 9 insertions, 6 deletions

diff --git a/ext/Pod-Functions/Functions_pm.PL b/ext/Pod-Functions/Functions_pm.PL
index 04bf5bcd8b..af5d37a5f8 100644
--- a/ext/Pod-Functions/Functions_pm.PL
+++ b/ext/Pod-Functions/Functions_pm.PL
@@ -58,13 +58,16 @@ foreach my $TL_node (@$tree[2 .. $#$tree]) {
 
             foreach my $func (@$para[2 .. $#$para]) {
                 next unless ref $func eq 'ARRAY';
-                die "Expected only C<> blocks in paragraph after item at $TL_node->[$i-2][1]{start_line}"
-                    unless $func->[0] eq 'C' && !ref $func->[2];
-                # Everything is plain text (ie $func->[2] is everything)
+                my $c_node =
+                    $func->[0] eq 'C' && !ref $func->[2] ? $func :
+                    $func->[0] eq 'L' && ref $func->[2]
+                        && $func->[2][0] eq 'C' && !ref $func->[2][2] ? $func->[2] :
+                    die "Expected only C<> blocks in paragraph after item at $TL_node->[$i-2][1]{start_line}";
+                # Everything is plain text (ie $c_node->[2] is everything)
                 # except for C<-I<X>>. So untangle up to one level of nested <>
                 my $funcname = join '', map {
                     ref $_ ? $_->[2] : $_
-                } @$func[2..$#$func];
+                } @$c_node[2..$#$c_node];
                 $funcname =~ s!(q.?)//!$1/STRING/!;
                 push @{$Kinds{$text}}, $funcname;
             }
@@ -204,7 +207,7 @@ L<perlfunc/"Perl Functions by Category"> section.
 
 =cut
 
-our $VERSION = '1.09';
+our $VERSION = '1.10';
 
 require Exporter;
 
diff --git a/ext/Pod-Functions/t/Functions.t b/ext/Pod-Functions/t/Functions.t
index 6758202437..2beccc1ac6 100644
--- a/ext/Pod-Functions/t/Functions.t
+++ b/ext/Pod-Functions/t/Functions.t
@@ -110,7 +110,7 @@ Functions for fixed-length data or records:
 Functions for filehandles, files, or directories:
      -X, chdir, chmod, chown, chroot, fcntl, glob, ioctl, link,
      lstat, mkdir, open, opendir, readlink, rename, rmdir,
-     stat, symlink, sysopen, umask, unlink, utime
+     select, stat, symlink, sysopen, umask, unlink, utime
 
 Keywords related to the control flow of your Perl program:
      __FILE__, __LINE__, __PACKAGE__, __SUB__, break, caller,