* 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 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-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 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
* 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
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 external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.