split-window as a command

split-window as a command

[Stephen Berman]

[I sent this yesterday, but it appears to have gotten lost on the way;
apologies for the duplication if it does finally arrive.]

The doc string of split-window says "Interactively, SIZE is the prefix
argument."  But in fact, invoking split-window with a prefix argument
has no effect, because its interactive spec is "i".  Maybe this is just
a doc bug, since, when split-window was still a C function, its doc
string said "Interactively, all arguments are nil."  But I don't see why
it is a command at all any more: invoked interactively, it has exactly
the same effect as invoking split-window-below without a prefix
argument, and since the latter does not ignore a prefix argument passed
to it, it does more than interactively called split-window.  So it
appears to be superfluous for split-window to be a command.  Or am I
overlooking something?

Steve Berman

Re: split-window as a command

[martin rudalics]

 > The doc string of split-window says "Interactively, SIZE is the prefix
 > argument."  But in fact, invoking split-window with a prefix argument
 > has no effect, because its interactive spec is "i".  Maybe this is just
 > a doc bug, since, when split-window was still a C function, its doc
 > string said "Interactively, all arguments are nil."  But I don't see why
 > it is a command at all any more: invoked interactively, it has exactly
 > the same effect as invoking split-window-below without a prefix
 > argument, and since the latter does not ignore a prefix argument passed
 > to it, it does more than interactively called split-window.  So it
 > appears to be superfluous for split-window to be a command.  Or am I
 > overlooking something?

Everything you say here is correct.  Can you please fix it?

Thanks, martin

Re: split-window as a command

[Stephen Berman]

On Fri, 12 Apr 2013 11:29:12 +0200 martin rudalics <rudalics@gmx.at> wrote:

>> The doc string of split-window says "Interactively, SIZE is the prefix
>> argument."  But in fact, invoking split-window with a prefix argument
>> has no effect, because its interactive spec is "i".  Maybe this is just
>> a doc bug, since, when split-window was still a C function, its doc
>> string said "Interactively, all arguments are nil."  But I don't see why
>> it is a command at all any more: invoked interactively, it has exactly
>> the same effect as invoking split-window-below without a prefix
>> argument, and since the latter does not ignore a prefix argument passed
>> to it, it does more than interactively called split-window.  So it
>> appears to be superfluous for split-window to be a command.  Or am I
>> overlooking something?
>
> Everything you say here is correct.  Can you please fix it?
>
> Thanks, martin

Here's a patch; I can't commit it to the Savannah repository, since I
don't have write access to it.



2013-04-12  Stephen Berman  <stephen.berman@gmx.net>

	* NEWS: Mention fixing `split-window' to be non-interactive.


=== modified file 'etc/NEWS'
*** etc/NEWS	2013-04-09 17:54:50 +0000
--- etc/NEWS	2013-04-12 10:34:13 +0000
***************
*** 76,81 ****
--- 76,86 ----
  \f
  * Editing Changes in Emacs 24.4
  
+ ** `split-window' is no longer a command, just a non-interactive function.
+ As a command it was a special case of `split-window-below', and as such
+ superfluous.  After being reimplemented in Lisp, its interactive form
+ was mistakenly retained.
+ 
  ** New commands `toggle-frame-fullscreen' and `toggle-frame-maximized',
  bound to <f11> and M-<f10>, respectively.
  


2013-04-12  Stephen Berman  <stephen.berman@gmx.net>

	* windows.texi (Splitting Windows): Change category of
	split-window from a command to a function.


=== modified file 'doc/lispref/windows.texi'
*** doc/lispref/windows.texi	2013-01-06 20:34:54 +0000
--- doc/lispref/windows.texi	2013-04-12 10:14:33 +0000
***************
*** 717,723 ****
  This section describes functions for creating a new window by
  @dfn{splitting} an existing one.
  
! @deffn Command split-window &optional window size side
  This function creates a new live window next to the window
  @var{window}.  If @var{window} is omitted or @code{nil}, it defaults
  to the selected window.  That window is ``split'', and reduced in
--- 717,723 ----
  This section describes functions for creating a new window by
  @dfn{splitting} an existing one.
  
! @defun split-window &optional window size side
  This function creates a new live window next to the window
  @var{window}.  If @var{window} is omitted or @code{nil}, it defaults
  to the selected window.  That window is ``split'', and reduced in
***************
*** 767,773 ****
  lieu of the usual action of @code{split-window}.  Otherwise, this
  function obeys the @code{window-atom} or @code{window-side} window
  parameter, if any.  @xref{Window Parameters}.
! @end deffn
  
    As an example, here is a sequence of @code{split-window} calls that
  yields the window configuration discussed in @ref{Windows and Frames}.
--- 767,773 ----
  lieu of the usual action of @code{split-window}.  Otherwise, this
  function obeys the @code{window-atom} or @code{window-side} window
  parameter, if any.  @xref{Window Parameters}.
! @end defun
  
    As an example, here is a sequence of @code{split-window} calls that
  yields the window configuration discussed in @ref{Windows and Frames}.



2013-04-12  Stephen Berman  <stephen.berman@gmx.net>

	* window.el (split-window): Remove interactive form, since as a
	command this function is a special case of split-window-below.


=== modified file 'lisp/window.el'
*** lisp/window.el	2013-01-02 16:13:04 +0000
--- lisp/window.el	2013-04-12 09:43:13 +0000
***************
*** 3686,3692 ****
  absolute value can be less than `window-min-height' or
  `window-min-width'; so this command can make a new window as
  small as one line or two columns.  SIZE defaults to half of
! WINDOW's size.  Interactively, SIZE is the prefix argument.
  
  Optional third argument SIDE nil (or `below') specifies that the
  new window shall be located below WINDOW.  SIDE `above' means the
--- 3686,3692 ----
  absolute value can be less than `window-min-height' or
  `window-min-width'; so this command can make a new window as
  small as one line or two columns.  SIZE defaults to half of
! WINDOW's size.
  
  Optional third argument SIDE nil (or `below') specifies that the
  new window shall be located below WINDOW.  SIDE `above' means the
***************
*** 3718,3724 ****
  window, these properties as well as the buffer displayed in the
  new window are inherited from the window selected on WINDOW's
  frame.  The selected window is not changed by this function."
-   (interactive "i")
    (setq window (window-normalize-window window))
    (let* ((side (cond
  		((not side) 'below)
--- 3718,3723 ----

Re: split-window as a command

[martin rudalics]

 > Here's a patch; I can't commit it to the Savannah repository, since I
 > don't have write access to it.

Could someone please commit and give Stephen write access ?

Thanks, martin

Re: split-window as a command

[Rand]

Stephen Berman <stephen.berman <at> gmx.net> writes:

> The doc string of split-window says "Interactively, SIZE is the prefix
> argument."  But in fact, invoking split-window with a prefix argument
> has no effect, because its interactive spec is "i".  Maybe this is just
> a doc bug, since, when split-window was still a C function, its doc
> string said "Interactively, all arguments are nil."  But I don't see why
> it is a command at all any more: invoked interactively, it has exactly
> the same effect as invoking split-window-below without a prefix
> argument, and since the latter does not ignore a prefix argument passed
> to it, it does more than interactively called split-window.  So it
> appears to be superfluous for split-window to be a command.  Or am I
> overlooking something?

It may be superfluous but it has always been a command and
removing the interactive form would break existing keybindings
and usage.

I think that:

* Fixing the doc-string would be better than removing the
interactive form.

* Changing the interactive form to use the prefix argument would
be better than fixing the doc-string.

--
Rand

Re: split-window as a command

[Xue Fuqiao]

On Fri, 12 Apr 2013 19:44:31 +0000 (UTC)
Rand <rand.user@ymail.com> wrote:

> It may be superfluous but it has always been a command and
> removing the interactive form would break existing keybindings
> and usage.

Maybe we can mark it as obsolete.

-- 
Xue Fuqiao
http://www.gnu.org/software/emacs/

Re: split-window as a command

[Stephen Berman]

On Fri, 12 Apr 2013 19:44:31 +0000 (UTC) Rand <rand.user@ymail.com> wrote:

> Stephen Berman <stephen.berman <at> gmx.net> writes:
>
>> The doc string of split-window says "Interactively, SIZE is the prefix
>> argument."  But in fact, invoking split-window with a prefix argument
>> has no effect, because its interactive spec is "i".  Maybe this is just
>> a doc bug, since, when split-window was still a C function, its doc
>> string said "Interactively, all arguments are nil."  But I don't see why
>> it is a command at all any more: invoked interactively, it has exactly
>> the same effect as invoking split-window-below without a prefix
>> argument, and since the latter does not ignore a prefix argument passed
>> to it, it does more than interactively called split-window.  So it
>> appears to be superfluous for split-window to be a command.  Or am I
>> overlooking something?
>
> It may be superfluous but it has always been a command and
> removing the interactive form would break existing keybindings
> and usage.

Maybe in the early days there was no split-window-vertically and
split-window was the only window-splitting command (I don't know).  But
at least since 18.59 (probably earlier) split-window has been redundant
as a command (and not documented in the Emacs manual), and has not had a
default key binding.  So any breakage would be in user settings or
third-party packages.  And the fix would simply be to add "-below" to
such occurrences of "split-window", which doesn't seem like much of a
hardship.  As for usage, since split-window never acted on a prefix
argument, replacing it with split-window-below interactively instead can
only be a win.

> I think that:
>
> * Fixing the doc-string would be better than removing the
> interactive form.

That would perpetuate its mistaken current status as a command.

> * Changing the interactive form to use the prefix argument would
> be better than fixing the doc-string.

That would mean adding code from split-window-below to process the
prefix argument, though split-window-below itself calls split-window.
That doesn't seem very clean.

It would be nice if there were a make-obsolete-command function, so
invoking split-window would warn: "This function is obsolete as a
command since 24.4; use `split-window-below' instead.

Steve Berman

Re: split-window as a command

[Xue Fuqiao]

On Sat, 13 Apr 2013 01:31:19 +0200
Stephen Berman <stephen.berman@gmx.net> wrote:

> It would be nice if there were a make-obsolete-command function, so
> invoking split-window would warn: "This function is obsolete as a
> command since 24.4; use `split-window-below' instead.

Agreed.  `define-obsolete-command-alias' is needed, too.

BTW if the warning is from echo area, it's too long (84 characters in
this case).  I have a (maybe) better version:

  This command is obsolete since 24.4; use `C-x 2' instead

It start with a capital letter but does not end with a period, just like
an error message.  The `C-x 2' is from the command (function or keyboard
macro) if the command is bounded.  And your version can be in the output
of `describe-function'.

-- 
Xue Fuqiao
http://www.gnu.org/software/emacs/

Re: split-window as a command

[Rand User]

From: Xue Fuqiao <xfq.free@gmail.com>



> BTW if the warning is from echo area, it's too long (84 characters in

> this case).  I have a (maybe) better version:
>
> This command is obsolete since 24.4; use `C-x 2' instead

Which command is obsolete?  Also, `C-x 2' looks more like a
key sequence than a command name.

If something like these obsolete warners are added, I think they should
only warn once per process and not every time you invoke the command.

Cheers,
Rand

Re: split-window as a command

[Xue Fuqiao]

On Fri, 12 Apr 2013 18:54:23 -0700 (PDT)
Rand User <rand.user@ymail.com> wrote:

> > BTW if the warning is from echo area, it's too long (84 characters in
> 
> > this case).  I have a (maybe) better version:
> >
> > This command is obsolete since 24.4; use `C-x 2' instead
> 
> Which command is obsolete?

The command you just executed.

Or we can use `split-window' here.

> Also, `C-x 2' looks more like a key sequence than a command name.

Yes.  There are 2 reasons to use `C-x 2' here:

1. It is usually too long to display two command names in the echo area;
(I even want to drop the " since 24.4".)

2. It is more convenient for users to execute the command, since they
won't need to use `describe-function' if they don't know the key
sequence for the command.

We can use `substitute-command-keys' for this feature.

> If something like these obsolete warners are added, I think they should
> only warn once per process and not every time you invoke the command.

Sounds fine to me.

-- 
Xue Fuqiao
http://www.gnu.org/software/emacs/

Re: split-window as a command

[Rand User]

> From: Xue Fuqiao <xfq.free@gmail.com>

>> 
>>  > I have a (maybe) better version:
>>  >
>>  > This command is obsolete since 24.4; use `C-x 2' instead
>> 
>>  Which command is obsolete?
> 
> The command you just executed.

I think explicitly giving the name of the obsolete command

and the replacement command would be better. Something similar
to the format used by `define-obsolete-function-alias'

    `split-window' is an obsolete command (as of 24.4); use `split-window-below' instead


or maybe

    The command `split-window' is obsolete (as of 24.4); use `split-window-below' instead



>> Also, `C-x 2' looks more like a key sequence than a command name.
>
> Yes.  There are 2 reasons to use `C-x 2' here:

>
> 1. It is usually too long to display two command names in the echo area;
> (I even want to drop the " since 24.4".)

>
>
> 2. It is more convenient for users to execute the command, since they

Encountering obsolete commands should be pretty rare,

so I think a detailed message is more important than
the convenience aspect.

Perhaps something like `disable-command' could be used
instead of just a message.

--
Rand

Re: split-window as a command

[Xue Fuqiao]

[-- Attachment #1: Type: text/plain, Size: 1795 bytes --]

On Fri, 12 Apr 2013 22:45:45 -0700 (PDT)
Rand User <rand.user@ymail.com> wrote:

> >>  > This command is obsolete since 24.4; use `C-x 2' instead

> I think explicitly giving the name of the obsolete command
> 
> and the replacement command would be better. Something similar
> to the format used by `define-obsolete-function-alias'
> 
>     `split-window' is an obsolete command (as of 24.4); use `split-window-below' instead
> 
> 
> or maybe
> 
>     The command `split-window' is obsolete (as of 24.4); use `split-window-below' instead
> 

In (info "(elisp) Documentation Tips"):

  Format the documentation string so that it fits in an Emacs window on
  an 80-column screen.  It is a good idea for most lines to be no wider
  than 60 characters.  The first line should not be wider than 67
  characters or it will look bad in the output of `apropos'.

Although I don't find a convention on echo area, I think it is good to
follow this convention.  See the attached files.

> >> Also, `C-x 2' looks more like a key sequence than a command name.
> >
> > Yes.  There are 2 reasons to use `C-x 2' here:
> >
> > 1. It is usually too long to display two command names in the echo area;
> > (I even want to drop the " since 24.4".)
> >
> > 2. It is more convenient for users to execute the command, since they
> 
> Encountering obsolete commands should be pretty rare,
> 
> so I think a detailed message is more important than
> the convenience aspect.

The detailed message can be in the output of `describe-function' and
`describe-key', the message in echo area shouldn't be too long.

> Perhaps something like `disable-command' could be used
> instead of just a message.

Sounds fine to me.

-- 
Xue Fuqiao
http://www.gnu.org/software/emacs/

[-- Attachment #2: screenshot.png --]
[-- Type: image/png, Size: 4285 bytes --]

[-- Attachment #3: screenshot2.png --]
[-- Type: image/png, Size: 4609 bytes --]

Re: split-window as a command

[Rand User]

From: Stephen Berman <stephen.berman@gmx.net>


> Maybe in the early days there was no split-window-vertically and
> split-window was the only window-splitting command (I don't know).  But
> at least since 18.59 (probably earlier) split-window has been redundant
> as a command (and not documented in the Emacs manual), and has not had a
> default key binding.  

To my knowledge, that's all correct.  

I kinda figured that `split-window' was made a command since its easier
to do `M-x split-window' than `M-x split-window-vertically'.

> So any breakage would be in user settings or third-party packages.   

That's the worst kind of breakage.  Emacs shouldn't break user code

for minor namespace cleanup.  

> As for usage, since split-window never acted on a prefix

> argument, replacing it with split-window-below interactively instead can
> only be a win.

I agree that `split-window-below' works better interactively than `split-window'
does.  Breaking backward compatibility is not a win however.

>> I think that:
>>
>> * Fixing the doc-string would be better than removing the
>> interactive form.
>
> That would perpetuate its mistaken current status as a command.

I don't think `split-window' was mistakenly made a command.

>> * Changing the interactive form to use the prefix argument would
>> be better than fixing the doc-string.
>
> That would mean adding code from split-window-below to process the
> prefix argument, though split-window-below itself calls split-window.
> That doesn't seem very clean.

The window splitting code in general doesn't seem very clean... :)

Maybe you could move some of the functionality in split-window-below
to split-window?

Cheers,

Rand

Re: split-window as a command

[martin rudalics]

 > The window splitting code in general doesn't seem very clean... :)

The whole concept of "splitting windows" is not very clean by itself.

 > Maybe you could move some of the functionality in split-window-below
 > to split-window?

IIUC the main purpose of `split-window-below' is to handle the option
`split-window-keep-point' without affecting `split-window'.

martin

Re: split-window as a command

[Stefan Monnier]

> It may be superfluous but it has always been a command and
> removing the interactive form would break existing keybindings
> and usage.

Let's remove the `interactive' spec and see what kind of breakage
comes along.


        Stefan

Re: split-window as a command

[Stephen Berman]

On Fri, 12 Apr 2013 22:10:51 -0400 Stefan Monnier <monnier@iro.umontreal.ca> wrote:

>> It may be superfluous but it has always been a command and
>> removing the interactive form would break existing keybindings
>> and usage.
>
> Let's remove the `interactive' spec and see what kind of breakage
> comes along.

Done.  To Rand: hope it doesn't hurt too much, but feel free to complain
if it does ;-).  (I already changed an old binding of split-window I had
in my initializations.)

Steve Berman