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
>   address@hidden
>   +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