New buffer help.

auto-complete · Mar 10, 2010 · d3ee77e · d3ee77e
1 parent 476a5f1
commit d3ee77e
Show file tree

Hide file tree

Showing 7 changed files with 101 additions and 41 deletions.
diff --git a/TODO.txt b/TODO.txt
@@ -1,5 +1,4 @@
 - help buffer
-- complete ignore list (doc)
 - etags, ctags
 - emacswiki
 - test facility

diff --git a/auto-complete.el b/auto-complete.el
@@ -320,6 +320,9 @@ If there is no common part, this will be nil.")
     (define-key map [down] 'ac-next)
     (define-key map [up] 'ac-previous)
 
+    (define-key map [f1] 'ac-help)
+    (define-key map (kbd "C-?") 'ac-help)
+
     (define-key map [C-down] 'ac-quick-help-scroll-down)
     (define-key map [C-up] 'ac-quick-help-scroll-up)
     (define-key map "\C-\M-n" 'ac-quick-help-scroll-down)
@@ -1042,6 +1045,10 @@ that have been made before in this function."
     (ac-remove-quick-help)
     (ac-update t)))
 
+(defun ac-help ()
+  (interactive)
+  (popup-menu-show-help ac-menu))
+
 (defun ac-set-quick-help-timer ()
   (when (and ac-use-quick-help
              (null ac-quick-help-timer))
@@ -1053,15 +1060,16 @@ that have been made before in this function."
     (setq ac-quick-help-timer nil)))
 
 (defun ac-quick-help (&optional force)
+  (interactive)
   (when (and (or force (null this-command))
              (ac-menu-live-p)
              (null ac-quick-help))
     (setq ac-quick-help
-          (popup-menu-show-help ac-menu nil
-                                :point ac-point
-                                :height ac-quick-help-height
-                                ;:scroll-bar t
-                                :nowait t))))
+          (popup-menu-show-quick-help ac-menu nil
+                                      :point ac-point
+                                      :height ac-quick-help-height
+                                      ;:scroll-bar t
+                                      :nowait t))))
 
 (defun ac-remove-quick-help ()
   (when ac-quick-help
@@ -1073,9 +1081,16 @@ that have been made before in this function."
   `(progn
      (defun ,name ,arglist ,@body)
      (put ',name 'ac-quick-help-command t)))
+
+(ac-define-quick-help-command ac-quick-help-scroll-down ()
+  (interactive)
+  (when ac-quick-help
+    (popup-scroll-down ac-quick-help)))
 
-(defun ac-make-quick-help-command (command)
-  (put command 'ac-quick-help-command t))
+(ac-define-quick-help-command ac-quick-help-scroll-up ()
+  (interactive)
+  (when ac-quick-help
+    (popup-scroll-up ac-quick-help)))
 
 
 
@@ -1234,16 +1249,6 @@ that have been made before in this function."
   (setq ac-selected-candidate nil)
   (ac-abort))
 
-(ac-define-quick-help-command ac-quick-help-scroll-down ()
-  (interactive)
-  (when ac-quick-help
-    (popup-scroll-down ac-quick-help)))
-
-(ac-define-quick-help-command ac-quick-help-scroll-up ()
-  (interactive)
-  (when ac-quick-help
-    (popup-scroll-up ac-quick-help)))
-
 (defun ac-trigger-key-command (&optional force)
   (interactive "P")
   (or (and (or force

diff --git a/doc/index.ja.txt b/doc/index.ja.txt
@@ -22,14 +22,15 @@ Auto Complete Mode
 ダウンロード
 ------------
 
-現在の安定板はv1.2です。
+現在の安定板はv1.2です（まだダウンロードできません）。
 
 * [auto-complete-1.2.tar.bz2](http://cx4a.org/pub/auto-complete/auto-complete-1.2.tar.bz2)
 * [auto-complete-1.2.tar.zip](http://cx4a.org/pub/auto-complete/auto-complete-1.2.tar.bz2)
 
 開発版を利用したい場合は次のリポジトリからチェックアウトしてください。
 
-<http://github.com/m2ym/auto-complete>
+* <http://cx4a.org/repo/auto-complete.git>
+* <http://github.com/m2ym/auto-complete> （ミラー）
 
 ユーザーマニュアル
 ------------------

diff --git a/doc/index.txt b/doc/index.txt
@@ -22,14 +22,15 @@ Screenshots
 Downloads
 ---------
 
-Current stable version is v1.2. Here are download links.
+Current stable version is v1.2. Here are download links (not yet available, sorry).
 
 * [auto-complete-1.2.tar.bz2](http://cx4a.org/pub/auto-complete/auto-complete-1.2.tar.bz2)
 * [auto-complete-1.2.tar.zip](http://cx4a.org/pub/auto-complete/auto-complete-1.2.tar.bz2)
 
 If you want to use or develop development version, please checkout from a repository.
 
-<http://github.com/m2ym/auto-complete>
+* <http://cx4a.org/repo/auto-complete.git>
+* <http://github.com/m2ym/auto-complete> (Mirror)
 
 User Manual
 -----------

diff --git a/doc/manual.ja.txt b/doc/manual.ja.txt
@@ -146,16 +146,23 @@ TABによる補完では共通部分の展開などで何度かTABを押す必
 
 その他の方法としてMetaキーと数字の組合せで選択することもできます。例えば`M-1`を押せば1番目の候補を選択して補完します。これもオーバーヘッドが大きいので極力使わないでください。
 
+### ヘルプ ###
+
+`auto-complete-mode`にはクイックヘルプとバッファヘルプの二つのヘルプ機能が備え付けられています。両者の違いは見せ方だけです。クイックヘルプは補完メニューのすぐ隣に表示するので、視線の移動が最小限で済むというメリットがありますが、表示領域が狭すぎると可読性が低くなるというデメリットがあります。またクイックヘルプは補完メニューを表示してからしばらく待つと自動的に表示されます。クイックヘルプを利用するには[`ac-use-quick-help`](#ac-use-quick-help)を`t`にしておく必要があります。表示までの時間は[`ac-quick-help-delay`](#ac-quick-help-delay)で制御できます。
+
+一方、ユーザーが明示的に命令することで表示されるのがバッファヘルプです。バッファヘルプはその名の通り、別ウィンドウにヘルプ用バッファを表示します。クイックヘルプに比べて視線の移動が大きい分、、可読性に優れています。バッファヘルプを表示するには補完中に`C-?`あるいは`f1`を押します。バッファヘルプ表示後はさらに`C-M-v`あるいは`C-M-S-v`でバッファヘルプの上下スクロールが可能です。それ以外の命令の場合はバッファヘルプを閉じてフォールバックします。
+
 ### まとめ ###
 
 補完は文字の入力によって開始されます。補完が開始されると次の表に示す操作が時的に有効になります。補完が完了したら、これらの操作は無効になります。
 
-| キー      | コマンド    | 説明                    |
-|-----------|-------------|-------------------------|
-| TAB, C-i  | ac-expand   | TABによる補完を実行する |
-| RET, C-m  | ac-complete | RETによる補完を実行する |
-| down, M-n | ac-next     | 次の候補を選択する      |
-| up, M-p   | ac-previous | 前の候補を選択する      |
+| キー      | コマンド    | 説明                     |
+|-----------|-------------|--------------------------|
+| TAB, C-i  | ac-expand   | TABによる補完を実行する  |
+| RET, C-m  | ac-complete | RETによる補完を実行する  |
+| down, M-n | ac-next     | 次の候補を選択する       |
+| up, M-p   | ac-previous | 前の候補を選択する       |
+| C-?, f1   | ac-help     | バッファヘルプを表示する |
 
 補完を途中で中断するには`C-g`を使うとよいでしょう。
 
@@ -549,6 +556,10 @@ Tips
 
 クイックヘルプを利用するかどうかです。
 
+### `ac-quick-help-delay` ###
+
+クイックヘルプを表示するまでの時間（秒）を実数で指定します。
+
 ### `ac-menu-height` ###
 
 補完メニューの行数を整数で指定します。

diff --git a/doc/manual.txt b/doc/manual.txt
@@ -146,6 +146,12 @@ Selecting candidates is not a complex operation. You can select candidates forwa
 
 There is other ways to select candidates. `M-1` to select candidate 1, `M-2` to select candidate 2, and so on.
 
+### ヘルプ ###
+
+`auto-complete-mode`にはクイックヘルプとバッファヘルプの二つのヘルプ機能が備え付けられています。両者の違いは見せ方だけです。クイックヘルプは補完メニューのすぐ隣に表示するので、視線の移動が最小限で済むというメリットがありますが、表示領域が狭すぎると可読性が低くなるというデメリットがあります。またクイックヘルプは補完メニューを表示してからしばらく待つと自動的に表示されます。クイックヘルプを利用するには[`ac-use-quick-help`](#ac-use-quick-help)を`t`にしておく必要があります。表示までの時間は[`ac-quick-help-delay`](#ac-quick-help-delay)で制御できます。
+
+一方、ユーザーが明示的に命令することで表示されるのがバッファヘルプです。バッファヘルプはその名の通り、別ウィンドウにヘルプ用バッファを表示します。クイックヘルプに比べて視線の移動が大きい分、、可読性に優れています。バッファヘルプを表示するには補完中に`C-?`あるいは`f1`を押します。バッファヘルプ表示後はさらに`C-M-v`あるいは`C-M-S-v`でバッファヘルプの上下スクロールが可能です。それ以外の命令の場合はバッファヘルプを閉じてフォールバックします。
+
 ### Summary ###
 
 Completion will be started by inserting characters. After completion is started, operations in the following table will be enabled temporarily. After completion is finished, these operations will be disable.
@@ -156,6 +162,7 @@ Completion will be started by inserting characters. After completion is started,
 | RET, C-m  | ac-complete | Completion by RET         |
 | down, M-n | ac-next     | Select next candidate     |
 | up, M-p   | ac-previous | Select previous candidate |
+| C-?, f1   | ac-help     | Show buffer help          |
 
 To stop completion, use `C-g` simply.
 
@@ -284,34 +291,34 @@ Here is an example. Think you are at \*scratch\* buffer. As we saied, this buffe
 
     (setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers))
 
-この例では、`ac-sources`を減らして、シンボル補完と同一メジャーモード間での単語補完のみを有効にしました。さて、これを次のEmacsの起動時にも有効にするにはどうしたらよいのでしょうか。\*scratch\*バッファ作成時に`emacs-lisp-mode-hook`というフックが実行されるので、このフックに適当な関数を追加するのがよいでしょう。
+This example changes `ac-source` setting and enable only symbol complteion and word completion among same major modes. Then, how can we enable this setting in next Emacas launching? We can change settings by adding a hook which is called when \*scratch\* buffer is created.
 
     (defun my-ac-emacs-lisp-mode ()
       (setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
 
     (add-hook 'emacs-lisp-mode-hook 'my-ac-emacs-lisp-mode)
 
-`.emacs`に`(ac-config-default)`が記述されている場合は、上記の方法では正しく動作しないかもしれません。というのも`(ac-config-default)`内部で同様のことを行っているので、どちらかが設定を上書きしてしまうからです。その場合は`(ac-config-default)`で利用する関数を再定義してしまうのがよいでしょう。`emacs-lisp-mode`の場合は、その関数名は`ac-emacs-lisp-mode-setup`です。詳しくは`auto-complete-config.el`を参照してください。
+If a code `(ac-config-default)` is written in `.emacs`, the code above may not be worked correctly. It is because of `(ac-config-default)` will overwrite the setting. In such case, you can redefine a function which is used in `(ac-config-default)`. The function name is `ac-emacs-lisp-mode-setup` in `emacs-lisp-mode`. See `auto-complete-config.el` for more details.
 
     (defun ac-emacs-lisp-mode-setup ()
       (setq ac-sources '(ac-source-symbols ac-source-words-in-same-mode-buffers)))
 
-さて、これで特定のメジャーモードで情報源を変更する方法が分かったと思います。まとめると次のようになるでしょう。
+So, now you know how to change sources in a specific major mode. Summary is:
 
-1. `ac-sources`を変更する関数を定義する
-2. `add-hook`で適当なモードフックにその関数を登録する（`c++-mode-hook`, `ruby-mode-hook`, `python-mode-hook`など）
+1. Define a function changing `ac-sources`
+2. Register the function to proper mode hoks (`c++-mode-hook`, `ruby-mode-hook`, and `python-mode-hook`, etc)
 
-では、全てのバッファに対して`ac-sources`を設定するにはどうしたらよいのでしょうか。その場合は`setq`ではなく`setq-default`で`ac-sources`を設定します。そうするとバッファローカル変数である`ac-sources`のデフォルト値が設定した値になります。
+By the way, how can we change a setting for all buffers? We use `setq-default` to change `ac-sources` instead of `setq` in such case. Then the default value of `ac-sources` will be changed to the value you specified.
 
     (setq-default ac-sources '(ac-source-words-in-all-buffer))
 
-他にも方法があります。`(ac-config-default)`は`auto-complete-mode`のフックである`auto-complete-mode-hook`に関数を追加することにより、`setq-default`によるデフォルト値の変更に近いことをやっています。その関数は`ac-common-setup`であり、`ac-sources`の先頭に`ac-source-filename`という情報源を追加しています。これにより`auto-complete-mode`が有効な全てのバッファで`ac-source-filename`が情報源の先頭に追加されます。なぜ先頭なのかというと、これにはオムニ補完の仕様が関係しているのですが、とりあえずここでは気にしなくてもいいです。つまるところ、`(ac-config-default)`を使っていて共通して`ac-sources`を変更したい場合は、この`ac-common-setup`関数を再定義することも一つの手段となります。
+There is other ways to do that. `(ac-config-default)`は`auto-complete-mode`のフックである`auto-complete-mode-hook`に関数を追加することにより、`setq-default`によるデフォルト値の変更に近いことをやっています。その関数は`ac-common-setup`であり、`ac-sources`の先頭に`ac-source-filename`という情報源を追加しています。これにより`auto-complete-mode`が有効な全てのバッファで`ac-source-filename`が情報源の先頭に追加されます。なぜ先頭なのかというと、これにはオムニ補完の仕様が関係しているのですが、とりあえずここでは気にしなくてもいいです。つまるところ、`(ac-config-default)`を使っていて共通して`ac-sources`を変更したい場合は、この`ac-common-setup`関数を再定義することも一つの手段となります。
 
     ;; 全てのバッファの`ac-sources`の末尾に辞書情報源を追加
     (defun ac-common-setup ()
       (setq ac-sources (append ac-sources '(ac-source-dictionary))))
 
-### 標準情報源 ###
+### Builtin Sources ###
 
 Here are defined sources in `auto-complete.el` and `auto-complete-config.el`.
 
@@ -547,6 +554,10 @@ Tips
 
 クイックヘルプを利用するかどうかです。
 
+### `ac-quick-help-delay` ###
+
+クイックヘルプを表示するまでの時間（秒）を実数で指定します。
+
 ### `ac-menu-height` ###
 
 補完メニューの行数を整数で指定します。

diff --git a/popup.el b/popup.el
@@ -743,16 +743,43 @@ See also `popup-item-propertize'."
   "Face for popup menu selection."
   :group 'popup)
 
-(defun popup-menu-show-help (menu &optional item &rest args)
+(defun popup-menu-document (menu &optional item)
+  (or item (setq item (popup-selected-item menu)))
+  (let ((doc (popup-item-document item)))
+    (if (functionp doc)
+        (setq doc (funcall doc (popup-item-value-or-self item))))
+    doc))
+
+(defun popup-menu-show-help (menu &optional item)
+  (let ((doc (popup-menu-document menu item)) event)
+    (when doc
+      (save-window-excursion
+        (with-current-buffer (get-buffer-create " *Popup Help*")
+          (erase-buffer)
+          (insert doc)
+          (goto-char (point-min))
+          (display-buffer (current-buffer)))
+        (block nil
+          (while (setq event (read-event))
+            (setq command )
+            (case (key-binding (vector event))
+              ('scroll-other-window
+               (scroll-other-window))
+              ('scroll-other-window-down
+               (scroll-other-window-down nil))
+              (t
+               (push event unread-command-events)
+               (return)))
+            (clear-this-command-keys)))))))
+
+(defun popup-menu-show-quick-help (menu &optional item &rest args)
   (or item (setq item (popup-selected-item menu)))
   (let* ((point (plist-get args :point))
          (height (or (plist-get args :height) (popup-height menu)))
          (min-height (min height (popup-current-height menu)))
          (around nil)
          (parent-offset (popup-offset menu))
-         (doc (popup-item-document item)))
-    (if (functionp doc)
-        (setq doc (funcall doc (popup-item-value-or-self item))))
+         (doc (popup-menu-document menu item)))
     (when (stringp doc)
       (if (popup-hidden-p menu)
           (setq around t
@@ -776,7 +803,7 @@ See also `popup-item-propertize'."
     (while (popup-live-p menu)
       (setq event (progn (clear-this-command-keys) (read-event prompt nil help-delay)))
       (if (null event)
-          (popup-menu-show-help menu)
+          (popup-menu-show-quick-help menu)
         (setq binding (popup-lookup-key-by-event (lambda (key) (lookup-key keymap key)) event))
         (cond
          ((eq binding 'popup-close)
@@ -799,6 +826,8 @@ See also `popup-item-propertize'."
           (popup-next menu))
          ((eq binding 'popup-previous)
           (popup-previous menu))
+         ((eq binding 'popup-help)
+          (popup-menu-show-help menu))
          ((eq binding 'popup-isearch)
           (popup-isearch menu))
          (binding
@@ -876,6 +905,9 @@ list of submenu."
     (define-key map "\C-p"      'popup-previous)
     (define-key map [up]        'popup-previous)
 
+    (define-key map [f1]        'popup-help)
+    (define-key map (kbd "\C-?") 'popup-help)
+
     (define-key map "\C-s"      'popup-isearch)
     map))