* Changes to windows.texi @ 2008-11-07 14:31 martin rudalics 2008-11-08 18:09 ` Eli Zaretskii 0 siblings, 1 reply; 11+ messages in thread From: martin rudalics @ 2008-11-07 14:31 UTC (permalink / raw) To: emacs-devel 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-07 14:31 Changes to windows.texi martin rudalics @ 2008-11-08 18:09 ` Eli Zaretskii 2008-11-08 19:56 ` martin rudalics 2008-11-09 15:13 ` Richard M. Stallman 0 siblings, 2 replies; 11+ messages in thread From: Eli Zaretskii @ 2008-11-08 18:09 UTC (permalink / raw) To: martin rudalics; +Cc: emacs-devel > 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-08 18:09 ` Eli Zaretskii @ 2008-11-08 19:56 ` martin rudalics 2008-11-08 20:16 ` Eli Zaretskii 2008-11-09 15:13 ` Richard M. Stallman 1 sibling, 1 reply; 11+ messages in thread From: martin rudalics @ 2008-11-08 19:56 UTC (permalink / raw) To: Eli Zaretskii; +Cc: emacs-devel 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-08 19:56 ` martin rudalics @ 2008-11-08 20:16 ` Eli Zaretskii 2008-11-08 21:54 ` martin rudalics 0 siblings, 1 reply; 11+ messages in thread From: Eli Zaretskii @ 2008-11-08 20:16 UTC (permalink / raw) To: martin rudalics; +Cc: emacs-devel > 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-08 20:16 ` Eli Zaretskii @ 2008-11-08 21:54 ` martin rudalics 2008-11-08 23:07 ` Eli Zaretskii 0 siblings, 1 reply; 11+ messages in thread From: martin rudalics @ 2008-11-08 21:54 UTC (permalink / raw) To: Eli Zaretskii; +Cc: emacs-devel >> 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 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-08 21:54 ` martin rudalics @ 2008-11-08 23:07 ` Eli Zaretskii 2008-11-09 15:13 ` Richard M. Stallman 0 siblings, 1 reply; 11+ messages in thread From: Eli Zaretskii @ 2008-11-08 23:07 UTC (permalink / raw) To: martin rudalics; +Cc: emacs-devel > 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-08 23:07 ` Eli Zaretskii @ 2008-11-09 15:13 ` Richard M. Stallman 2008-11-09 18:47 ` Eli Zaretskii 0 siblings, 1 reply; 11+ messages in thread From: Richard M. Stallman @ 2008-11-09 15:13 UTC (permalink / raw) To: Eli Zaretskii; +Cc: rudalics, emacs-devel > > 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-09 15:13 ` Richard M. Stallman @ 2008-11-09 18:47 ` Eli Zaretskii 2008-11-10 19:28 ` Richard M. Stallman 0 siblings, 1 reply; 11+ messages in thread From: Eli Zaretskii @ 2008-11-09 18:47 UTC (permalink / raw) To: rms; +Cc: rudalics, emacs-devel > 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-09 18:47 ` Eli Zaretskii @ 2008-11-10 19:28 ` Richard M. Stallman 0 siblings, 0 replies; 11+ messages in thread From: Richard M. Stallman @ 2008-11-10 19:28 UTC (permalink / raw) To: Eli Zaretskii; +Cc: rudalics, emacs-devel > 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-08 18:09 ` Eli Zaretskii 2008-11-08 19:56 ` martin rudalics @ 2008-11-09 15:13 ` Richard M. Stallman 2008-11-09 21:23 ` Eli Zaretskii 1 sibling, 1 reply; 11+ messages in thread From: Richard M. Stallman @ 2008-11-09 15:13 UTC (permalink / raw) To: Eli Zaretskii; +Cc: rudalics, emacs-devel 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: Changes to windows.texi 2008-11-09 15:13 ` Richard M. Stallman @ 2008-11-09 21:23 ` Eli Zaretskii 0 siblings, 0 replies; 11+ messages in thread From: Eli Zaretskii @ 2008-11-09 21:23 UTC (permalink / raw) To: rms; +Cc: rudalics, emacs-devel > 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. ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2008-11-10 19:28 UTC | newest] Thread overview: 11+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2008-11-07 14:31 Changes to windows.texi martin rudalics 2008-11-08 18:09 ` Eli Zaretskii 2008-11-08 19:56 ` martin rudalics 2008-11-08 20:16 ` Eli Zaretskii 2008-11-08 21:54 ` martin rudalics 2008-11-08 23:07 ` Eli Zaretskii 2008-11-09 15:13 ` Richard M. Stallman 2008-11-09 18:47 ` Eli Zaretskii 2008-11-10 19:28 ` Richard M. Stallman 2008-11-09 15:13 ` Richard M. Stallman 2008-11-09 21:23 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).