Rearranging and revising the "open" section of perlfunc.pod for clarity

[jmacdotorg]

The open section of the perlfunc manual page comprises a single, very long section of text, interspersed with example-code blocks, covering many features of this complex and core Perl function. While every individual sentence or example within this text is factually accurate, the whole page makes for quite a daunting read. It runs for the length-equivalent of six printed pages with no sub-headings, frequently changing its focus on different aspects of open while not necessarily clarifying which construe common cases or best practices.

This pull request proposes revisions to address these issues. It aims to make this documentation section more approachable to Perl newcomers, without losing its value as a thorough reference.

Most significantly, this work rearranges the content into several nested sub-sections. Since perlfunc lists all its functions as =item entries within one single and enormously long =over/=back pair, I have implemented these sub-sections as =over/=back sub-lists, with =items serving as headers. (A handful of other perlfunc sections, such as eval, do something like this already.)

I ordered these sections, and rearranged the existing documentation under them, so as to put open best practices and most-common use-cases first. After it explains using open with normal files, the text describes somewhat less-common use-cases of opening filehandles into commands and scalar references, before getting into rarer uses like duping. It ends with "legacy syntax" of calling open with less than three arguments, and then a miscellany of other considerations and cross-references.

While most of the text is unchanged from that currently found in blead, I did add or update some text for the sake of improved flow within this new arrangement. I also took the liberty to rewrite the introductory paragraphs, prior to the first sub-header, making an effort to define and demystify "filehandle" as soon as possible.

An aside, for transparency's sake: I submit this work as part of a TPF-funded project, whose original proposal you can read online.

[Grinnz]

Nice improvement overall. 👍

[Grinnz]

FYI the test failures are from pod checker:

#   "Verbatim line length including indents exceeds 79 by"  (10 occurrences, expected 0)
#     +7 (including 12 from =over's) near line 4501 of pod/perlfunc.pod
#     +3 (including 12 from =over's) near line 4547 of pod/perlfunc.pod
#     +2 (including 8 from =over's) near line 4615 of pod/perlfunc.pod
#     +4 (including 8 from =over's) near line 4680 of pod/perlfunc.pod
#     +4 (including 8 from =over's) near line 4684 of pod/perlfunc.pod
#     +3 (including 8 from =over's) near line 4750 of pod/perlfunc.pod
#     +3 (including 8 from =over's) near line 4751 of pod/perlfunc.pod
#     +4 (including 8 from =over's) near line 4753 of pod/perlfunc.pod
#     +1 (including 12 from =over's) near line 4832 of pod/perlfunc.pod
#     +2 (including 12 from =over's) near line 4902 of pod/perlfunc.pod
#   "line containing nothing but whitespace in paragraph"  (4 occurrences, expected 0)
#      near line 4472 of pod/perlfunc.pod
#      near line 4488 of pod/perlfunc.pod
#      near line 4500 of pod/perlfunc.pod
#      near line 4655 of pod/perlfunc.pod

Basically a bunch of your lines are too long because they are in nested =over, and the other ones are probably lines with trailing whitespace.