emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Changes to windows.texi


From: Eli Zaretskii
Subject: Re: Changes to windows.texi
Date: Sat, 08 Nov 2008 20:09:05 +0200

> Date: Fri, 07 Nov 2008 15:31:40 +0100
> From: martin rudalics <address@hidden>
> 
> 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
  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.

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.




reply via email to

[Prev in Thread] Current Thread [Next in Thread]