This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfunc overhaul
authorLukas Mai <l.mai@web.de>
Sat, 27 Feb 2016 04:17:57 +0000 (05:17 +0100)
committerLukas Mai <l.mai@web.de>
Sat, 27 Feb 2016 08:22:40 +0000 (09:22 +0100)
commit2263ed233c353b5d6d0140b67c1528c3a9509b4b
treecf3aeb1282a348523452155235573c63dfbf52d9
parenta7629b1f1e427a2940c7d4d09d73c2d8e5c937c0
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.
ext/Pod-Functions/Functions_pm.PL
ext/Pod-Functions/t/Functions.t
pod/perlfunc.pod
t/porting/known_pod_issues.dat