Re: Making scripts with sawfish-client

["Eric Mangold" <teratorn world-net net>]

On Mon, 17 Apr 2006 10:57:14 +1000, Geoff Kuenning <geoff cs hmc edu>  
wrote:

> I don't think it's particularly inviting to outsiders if we get
> defensive about perfectly reasonable questions and criticisms.

Sure, I agree. I just don't think the criticisms were perfectly reasonable  
the way they were presented. I welcome constructive criticism. That means  
being specific about what you think is wrong, how you propose it should be  
fixed, and the rationale behind it.

I've offered the OP as many specific suggestions and I can think of. If he  
can provide us with more detailed information I'm sure we can do better.  
Nobody is getting paid here, you know. The burden lies as much with those  
seeking support as with those giving it.

> The reality is that sawfish, like many (or most) open-source projects,
> could benefit from quite a bit more documentation.  The UI to the
> window manager itself is reasonably well covered by the texinfo
> manual.  But the stuff in librep is discussed only in documentation
> strings.  That brings up the classic elisp problem: doc strings tend
> to be terse, and you often can't even find out that a function exists
> unless you already have a good guess as to its name.
> As the original poster said:
>
> > In our case, what we need is a clear documentation about how to use the
> > tools. That means tutorials and howto, and not an API list (that will be
> > maybe useful, but later).
>
> That stuff doesn't exist at all.  If it _did_ exist, sawfish would be
> much more widely used.  How successful do you think Python would be if
> there was nothing except a brief listing of library functions with
> 2-line descriptions?

If I gave the impression that sawfish/librep doesn't need any more docs  
that I'm sorry. Yes absolutely it could benefit from more and better docs.  
Almost any project could.

I can't think of too many topics to write HOWTOs or guides on though.  
Here's one:

	- sawfish and/or librep event loop. how it works,
        how it integrates with GTK, and how to hook in to it.

> It's reasonable to respond that nobody has written anything and nobody
> has volunteered to do so.  But it's counterproductive to claim that
> nothing needs to be written, or to suggest that the solution to such
> problems is to make everybody figure it out themselves.

I merely suggested that it doesn't appear to be *that* big of a problem,  
judging from the lack of questions on the subject and the surplus of  
working code written for sawfish.

I believe questions relating to the OP's original task should be easily  
answered by the existing documentation.

If anyone has good ideas for guides/tutorials/HOWTOs please post them here  
AND add them to the wiki so they're not forgotten about. I've added a  
"Documentation Wanted" section to the Doc page on the wiki:
http://sawfish.endorphin.org/SawfishWiki/SawfishDocumentation

Cheers,
Eric