bug#10334: 24.0.92; Doc fix

bug#10334: 24.0.92; Doc fix

[Dani Moncayo]

Hi,

Here's a documentation patch:
* The first part of the hunk clarifies a bit that paragraph,
explaining first how the new buffer's major mode is determined, and
then how is re-established when the buffer is saved to a file.
* The second part fixes a mistake.


=== modified file 'doc/emacs/buffers.texi'
--- doc/emacs/buffers.texi      2011-10-23 14:57:53 +0000
+++ doc/emacs/buffers.texi      2011-12-20 18:38:44 +0000
@@ -103,19 +103,20 @@
 buffer name.  @xref{Completion Exit}, for details.

  One reason to create a new buffer is to use it for making temporary
-notes.  If you try to save it, Emacs asks for the file name to use.
-The default value of the variable @code{major-mode} determines the new
-buffer's major mode; the default value is Fundamental mode.  @xref{Major
-Modes}.
+notes.  The default value of the variable @code{major-mode} determines
+the new buffer's major mode; the default value is Fundamental mode.
+@xref{Major Modes}.  If you try to save it, Emacs asks for the file
+name to use, and the major mode is then re-established, based on that
+file name.

 @kindex C-x @key{LEFT}
 @kindex C-x @key{RIGHT}
 @findex next-buffer
 @findex previous-buffer
  For conveniently switching between a few buffers, use the commands
-@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}.  @kbd{C-x @key{RIGHT}}
+@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}.  @kbd{C-x @key{LEFT}}
 (@code{previous-buffer}) selects the previous buffer (following the order
-of most recent selection in the current frame), while @kbd{C-x @key{LEFT}}
+of most recent selection in the current frame), while @kbd{C-x @key{RIGHT}}
 (@code{next-buffer}) moves through buffers in the reverse direction.

 @kindex C-x 4 b



--
Dani Moncayo

In GNU Emacs 24.0.92.1 (i386-mingw-nt6.1.7601)
 of 2011-12-16 on DANI-PC
Windowing system distributor `Microsoft Corp.', version 6.1.7601
configured using `configure --with-gcc (4.6) --no-opt --cflags
-fno-omit-frame-pointer'

bug#10334: 24.0.92; Doc fix

[Dani Moncayo]

Another thing that should be fixed:

Info node "(emacs)Misc Buffer" follows the typical structure which
first describes some commands briefly, and then gives more detailed
explanations.  But this structure is broken in these cases:
* The command `view-buffer' appears at the top (summary section) but
not at the bottom (detailed section).
* Conversely, the commands `append-to-buffer' and `insert-buffer'
appear at the bottom but not at the top.


-- 
Dani Moncayo

bug#10334: 24.0.92; Doc fix

[Eli Zaretskii]

> Date: Tue, 20 Dec 2011 19:56:37 +0100
> From: Dani Moncayo <dmoncayo@gmail.com>
> 
> Here's a documentation patch:

Thanks.

>   One reason to create a new buffer is to use it for making temporary
> -notes.  If you try to save it, Emacs asks for the file name to use.
> -The default value of the variable @code{major-mode} determines the new
> -buffer's major mode; the default value is Fundamental mode.  @xref{Major
> -Modes}.
> +notes.  The default value of the variable @code{major-mode} determines
> +the new buffer's major mode; the default value is Fundamental mode.
> +@xref{Major Modes}.  If you try to save it, Emacs asks for the file
> +name to use, and the major mode is then re-established, based on that
> +file name.

This change makes the text harder to understand.  Previously, it was
clear that "it" in "If you try to save it" referred to the new buffer,
because that sentence directly followed the one which talked about
creating a new buffer.  By moving "If you try to save it", you made
"it" ambiguous: now it's unclear what it refers to; it could be the
major mode, for example.

Here's what I think is a better version:

 One reason to create a new buffer is to use it for making temporary
 notes.  If you try to save it, Emacs asks for the file name to use.
 The default value of the variable @code{major-mode} determines the
 new buffer's major mode; the default value is Fundamental mode
 (@pxref{Major Modes}).  However, the file name you give when saving
 the buffer may cause Emacs to change the buffer's major mode as
 appropriate for that file name.

bug#10334: 24.0.92; Doc fix

[Dani Moncayo]

> Here's what I think is a better version:
>
>  One reason to create a new buffer is to use it for making temporary
>  notes.  If you try to save it, Emacs asks for the file name to use.
>  The default value of the variable @code{major-mode} determines the
>  new buffer's major mode; the default value is Fundamental mode
>  (@pxref{Major Modes}).  However, the file name you give when saving
>  the buffer may cause Emacs to change the buffer's major mode as
>  appropriate for that file name.

That's fine with me.

-- 
Dani Moncayo

bug#10334: 24.0.92; Doc fix

[Dani Moncayo]

Here's another doc fix:

=== modified file 'doc/emacs/text.texi'
--- doc/emacs/text.texi 2012-01-05 09:46:05 +0000
+++ doc/emacs/text.texi 2012-01-08 12:07:40 +0000
@@ -546,8 +546,8 @@
 newline as the end of a sentence; a period followed by just one space
 indicates an abbreviation, not the end of a sentence.  Accordingly,
 the fill commands will not break a line after a period followed by
-just one space.  If you change the variable
-@code{sentence-end-double-space} to a non-@code{nil} value, the fill
+just one space.  If you set the variable
+@code{sentence-end-double-space} to @code{nil}, the fill
 commands will break a line after a period followed by one space, and
 put just one space after each period.  @xref{Sentences}, for other
 effects and possible drawbacks of this.


-- 
Dani Moncayo

bug#10334: 24.0.92; Doc fix

[Chong Yidong]

Dani Moncayo <dmoncayo@gmail.com> writes:

> Here's another doc fix:

Thanks, I've committed the various fixed you pointed out in this thread
to the trunk.

> * The command `view-buffer' appears at the top (summary section) but
> not at the bottom (detailed section).
> * Conversely, the commands `append-to-buffer' and `insert-buffer'
> appear at the bottom but not at the top.

These are because the commands are discussed in detail elsewhere.  I
edited the text to make this clearer.

bug#10334: 24.0.92; Doc fix

[Dani Moncayo]

> Thanks, I've committed the various fixed you pointed out in this thread
> to the trunk.

Thanks Chong.  But I wonder why you didn't mention anything about the
major-mode re-setting that may take place after you save the new
buffer to a file.  Eli's version explained this point:

> One reason to create a new buffer is to use it for making temporary
> notes.  If you try to save it, Emacs asks for the file name to use.
> The default value of the variable @code{major-mode} determines the
> new buffer's major mode; the default value is Fundamental mode
> (@pxref{Major Modes}).  However, the file name you give when saving
> the buffer may cause Emacs to change the buffer's major mode as
> appropriate for that file name.

-- 
Dani Moncayo

bug#10334: 24.0.92; Doc fix

[Dani Moncayo]

>> Thanks, I've committed the various fixed you pointed out in this thread
>> to the trunk.
>
> Thanks Chong.  But I wonder why you didn't mention anything about the
> major-mode re-setting that may take place after you save the new
> buffer to a file.

Ping.

I think that the explanation about the new buffer's major mode would
be more complete if we mention that the major mode may change when the
buffer is saved to a file.

For example:

=== modified file 'doc/emacs/buffers.texi'
--- doc/emacs/buffers.texi      2012-02-09 06:43:23 +0000
+++ doc/emacs/buffers.texi      2012-02-23 20:28:35 +0000
@@ -106,7 +106,9 @@
 determines the new buffer's major mode; the default value is
 Fundamental mode.  @xref{Major Modes}.  One reason to create a new
 buffer is to use it for making temporary notes.  If you try to save
-it, Emacs asks for the file name to use.
+it, Emacs asks for the file name to use, and the buffer's major mode
+is re-established taking that file name into account (@pxref{Choosing
+Modes}).

 @kindex C-x @key{LEFT}
 @kindex C-x @key{RIGHT}




-- 
Dani Moncayo

bug#10334: 24.0.92; Doc fix

[Chong Yidong]

Dani Moncayo <dmoncayo@gmail.com> writes:

> I think that the explanation about the new buffer's major mode would
> be more complete if we mention that the major mode may change when the
> buffer is saved to a file.

Committed, thanks.