From: Tomi Ollila <tomi.ollila@iki.fi>
To: Mark Walters <markwalters1009@gmail.com>,
Austin Clements <amdragon@MIT.EDU>,
notmuch@notmuchmail.org
Subject: Re: [PATCH 4/6] emacs: Support overriding help and describing prefix action
Date: Mon, 07 Oct 2013 08:54:37 +0300 [thread overview]
Message-ID: <m2wqlpiq1u.fsf@guru.guru-group.fi> (raw)
In-Reply-To: <87wqlqqhrn.fsf@qmul.ac.uk>
On Sun, Oct 06 2013, Mark Walters <markwalters1009@gmail.com> wrote:
> This whole series looks good to me. If you are rolling another version
> for any reason I have one trivial comment
>
> On Sun, 06 Oct 2013, Austin Clements <amdragon@MIT.EDU> wrote:
>> Traditionally, function documentation strings are intended primarily
>> for programmers, rather than users. They're written from the
>> perspective of calling the function, not interactively invoking it.
>> They're only ever displayed along with the function prototype (and
>> often refer to argument names). And built-in help commands like
>> `describe-bindings' show the name of the command, not its
>> documentation.
>>
>> The notmuch help system is like `describe-bindings', but tries to be
>> more user-friendly by displaying documentation strings, rather than
>> Elisp command names. For most commands, this is fine, but for some
>> the "programmer description" is inappropriate for interactive use.
>> This is particularly noticeable for commands that take an optional
>> prefix argument.
>>
>> This patch adds support for two symbol properties: notmuch-doc and
>> notmuch-prefix-doc, which let a command override its interactive
>> documentation and provide separate documentation for its prefixed
>> invocation. If notmuch-prefix-doc is present, we add an extra line to
>> the help giving the prefixed key sequence along with the documentation
>> for the prefixed command.
>> ---
>> emacs/notmuch.el | 29 ++++++++++++++++++++++++-----
>> 1 file changed, 24 insertions(+), 5 deletions(-)
>>
>> diff --git a/emacs/notmuch.el b/emacs/notmuch.el
>> index a36849f..278bd35 100644
>> --- a/emacs/notmuch.el
>> +++ b/emacs/notmuch.el
>> @@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."
>> "M-"
>> (concat desc " "))))
>>
>> -(defun notmuch-describe-keymap (keymap &optional prefix tail)
>> +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)
>> "Return a list of strings, each describing one key in KEYMAP.
>>
>> Each string gives a human-readable description of the key and the
This series Looks Good To Me, too.
> It would be nice to document the ua-keys variable here. It took me some
> time to work out what was going in (and I worked out based on the
> caller).
I did not have any problems understanding this -- probably due to me
having played so much with where-is-internal and such commands...
... just that this looks to me as 'first-ua-key' (ua being unversal
argument, not user agent ;)
If there is need for new version then documenting this would not hurt...
if not followup-patch to add this documentation (w/ one line commit
message for least review effort! ;) could do)
Tomi
>
> Best wishes
>
> Mark
>
>> @@ -151,10 +151,19 @@ first line of documentation for the bound function."
>> ((keymapp binding)
>> (setq tail
>> (notmuch-describe-keymap
>> - binding (notmuch-prefix-key-description key) tail)))
>> + binding ua-keys (notmuch-prefix-key-description key) tail)))
>> (t
>> + (when (and ua-keys (symbolp binding)
>> + (get binding 'notmuch-prefix-doc))
>> + ;; Documentation for prefixed command
>> + (let ((ua-desc (key-description ua-keys)))
>> + (push (concat ua-desc " " prefix (format-kbd-macro (vector key))
>> + "\t" (get binding 'notmuch-prefix-doc))
>> + tail)))
>> + ;; Documentation for command
>> (push (concat prefix (format-kbd-macro (vector key)) "\t"
>> - (notmuch-documentation-first-line binding))
>> + (or (and (symbolp binding) (get binding 'notmuch-doc))
>> + (notmuch-documentation-first-line binding)))
>> tail))))
>> keymap)
>> tail)
>> @@ -165,14 +174,24 @@ first line of documentation for the bound function."
>> (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)
>> (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))
>> (keymap (symbol-value (intern keymap-name)))
>> - (desc-list (notmuch-describe-keymap keymap))
>> + (ua-keys (where-is-internal 'universal-argument keymap t))
>> + (desc-list (notmuch-describe-keymap keymap ua-keys))
>> (desc (mapconcat #'identity desc-list "\n")))
>> (setq doc (replace-match desc 1 1 doc)))
>> (setq beg (match-end 0)))
>> doc))
>>
>> (defun notmuch-help ()
>> - "Display help for the current notmuch mode."
>> + "Display help for the current notmuch mode.
>> +
>> +This is similar to `describe-function' for the current major
>> +mode, but bindings tables are shown with documentation strings
>> +rather than command names. By default, this uses the first line
>> +of each command's documentation string. A command can override
>> +this by setting the 'notmuch-doc property of its command symbol.
>> +A command that supports a prefix argument can explicitly document
>> +its prefixed behavior by setting the 'notmuch-prefix-doc property
>> +of its command symbol."
>> (interactive)
>> (let* ((mode major-mode)
>> (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))
>> --
>> 1.8.4.rc3
>>
>> _______________________________________________
>> notmuch mailing list
>> notmuch@notmuchmail.org
>> http://notmuchmail.org/mailman/listinfo/notmuch
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch
next prev parent reply other threads:[~2013-10-07 5:54 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-10-06 3:22 [PATCH 0/6] emacs: Built-in help improvements and clean up doc strings Austin Clements
2013-10-06 3:22 ` [PATCH 1/6] emacs: `notmuch-mua-new-forward-message' is not interactive Austin Clements
2013-10-06 3:22 ` [PATCH 2/6] emacs: `notmuch-mua-new-reply' is also " Austin Clements
2013-10-06 3:22 ` [PATCH 3/6] emacs: Clean up a few documentation strings Austin Clements
2013-10-06 3:22 ` [PATCH 4/6] emacs: Support overriding help and describing prefix action Austin Clements
2013-10-06 20:14 ` Mark Walters
2013-10-07 5:54 ` Tomi Ollila [this message]
2013-10-07 22:49 ` Austin Clements
2013-10-06 3:22 ` [PATCH 5/6] emacs: Improve interactive use documentation Austin Clements
2013-10-06 3:22 ` [PATCH 6/6] News for Emacs help improvements Austin Clements
2013-10-07 23:40 ` David Bremner
2013-10-07 22:48 ` [PATCH 7/6] emacs: Improved `notmuch-describe-keymap' documentation Austin Clements
2013-10-08 6:46 ` Mark Walters
2013-10-10 10:45 ` David Bremner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://notmuchmail.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m2wqlpiq1u.fsf@guru.guru-group.fi \
--to=tomi.ollila@iki.fi \
--cc=amdragon@MIT.EDU \
--cc=markwalters1009@gmail.com \
--cc=notmuch@notmuchmail.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).