From: Austin Clements Date: Mon, 7 Oct 2013 22:49:57 +0000 (+2000) Subject: Re: [PATCH 4/6] emacs: Support overriding help and describing prefix action X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=b0432ee6b8f3500cbc24241c40a88fcacad6c73a;p=notmuch-archives.git Re: [PATCH 4/6] emacs: Support overriding help and describing prefix action --- diff --git a/38/b7708c97454bf526cc0a2b16348d49771268ea b/38/b7708c97454bf526cc0a2b16348d49771268ea new file mode 100644 index 000000000..0b2c851eb --- /dev/null +++ b/38/b7708c97454bf526cc0a2b16348d49771268ea @@ -0,0 +1,183 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 1CD73431FAF + for ; Mon, 7 Oct 2013 15:50:07 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -0.7 +X-Spam-Level: +X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 + tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id qIC7nNgD3teE for ; + Mon, 7 Oct 2013 15:50:01 -0700 (PDT) +Received: from dmz-mailsec-scanner-1.mit.edu (dmz-mailsec-scanner-1.mit.edu + [18.9.25.12]) + by olra.theworths.org (Postfix) with ESMTP id 6D907431FAE + for ; Mon, 7 Oct 2013 15:50:01 -0700 (PDT) +X-AuditID: 1209190c-b7fd38e0000009aa-28-52533a98a3c6 +Received: from mailhub-auth-1.mit.edu ( [18.9.21.35]) + by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP + id D2.E1.02474.89A33525; Mon, 7 Oct 2013 18:50:00 -0400 (EDT) +Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11]) + by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id r97Mo0RH009653; + Mon, 7 Oct 2013 18:50:00 -0400 +Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91]) + (authenticated bits=0) + (User authenticated as amdragon@ATHENA.MIT.EDU) + by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r97MnwWS001555 + (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT); + Mon, 7 Oct 2013 18:49:59 -0400 +Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80) + (envelope-from ) + id 1VTJck-0001Ni-7x; Mon, 07 Oct 2013 18:49:58 -0400 +Date: Mon, 7 Oct 2013 18:49:57 -0400 +From: Austin Clements +To: Mark Walters +Subject: Re: [PATCH 4/6] emacs: Support overriding help and describing prefix + action +Message-ID: <20131007224957.GL21611@mit.edu> +References: <1381029768-11883-1-git-send-email-amdragon@mit.edu> + <1381029768-11883-5-git-send-email-amdragon@mit.edu> + <87wqlqqhrn.fsf@qmul.ac.uk> +MIME-Version: 1.0 +Content-Type: text/plain; charset=us-ascii +Content-Disposition: inline +In-Reply-To: <87wqlqqhrn.fsf@qmul.ac.uk> +User-Agent: Mutt/1.5.21 (2010-09-15) +X-Brightmail-Tracker: + H4sIAAAAAAAAA+NgFmpmleLIzCtJLcpLzFFi42IR4hRV1p1hFRxksL3FxmL1XB6L6zdnMjsw + eeycdZfd49mqW8wBTFFcNimpOZllqUX6dglcGWdmdLAX7FWrOHO0soGxU66LkZNDQsBE4sje + AywQtpjEhXvr2boYuTiEBPYxSix+9Z8ZwtnAKHG1+QuUc4pJ4sfSdewQzhJGidv3bjKD9LMI + qEjsnzqVEcRmE9CQ2LZ/OZgtIqAjcfvQAnYQm1lAWuLb72YmEFtYIEzi5+WLYL28QDUXjn+A + 2jCVUWLTvANsEAlBiZMzn7BANGtJ3Pj3EqiZA2zQ8n8cIGFOoF2dm3vA5ogC3TDl5Da2CYxC + s5B0z0LSPQuhewEj8ypG2ZTcKt3cxMyc4tRk3eLkxLy81CJdQ73czBK91JTSTYzgsJbk2cH4 + 5qDSIUYBDkYlHl6Bw0FBQqyJZcWVuYcYJTmYlER5eyyDg4T4kvJTKjMSizPii0pzUosPMUpw + MCuJ8AoYAeV4UxIrq1KL8mFS0hwsSuK8Nznsg4QE0hNLUrNTUwtSi2CyMhwcShK8kSBDBYtS + 01Mr0jJzShDSTBycIMN5gIbPA6nhLS5IzC3OTIfIn2JUlBLnnQ2SEABJZJTmwfXC0s4rRnGg + V4R5d4BU8QBTFlz3K6DBTECDddkDQQaXJCKkpBoYSyY72vSem9J0QdNhmu3pZe95ePc8cbJv + +r1Q+K6Fz99v2iLPT596eHmfTLS1qdADud9lLj/m6b8+xpYnPuPIO56aS8+PfL/snho0Qex2 + msnyjxLvI3yvv9+o09FlUbz++eYoHelH5002HTr4+7Nqr+h7dZ8qHrGHy9qLDKp3fVxpFfVc + 9O+EW0osxRmJhlrMRcWJAKXlQ/AWAwAA +Cc: notmuch@notmuchmail.org +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Mon, 07 Oct 2013 22:50:07 -0000 + +Quoth Mark Walters on Oct 06 at 9:14 pm: +> +> 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 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 +> +> 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). + +Just sent a follow-up patch that improves this function documentation. + +> 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)))))