Suggestions on Emacs's Inline Doc

perm url: http://xahlee.org/emacs/modernization_inline_doc.html

Suggestions on Emacs's Inline Doc

Xah Lee, 2009-01-17

In emacs, you can press “Ctrl+x h ‹function name›” to see any elisp function's inline documentation, and if the cursor is on a function, it defaults to lookup that function. This integrated facility is extremely convenient. Some other scripting languages such as Perl, Python, Ruby, Javascript etc do provide such lookup too, often thru their command-line interface, but is nowhere near as convenient as in the emacs environment.

However, some improvement can be made. Here are some suggestions:

  • (1) make elisp-index-search's default prompt to be the symbol under cursor. This seems useful and consistent with other emacs lookup commands.
  • (2) make describe-function display a link to the elisp manual's node on that function.
  • (3) make describe-function display related functions as in “See also: ...”

For (1), few people have suggested implementations here: http://groups.google.com/group/gnu.emacs.help/browse_frm/thread/f248ae0258c1b37a

Here's one that works for me:

(defadvice elisp-index-search (before interactive-default activate)
  "Provide the symbol at point as the default when reading TOPIC interactively."
  (interactive
   (let ((symbol-at-point (thing-at-point 'symbol)))
     (list (read-string (if symbol-at-point
                            (format "Topic (%s): " symbol-at-point)
                          (format "Topic: "))
                        nil nil symbol-at-point)))))

For (2), showing a link to elisp manual of pertinent page would be convenient. Because sometimes inline doc is not detailed enough or doesn't provide context.

For (3), listing similar functions, is a practical need. For example, when looking up on goto-line, it might say “See also: goto-line, move-to-column, ...” etc..

Note that listing related functions in a function's doc is in many programing lang manuals. e.g Mathematica, MS's JScript, PHP ... they are quite useful. Because for those not expert yet of a lang (which is majority), often they do not know similar functions or do not know if there's manual page that list such, and often are confused about the differences of many functions that seem the same. By providing a list of similar functions, a coder can easily locate the right function to use for his task.

Note: some of the above suggestions are reported to emacs dev as bug number: #575, #1119.

Popular posts from this blog

11 Years of Writing About Emacs

does md5 creates more randomness?

Google Code shutting down, future of ErgoEmacs