From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.devel Subject: Re: Changes to windows.texi Date: Sat, 08 Nov 2008 20:56:57 +0100 Message-ID: <4915EF09.3080806@gmx.at> References: <4914514C.9020700@gmx.at> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-15; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1226174371 31465 80.91.229.12 (8 Nov 2008 19:59:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 8 Nov 2008 19:59:31 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Nov 08 21:00:34 2008 connect(): Connection refused Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1Kytyz-00079D-O2 for ged-emacs-devel@m.gmane.org; Sat, 08 Nov 2008 21:00:34 +0100 Original-Received: from localhost ([127.0.0.1]:55772 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Kytxs-0002yw-AL for ged-emacs-devel@m.gmane.org; Sat, 08 Nov 2008 14:59:24 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Kytxo-0002yG-Q5 for emacs-devel@gnu.org; Sat, 08 Nov 2008 14:59:20 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Kytxn-0002xe-81 for emacs-devel@gnu.org; Sat, 08 Nov 2008 14:59:20 -0500 Original-Received: from [199.232.76.173] (port=55364 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Kytxn-0002xb-2n for emacs-devel@gnu.org; Sat, 08 Nov 2008 14:59:19 -0500 Original-Received: from mail.gmx.net ([213.165.64.20]:58867) by monty-python.gnu.org with smtp (Exim 4.60) (envelope-from ) id 1Kytxm-0004WV-Eg for emacs-devel@gnu.org; Sat, 08 Nov 2008 14:59:18 -0500 Original-Received: (qmail invoked by alias); 08 Nov 2008 19:59:15 -0000 Original-Received: from 88-117-45-231.adsl.highway.telekom.at (EHLO [88.117.45.231]) [88.117.45.231] by mail.gmx.net (mp022) with SMTP; 08 Nov 2008 20:59:15 +0100 X-Authenticated: #14592706 X-Provags-ID: V01U2FsdGVkX189/nNAzn496jE1QmmMqJaQtSmYvubaeinBFV8+2e sRofoCnfUcO4nN User-Agent: Thunderbird 2.0.0.16 (Windows/20080708) In-Reply-To: X-Y-GMX-Trusted: 0 X-FuHaFi: 0.63 X-detected-operating-system: by monty-python.gnu.org: Genre and OS details not recognized. X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:105473 Archived-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