Final Report - Revising Perl's open and perlopentut manual pages
Thu, 07-May-2020 by
Jason A. Crome
edit post
<![CDATA[
Jason McIntosh has completed work on the grant for revising Perl's open and perlopentut manual pages. He writes:
> I ultimately delivered this work as two pull requests into Perl's GitHub repository: https://github.com/Perl/perl5/pull/17717, which covers revisions to the "open" section of perlfunc.pod, and https://github.com/Perl/perl5/pull/17726, which replaces the three "To Be Announced" sections at the end of perlopentut.pod. I made these pull requests under the very helpful guidance of the folks in the #p5p channel on irc.perl.org. Dan Book and Karen Etheridge reviewed the work on GitHub.
>
> As my descriptions on those two pages state, my perlfunc.pod edits primarily involved "refactoring" the existing text so that the entry led with common cases and best practices before continuing into less-common cases, legacy syntax, and noteworthy-but-miscellaneous concerns. I reordered the paragraphs and examples into a new structure of nested subsections with headings -- a little tricky, given the confines of perlfunc.pod, but I ended up pleased with the results. I also rewrote the introductory section to more quickly define and clarify filehandles, as a basic concept.
>
> For perlopentut.pod, I left all the existing text exactly as I found it, up to the first of the three "To Be Announced" placeholders at the end of the document. Here, I wrote a new tutorial section under the existing header "Opening Pipes". Then I simply deleted the placeholder about using sysopen (since it literally suggested that it might get deleted in the future), and replaced the "SEE ALSO" placeholder with a simple cross-reference back to the "open" section of perlfunc.
>
> I performed this work during the first two full weeks of April. I assert that it hews closely to the plans described in my original grant proposal. With these documentation patches formally proposed to and reviewed by the p5p team via GitHub, I consider the project delivered.
]]>
Comments (0)
