3d/42a8265e7f7690bd19a7b222c024ece5a76e3b

   1 Return-Path: <tomi.ollila@iki.fi>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 56F6C431FAF\r
   6         for <notmuch@notmuchmail.org>; Sun,  6 Oct 2013 22:54:53 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: 0\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]\r
  12         autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id TOZtoTNG6zQJ for <notmuch@notmuchmail.org>;\r
  16         Sun,  6 Oct 2013 22:54:46 -0700 (PDT)\r
  17 Received: from guru.guru-group.fi (guru.guru-group.fi [46.183.73.34])\r
  18         by olra.theworths.org (Postfix) with ESMTP id 7C8BA431FAE\r
  19         for <notmuch@notmuchmail.org>; Sun,  6 Oct 2013 22:54:46 -0700 (PDT)\r
  20 Received: from guru.guru-group.fi (localhost [IPv6:::1])\r
  21         by guru.guru-group.fi (Postfix) with ESMTP id 9B735100030;\r
  22         Mon,  7 Oct 2013 08:54:38 +0300 (EEST)\r
  23 From: Tomi Ollila <tomi.ollila@iki.fi>\r
  24 To: Mark Walters <markwalters1009@gmail.com>,\r
  25         Austin Clements <amdragon@MIT.EDU>, notmuch@notmuchmail.org\r
  26 Subject: Re: [PATCH 4/6] emacs: Support overriding help and describing prefix\r
  27         action\r
  28 In-Reply-To: <87wqlqqhrn.fsf@qmul.ac.uk>\r
  29 References: <1381029768-11883-1-git-send-email-amdragon@mit.edu>\r
  30         <1381029768-11883-5-git-send-email-amdragon@mit.edu>\r
  31         <87wqlqqhrn.fsf@qmul.ac.uk>\r
  32 User-Agent: Notmuch/0.16+87~g451fefe (http://notmuchmail.org) Emacs/24.3.1\r
  33         (x86_64-unknown-linux-gnu)\r
  34 X-Face: HhBM'cA~<r"^Xv\KRN0P{vn'Y"Kd;zg_y3S[4)KSN~s?O\"QPoL\r
  35         $[Xv_BD:i/F$WiEWax}R(MPS`^UaptOGD`*/=@\1lKoVa9tnrg0TW?"r7aRtgk[F\r
  36         !)g;OY^,BjTbr)Np:%c_o'jj,Z\r
  37 Date: Mon, 07 Oct 2013 08:54:37 +0300\r
  38 Message-ID: <m2wqlpiq1u.fsf@guru.guru-group.fi>\r
  39 MIME-Version: 1.0\r
  40 Content-Type: text/plain\r
  41 X-BeenThere: notmuch@notmuchmail.org\r
  42 X-Mailman-Version: 2.1.13\r
  43 Precedence: list\r
  44 List-Id: "Use and development of the notmuch mail system."\r
  45         <notmuch.notmuchmail.org>\r
  46 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  47         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  48 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  49 List-Post: <mailto:notmuch@notmuchmail.org>\r
  50 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  51 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  52         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  53 X-List-Received-Date: Mon, 07 Oct 2013 05:54:53 -0000\r
  54 \r
  55 On Sun, Oct 06 2013, Mark Walters <markwalters1009@gmail.com> wrote:\r
  56 \r
  57 > This whole series looks good to me. If you are rolling another version\r
  58 > for any reason I have one trivial comment\r
  59 >\r
  60 > On Sun, 06 Oct 2013, Austin Clements <amdragon@MIT.EDU> wrote:\r
  61 >> Traditionally, function documentation strings are intended primarily\r
  62 >> for programmers, rather than users.  They're written from the\r
  63 >> perspective of calling the function, not interactively invoking it.\r
  64 >> They're only ever displayed along with the function prototype (and\r
  65 >> often refer to argument names).  And built-in help commands like\r
  66 >> `describe-bindings' show the name of the command, not its\r
  67 >> documentation.\r
  68 >>\r
  69 >> The notmuch help system is like `describe-bindings', but tries to be\r
  70 >> more user-friendly by displaying documentation strings, rather than\r
  71 >> Elisp command names.  For most commands, this is fine, but for some\r
  72 >> the "programmer description" is inappropriate for interactive use.\r
  73 >> This is particularly noticeable for commands that take an optional\r
  74 >> prefix argument.\r
  75 >>\r
  76 >> This patch adds support for two symbol properties: notmuch-doc and\r
  77 >> notmuch-prefix-doc, which let a command override its interactive\r
  78 >> documentation and provide separate documentation for its prefixed\r
  79 >> invocation.  If notmuch-prefix-doc is present, we add an extra line to\r
  80 >> the help giving the prefixed key sequence along with the documentation\r
  81 >> for the prefixed command.\r
  82 >> ---\r
  83 >>  emacs/notmuch.el | 29 ++++++++++++++++++++++++-----\r
  84 >>  1 file changed, 24 insertions(+), 5 deletions(-)\r
  85 >>\r
  86 >> diff --git a/emacs/notmuch.el b/emacs/notmuch.el\r
  87 >> index a36849f..278bd35 100644\r
  88 >> --- a/emacs/notmuch.el\r
  89 >> +++ b/emacs/notmuch.el\r
  90 >> @@ -140,7 +140,7 @@ This is basically just `format-kbd-macro' but we also convert ESC to M-."\r
  91 >>      "M-"\r
  92 >>        (concat desc " "))))\r
  93 >>  \r
  94 >> -(defun notmuch-describe-keymap (keymap &optional prefix tail)\r
  95 >> +(defun notmuch-describe-keymap (keymap ua-keys &optional prefix tail)\r
  96 >>    "Return a list of strings, each describing one key in KEYMAP.\r
  97 >>  \r
  98 >>  Each string gives a human-readable description of the key and the\r
  99 \r
 100 This series Looks Good To Me, too.\r
 101 \r
 102 > It would be nice to document the ua-keys variable here. It took me some\r
 103 > time to work out what was going in (and I worked out based on the\r
 104 > caller).\r
 105 \r
 106 I did not have any problems understanding this -- probably due to me\r
 107 having played so much with where-is-internal and such commands...\r
 108 ... just that this looks to me as 'first-ua-key' (ua being unversal \r
 109 argument, not user agent ;)\r
 110 \r
 111 If there is need for new version then documenting this would not hurt...\r
 112 if not followup-patch to add this documentation (w/ one line commit\r
 113 message for least review effort! ;) could do)\r
 114 \r
 115 Tomi\r
 116 \r
 117 >\r
 118 > Best wishes\r
 119 >\r
 120 > Mark\r
 121 >\r
 122 >> @@ -151,10 +151,19 @@ first line of documentation for the bound function."\r
 123 >>         ((keymapp binding)\r
 124 >>          (setq tail\r
 125 >>                (notmuch-describe-keymap\r
 126 >> -               binding (notmuch-prefix-key-description key) tail)))\r
 127 >> +               binding ua-keys (notmuch-prefix-key-description key) tail)))\r
 128 >>         (t\r
 129 >> +        (when (and ua-keys (symbolp binding)\r
 130 >> +                   (get binding 'notmuch-prefix-doc))\r
 131 >> +          ;; Documentation for prefixed command\r
 132 >> +          (let ((ua-desc (key-description ua-keys)))\r
 133 >> +            (push (concat ua-desc " " prefix (format-kbd-macro (vector key))\r
 134 >> +                          "\t" (get binding 'notmuch-prefix-doc))\r
 135 >> +                  tail)))\r
 136 >> +        ;; Documentation for command\r
 137 >>          (push (concat prefix (format-kbd-macro (vector key)) "\t"\r
 138 >> -                      (notmuch-documentation-first-line binding))\r
 139 >> +                      (or (and (symbolp binding) (get binding 'notmuch-doc))\r
 140 >> +                          (notmuch-documentation-first-line binding)))\r
 141 >>                tail))))\r
 142 >>     keymap)\r
 143 >>    tail)\r
 144 >> @@ -165,14 +174,24 @@ first line of documentation for the bound function."\r
 145 >>      (while (string-match "\\\\{\\([^}[:space:]]*\\)}" doc beg)\r
 146 >>        (let* ((keymap-name (substring doc (match-beginning 1) (match-end 1)))\r
 147 >>           (keymap (symbol-value (intern keymap-name)))\r
 148 >> -         (desc-list (notmuch-describe-keymap keymap))\r
 149 >> +         (ua-keys (where-is-internal 'universal-argument keymap t))\r
 150 >> +         (desc-list (notmuch-describe-keymap keymap ua-keys))\r
 151 >>           (desc (mapconcat #'identity desc-list "\n")))\r
 152 >>      (setq doc (replace-match desc 1 1 doc)))\r
 153 >>        (setq beg (match-end 0)))\r
 154 >>      doc))\r
 155 >>  \r
 156 >>  (defun notmuch-help ()\r
 157 >> -  "Display help for the current notmuch mode."\r
 158 >> +  "Display help for the current notmuch mode.\r
 159 >> +\r
 160 >> +This is similar to `describe-function' for the current major\r
 161 >> +mode, but bindings tables are shown with documentation strings\r
 162 >> +rather than command names.  By default, this uses the first line\r
 163 >> +of each command's documentation string.  A command can override\r
 164 >> +this by setting the 'notmuch-doc property of its command symbol.\r
 165 >> +A command that supports a prefix argument can explicitly document\r
 166 >> +its prefixed behavior by setting the 'notmuch-prefix-doc property\r
 167 >> +of its command symbol."\r
 168 >>    (interactive)\r
 169 >>    (let* ((mode major-mode)\r
 170 >>       (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))\r
 171 >> -- \r
 172 >> 1.8.4.rc3\r
 173 >>\r
 174 >> _______________________________________________\r
 175 >> notmuch mailing list\r
 176 >> notmuch@notmuchmail.org\r
 177 >> http://notmuchmail.org/mailman/listinfo/notmuch\r
 178 > _______________________________________________\r
 179 > notmuch mailing list\r
 180 > notmuch@notmuchmail.org\r
 181 > http://notmuchmail.org/mailman/listinfo/notmuch\r