Some organizational tweaks

S16-io.pod

@@ -9,19 +9,17 @@ Synopsis 16: I/O
 
     Created: 12 Sep 2006
 
-    Last Modified: 4 Jan 2015
+    Last Modified: 5 Jan 2015
     Version: 29
 
 Many of these functions will work as in Perl 5, except we're trying to
 rationalize everything into roles.  For now you can assume most of the
 important functions will automatically be in the C<CORE::> namespace.
 However, with IO operations in particular, many of them are really very
 basic global functions (terms) which take or generate a handle.  These
-functions can be accessed using a method interface as well, of course.
+functions can be accessed using a method interface as well.
 
-=head1 IO
-
-=head2 Overridable IO handles
+=head1 Overridable IO handles
 
 In Perl 6, there are the I<standard> IO handles, and any number of overriding
 inner filehandles for the same symbol.
@@ -75,7 +73,7 @@ In short:
     read                      binary reading (Buf)
     write                     binary writing (Buf)
 
-=head2 A changing world
+=head1 A changing world
 
 The world in which we expect Perl 6 to operate, has changed significantly in
 the past 10 years.  From an I/O point of view, there are no operating systems
@@ -102,7 +100,7 @@ difference between path names that are directories, and path names that
 aren't.  Directories are always represented with a trailing slash (C<"/">),
 others will never have a trailing slasl.
 
-=head2 Path Names and the .IO coercer
+=head1 Path Names and the .IO coercer
 
 Path names are just strings (C<Str>).  Methods that return path names, will
 just return strings.  As soon as you need to do manipulation on the path name
@@ -133,7 +131,7 @@ coercer returns one of 4 object types:
 All these classes are consumers of the C<IO::Locally> role, which provided all
 of the methods that have to do with paths (such as C<.basename>).
 
-=head2 $*CWD and chdir()
+=head1 $*CWD and chdir()
 
 The dynamic variable $*CWD is an C<IO::Dir> object representing the current
 working directory.  It is normally set with the C<chdir()> function, which will
@@ -166,7 +164,7 @@ or you can use C<chdir()> with a temporary C<$*CWD>:
   }
   ... your code in original $*CWD again ...
 
-=head2 $*TMPDIR and tmpdir()
+=head1 $*TMPDIR and tmpdir()
 
 The dynamic variable C<$*TMPDIR> is an C<IO::Dir> object which points to the
 system's directory for temporary files.  It can be set with the C<tmpdir()>
@@ -190,7 +188,7 @@ appropriate C<Failure>.
 The initialization of C<$*TMPDIR> at startup is set depending on the OS you're
 on.
 
-=head2 $*HOME and homedir()
+=head1 $*HOME and homedir()
 
 The dynamic variable C<$*HOME> is an C<IO::Dir> object which points to the
 user's home directory.  It can be set with the C<homedir()> function
@@ -213,14 +211,14 @@ appropriate C<Failure>.
 
 The initialization of C<$*HOME> at startup is set depending on the OS you're on.
 
-=head2 Functions and Classes
+=head1 Functions, Roles and Classes
 
 The functions and classes that define most of the functionality for IO are
 more thoroughly defined in S32-setting-library/IO.pod.  The main functions
 used are listed in S29 with references to S32-setting-library/IO.pod.
 An overview:
 
-=head3 Functions
+=head2 Functions
 
   print(@text)                   # print text on $*OUT
   say(@text)                     # print text + newline on $*OUT
@@ -248,8 +246,6 @@ An overview:
   temp $*CWD = chdir('/foo')     # set $*CWD for the current scope
 
   indir('/foo', { ... })         # execute code with temporary $*CWD
-      ...
-  };
 
   tmpdir('/foo')                 # set $*TMPDIR
   temp $*TMPDIR = tmpdir('/foo') # set $*TMPDIR for the current scope
@@ -266,7 +262,7 @@ An overview:
   link($target,$source)          # create a hard-link to a file
   symlink($target,$source)       # create a symbolic link to a file
 
-=head3 IO::Locally role
+=head2 IO::Locally role
 
 The best way to create an object that does the C<IO::Locally> role, is to use
 the C<.IO> coercer.  It takes an optional C<:CWD> parameter to indicate what
@@ -281,7 +277,7 @@ These classes consume the IO::Locally role:
   IO::Handle    # an opened regular file
   IO::File      # a regular file
   IO::Dir       # a directory
-  IO::Local     # something else that exists
+  IO::Local     # something else that exists (locally)
   IOU           # not recognized as something that exists
 
 The following file test methods are provided by the IO::Locally role, or are
@@ -352,7 +348,7 @@ given path (in alphabetical order):
 
 Methods that access the file system to operate on the given path (in
 alphabetical order).  May only operate on certain consumers of the IO::Locally
-role::
+role:
 
   accessed       last access time (if available)
   changed        last (metadata) changed time
@@ -375,7 +371,7 @@ role::
   unlink         remove as file
   words          contents of file as words
 
-=head3 IO::Handle Class
+=head2 PIO role
 
   class IO::Handle does IO { }