RE: async-shell-command

[Drew Adams]

> Also, I'm pretty sure that the current meaning of the prefix argument
> for `async-shell-command' /must/ be documented - it is far from obvious,
> and can be learned only from careful reading of the code.

You need not read the code, but you do need to read the doc
string carefully.  The info about the arguments is available,
but not clearly and directly.

For `async-shell-command' the doc string says:

 "Like `shell-command', but..."

But like it in what ways, one might wonder?  In fact and in
particular, it is like `shell-command' wrt the arguments.

It would be better for this doc string to explicitly refer a
reader to the doc string of `shell-command' for info about
the arguments, including the use of a prefix arg.

> I'm going to prepare such a patch for docs (both the docstring
> and the manual) first.

Thank you.  I'm sure it will be an improvement.

(Note too that the second line of the doc string should not be
blank.  Dunno why some people seem to think it is right to add
such a line.  I suspect that it comes from reading the doc
string only in the Lisp source instead of trying `C-h f'.)