Changes to windows.texi

Changes to windows.texi

[martin rudalics]

I now rewrote windows.texi a bit including the following changes:

- Two new nodes covering dedicated windows and window parameters.

- Window balancing and the buffer-local interpretation of
   window-configuration-change-hook added.

- An entry for window-point-insertion-type was added but needs a line
   telling why this is useful.

- The attributes listing stuff in *Basic Windows* was removed because it
   was inaccurate and not very useful (IMHO), and took away some space.
   If people think it's needed, I'll resurrect and update it.

- The redisplay-end-trigger stuff was left alone.  I suppose this should
   be removed as soon as an appropriate section has been added to font
   locking.

- I have not done much in the scrolling department.  Someone more
   familiar with the subject should see into this (candidates are the new
   behavior of scroll-preserve-screen-position and recenter-top-bottom).

Thanks in advance to everyone who intends to polish up the style of
these changes.  The ChangeLog entry should hint at what has been
mistreated most.

martin

Re: Changes to windows.texi

[Eli Zaretskii]

> Date: Fri, 07 Nov 2008 15:31:40 +0100
> From: martin rudalics <rudalics@gmx.at>
> 
> I now rewrote windows.texi a bit including the following changes:

Thanks.

> Thanks in advance to everyone who intends to polish up the style of
> these changes.

I made some corrections.

One problem that consistently shows up in your changes is demonstrated
by the following example:

  The selected window's buffer is usually the current buffer (except
  when @code{set-buffer} has been used), @xref{Current Buffer}.

This usage of @xref in the middle of a sentence produces badly
capitalized English, because @xref generates "See ..." with a capital
S.  The right way of writing this kind of text is either

  The selected window's buffer is usually the current buffer (except
  when @code{set-buffer} has been used), see @ref{Current Buffer}.

or

  The selected window's buffer is usually the current buffer (except
  when @code{set-buffer} has been used) (@pxref{Current Buffer}).

(The latter doesn't look good because of the other parenthesized text,
but that's another matter.)  I fixed all such invalid uses of @xref.

Another potential issue is as in this example, which is a full
sentence:

  @var{window} defaults to the selected window.

This makes "window", starting with a lower-case w, begin a sentence,
which might look like a typo in the printed manual.  (In the Info
manual, @var upcases its argument, so the problem is not visible.)
the original text was

  If @var{window} is omitted, this function returns the buffer for the
  selected window.

and thus didn't have this problem.  I didn't fix these sentences.

There are some changes whose motivation is unclear to me.  For
example, this change:

   @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
  -This function makes @var{buffer-or-name} the current buffer and
  -displays it in a window not currently selected.  It then selects that
  -window.  The handling of the buffer is the same as in
  -@code{switch-to-buffer}.
  +This function makes @var{buffer-or-name} the current buffer, displays it
  +in a window not currently selected, and selects that window.  The
  +handling of the buffer is the same as in @code{switch-to-buffer}.

looks for the worse to me, because it made one complex sentence out of
2 simpler ones.

I also don't understand why you removed paragraph indentation as in
this example:

  -  Here is how you can determine whether a given position @var{position}
  -is off the screen due to horizontal scrolling:
  +Here is how you can determine whether a given position @var{position} is
  +off the screen due to horizontal scrolling:

I didn't fix these, either.

Re: Changes to windows.texi

[martin rudalics]

Many thanks for looking into this.

 > One problem that consistently shows up in your changes is demonstrated
 > by the following example:
 >
 >   The selected window's buffer is usually the current buffer (except
 >   when @code{set-buffer} has been used), @xref{Current Buffer}.
 >
 > This usage of @xref in the middle of a sentence produces badly
 > capitalized English, because @xref generates "See ..." with a capital
 > S.  The right way of writing this kind of text is either

Here makeinfo (GNU texinfo - 4.8) does not capitalize the S for @xref,
so I was not aware of any such a problem.  Or does it capitalize them
only in the printed manual?

 > Another potential issue is as in this example, which is a full
 > sentence:
 >
 >   @var{window} defaults to the selected window.
 >
 > This makes "window", starting with a lower-case w, begin a sentence,
 > which might look like a typo in the printed manual.  (In the Info
 > manual, @var upcases its argument, so the problem is not visible.)
 > the original text was
 >
 >   If @var{window} is omitted, this function returns the buffer for the
 >   selected window.
 >
 > and thus didn't have this problem.  I didn't fix these sentences.

The problem is that I would have to write

    If @var{window} is omitted or @code{nil}, this function returns the
    buffer for the selected window.

to be correct, which means the sentence gets twice as long.  And there
are many instances of that.  Writing

    If @var{window} is omitted or @code{nil}, the selected window is
    used.

doesn't strike me as elegant either.  Anyway, I'll try to fix these
somehow.

 > There are some changes whose motivation is unclear to me.  For
 > example, this change:
 >
 >    @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
 >   -This function makes @var{buffer-or-name} the current buffer and
 >   -displays it in a window not currently selected.  It then selects that
 >   -window.  The handling of the buffer is the same as in
 >   -@code{switch-to-buffer}.
 >   +This function makes @var{buffer-or-name} the current buffer, displays it
 >   +in a window not currently selected, and selects that window.  The
 >   +handling of the buffer is the same as in @code{switch-to-buffer}.
 >
 > looks for the worse to me, because it made one complex sentence out of
 > 2 simpler ones.

If possible, please fix such stylistic issues.  I sometimes wanted to
avoid using "It" at the beginning of a sentence.

 > I also don't understand why you removed paragraph indentation as in
 > this example:
 >
 >   -  Here is how you can determine whether a given position @var{position}
 >   -is off the screen due to horizontal scrolling:
 >   +Here is how you can determine whether a given position @var{position} is
 >   +off the screen due to horizontal scrolling:
 >
 > I didn't fix these, either.

This must have happened when I refilled them.  I shall look into this.

Are such indentations necessary for formatting or are they a stylistic
convention?  That is, makeinfo produces them anyway, and throughout the
manuals I find both styles mixed.

martin

Re: Changes to windows.texi

[Eli Zaretskii]

> Date: Sat, 08 Nov 2008 20:56:57 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
> Many thanks for looking into this.

And many thanks for making the changes in the first place.

> Here makeinfo (GNU texinfo - 4.8) does not capitalize the S for @xref,
> so I was not aware of any such a problem.  Or does it capitalize them
> only in the printed manual?

It should capitalize them everywhere.  Are you sure it doesn't for
you?  Not even at the beginning of a sentence?

>  > Another potential issue is as in this example, which is a full
>  > sentence:
>  >
>  >   @var{window} defaults to the selected window.
>  >
>  > This makes "window", starting with a lower-case w, begin a sentence,
>  > which might look like a typo in the printed manual.  (In the Info
>  > manual, @var upcases its argument, so the problem is not visible.)
>  > the original text was
>  >
>  >   If @var{window} is omitted, this function returns the buffer for the
>  >   selected window.
>  >
>  > and thus didn't have this problem.  I didn't fix these sentences.
> 
> The problem is that I would have to write
> 
>     If @var{window} is omitted or @code{nil}, this function returns the
>     buffer for the selected window.
> 
> to be correct, which means the sentence gets twice as long.  And there
> are many instances of that.  Writing
> 
>     If @var{window} is omitted or @code{nil}, the selected window is
>     used.
> 
> doesn't strike me as elegant either.  Anyway, I'll try to fix these
> somehow.

I suggest

  The default for @var{window} is the selected window.

>  > I also don't understand why you removed paragraph indentation as in
>  > this example:
>  >
>  >   -  Here is how you can determine whether a given position @var{position}
>  >   -is off the screen due to horizontal scrolling:
>  >   +Here is how you can determine whether a given position @var{position} is
>  >   +off the screen due to horizontal scrolling:
>  >
>  > I didn't fix these, either.
> 
> This must have happened when I refilled them.  I shall look into this.
> 
> Are such indentations necessary for formatting or are they a stylistic
> convention?

I think it's a convention to have the first paragraph of a section not
to be indented, and indent all the others, although the manual is not
always consistent in this.

Richard, could you please answer this question?

> That is, makeinfo produces them anyway

What makeinfo does is controlled by @firstparagraphindent and
@paragraphindent.

Re: Changes to windows.texi

[martin rudalics]

 >> Here makeinfo (GNU texinfo - 4.8) does not capitalize the S for @xref,
 >> so I was not aware of any such a problem.  Or does it capitalize them
 >> only in the printed manual?
 >
 > It should capitalize them everywhere.  Are you sure it doesn't for
 > you?  Not even at the beginning of a sentence?

Only at the beginning of a sentence.  Anywhere else it does _not_
capitalize them.  But maybe Emacs' Info is more clever here than the
stand-alone reader?

 > I suggest
 >
 >   The default for @var{window} is the selected window.

Fine.  I'll use that.

 >> Are such indentations necessary for formatting or are they a stylistic
 >> convention?
 >
 > I think it's a convention to have the first paragraph of a section not
 > to be indented, and indent all the others, although the manual is not
 > always consistent in this.

It seems to me that more often the first paragraph is indented and the
remaining ones aren't.

 > What makeinfo does is controlled by @firstparagraphindent and
 > @paragraphindent.

Shouldn't `fill-paragraph' be able to DTRT then?

martin

Re: Changes to windows.texi

[Eli Zaretskii]

> Date: Sat, 08 Nov 2008 22:54:09 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
>  >> Here makeinfo (GNU texinfo - 4.8) does not capitalize the S for @xref,
>  >> so I was not aware of any such a problem.  Or does it capitalize them
>  >> only in the printed manual?
>  >
>  > It should capitalize them everywhere.  Are you sure it doesn't for
>  > you?  Not even at the beginning of a sentence?
> 
> Only at the beginning of a sentence.  Anywhere else it does _not_
> capitalize them.  But maybe Emacs' Info is more clever here than the
> stand-alone reader?

I think that's because Emacs produces "see" from the "*Note" part when
it displays the Info file.  Look at the Info file literally, and you
will see a capitalized "*Note" in a middle of a sentence.

>  > I think it's a convention to have the first paragraph of a section not
>  > to be indented, and indent all the others, although the manual is not
>  > always consistent in this.
> 
> It seems to me that more often the first paragraph is indented and the
> remaining ones aren't.

I think this is a mistake, but let's see what Richard says.

>  > What makeinfo does is controlled by @firstparagraphindent and
>  > @paragraphindent.
> 
> Shouldn't `fill-paragraph' be able to DTRT then?

You mean, in Texinfo Mode? maybe.

Re: Changes to windows.texi

[Richard M. Stallman]

    >  > I think it's a convention to have the first paragraph of a section not
    >  > to be indented, and indent all the others, although the manual is not
    >  > always consistent in this.
    > 
    > It seems to me that more often the first paragraph is indented and the
    > remaining ones aren't.

    I think this is a mistake, but let's see what Richard says.

It does not make a big difference, but the cleanest thing is to treat
all the paragraphs in one manual the same.

Re: Changes to windows.texi

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> Date: Sun, 09 Nov 2008 10:13:37 -0500
> Cc: rudalics@gmx.at, emacs-devel@gnu.org
> 
>     >  > I think it's a convention to have the first paragraph of a section not
>     >  > to be indented, and indent all the others, although the manual is not
>     >  > always consistent in this.
>     > 
>     > It seems to me that more often the first paragraph is indented and the
>     > remaining ones aren't.
> 
>     I think this is a mistake, but let's see what Richard says.
> 
> It does not make a big difference, but the cleanest thing is to treat
> all the paragraphs in one manual the same.

The Texinfo manual's recommendations are like I said above.

Re: Changes to windows.texi

[Richard M. Stallman]

    > It does not make a big difference, but the cleanest thing is to treat
    > all the paragraphs in one manual the same.

    The Texinfo manual's recommendations are like I said above.

Someone must have changed it since I wrote it.

Re: Changes to windows.texi

[Richard M. Stallman]

    This usage of @xref in the middle of a sentence produces badly
    capitalized English, because @xref generates "See ..." with a capital
    S.  The right way of writing this kind of text is either

      The selected window's buffer is usually the current buffer (except
      when @code{set-buffer} has been used), see @ref{Current Buffer}.

It isn't correct to use a comma there -- you need a semicolon.

      If @var{window} is omitted, this function returns the buffer for the
      selected window.

Better is "If you omit..." since it is the active voice.

Re: Changes to windows.texi

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> CC: rudalics@gmx.at, emacs-devel@gnu.org
> Date: Sun, 09 Nov 2008 10:13:34 -0500
> 
>     This usage of @xref in the middle of a sentence produces badly
>     capitalized English, because @xref generates "See ..." with a capital
>     S.  The right way of writing this kind of text is either
> 
>       The selected window's buffer is usually the current buffer (except
>       when @code{set-buffer} has been used), see @ref{Current Buffer}.
> 
> It isn't correct to use a comma there -- you need a semicolon.

Fixed.