Re: Changes to windows.texi

[martin rudalics <rudalics@gmx.at>]

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