mayer@hplabsz.HPL.HP.COM (Niels Mayer) (07/28/87)
It would be really nice if the help-function documentation in gnuemacs would show the list of parameters to a function in addition to a description of the parameters.... When I called up documentation on "call-process" I got the following: call-process: Call PROGRAM in separate process. Program's input comes from file INFILE (nil means /dev/null). Insert output in BUFFER before point; t means current buffer; nil for BUFFER means discard it; 0 means discard and don't wait. Fourth arg DISPLAY non-nil means redisplay buffer as output is inserted. Remaining arguments are strings passed as command arguments to PROGRAM. This function waits for PROGRAM to terminate; if you quit, the process is killed. The above documentation would've been made much more useful f it had been prefixed with usage: (call-process <PROGRAM> <INFILE> <BUFFER> <DISPLAY> <arg1 ... argN>) since nothing in the documentation explicitly tells me what the order of the arguments are. (<BUFFER>, for example, is mentioned twice in the documentation text above, before <DISPLAY>) There are obvious implementation problems in having the cpp DEFUN macro that defines call-proces automatically label the arguments in creating the online documentation string. The grungy way, of course, is to actually include the "usage:" string in the documentation.... I'm sure RMS or one of his disciples can figure something out. Gnu Akhbar! May the holy GNU be praised! -- Niels.
smithln@rochester.arpa (Neil Smithline) (07/28/87)
In article <588@hplabsz.HPL.HP.COM> mayer@hplabsz.UUCP (Niels Mayer) writes:
#
#It would be really nice if the help-function documentation in gnuemacs
#would show the list of parameters to a function in addition to a
#description of the parameters.... When I called up documentation on
#"call-process" I got the following:
# ....
#The above documentation would've been made much more useful f it had been
#prefixed with
# usage: (call-process <PROGRAM> <INFILE> <BUFFER> <DISPLAY> <arg1 ... argN>)
#since nothing in the documentation explicitly tells me what the order of
#the arguments are. (<BUFFER>, for example, is mentioned twice in the
#documentation text above, before <DISPLAY>)
I have to disagree with you. This comment does provide full
information on the order of the arguments. The first one mentioned is
the first argument, the second *unique* argument is the second one and
so on. It is obvious that there are not two arguments called
<BUFFER> - if there were then one would be called <BUFFER1> and the
other <BUFFER2> or something like that.
Neil Smithline
ARPA: smithln@cs.rochester.edu
UUCP: ..!{allegra,decvax,seismo}!rochester!smithln
Mail: CS Dept., University of Rochester, Rochester NY 14627
--
Neil Smithline
ARPA: smithln@cs.rochester.edu
UUCP: ..!{allegra,decvax,seismo}!rochester!smithln
Mail: CS Dept., University of Rochester, Rochester NY 14627ram-ashwin@YALE.ARPA (Ashwin Ram) (08/07/87)
[Niels Mayer:] > #It would be really nice if the help-function documentation in gnuemacs > #would show the list of parameters to a function in addition to a > #description of the parameters [Neil Smithline:] > I have to disagree with you. This comment does provide full > information on the order of the arguments. While I agree that reading through the documentation comment does provide this information (*iff* the documentor wrote it carefully), I think the original suggestion is an excellent one. Calling describe-function should automatically generate call-process (program infile buffer display &optional args): ...doc for call-process... rather than call-process: ...doc for call-process... This is useful even with well-written documentation; with poorly documented code it is invaluable. For the latter reason, the function-name + args header should be generated automatically without relying on everyone to type it in for every function they write. -- Ashwin. ARPA: Ram-Ashwin@yale UUCP: {decvax,linus,seismo}!yale!Ram-Ashwin BITNET: Ram@yalecs
gudeman@arizona.edu (David Gudeman) (08/08/87)
Another thing that would be useful is a way to find out where a function came from, i.e.: (where-from 'dired) => "<emacs-dir>/lisp/dired.elc" (load-file "~/mydired.el") (where-from 'dired) => "~/mydired.el"
kyle@xanth.UUCP (Kyle Jones) (08/13/87)
All the online documentation improvements discussed so far seem to be to aid the Emacs-Lisp programmer. However, the online documentation is more often used by the people who don't want to program in Elisp but do need to know what a function does. Having things like &optional appear is going to confuse the daylights out of these people. Since the argument order and function discipline can be conveyed easily without exposing esoteric constructs like &optional, &rest, etc. to the uninitiated, this seems the best way to go. Emacs-Lisp programmers can always "use the force" and look at the source for most of the information needed. kyle jones <kyle@odu.edu> old dominion university, norfolk, va
gaynor@topaz.rutgers.edu (Silver) (08/13/87)
So many people are blissfully ignorant of GNU's help facilities.
They're not advertised enough when they need to be.
I would suggest two changes for your (collective) consideration.
First, devote a larger portion of the startup message to help. I
would imagine something along the lines of:
"C-h" - help - the help prefix
"C-h a" - apropos - give information on a keyword
"C-h k" - keys - describe the function run by a key sequence
"C-h f" - function - describe a function
Second, I would suggest a more informative second level of help
message.
A B C F I K L M N S T V W C-c C-w C-n C-w Type C-h again for more help:
isn't really too informative. Maybe
a-propos, k-ey sequence, f-unction, ..., or C-h again for more help:
might be better.
Silver.
VOICE: Andy Gaynor (Silver) PHONE: 201-545-0458
INTERNET: gaynor@topaz.rutgers.edu ICBM: 40 34 N / 74 45 W
UUCP: ...!<vertabrea>!rutgers!topaz.rutgers.edu!gaynor
ROOF: 81 Hassart Street, New Brunswick, NJ 08901
_____ _____
\ / "While Bill wrestles the alligator, \---/
\d/ I'll poor myself another martini..." \d/
V - Marlin Perkins V
| |
__|__ __|__montnaro@sprite.steinmetz (Skip Montanaro) (08/14/87)
In article <13956@topaz.rutgers.edu> gaynor@topaz.rutgers.edu (Silver) writes: >Second, I would suggest a more informative second level of help >message. > >A B C F I K L M N S T V W C-c C-w C-n C-w Type C-h again for more help: > >isn't really too informative. Maybe > >a-propos, k-ey sequence, f-unction, ..., or C-h again for more help: > >might be better. > >Silver. There really is no need for such a short second level help message, since the minibuffer can be grown to an appropriate size: Apropos Bindings Command(?) Function Info Key Lossage Mode News Syntax Tutorial Variable Where-is ^Copying ^Distribution ^Warranty It fits comfortably in two lines. ^H-c presents a bit of a non-mnemonic problem, though. Skip Montanaro (montanaro@ge-crd.arpa or uunet!steinmetz!desdemona!montanaro) "Believing I had supernatural powers, I slammed into a brick wall." -- P. Simon
ram-ashwin@YALE.ARPA (Ashwin Ram) (08/20/87)
OK, then how about a flag that you can set to NOVICE or EXPERT, depending on
what kind of help you're looking for?
-- Ashwin.
ARPA: Ram-Ashwin@cs.yale.edu
UUCP: {decvax,linus,seismo}!yale!Ram-Ashwin
BITNET: Ram@yalecspedz@bobkat.UUCP (Pedz Thing) (08/25/87)
One thing that I think would be helpful and pratical is some indicator
which tells if the function is implemented in C or in Lisp. When I am
writing lisp code I would like to know so that I can pick the fastest
one.
--
Cute signature line employing many literary allusions and puns.
Standard disclaimer concerning my mental incompetance.
Perry Smith a.k.a. (Pedz Thing)
pedz@bobkat or {ti-csl,infotel}!pollux!bobkat!pedzthomas%spline.uucp@utah-gr.UUCP (Spencer W. Thomas) (08/28/87)
[A suggestion was made that the documentation should indicate whether
a particular function is implemented in C or not]
This is certainly not appropriate for the online user documentation.
For the (mostly non-existent) programmer's manual, maybe. Anyway, for
now, you can always use symbol-function to give you this indication:
(symbol-function 'forward-char)
#<subr forward-char>
(symbol-function 'next-line)
(lambda (arg) 125274 (interactive "p") (byte-code
"BCU*
nil 1 forward-line 10 line-move] 4))
Here is a little function that will do the work for you:
(defun c-function-p (sym)
"Returns T if the function named by SYM is implemented in C."
(interactive "aFunction: ")
(if (interactive-p)
(message "Function %s is%s defined in C." sym
(if (not (listp (symbol-function sym))) "" " not"))
(not (listp (symbol-function sym)))))
(c-function-p 'forward-char)
t
(c-function-p 'next-line)
nil
=Spencer ({ihnp4,decvax}!utah-cs!thomas, thomas@cs.utah.edu)