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

[Eric Abrahamsen]

David Bjergaard <address@hidden> writes:

> Hi Eric,
>
> As promised, some more comments (though not many) inline:
>
> Eric Abrahamsen <address@hidden> writes:
>
>> David Bjergaard <address@hidden> writes:
>>
> [snip]
>> No I meant the two small patches I sent directly to the list yesterday.
>> They're pretty minor, but I think useful.
> Please include these with your pull request when you send in the edits
> to the texinfo manual.  They are useful edits, so we'll want to
> highlight them in the next release, just include a message in the pull
> request so  I don't forget later :).

Will do -- I'll add the smaller changes as separate commits before the
addition to the manual.

>>
>>
>> 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.
> An offhand thought, does:
> (define-key *top-map* (kbd "R") "describe-key \"C-t n\"") 
> work? (I haven't ready any of the source, so this is pure speculation)

I re-read your first email and realized you actually answered my
question there -- the only way to create multi-key sequences (eg "C-t n
p") is to chain keymaps. Ie, what I'm trying to do above simply isn't
meant to work (it doesn't work with an interactive prompt, either).
Sorry for the noise!

>> 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.
>>
> OK, but if its not pressing I'll forget about it :).  If you want some
> research done make some noise and I'll try to dig into it.

Or I could dig into it myself :)

It actually wasn't that confusing, I was just looking in the wrong
place. The definition of "next", for instance, looks like this:

(defcommand (next tile-group) ... )

The second atom is put into the "class" slot of the command struct. It
indicates the group types under which the command is valid (as far as I
know there's only tile-group and floating-group). This is how so many
commands get disabled in floating groups. `command-active-p' checks if
the current group and the class slot of a command match up. Hence the
"minor modes" TODO in the comments that function.

I'm going to add a bit to both the manual and the docstring of
defcommand, you can take a look when the pull request comes through.

>> 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.
>>
> I suppose that it may be more appropriate to call this
> "eval-stumpwm-command" but that might be a mouthful... In either case,
> leaving it as is now is not a big deal.

Agreed.

>>> I'll read over the manual content soon and send more detailed comments.
> I actually have no major comments! I like the pedagogical approach. 
>>>>   All command arguments must be of a defined “StumpWM type”. The
>>>>   following types are pre-defined: [this list doesn’t need to be both
>>>>   here and in “Miscellaneous Commands”. I’m leaning toward listing types
>>>>   here, and having a link to this spot from misc. commands]
> I agree, as this will be more pertinent to your discussion here. If,
> however, this list won't change at all (or very much) it may be work
> duplicating it for the sake of convenience.  I know the counter argument
> is that it introduces two places that need to be updated...

My guess is it will change very rarely. Let's leave it in both places.

>>>
>>> Thanks for all your hard work!
> Just want to reiterate this, its clear a lot of research went into
> getting the explanation of the macros correct!

My pleasure, I'm glad to be able to contribute! I hope to continue
providing fixes/features, and this was good background research.

E