Index: /trunk/Nebulous/lib/Nebulous/Keys.pod
===================================================================
--- /trunk/Nebulous/lib/Nebulous/Keys.pod	(revision 16239)
+++ /trunk/Nebulous/lib/Nebulous/Keys.pod	(revision 16240)
@@ -1,83 +1,145 @@
-# neb://<volume name>/...
-# neb:path...
-# neb:/path... (same as neb:path, leading '/' is stripped)
-# neb:///path... (same as neb:path)
+=pod
 
-key:        foo/bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+=head1 NAME
 
-key:        /foo/bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+Nebulous::Keys - Nebulous Keys Explained
 
-key:        //foo/bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+=head1 DESCRIPTION
 
-key:        ///foo/bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+The Nebulous system interprets it's storage object keys in a I<slightly>
+magical manner.  It supports both plain vanilla C<key strings> and keys in the
+form of an L<URI>.  In the L<URI> form a specific storage volume can be implied
+(as a request, not a requirement).  Both key forms are subject to mangling such
+that I<IF> the key I<looks> like a C<POSIX> semantics file path, it is
+canocalized.
 
-key:        foo////bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+=head1 RESERVED SYNTAX
 
-key:        foo/bar/baz/quix/
-mangled to: foo/bar/baz/quix
-volume:     any
+This particular syntax is disallowed and is reserved for future use
 
-# URI w/ volume name
+    <neb:<phrase>/<path>
 
-key:        neb://foo/bar/baz/quix
-mangled to: bar/baz/quix
-volume:     foo
+=head1 EXAMPLES
 
-key:        neb://foo//bar/baz/quix
-mangled to: bar/baz/quix
-volume:     foo
+=head2 Key Strings
 
-key:        neb://foo///bar/baz/quix
-mangled to: bar/baz/quix
-volume:     foo
+    key:        foo/bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
 
-key:        neb://foo/bar///baz/quix
-mangled to: bar/baz/quix
-volume:     foo
+    key:        /foo/bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
 
-key:        neb://foo/bar/baz/quix/
-mangled to: bar/baz/quix
-volume:     foo
+    key:        //foo/bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
 
-# URI w/o volume name
+    key:        ///foo/bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
 
-key:        neb:/foo/bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+    key:        foo////bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
 
-key:        neb:///foo/bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+    key:        foo/bar/baz/quix/
+    mangled to: foo/bar/baz/quix
+    volume:     any
 
-key:        neb://///foo/bar/baz/quix
-mangled to: foo/bar/baz/quix
-volume:     any
+=head2 URI w/ volume name
 
-# key w/ whitespace
+neb://<volume>/<path>
 
-like( $@, qr/may not contain whitespace/, "whitespace" );
-"/ foo/bar/baz/quix"
-" /foo/bar/baz/quix"
-"/foo/bar/baz/quix "
+    key:        neb://foo/bar/baz/quix
+    mangled to: bar/baz/quix
+    volume:     foo
 
-# URI w/ whitespace
+    key:        neb://foo//bar/baz/quix
+    mangled to: bar/baz/quix
+    volume:     foo
 
-"neb ://foo/bar/baz/quix"
-"neb:// foo/bar/baz/quix"
-" neb://foo/bar/baz/quix"
-"neb://foo/bar/baz/quix "
+    key:        neb://foo///bar/baz/quix
+    mangled to: bar/baz/quix
+    volume:     foo
 
-# URI w/o volume requires leading slash
+    key:        neb://foo/bar///baz/quix
+    mangled to: bar/baz/quix
+    volume:     foo
 
-like( $@, qr/requires a leading slash/, "leading slash" );
-neb:foo/bar/baz/quix
+    key:        neb://foo/bar/baz/quix/
+    mangled to: bar/baz/quix
+    volume:     foo
+
+=head2 URI w/o volume name
+
+neb:/<path>
+
+    key:        neb:/foo/bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
+
+    key:        neb:///foo/bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
+
+    key:        neb://///foo/bar/baz/quix
+    mangled to: foo/bar/baz/quix
+    volume:     any
+
+=head2 Forbidden Keys
+
+=head3 Key with whitespace
+
+    "/ foo/bar/baz/quix"
+    " /foo/bar/baz/quix"
+    "/foo/bar/baz/quix "
+
+=head3 URI with whitespace
+
+    "neb ://foo/bar/baz/quix"
+    "neb:// foo/bar/baz/quix"
+    " neb://foo/bar/baz/quix"
+    "neb://foo/bar/baz/quix "
+
+=head3 URI with out a volume requires a leading slash
+
+    neb:foo/bar/baz/quix
+
+=head1 CREDITS
+
+Just me, myself, and I.
+
+=head1 SUPPORT
+
+Please contact the author directly via e-mail.
+
+=head1 AUTHOR
+
+Joshua Hoblitt <jhoblitt@cpan.org>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2008  Joshua Hoblitt.  All rights reserved.
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program; if not, write to the Free Software Foundation, Inc., 59 Temple
+Place - Suite 330, Boston, MA  02111-1307, USA.
+
+The full text of the license can be found in the LICENSE file included with
+this module, or in the L<perlgpl> Pod as supplied with Perl 5.8.1 and later.
+
+=head1 SEE ALSO
+
+L<Nebulous::Server>, L<Nebulous::Client>, L<nebclient(3)>
+
+=cut