Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!seismo!rutgers!ucla-cs!zen!ucbvax!hplabs!hplabsz!mayer
From: mayer@hplabsz.HPL.HP.COM (Niels Mayer)
Newsgroups: comp.emacs
Subject: Improvement Suggestion for Gnu Emacs online documentation
Message-ID: <588@hplabsz.HPL.HP.COM>
Date: Mon, 27-Jul-87 19:51:14 EDT
Article-I.D.: hplabsz.588
Posted: Mon Jul 27 19:51:14 1987
Date-Received: Wed, 29-Jul-87 02:13:42 EDT
Reply-To: mayer@hplabsz.UUCP (Niels Mayer)
Organization: Hewlett-Packard Laboratories
Lines: 31


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.