[io grant] Improve &open/IO::Handle.open docs

- KISS &open; show a couple of basic examples and direct to
    IO::Handle.open for all the gory details
- List IO::Handle.open method
- Document all the possible mode options, in their overengineered glory
- List modes in a code chunk instead of a big =item list, which
    IMO is kinda hard to take in in whole
- Direct to docs of attributes for all the args that affect handle's
    attributes.

doc/Type/IO.pod6

@@ -241,125 +241,27 @@ say "Hi, $name! Nice to meet you!";
 
 =head2 sub open
 
-=for code :skip-test
-my $fh = open(IO::Path() $path, :$r, :$w, :$a, :$rw,
-              :$bin, :$enc, :$nl-in, :$nl-out, :$chomp)
-
-Opens the C<$path> (by default in text mode) with the given options,
-returning an L<IO::Handle> object. In order to close the L<IO::Handle>
-one needs to call L<close|/routine/close> explicitly or use a L<LEAVE|/syntax/LEAVE>
-phaser.
-
-=head3 File mode options
-
-=item read-only mode, C<:r>
-
-Open the file as read only, e.g.:
-
-=for code :skip-test
-my $fh = open("path/to/file", :r);
-
-This is the default mode for C<open>.
-
-Write-related methods on the returned C<IO::Handle> object will fail in this
-mode:
-
-    my $fh = open("test");   # the file "test" already exists
-    $fh.print("new text\n"); # fails
-    CATCH { default { put .^name, ': ', .Str } };
-    # OUTPUT: «X::AdHoc: Failed to write bytes to filehandle: bad file descriptor␤»
-
-=item write-only mode, C<:w>
-
-Open the file for writing, creating it if it doesn't exist or overwriting
-the file if it does exist, e.g.:
-
-    my $fh = open("path-to-file", :w);
-
-Read-related methods will fail in this mode:
-
-    my $fh = open("test", :w);
-    $fh.print("stuff\n");
-    $fh.print("more stuff\n");
-    $fh.seek(0);      # return to the start of the file
-    $fh.get();        # fails
-    CATCH { default { put .^name, ': ', .Str } };
-    # OUTPUT: «Reading from filehandle failed: bad file descriptor␤»
-
-=item read-write mode, C<:rw>
-
-Open the file for reading and writing, creating the file if it doesn't
-exist or overwriting the file if it already exists.
-
-    my $fh = open("path-to-file", :rw);
-
-=item append mode, C<:a>
+    multi sub open(IO() $path, |args --> IO::Handle:D)
 
-Open the file for appending.  If the file does not exist, create it.  If the
-file already exists, append data to it.
+Creates L<a handle|/type/IO::Handle> with the given C<$path>, and calls
+L«C<IO::Handle.open>|/type/IO::Handle», passing any of the remaining arguments
+to it. Note that L<IO::Path> type provides numerious methods for reading and
+writing from files, so in many common cases you do not need to C<open> files
+or deal with L<IO::Handle> type directly.
 
-    my $fh = open("path-to-file", :a);
-
-=head3 Encoding options
-
-=item binary mode, C<:bin>
-
-Open the file in binary mode (byte mode):
-
-    my $fh = open("path-to-file", :bin);
-
-A file opened with C<:bin> may still be processed line-by-line, but IO will
-be in terms of L<Buf|/type/Buf> rather than L<Str|/type/Str> types.  Default
-is C<False>, implying text semantics.
-
-=item text mode encoding, C<:enc>
-
-The encoding to use if opened in text mode.
-
-    my $fh1 = open 'path-to-file';                # default, utf-8
-    my $fh2 = open 'path-to-file', :enc<latin-1>; # explicit, latin-1
-
-Defaults to C<utf8>. Attempting to set the encoding while C<:bin> is true
-will cause C<X::IO::BinaryAndEncoding> exception to be thrown. Note that
-specifying L<Str> type object or C<Nil> as encoding is the same as not
-specifying the argument at all; use C<:bin> argument if you want to enable
-binary mode.
-
-The values are case-insensitive. The available encodings
-vary by implementation and backend. On Rakudo MoarVM the following are
-supported:
-
-=for code :skip-test
-  utf8
-  utf16
-  utf8-c8
-  iso-8859-1
-  windows-1252
-  ascii
-
-Implementation may choose to also provide support for aliases, e.g. Rakudo
-allows aliases C<latin-1> for C<iso-8859-1> encoding and dashed utf versions:
-C<utf-8> and C<utf-16>.
-
-=head3 Newline options
-
-=item end-of-line (EOL) marker, C<:nl-in>, C<:nl-out>
-
-C<nl-in> is the marker used to indicate the end of a line of
-text. Only used in text mode. Defaults to C<["\n", "\r\n"]> and does
-not include C<"\r">. C<nl-out> defaults to C<"\n">.
-
-    # explicitly use CR-LF as EOL character
-    my $fh = open("path-to-file", nl-in => "\r\n");
-
-=item chomp mode, C<:chomp>
+=begin code :skip-test
+    my $fh = open :w, '/tmp/some-file.txt';
+    $fh.say: 'I ♥ writing Perl code';
+    $fh.close;
 
-Whether or not to remove newline characters from text obtained with
-C<.lines> and C<.get>.  Defaults to C<True>.
+    $fh = open '/tmp/some-file.txt';
+    print $fh.readchars: 4;
+    $fh.seek: 7, SeekFromCurrent;
+    say $fh.readchars: 4;
+    $fh.close;
 
-    # don't remove newline characters from input
-    my $fh = open("path-to-file", chomp => False);
-    say $fh.get();     # returns line including newline char
+    # OUTPUT: «I ♥ Perl␤»
+=end code
 
 =head2 sub slurp
 

doc/Type/IO/Handle.pod6

@@ -8,6 +8,67 @@
 
 =head1 Methods
 
+=head2 method open
+
+Defined as:
+
+    method open(IO::Handle:D: :$r, :$w, :$x, :$a, :$update, :$rw, :$rx, :$ra, Str :$mode, :$create, :$append, :$truncate, :$exclusive, :$bin, :$enc, :$chomp = $!chomp, :$nl-in = $!nl-in, Str:D :$nl-out = $!nl-out --> IO::Handle:D)
+
+Opens the handle in one of the modes. L<Fails|/routine/fail> with appropriate
+exception if the open fails.
+
+See description of individual methods for the accepted values and behaviour
+of L«C<:$chomp>|/type/IO::Handle#method_chomp»,
+L«C<:$nl-in>|/type/IO::Handle#method_nl-in»,
+L«C<:$nl-out>|/type/IO::Handle#method_nl-out», and
+L«C<:$enc>|/type/IO::Handle#method_encoding». The values for parameters default
+to the invocant attributes and if any of them are provided, the attributes will
+be updated to the new values. Specify C<:$bin> set to C<True> instead of
+C<:$enc> to indicate the handle should be opened in binary mode. Specifying
+undefined value as C<:$enc> is equivalent to not specifying C<:$enc> at all.
+Specifying both a defined encoding as C<:$enc> and C<:$bin> set to true will
+cause C<X::IO::BinaryAndEncoding> exception to be thrown.
+
+The open mode defaults to non-exclusive, read only (same as specifying
+C<:r>) and can be controlled by a mix of the following arguments:
+
+=begin code :skip-test
+    :r      same as specifying   :mode<ro>
+
+    :w      same as specifying   :mode<wo>, :create, :truncate
+    :a      same as specifying   :mode<wo>, :create, :append
+    :x      same as specifying   :mode<wo>, :create, :exclusive
+
+    :update same as specifying   :mode<rw>
+    :rw     same as specifying   :mode<rw>, :create
+    :ra     same as specifying   :mode<rw>, :create, :append
+    :rx     same as specifying   :mode<rw>, :create, :exclusive
+=end code
+
+Support for combinations of modes I<other> than what is listed above
+is implementation-dependent and should be assumed unsupported. That is,
+specifying, for example, C<.open(:r :create)> or
+C<.open(:mode<wo> :append :truncate)> might work or might cause the Universe
+to implode, depending on a particular implementation.
+
+The mode details are:
+
+=begin code
+    :mode<ro>  means "read only"
+    :mode<wo>  means "write only"
+    :mode<rw>  means "read and write"
+
+    :create    means the file will be created, if it does not exist
+    :truncate  means the file will be emptied, if it exists
+    :exclusive means .open will fail if the file already exists
+    :append    means writes will be done at the end of file's current contents
+=end code
+
+Attempts to open a directory, write to a handle opened in read-only mode
+or read from a handle opened in write-only mode,
+or using text-reading methods on a handle opened in binary mode will
+fail or throw.
+
 =head2 method comb
 
 Defined as:
@@ -149,6 +210,22 @@ currently in binary mode. Specifying an optional positional C<$enc> argument
 switches the encoding used by the handle; specify C<Nil> as encoding to put the
 handle into binary mode.
 
+The accepted values for encoding are case-insensitive. The available encodings
+vary by implementation and backend. On Rakudo MoarVM the following are
+supported:
+
+=for code :skip-test
+  utf8
+  utf16
+  utf8-c8
+  iso-8859-1
+  windows-1252
+  ascii
+
+Implementation may choose to also provide support for aliases, e.g. Rakudo
+allows aliases C<latin-1> for C<iso-8859-1> encoding and dashed utf versions:
+C<utf-8> and C<utf-16>.
+
 =begin code :skip-test
     with 'foo'.IO {
         .spurt: "First line is text, then:\nBinary";