glib filename_to_uri docs

[Kevin Ryde <user42 zip com au>]

I was looking at Glib::filename_to_uri and from_uri and though to write
a couple of words for the docs.

I'm a bit unsure how a utf8 hostname goes in or comes out.  Dunno what
it'd normally look like encoded in a file:// anyway.  There might be a
utf8-flag issue there for the hostname return, but quietly glossing over
it to start with ...

(I'm also not sure if I like URI::file better.  I was only looking at
them for filename to uri to pass to a browser, and unless there's
bizarre chars in my path I suppose I hardly need either :-)

Index: Glib.pm
===================================================================
--- Glib.pm     (revision 1055)
+++ Glib.pm     (working copy)
@@ -1,4 +1,4 @@
-# Copyright (C) 2003-2008 by the gtk2-perl team (see the file AUTHORS for
+# Copyright (C) 2003-2009 by the gtk2-perl team (see the file AUTHORS for
 # the full list)
 #
 # This library is free software; you can redistribute it and/or modify it under
@@ -420,7 +420,7 @@
 
 =back
 
-Other functions for converting URIs are currently missing. Also, it might
+It might
 be useful to know that perl currently has no policy at all regarding
 filename issues, if your scalar happens to be in utf-8 internally it will
 use utf-8, if it happens to be stored as bytes, it will use it as-is.
@@ -444,7 +444,54 @@
 
 =back
 
+The following convert filenames to and from URI encoding.  (See also
+L<URI::file>.)
 
+=over 4
+
+=item $string = filename_to_uri ($filename, $hostname)
+
+=item $string = Glib->filename_to_uri ($filename, $hostname)
+
+Return a "file://" schema URI for a filename.  Unsafe and non-ascii chars in
+C<$filename> are escaped with URI "%" forms.
+
+C<$filename> must be an absolute path as a byte string in local filesystem
+encoding.  C<$hostname> is a utf-8 string, or empty or C<undef> for no host
+specified.  For example,
+
+    filename_to_uri ('/my/x%y/<dir>/foo.html', undef);
+    # returns 'file:///my/x%25y/%3Cdir%3E/foo.html'
+
+If C<$filename> is a relative path or C<$hostname> doesn't look like a
+hostname then C<filename_to_uri> croaks with a C<Glib::Error>.
+
+When using the class style C<< Glib->filename_to_uri >> remember that the
+C<$hostname> argument is mandatory.  If you forget then it looks like a
+2-argument call with filename of "Glib" and hostname of what you meant to be
+the filename.
+
+=item $filename = filename_from_uri ($uri)
+
+=item ($filename, $hostname) = filename_from_uri ($uri)
+
+Extract the filename and hostname from a "file://" schema URI.  In scalar
+context just the filename is returned, in array context both filename and
+hostname are returned.
+
+The filename returned is bytes in the local filesystem encoding.  The
+hostname returned is utf-8.  For example,
+
+    ($f,$h) = filename_from_uri ('file://foo.com/r%26b/bar.html');
+    # returns '/r&b/bar.html' and 'foo.com'
+
+If C<$uri> is not a "file:", or is mal-formed, or the hostname part doesn't
+look like a host name then C<filename_from_uri> croaks with a
+C<Glib::Error>.
+
+=back
+
+
 =head1 EXCEPTIONS
 
 The C language doesn't support exceptions; GLib is a C library, and of course