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

[Jasper Huijsmans]

Joe Klemmer schreef:
> 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.
> 

Probably the easiest way is to take one of the existing themes and start 
changing stuff to see what it does. In fact that's is the easiest way to 
  do any sort of development ;-)

> 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).

API docs are important as a reference to check the exact syntax of 
functions, members of data structs, etc. They suck as a way to learn how 
to use an API.

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

Try the README.Plugins from the panel sources or 
http://www.foo-projects.org/~jasper/plugins/README.Plugins as a quick 
start. Hopefully it is a little easier to follow.

After that I can only suggest to have a look at existing plugins. I 
guess it's best to start with the simple ones like the separator plugin 
or the clock.

[...stuff about COBOL ;-) ...]
> 
> 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.

Nah, the reason is that writing real tutorials is much more difficult 
and requires much more effort.


Hope that helped a little...

	Jasper