From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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)))))