bug#22926: 24.5; `shell-command', `shell-command-default-error-buffer'

bug#22926: 24.5; `shell-command', `shell-command-default-error-buffer'

[Drew Adams]

1. Doc string of `shell-command': Mention that you are prompted for the
   command.

2. `shell-command-default-error-buffer': Make it a user option.

3. In general, orient the doc a bit more toward interactive use.
   Especially since the doc suggests that it is especially for
   interactive use:

    In Elisp, you will often be better served by calling `call-process' or
    `start-process' directly, since it offers more control and does not impose
    the use of a shell (with its need to quote arguments).

4. Also, some lines in the doc string are too long (but not by much: 74
   chars max instead of 70).


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

bug#22926: 24.5; `shell-command', `shell-command-default-error-buffer'

[Eli Zaretskii]

> Date: Sun, 6 Mar 2016 07:14:47 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. Doc string of `shell-command': Mention that you are prompted for the
>    command.

Done.

> 2. `shell-command-default-error-buffer': Make it a user option.

Not sure it's necessary.

> 3. In general, orient the doc a bit more toward interactive use.

Upon reading the doc string, it already is: the entire first part of
it is specifically about interactive invocations.  If you have more
specific suggestions, let's hear them.

> 4. Also, some lines in the doc string are too long (but not by much: 74
>    chars max instead of 70).

I don't see how this can be helped, as those lines generally reference
symbols with long names.

bug#22926: 24.5; `shell-command', `shell-command-default-error-buffer'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> 2. `shell-command-default-error-buffer': Make it a user option.
>
> Not sure it's necessary.

I agree.  And I think you covered the other points in this bug report...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#22926: 24.5; `shell-command', `shell-command-default-error-buffer'

[Drew Adams]

> > 1. Doc string of `shell-command': Mention that you are prompted
> >    for the command.
> 
> Done.

Thx.

> > 2. `shell-command-default-error-buffer': Make it a user option.
> 
> Not sure it's necessary.

Why should it be an internal variable?  Did you check how it is used?

> > 4. Also, some lines in the doc string are too long (but not by
> >    much: 74 chars max instead of 70).
> 
> I don't see how this can be helped, as those lines generally
> reference symbols with long names.

Huh?  This is the longest line (but the mailer will perhaps wrap it):

 `start-process' directly, since it offers more control and does not impose

This is the second longest:

 In an interactive call, the variable `shell-command-default-error-buffer'

This the third longest:

 insert output in current buffer.  (This cannot be done asynchronously.)

None of those involves a symbol whose name is 68 or more chars.
They can all be shortened to 70 chars or less.

(All the other lines are 70 chars or less.)

bug#22926: 24.5; `shell-command', `shell-command-default-error-buffer'

[Eli Zaretskii]

> Date: Sun, 6 Mar 2016 13:30:59 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 22926@debbugs.gnu.org
> 
> > > 2. `shell-command-default-error-buffer': Make it a user option.
> > 
> > Not sure it's necessary.
> 
> Why should it be an internal variable?  Did you check how it is used?

I'm just saying it's not obvious we should do that.

> > > 4. Also, some lines in the doc string are too long (but not by
> > >    much: 74 chars max instead of 70).
> > 
> > I don't see how this can be helped, as those lines generally
> > reference symbols with long names.
> 
> Huh?  This is the longest line (but the mailer will perhaps wrap it):
> 
>  `start-process' directly, since it offers more control and does not impose
> 
> This is the second longest:
> 
>  In an interactive call, the variable `shell-command-default-error-buffer'
> 
> This the third longest:
> 
>  insert output in current buffer.  (This cannot be done asynchronously.)

The second one cannot be usefully made shorter (going from 72 columns
to 36 doesn't sound like a move for the best).  And since we have a 72
column line, having a 74-column line in the same doc string doesn't
sound like a disaster to me.

bug#22926: 24.5; `shell-command', `shell-command-default-error-buffer'

[Drew Adams]

> The second one cannot be usefully made shorter (going from 72
> columns to 36 doesn't sound like a move for the best).

I disagree.  A maximum limit is a maximum limit.  And it can affect
operations and tools such as window/frame fitting.

A 36-column line is not a "disaster".  Even a 2-column line is not
a disaster.

> And since we have a 72 column line, having a 74-column line in the
> same doc string doesn't sound like a disaster to me.

Etc., etc.  And if 74 then why not 76?  And if 76 then why not 78...

The lines should respect the maximum limit.  Simple, clear.  Helps
users both directly and indirectly (e.g. window/frame fitting).

And no, it is not a "disaster" if lines do not respect the rule.
But it is a bug - not all bugs are disasters.