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. However, some improvement can be made. Here are some suggestions:
For (1), few people have suggested implementations here: groups.google.com gnu.emacs.help.
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..
Listing related functions in a function's doc is in many programing lang manuals. e.g Mathematica, Microsoft'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.
For (4), Extend describe-function to other languages than emacs lisp, would be a major improvement. For example, in Perl, to lookup a function, i have to type “Alt+x perldoc -f ‹function name› Enter”. To look up a function while coding in Python, i typically have to switch to shell, start python interactive interpreter, type “help()” then the function's name. To lookup PHP keywords, i have to switch to browser then type “http://php.net/‹keyword name›”. Emacs can automate all these. When describe-function is called, it can simply check the value of “major-mode” local variable to determine the current language, then, switch to web browser with a appropriate url for that function's doc. If the language's documentation does provide a “info” format, then the integration would be seamless. (for a proof of concept, see: Dictionary and Reference Lookup with Emacs.)