PATCH perl.pod: Suggested reorganization of table of contents

Message-Id: <20011018102535.19264.qmail@plover.com>

p4raw-id: //depot/perl@12490

diff --git a/pod/perl.pod b/pod/perl.pod
index 57416bc..72b5343 100644 (file)
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -18,53 +18,67 @@ navigate the rest of Perl's extensive documentation.
 
 For ease of access, the Perl manual has been split up into several sections.
 
+=head2 Overview
+
     perl               Perl overview (this section)
     perlintro          Perl introduction for beginners
-    perlfaq            Perl frequently asked questions
     perltoc            Perl documentation table of contents
-    perlbook           Perl book information
 
+
+=head2 Tutorials
+
+    perlfaq            Perl frequently asked questions
+      perlfaq1         General Questions About Perl
+      perlfaq2         Obtaining and Learning about Perl
+      perlfaq3         Programming Tools
+      perlfaq4         Data Manipulation
+      perlfaq5         Files and Formats
+      perlfaq6         Regexes
+      perlfaq7         Perl Language Issues
+      perlfaq8         System Interaction
+      perlfaq9         Networking
+  
+    perlrequick                Perl regular expressions quick start
+    perlretut          Perl regular expressions tutorial
+
+    perlreftut         Perl references short introduction
+    perldsc            Perl data structures intro
+    perllol            Perl data structures: arrays of arrays
+
+    perldebtut         Perl debugging tutorial
+
+    perlopentut                Perl open() tutorial
+
+    perlboot           Perl OO tutorial for beginners
+    perltoot           Perl OO tutorial, part 1
+    perltootc          Perl OO tutorial, part 2
+    perlbot            Perl OO tricks and examples
+
+=head2 Reference Manual
     perlsyn            Perl syntax
     perldata           Perl data structures
     perlop             Perl operators and precedence
     perlsub            Perl subroutines
-    perlfunc           Perl builtin functions
-    perlreftut         Perl references short introduction
-    perldsc            Perl data structures intro
-    perlrequick                Perl regular expressions quick start
+    perlfunc           Perl built-in functions
     perlpod            Perl plain old documentation
-    perlstyle          Perl style guide
-    perltrap           Perl traps for the unwary
-
     perlrun            Perl execution and options
     perldiag           Perl diagnostic messages
     perllexwarn                Perl warnings and their control
-    perldebtut         Perl debugging tutorial
     perldebug          Perl debugging
-
     perlvar            Perl predefined variables
-    perllol            Perl data structures: arrays of arrays
-    perlopentut                Perl open() tutorial
-    perlretut          Perl regular expressions tutorial
-
     perlre             Perl regular expressions, the rest of the story
     perlref            Perl references, the rest of the story
-
     perlform           Perl formats
-
-    perlboot           Perl OO tutorial for beginners
-    perltoot           Perl OO tutorial, part 1
-    perltooc           Perl OO tutorial, part 2
     perlobj            Perl objects
-    perlbot            Perl OO tricks and examples
     perltie            Perl objects hidden behind simple variables
+      perldbmfilter    Perl DBM filters
 
     perlipc            Perl interprocess communication
     perlfork           Perl fork() information
     perlnumber         Perl number semantics
 
     perlthrtut         Perl threads tutorial
-    perlothrtut                Perl old threads tutorial
+      perlothrtut              Perl threads tutorial
 
     perlport           Perl portability guide
     perllocale         Perl locale support
@@ -74,23 +88,19 @@ For ease of access, the Perl manual has been split up into several sections.
     perlsec            Perl security
 
     perlmod            Perl modules: how they work
-    perlmodinstall     Perl modules: how to install from CPAN
     perlmodlib         Perl modules: how to write and use
     perlmodstyle       Perl modules: how to write modules with style
+    perlmodinstall     Perl modules: how to install from CPAN
     perlnewmod         Perl modules: preparing a new module for distribution
 
-    perlfaq1           General Questions About Perl
-    perlfaq2           Obtaining and Learning about Perl
-    perlfaq3           Programming Tools
-    perlfaq4           Data Manipulation
-    perlfaq5           Files and Formats
-    perlfaq6           Regexes
-    perlfaq7           Perl Language Issues
-    perlfaq8           System Interaction
-    perlfaq9           Networking
+    perlutil           utilities packaged with the Perl distribution
 
     perlcompile                Perl compiler suite intro
 
+    perlfilter         Perl source filters
+
+=head2 Internals and C Language Interface
+
     perlembed          Perl ways to embed perl in your C or C++ application
     perldebguts                Perl debugging guts and tips
     perlxstut          Perl XS tutorial
@@ -98,16 +108,21 @@ For ease of access, the Perl manual has been split up into several sections.
     perlclib           Internal replacements for standard C library functions
     perlguts           Perl internal functions for those doing extensions
     perlcall           Perl calling conventions from C
-    perlutil           utilities packaged with the Perl distribution
-    perlfilter         Perl source filters
-    perldbmfilter      Perl DBM filters
+
     perlapi            Perl API listing (autogenerated)
     perlintern         Perl internal functions (autogenerated)
     perliol            C API for Perl's implementation of IO in Layers
     perlapio           Perl internal IO abstraction interface
-    perltodo           Perl things to do
+
     perlhack           Perl hackers guide
 
+=head2 Miscellaneous
+
+    perlbook           Perl book information
+    perlstyle          Perl style guide
+    perltrap           Perl traps for the unwary
+    perltodo           Perl things to do
+
     perlhist           Perl history records
     perldelta          Perl changes since previous version
     perl572delta       Perl changes in version 5.7.2
@@ -117,6 +132,8 @@ For ease of access, the Perl manual has been split up into several sections.
     perl5005delta      Perl changes in version 5.005
     perl5004delta      Perl changes in version 5.004
 
+=head2 Platform-Specific
+
     perlaix            Perl notes for AIX
     perlamiga          Perl notes for AmigaOS
     perlapollo         Perl notes for Apollo DomainOS
@@ -146,8 +163,6 @@ For ease of access, the Perl manual has been split up into several sections.
     perlvos            Perl notes for Stratus VOS
     perlwin32          Perl notes for Windows
 
-(If you're intending to read these straight through for the first time,
-the suggested order will tend to reduce the number of forward references.)
 
 By default, the manpages listed above are installed in the 
 F</usr/local/man/> directory.