PATCH perl.pod: Suggested reorganization of table of contents

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

p4raw-id: //depot/perl@12490

1 files changed, 53 insertions, 38 deletions

diff --git a/pod/perl.pod b/pod/perl.pod
index 57416bcd6c..72b534318c 100644
--- 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.