Comment about Xfwm4 theme how-to & some ancillary comments on programming documentation

[Joe Klemmer]

There seems to be something missing (or at least I can't find it) in
this how-to.  It does a great job and detailing the image information
but it only briefly mentions the "themerc" file and a few of it's
settings.  It would be very helpful to have an example rc file in the
how-to so that it would make it easier to put all the bits together.

Side comment: 
I personally understand things when given examples rather than prototype
information on them.  A perfect example is programming api's and such.
I'll use the xfce4 api documentation to explain what I mean (and to keep
this at least superficially on topic).

Picking something at random, let's look at the libxfce4panel reference
manual.  The second entry is listed as XfcePanelPlugin.  The synopsis
for it reads -

            XfcePanelPlugin;
void        (*XfcePanelPluginFunc)          (XfcePanelPlugin *plugin);
const char* xfce_panel_plugin_get_name      (XfcePanelPlugin *plugin);
const char* xfce_panel_plugin_get_id        (XfcePanelPlugin *plugin);
const char* xfce_panel_plugin_get_display_name
                                            (XfcePanelPlugin *plugin);
int         xfce_panel_plugin_get_size      (XfcePanelPlugin *plugin);
XfceScreenPosition xfce_panel_plugin_get_screen_position
                                            (XfcePanelPlugin *plugin);
void        xfce_panel_plugin_set_expand    (XfcePanelPlugin *plugin,
                                             gboolean expand);
gboolean    xfce_panel_plugin_get_expand    (XfcePanelPlugin *plugin);
GtkOrientation xfce_panel_plugin_get_orientation
                                            (XfcePanelPlugin *plugin);
void        xfce_panel_plugin_add_action_widget
                                            (XfcePanelPlugin *plugin,
                                             GtkWidget *widget);
void        xfce_panel_plugin_menu_insert_item
                                            (XfcePanelPlugin *plugin,
                                             GtkMenuItem *item);
void        xfce_panel_plugin_menu_show_about
                                            (XfcePanelPlugin *plugin);
void        xfce_panel_plugin_menu_show_configure
                                            (XfcePanelPlugin *plugin);
void        xfce_panel_plugin_block_menu    (XfcePanelPlugin *plugin);
void        xfce_panel_plugin_unblock_menu  (XfcePanelPlugin *plugin);
void        xfce_panel_plugin_register_menu (XfcePanelPlugin *plugin,
                                             GtkMenu *menu);
char*       xfce_panel_plugin_lookup_rc_file
                                            (XfcePanelPlugin *plugin);
char*       xfce_panel_plugin_save_location (XfcePanelPlugin *plugin,
                                             gboolean create);

This shows the prototypes and casts and all that great mumbo-jumbo that
you find in most programming reference manuals.  This is pure gibberish
to me.  Not the specific XfcePanelPlugin content but the whole method of
describing it that's used in every manual for every function in every
language I've ever dealt with.

Maybe it's due to the fact that I have no formal education in
programming (or anything else, for that matter as my career in Higher
Education was less than stellar {20 credits accumulated in three
semesters}).  However, give me some example code and at least a verbal
description of what it's supposed to do and I'm fine.  It is also why I
have so much trouble learning C/C++ and similar languages.  I learned
COBOL in a few weeks; shell in slightly less time; awk in two days;
perl...  well, no one really learns perl, you just get familiar enough
with it to cause all kinds of damage.

I have learned and forgotten other similar languages over the years but
I know that, given a little time, I can ramp myself back up in them just
fine.  

It reminds me of my old Fidonet days.  When I was first looking to join
I had to install a front end.  The two major choices were FrontDoor and
BinkleyTerm.  FrontDoor was configured by a config program that used the
familiar method of screens with text entry lines.  Binkley was
configured by one big config file with many examples in it.  Needless to
say I chose Binkley.

Anyway, the point is that, for me, the standard method of describing
things for programming doesn't work.  I believe I'm not the only one who
finds this true.  But I bet that most real hackers don't.  Which is why
this form of documentation endures.

Joe

[You know, this rambling isn't half bad.  I think I'll put this in my
blog.]