Re: On keybindings and the slow erosion of help's utility

> But in the API I described, each condition can only return nil, command,
> or keymap. If our (org-metaright--try-hook) already executed the
> command, it cannot return nil - that would make us search further, which
> we do not want. It cannot return a command or keymap either - we do not
> want to execute those. Maybe, we can treat non-keymap, non-command
> return value as "stop here, we are done". That's an option, yes.

I'd let the condition return a dummy command like `ignore`, just
like we already do for similar purposes in keymaps.

>>> I proposed a very particular shape for those (to be implemented inside
>>> user-level `keymap-dynamic-bind'), but we do not have to hard-code them.
>>
>> I see.  I'm trying to look at it from the `C-h k` side where we want the
>> API to be minimalist (the hard coding of sub-elements would be fine on
>> the side of helper macros/functions to define&set such "dynamic keymaps"=
).
>
> That's what I meant by
>
> 	  (dynamic-bind
> 	    :filter   FILTER-FN      ; runs hook: hook =E2=86=92 command/keymap/=
nil
> 	    :doc      DOC-FN         ; (dynamic-binding) =E2=86=92 string for C-=
h k
> 	    :enumerate ENUM-FN       ; (dynamic-binding) =E2=86=92 list for wher=
e-is
> 	    :default  COMMAND)       ; fallback when hook returns nil
>
> :doc is a custom function that will take care about rendering
> documentation. The `keymap-dynamic-bind' will define a particular
> standard shape of :doc function, but it can be anything.

Ah, I see, so that would be the "equivalent" in your model to my
`composite-command`.

[ FWIW, my mental model of `partial-binding` and `composite-command` are
  OClosures, for which we can already define dynamic docstrings via
  `cl-defmethod`.  I'm thinking that we'd have two subtypes of
  `partial-binding`: those that have a condition and a command (active
  only when the (side-effect free) condition is satisfied), and those
  that have only a command (which returns nil to indicate that it didn't
  do anything and we should keep trying with others, i.e. for when the
  condition can't be side-effect free).  ]

>> But `:doc` is in the argument to the macro, so the question is where
>> does it get stashed in the output of the macro, if not in the function's
>> docstring (where it's a bit of an abuse)?
> What I have in mind is
> (keymap-dynamic-bind org-metaright-filters
>  (:doc "Overall keymap docstring")
>  (#'org-metaright--at-heading :doc "Condition-specific docstring"))

I see.

>> OTOH, it's fine *if* `lookup-key` doesn't evaluate the conditions and
>> just returns the whole dynamic keymap.
> Sure.

But that brings us back to whether the conditions are evaluated during
keymap lookup or afterwards.

> I think https://elpa.nongnu.org/nongnu/casual.html as a whole is a
> counterexample to your intuition. It defines whole keymaps depending on
> cursor location. For example, see
> https://elpa.nongnu.org/nongnu/doc/casual.html#Dired-Usage
>
> Another example is context menus :)

But these are "all keymaps" aren't they?

> One important thing in this code that we did not discuss yet is prefix
> argument. It will need to be passed to the conditions.

Yup.  That's easy if we evaluate the conditions when we run the command
rather than when we lookup the keymap.


=3D=3D=3D Stefan