Re: [STUMP] manual addition part 2: commands and types

[Eric Abrahamsen]

David Bjergaard <address@hidden> writes:

> Hi Eric,
>
> Thanks for the documentation work!  Response inline:
>
> Eric Abrahamsen <address@hidden> writes:
>
>> Okay, here's the next new bit for the manual: Chapter 3 on commands and
>> custom types. This was pretty interesting to research. I'll leave it
>> here for a week or so for comments, then create a pull request. The docs
>> as I've written them depend on the last two patches I sent to the list
>> -- if there's a problem with those, it would be easy to adjust back.
> Sounds good, I'm pretty sure I merged your changes into the master
> branch a few days ago, I'm referring to:
> https://github.com/stumpwm/stumpwm/pull/80

No I meant the two small patches I sent directly to the list yesterday.
They're pretty minor, but I think useful.

>>
>> TL;DR: I have a couple of outstanding questions -- if anyone who's done
>> command spelunking has any experience to share, that would be great.
>>
>> 1. Command arguments are given as strings, and most types do a good job
>> of parsing strings into whatever vlaue they actually need. I can't see
>> how :key and :key-seq can parse multiple keypresses, though. What I mean
>> is, if :key-seq prompts for a value, you can enter it fine in the input
>> window. But if you try to pass it as part of the argument line, I can
>> make eg "C-t" work, but not "C-t n" (or "C-tn" or "C-t\n" or...). It's
>> not that big a deal, but if there's a string notation that would allow
>> more complex keypresses to be parsed, I'd like to know.
> If I'm following your explanation you want to be able to write a
> key-sequence string that corresponds to the set of keys that have to be
> struck to execute a command?  
>
> The way it works now is that you bind a key to another keymap, and that
> keymap defines another set of commands (including the possibility of
> another keymap :)) The upshot is that you can chain together an
> arbitrary sequence of keymaps to make any key-sequence imaginable ("C-t o
> a d" is possible).  The downside is, as you note, that you can't parse
> an arbitrary string into that sequence, ie:
> (define-key *top-map* (kbd "o a d") "exec foo") 
> doesn't work.

Not quite -- sorry, I should have just given an example. Some commands
take a :key-seq argument, but if you want to fix that argument in the
command string, I don't know how to provide a multi-key sequence so that
there are no spaces to confuse the argument line parsing. ie this works:

(define-key *top-map* (kbd "R") "describe-key C-t")

but this is parsed as two separate arguments:

(define-key *top-map* (kbd "R") "describe-key C-t n")

None of the variants I tried worked. Not that this matter much, but it's
the only type that I can't figure out how to represent with a string.

>>
>> 2. Command names can be given as a list as well as a symbol. If a list,
>> the first element is used as the command name. Looking at existing code
>> gives the impression that the second element is meant to be some sort of
>> method dispatch mechanism, but doesn't actually appear to be implemented
>> at the moment. Does anyone know if this actually does anything now?
> I'd have to dig to help figure this out, so I'll defer this for the
> weekend (if I have time).

I think it can be ignored altogether for now, for the purposes of the
manual. I just thought if anyone had any on-hand knowledge, we could put
it in. Not pressing.

>>
>> 3. The `colon' command is bound to the semicolon, not the colon. Just
>> saying.
> I'm open to renaming if the resulting changes touch a reasonably small
> subset of the code... I think this is a holdover from ratpoison (though
> I could be wrong).  I always think of it as "C-t ;"-> execute stumpwm
> command, "C-t :"-> execute lisp-form on the lisp hosting stumpwm 
> where you have to hold an extra key (shift) to get to the higher level
> abstraction (lisp vs stumpwm itself).  

Yup, that's how I think of it as well, and it's never caused me any
problems. This smacks of bike-shedding, but on the other hand here's a
command whose name means absolutely nothing, except for the key it's
supposed to be on, and it's not on that key.

>>
>> Thanks!
>> Eric
>>
> I'll read over the manual content soon and send more detailed comments.
>
> Thanks for all your hard work!
>     Dave