Re: [gthumb-list] Gthumb help system versus FreeBSD -- some progress made

["Ronald F. Guilmette" <rfg tristatelogic com>]

Dr. Chudobiak,

While I laud your effort to provide me with the requested enlightenment,
I'm afraid I I have to take issue with the practical and pragmatic
usefulness of some of the bits of so-called documentation you've pointed
me to.

I did stipulate that I was looking for ``meaningful'' bits of documentation.
In many cases, the material at the URLs you have been kind enough to provide
simply doesn't qualify.  Not even approximately.

(I suppose that I ought to clarify that I had already found and looked at
many of these bits of gnome/gtk/glib/gio ``documentation'' even before I
posted my underwhelming appreciation of the documentation yesterday.
However, as you'll see below, I found most if not all of these bits
raised more questions than they answered.)

When key concepts and/or terminology are left entirely to the reader's
imagination, the result is more befuddlement than enlightenment.

I elaborate more specifically below...


In message <4FAA4C0F 8020703 avtechpulse com>, 
"Dr. Michael J. Chudobiak" <mjc avtechpulse com> wrote:

> > Please do direct me to any documentation that would spell out the
> > functionality that the developers intended should be provided by any or
> > all of the following functions:
> >
> >      gtk_show_uri
> http://developer.gnome.org/gtk/stable/gtk-Filesystem-utilities.html#gtk-show-uri

... "The uri must be of a form understood by GIO..."

For someone (such as myself) encountering this for the the first time, this
bit of documentation raises more questions than it answers, I think.
Questions such as ``What the bleep is GIO?  And how the bleep can one know
what forms of URIs are or are not understood by it?''

I do believe that this particular man page could do with the addition of a
traditional "SEE ALSO" section and also (as I've now learned) a "FILES"
section which would mention:

        /usr/local/share/applications/mimeapps.list
        /usr/local/share/applications/defaults.list
        ~/.local/share/applications/mimeapps.list
        ~/.local/share/applications/defaults.list

(I note that there are many points within this man page where there are
hyperlinks to other pages.  Does it not seems as if at least one hyperlink
to whatever documentation exists regarding this "GIO" think would have
been appropriate?)

> >      g_app_info_launch_default_for_uri
> http://developer.gnome.org/gio/stable/GAppInfo.html#g-app-info-launch-default-
> for-uri

"Utility function that launches the default application registered to handle the specified uri.."

Registered?  Registered how?  Registered where?  Registered by whom?  When?

Aagain, this is does not qualify as ``meaningful'' documentation, as I would
define that term.

> >      g_file_new_for_uri
> http://developer.gnome.org/gio/2.32/GFile.html#g-file-new-for-uri

"Constructs a GFile for a given URI. This operation never fails, but the returned object might not support 
any I/O operation if uri is malformed or if the uri type is not supported."

How idoes this function construct a GFile from a URI?  At least a little hint
about that might be helpful.

More importantly, how (and where) does one find out what does or does not
constitute a "well formed" URI, for purposes of this function, specifically?

More importantly still, how (and where) does one find out what does or does not
constitute a "supported" URI, for purposes of this function, specifically?

> >      g_vfs_get_file_for_uri
> http://developer.gnome.org/gio/stable/GVfs.html#g-vfs-get-file-for-uri

"This operation never fails, but the returned object might not support any I/O operation if the URI is 
malformed or if the URI scheme is not supported."

See questions above.  What is (or isn't) a malformed URI?  What is a "supported"
URI?  How and where can the reader find out?

More importantly, how is THUS function different from "g_file_new_for_uri"?
Based on the (terse & inadequate) descriptions of these two funtions, it
would appera that both do the exact same thing.  So why have two such
functions?  Why not get rid of one or the other?

> >      g_local_vfs_get_file_for_uri
> well, that's a private internal function - you'd have to read the source 
> code

OK, fair enough.

> >      g_filename_from_uri
> http://developer.gnome.org/glib/2.30/glib-URI-Functions.html#g-filename-from-u
> ri

"Converts an escaped ASCII-encoded URI to a local filename in the encoding
used for filenames."

The obvious question:  How?  How does this conversion occur?  According to
what rules?  According to what algorithm?

This is probably THE single worst bit of ``documentation'' I've ever seen
in my life.  (And believe me, I've seen plenty.)  This goes beyond even
ordinary everyday run-of-the-mill opaqueness.  This qualifies as not only
unfathomable, but worse than useless.

> >      g_file_query_default_handler
> http://developer.gnome.org/gio/2.32/GFile.html#g-file-query-default-handler

"Returns the GAppInfo that is registered as the default application to handle
the file specified by file. "

Registered how?  Registered by who?  Registered where?  Registered when?

> >      g_app_info_get_default_for_uri_scheme
> http://developer.gnome.org/gio/stable/GAppInfo.html#g-app-info-get-default-for
> -uri-scheme

"Gets the default application for handling URIs with the given URI scheme.
A URI scheme is the initial part of the URI, up to but not including the
':', e.g. "http", "ftp" or "sip"."

I already knew what a URI scheme was.  What I didn't know (and what this
bit of ``documentation'' failed to provide) was some clarity about how and
where the default application for handling different URI schemes is
specified.  And I would _still_ be utterly mystified about this if I had
not been lucky enough to find (after some judicious Googling) the following
page on some site that, as far as I can tell, has no formal association at
all with the GNOME project:

    https://wiki.archlinux.org/index.php/Default_Applications

Had it not been for the abundant, clear, and specific clues in THAT document,
gthumb's help subsystem would still be providing me only with the excruciatingly
opaque "Operation not supported" error message.

> >      g_app_info_get_default_for_type
> http://developer.gnome.org/gio/stable/GAppInfo.html#g-app-info-get-default-for
> -type

"Gets the default GAppInfo for a given content type."

I rest my case.  If there were ever a more opaque bit of ``documentation''
written in the entire history of the Universe, I have yet to find it.

> >      get_all_desktop_entries_for_mime_type
> >      mime_info_cache_init
> >      mime_info_cache_init_dir_lists
> >      get_applications_search_path
> >      search_path_init
> >      mime_info_cache_dir_init_mimeapps_list
> private internal functions, read the source

OK, fair enough.

> >      g_get_system_data_dirs
> http://developer.gnome.org/glib/2.28/glib-Miscellaneous-Utility-Functions.html
> #g-get-system-data-dirs

"Returns an ordered list of base directories in which to access system-wide
application data.  On UNIX platforms this is determined using the mechanisms
described in the XDG Base Directory Specification.  In this case the list of
directories retrieved will be XDG_DATA_DIRS."

Now here we at last have sonmething that it written clearly, unambiguously,
and with useful specifics.  If fact, there's only one problem with _this_
bit of documentation...  Apparently it is factually wrong.

Me personally?  I do not have XDG_DATA_DIRS defined AT ALL in my environment.
And yet somehow, this whole confusing mismash of gtk/gio/glib _was_ able to
find the file called /usr/local/share/applications/mimeapps.list because
apparently, even if you don't have XDG_DATA_DIRS defined in your environment,
some part of this whole mess helpfully provides a default directory to
look in in such a case, i.e.  /usr/local/share/applications.

It certainly gives one hope to find that there is at least one bit of well
written and specific documentation in and among the entire gnome/gtk/gio/glib
panoply.  It would have been even more impressive if this one small piece
of documentation had actually been accurate.

> It sounds like your minimalist window manager is not implementing the 
> default application and mime type handling specified by freedesktop 
> standards

OK.  Sounds like a good theory to me!

But you are saying that as if it somehow makes it the responsibility of (in
my case) fvwm2 to fill in the /usr/local/share/applications/mimeapps.list
file, as necessary to make gthumb happy.  And personally, I don't see it
that way.  In fact, today I am going to write and submit a FreeBSD bug
report saying that (in my opinion) part of the standard process of installing
yelp should be to run the following small script:

=========================================================================
#!/bin/sh

(echo '[Added Associations]'; \
  echo 'x-scheme-handler/ghelp=yelp.desktop') \
    >> /usr/local/share/applications/mimeapps.list
=========================================================================

(Yesterday, I already filed a FreeBSD bug report saying that installation
of gthumb should be made dependent upon the prior intallation of yelp.)

> http://www.freedesktop.org/wiki/Specifications/mime-actions-spec). It's 
> not a gnome-specific thing.

OK.  Granted.  It is a FreeDeskTop thing.  Makes no difference.  The
bottom line is that some folks who either build or maintain window managers
(e.g. fvwm2) don't play in that pool.  I, however, would like to use _both_
their stuff _and_ gthumb.  In an ideal world I should be able to do both.


Regards,
rfg