Re: [RP] Request: Documentation change

[Zach White]

On Mon, Sep 12, 2005 at 06:17:47AM -0500, Joe Corneli wrote:
*snip*
> Furthermore, this:
> 
>    +These all correspond to keys on the keypad:
> 
> is dubious.  The "correspondence" you allude to, while not entirely in
> your head, is by no means set in stone either.  Indeed, I believe that
> you have simply produced two lists of _keysyms_, some of which happen
> to have "KP_" attached to them.

I have indeed done exactly that, and you're right that these values aren't
set in stone. However, we're talking about documentation here. Redundancy
in documentation usually isn't a bad thing. This list is also accurate for
both XFree86 and X.org. 

Maybe just documenting that a list of keysyms can be found in keysymdef.h
is sufficient for 95% of ratpoison's users. That last 5%, however, may not
have headers installed on the machine they're using. Perhaps they're using
something silly that doesn't install headers by default. Maybe they've
built an embedded system that has no compiler but has the documentation.
Maybe they have some other reason entirely.

Whatever the case, documenting this information in the ratpoison manual
is a good thing. IMHO, having documentation that is accurate now and may
not be accurate later is better than having no documentation at all. As
I said in my original post, it took me a couple hours to track these
down. By documenting keysymdef.h, at the least, you tell the user where
to find this information, saving some frustration. Documenting a set
of known good values will save even more frustration.

I agree that Modeswitch shouldn't be in there. I missed that one when I was 
pruning the list.

-Zach