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.

1 files changed, 65 insertions, 0 deletions

diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index dbf52044e7..14c0bb9b05 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -12,11 +12,14 @@
 #   known instances of that message there are in the pod.  -1 means that the
 #   program can expect any number of this type of message.
 _control87(3)
+accept(2)
+access(2)
 Algorithm::C3
 AnyEvent
 Apache::MP3
 Archive::Extract
 Array::Base
+atan2(3)
 Attribute::Constant
 autobox
 B::Generate
@@ -25,6 +28,7 @@ B::Lint::Debug
 B::Utils
 basename(1)
 Benchmark::Perl::Formance
+bind(2)
 ByteLoader
 bzip2(1)
 Carp::Always
@@ -32,6 +36,8 @@ Carp::Assert
 Carp::Clan
 CGI
 chcp(1)
+chmod(2)
+chown(2)
 Class::Accessor
 Class::C3
 Class::ISA
@@ -39,13 +45,18 @@ Class::PseudoHash
 Class::Tiny
 Class::Tiny::Antlers
 Classic::Perl
+clearerr(3)
 Clone
+closedir(2)
+connect(2)
 Coro
 cpan2dist(1)
 CPAN::Changes::Spec
 cpanp(1)
 CPANPLUS
+crypt(3)
 Crypt::Random
+ctime(3)
 curl(1)
 Dancer
 Data::Alias
@@ -60,6 +71,8 @@ DateTime
 DB_File(3)
 DBI
 DBIx::Profile
+dbm(3)
+dbm_open(3)
 Devel::CallParser
 Devel::Callsite
 Devel::Cover
@@ -70,13 +83,22 @@ Devel::NYTProf
 Devel::PPPort
 Devel::SawAmpersand
 Devel::Spy
+dirfd(3)
 dirname(1)
+dup(2)
 Encode::Detect
 Encode::Locale
 Eval::WithLexicals
+execvp(3)
 Exporter::Easy
 ExtUtils::Constant::ProxySubs
+fchdir(2)
+fchmod(2)
+fchown(2)
+fcntl(2)
+fdopen(3)
 fetch(1)
+fgrep(1)
 File::chdir
 File::Copy::Recursive
 File::Findgrep
@@ -84,13 +106,25 @@ File::Map
 File::MMagic
 File::ShareDir
 find(1)
+flock(2)
 flock(3)
+fopen(3)
+fork(2)
+fread(3)
+fseek(3)
 fsync(3c)
 Function::Parameters
+futimes(2)
 Future
 gcc(1)
+gdbm(3)
 Getopt::Std
+getpgrp(2)
 getpriority(2)
+getpwnam(3)
+getsockopt(2)
+gettimeofday(2)
+grep(1)
 Hook::LexWrap
 HTML::StripScripts
 HTTP::Lite
@@ -99,7 +133,9 @@ iconv(3)
 inetd(8)
 invoker
 IO::Socket::IP
+ioctl(2)
 IPC::Run
+IPC::Shareable
 IPC::Signal
 kill(3)
 langinfo(3)
@@ -110,12 +146,15 @@ Lingua::KO::Hangul::Util
 Lingua::KO::Romanize::Hangul
 Lingua::ZH::Romanize::Pinyin
 List::Gather
+listen(2)
 local::lib
+lockf(3)
 Log::Message
 Log::Message::Config
 Log::Message::Handlers
 Log::Message::Item
 Log::Message::Simple
+lseek(2)
 LWP::ConsoleLogger
 Mail::Send
 Mail::SpamAssassin
@@ -142,6 +181,9 @@ Module::Starter
 Moo
 Moose
 MRO::Compat
+msgctl(2)
+msgget(2)
+ndbm(3)
 NgxQueue
 nl_langinfo(3)
 Number::Format
@@ -177,6 +219,7 @@ Pod::Plainer
 Pod::PXML
 poll(2)
 prctl(2)
+printenv(1)
 printf(3)
 provide
 pstruct
@@ -184,16 +227,31 @@ ptar(1)
 ptargrep(1)
 pwd_mkdb(8)
 RDF::Trine
+read(2)
 Readonly
+recvfrom(2)
 recvmsg(3)
+rename(2)
 Role::Tiny
 s2p
 Scalar::Readonly
+sdbm(3)
+select(2)
+semctl(2)
+semget(2)
 Semi::Semicolons
+semop(2)
 sendmail(1)
+sendmsg(2)
 sendmsg(3)
+sendto(2)
+setitimer(2)
 setlocale(3)
+setpgid(2)
+setpgrp(2)
+setpriority(2)
 sha1sum(1)
+shadow(3)
 Shell
 Shell::Command
 sock_init(3)
@@ -209,6 +267,7 @@ String::Scanf
 Switch
 tar(1)
 Template::Declare
+Term::ReadKey
 Term::UI
 Term::UI::History
 Test::Harness::TAP
@@ -222,8 +281,10 @@ Text::Unidecode
 Time::Object
 Tk
 Tk::Pod
+touch(1)
 tr(1)
 tty(1)
+umask(2)
 Unicode::CaseFold
 Unicode::Casing
 Unicode::GCString
@@ -233,12 +294,16 @@ Unicode::Semantics
 Unicode::Tussle
 Unicode::Unihan
 unzip(1)
+utime(2)
 Version::Requirements
 wait(2)
+wait4(2)
+waitpid(2)
 waitpid(3)
 Want
 wget(1)
 Win32::Locale
+write(2)
 XML::LibXML
 YAML
 YAML::Syck