--- /dev/null
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 1CD73431FAF\r
+ for <notmuch@notmuchmail.org>; Mon, 7 Oct 2013 15:50:07 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id qIC7nNgD3teE for <notmuch@notmuchmail.org>;\r
+ Mon, 7 Oct 2013 15:50:01 -0700 (PDT)\r
+Received: from dmz-mailsec-scanner-1.mit.edu (dmz-mailsec-scanner-1.mit.edu\r
+ [18.9.25.12])\r
+ by olra.theworths.org (Postfix) with ESMTP id 6D907431FAE\r
+ for <notmuch@notmuchmail.org>; Mon, 7 Oct 2013 15:50:01 -0700 (PDT)\r
+X-AuditID: 1209190c-b7fd38e0000009aa-28-52533a98a3c6\r
+Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])\r
+ by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id D2.E1.02474.89A33525; Mon, 7 Oct 2013 18:50:00 -0400 (EDT)\r
+Received: from outgoing.mit.edu (outgoing-auth-1.mit.edu [18.9.28.11])\r
+ by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id r97Mo0RH009653; \r
+ Mon, 7 Oct 2013 18:50:00 -0400\r
+Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
+ (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.8/8.12.4) with ESMTP id r97MnwWS001555\r
+ (version=TLSv1/SSLv3 cipher=DHE-RSA-AES128-SHA bits=128 verify=NOT);\r
+ Mon, 7 Oct 2013 18:49:59 -0400\r
+Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.80)\r
+ (envelope-from <amdragon@MIT.EDU>)\r
+ id 1VTJck-0001Ni-7x; Mon, 07 Oct 2013 18:49:58 -0400\r
+Date: Mon, 7 Oct 2013 18:49:57 -0400\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: Mark Walters <markwalters1009@gmail.com>\r
+Subject: Re: [PATCH 4/6] emacs: Support overriding help and describing prefix\r
+ action\r
+Message-ID: <20131007224957.GL21611@mit.edu>\r
+References: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
+ <1381029768-11883-5-git-send-email-amdragon@mit.edu>\r
+ <87wqlqqhrn.fsf@qmul.ac.uk>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\r
+Content-Disposition: inline\r
+In-Reply-To: <87wqlqqhrn.fsf@qmul.ac.uk>\r
+User-Agent: Mutt/1.5.21 (2010-09-15)\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFmpmleLIzCtJLcpLzFFi42IR4hRV1p1hFRxksL3FxmL1XB6L6zdnMjsw\r
+ eeycdZfd49mqW8wBTFFcNimpOZllqUX6dglcGWdmdLAX7FWrOHO0soGxU66LkZNDQsBE4sje\r
+ AywQtpjEhXvr2boYuTiEBPYxSix+9Z8ZwtnAKHG1+QuUc4pJ4sfSdewQzhJGidv3bjKD9LMI\r
+ qEjsnzqVEcRmE9CQ2LZ/OZgtIqAjcfvQAnYQm1lAWuLb72YmEFtYIEzi5+WLYL28QDUXjn+A\r
+ 2jCVUWLTvANsEAlBiZMzn7BANGtJ3Pj3EqiZA2zQ8n8cIGFOoF2dm3vA5ogC3TDl5Da2CYxC\r
+ s5B0z0LSPQuhewEj8ypG2ZTcKt3cxMyc4tRk3eLkxLy81CJdQ73czBK91JTSTYzgsJbk2cH4\r
+ 5qDSIUYBDkYlHl6Bw0FBQqyJZcWVuYcYJTmYlER5eyyDg4T4kvJTKjMSizPii0pzUosPMUpw\r
+ MCuJ8AoYAeV4UxIrq1KL8mFS0hwsSuK8Nznsg4QE0hNLUrNTUwtSi2CyMhwcShK8kSBDBYtS\r
+ 01Mr0jJzShDSTBycIMN5gIbPA6nhLS5IzC3OTIfIn2JUlBLnnQ2SEABJZJTmwfXC0s4rRnGg\r
+ V4R5d4BU8QBTFlz3K6DBTECDddkDQQaXJCKkpBoYSyY72vSem9J0QdNhmu3pZe95ePc8cbJv\r
+ +r1Q+K6Fz99v2iLPT596eHmfTLS1qdADud9lLj/m6b8+xpYnPuPIO56aS8+PfL/snho0Qex2\r
+ msnyjxLvI3yvv9+o09FlUbz++eYoHelH5002HTr4+7Nqr+h7dZ8qHrGHy9qLDKp3fVxpFfVc\r
+ 9O+EW0osxRmJhlrMRcWJAKXlQ/AWAwAA\r
+Cc: notmuch@notmuchmail.org\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Mon, 07 Oct 2013 22:50:07 -0000\r
+\r
+Quoth Mark Walters on Oct 06 at 9:14 pm:\r
+> \r
+> This whole series looks good to me. If you are rolling another version\r
+> for any reason I have one trivial comment\r
+> \r
+> On Sun, 06 Oct 2013, Austin Clements <amdragon@MIT.EDU> wrote:\r
+> > Traditionally, function documentation strings are intended primarily\r
+> > for programmers, rather than users. They're written from the\r
+> > perspective of calling the function, not interactively invoking it.\r
+> > They're only ever displayed along with the function prototype (and\r
+> > often refer to argument names). And built-in help commands like\r
+> > `describe-bindings' show the name of the command, not its\r
+> > documentation.\r
+> >\r
+> > The notmuch help system is like `describe-bindings', but tries to be\r
+> > more user-friendly by displaying documentation strings, rather than\r
+> > Elisp command names. For most commands, this is fine, but for some\r
+> > the "programmer description" is inappropriate for interactive use.\r
+> > This is particularly noticeable for commands that take an optional\r
+> > prefix argument.\r
+> >\r
+> > This patch adds support for two symbol properties: notmuch-doc and\r
+> > notmuch-prefix-doc, which let a command override its interactive\r
+> > documentation and provide separate documentation for its prefixed\r
+> > invocation. If notmuch-prefix-doc is present, we add an extra line to\r
+> > the help giving the prefixed key sequence along with the documentation\r
+> > for the prefixed command.\r
+> > ---\r
+> > emacs/notmuch.el | 29 ++++++++++++++++++++++++-----\r
+> > 1 file changed, 24 insertions(+), 5 deletions(-)\r
+> >\r
+> > diff --git a/emacs/notmuch.el b/emacs/notmuch.el\r
+> > index a36849f..278bd35 100644\r
+> > --- a/emacs/notmuch.el\r
+> > +++ b/emacs/notmuch.el\r
+> > @@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."\r
+> > "M-"\r
+> > (concat desc " "))))\r
+> > \r
+> > -(defun notmuch-describe-keymap (keymap &optional prefix tail)\r
+> > +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)\r
+> > "Return a list of strings, each describing one key in KEYMAP.\r
+> > \r
+> > Each string gives a human-readable description of the key and the\r
+> \r
+> It would be nice to document the ua-keys variable here. It took me some\r
+> time to work out what was going in (and I worked out based on the\r
+> caller).\r
+\r
+Just sent a follow-up patch that improves this function documentation.\r
+\r
+> Best wishes\r
+> \r
+> Mark\r
+> \r
+> > @@ -151,10 +151,19 @@ first line of documentation for the bound function."\r
+> > ((keymapp binding)\r
+> > (setq tail\r
+> > (notmuch-describe-keymap\r
+> > - binding (notmuch-prefix-key-description key) tail)))\r
+> > + binding ua-keys (notmuch-prefix-key-description key) tail)))\r
+> > (t\r
+> > + (when (and ua-keys (symbolp binding)\r
+> > + (get binding 'notmuch-prefix-doc))\r
+> > + ;; Documentation for prefixed command\r
+> > + (let ((ua-desc (key-description ua-keys)))\r
+> > + (push (concat ua-desc " " prefix (format-kbd-macro (vector key))\r
+> > + "\t" (get binding 'notmuch-prefix-doc))\r
+> > + tail)))\r
+> > + ;; Documentation for command\r
+> > (push (concat prefix (format-kbd-macro (vector key)) "\t"\r
+> > - (notmuch-documentation-first-line binding))\r
+> > + (or (and (symbolp binding) (get binding 'notmuch-doc))\r
+> > + (notmuch-documentation-first-line binding)))\r
+> > tail))))\r
+> > keymap)\r
+> > tail)\r
+> > @@ -165,14 +174,24 @@ first line of documentation for the bound function."\r
+> > (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)\r
+> > (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))\r
+> > (keymap (symbol-value (intern keymap-name)))\r
+> > - (desc-list (notmuch-describe-keymap keymap))\r
+> > + (ua-keys (where-is-internal 'universal-argument keymap t))\r
+> > + (desc-list (notmuch-describe-keymap keymap ua-keys))\r
+> > (desc (mapconcat #'identity desc-list "\n")))\r
+> > (setq doc (replace-match desc 1 1 doc)))\r
+> > (setq beg (match-end 0)))\r
+> > doc))\r
+> > \r
+> > (defun notmuch-help ()\r
+> > - "Display help for the current notmuch mode."\r
+> > + "Display help for the current notmuch mode.\r
+> > +\r
+> > +This is similar to `describe-function' for the current major\r
+> > +mode, but bindings tables are shown with documentation strings\r
+> > +rather than command names. By default, this uses the first line\r
+> > +of each command's documentation string. A command can override\r
+> > +this by setting the 'notmuch-doc property of its command symbol.\r
+> > +A command that supports a prefix argument can explicitly document\r
+> > +its prefixed behavior by setting the 'notmuch-prefix-doc property\r
+> > +of its command symbol."\r
+> > (interactive)\r
+> > (let* ((mode major-mode)\r
+> > (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))\r
projects / notmuch-archives.git / commitdiff