emacs-Xtra

emacs-Xtra

[Nick Roberts]

I think emacs-Xtra is becoming a bit of a dog's breakfast (possibly an
ms-dog's breakfast!).  If I want to find something out about VC, I don't want
to have to search through *two* manuals to find it because I can't guess
where the arbitrary split has been made.

I think the all the documentation for VC should be in one manual.  I have
two suggestions:

1) VC has its own manual like PCL-CVS does.

2) All the programming/development topics are moved to a separate manual
   (Emacs IDE?) and only the obscure stuff is left in emacs-Xtra.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: emacs-Xtra

[Richard Stallman]

The stuff about VC that's in the Emacs manual is there because it is
important enough that we should keep it in the printed manual.  At
least, I think it's that important; that's why I decided to keep it
there.

    1) VC has its own manual like PCL-CVS does.

That would be no good because this would be missing from the printed
manual.

    2) All the programming/development topics are moved to a separate manual
       (Emacs IDE?) and only the obscure stuff is left in emacs-Xtra.

If this means splitting the Emacs Manual into two manuals, both of which
we would print, maybe that is a good idea--but how would we split it?

(Version control is not used solely for editing programs, so including
VC in a manual for "editing programs with Emacs" would not be right.)

Re: emacs-Xtra

[Nick Roberts]

 >     2) All the programming/development topics are moved to a separate manual
 >        (Emacs IDE?) and only the obscure stuff is left in emacs-Xtra.
 > 
 > If this means splitting the Emacs Manual into two manuals, both of which
 > we would print, maybe that is a good idea--but how would we split it?

In such a way that that fairly self contained topics like VC stay together.
You declined to say how much smaller the Emacs Manual needs to be, but I would
keep as much in it as possible.

Without this information, I would guess that the Avanced Features section could
be Volume Two and everything before, and everything after (Recovery from
Problems), could be Volume One.

 > (Version control is not used solely for editing programs, so including
 > VC in a manual for "editing programs with Emacs" would not be right.)

Emacs User Manaual Vol 1: Basics
Emacs User Manaual Vol 2: Advanced Features

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: emacs-Xtra

[Nic]

Nick Roberts <nickrob@snap.net.nz> writes:

>  >     2) All the programming/development topics are moved to a separate manual
>  >        (Emacs IDE?) and only the obscure stuff is left in emacs-Xtra.
>  > 
>  > If this means splitting the Emacs Manual into two manuals, both of which
>  > we would print, maybe that is a good idea--but how would we split it?
>
> In such a way that that fairly self contained topics like VC stay together.
> You declined to say how much smaller the Emacs Manual needs to be, but I would
> keep as much in it as possible.
>
> Without this information, I would guess that the Avanced Features section could
> be Volume Two and everything before, and everything after (Recovery from
> Problems), could be Volume One.
>
>  > (Version control is not used solely for editing programs, so including
>  > VC in a manual for "editing programs with Emacs" would not be right.)
>
> Emacs User Manaual Vol 1: Basics
> Emacs User Manaual Vol 2: Advanced Features

How about just publishing an extra manual with the information in it
needed for programmers?

I'm sure we could find a whole lot more to put in that - and maybe
trim down the Emacs manual. 

So: there would be duplication (vc information in both) but one would
be able to control that with texinfo builds.


Nic Ferrier

Re: emacs-Xtra

[Eli Zaretskii]

> From: Nic <nferrier@tapsellferrier.co.uk>
> Date: Thu, 13 Apr 2006 08:10:16 +0100
> Cc: rms@gnu.org, emacs-devel@gnu.org
> 
> How about just publishing an extra manual with the information in it
> needed for programmers?

Since most Emacs users are programmers, I doubt that this would be a
useful partition.  That is, the number of places where we would need
to handle duplication will be very large.

On top of that, some advanced features are not only for programmers,
i.e. they are not directly related to any programmer-only activities.

Re: emacs-Xtra

[Richard Stallman]

    How about just publishing an extra manual with the information in it
    needed for programmers?

    I'm sure we could find a whole lot more to put in that - and maybe
    trim down the Emacs manual. 

I would like to see specific suggestions for how to do this.  With
specific suggestions, I could criticize them, try to improve them, or
maybe use them.

To me the problem looks rather hard.

Re: emacs-Xtra

[Nic]

")
Message-ID: <87d5fjsss2.fsf@nicferrier.tapsellferrier.co.uk>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii

Richard Stallman <rms@gnu.org> writes:

>     How about just publishing an extra manual with the information in it
>     needed for programmers?
>
>     I'm sure we could find a whole lot more to put in that - and maybe
>     trim down the Emacs manual. 
>
> I would like to see specific suggestions for how to do this.  With
> specific suggestions, I could criticize them, try to improve them, or
> maybe use them.

Whoops. I'm not sure I'd thought about this that much.

But I do think that an emacs manual for developers would be a good
idea. Emacs the IDE.

Much more detail on the various programming modes and tools could be
provided in such a manual.

If I have time over the next 2 weeks I'll try and come up with a
sketch of a table of contents for you to consider.


Nic

Re: emacs-Xtra

[Richard Stallman]

If someone provides a specific suggestion for splitting the Emacs manual
I will be glad to consider it.

Re: emacs-Xtra

[Ted Zlatanov]

On 13 Apr 2006, nickrob@snap.net.nz wrote:

> Emacs User Manual Vol 1: Basics
> Emacs User Manual Vol 2: Advanced Features

Why not just volumes 1 and 2, like the ELisp reference manual?  The
division could be basics vs. advanced, generally speaking, but there's
no need to spell it out in case a third volume is needed, or topics
are moved around.

I like the idea of one manual, rather than several.  The Emacs Manual
is how I learned about most of the Emacs features I use.

Ted

Re: emacs-Xtra

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Thu, 13 Apr 2006 14:40:27 -0400
> 
> On 13 Apr 2006, nickrob@snap.net.nz wrote:
> 
> > Emacs User Manual Vol 1: Basics
> > Emacs User Manual Vol 2: Advanced Features
> 
> Why not just volumes 1 and 2, like the ELisp reference manual?

Dividing the manual into 2 volumes doesn't solve the problem which is
the main cause for trying to keep the manual's size down.  The main
cause is that a larger manual increases the price of printing the
books, and thus makes it harder for the FSF to publish new versions.
(I'm guessing that publishing 2 volumes will increase the price even
more.)

So we need to find a solution that makes the _printed_ manuals
smaller.  Dividing into two volumes doesn't help.

Re: emacs-Xtra

[Ted Zlatanov]

On 14 Apr 2006, eliz@gnu.org wrote:

> Dividing the manual into 2 volumes doesn't solve the problem which is
> the main cause for trying to keep the manual's size down.  The main
> cause is that a larger manual increases the price of printing the
> books, and thus makes it harder for the FSF to publish new versions.
> (I'm guessing that publishing 2 volumes will increase the price even
> more.)

By the same reasoning the FSF should not publish a two-part ELisp
reference manual, because half of it could be online and it's cheaper
to publish one book.  I think that's false reasoning.  If the price is
prohibitive, let the FSF decide *that*, but Emacs certainly contains
enough for two and even three manuals, so we should not start with the
assumption that we have to have a smaller manual.  Remember also that
two books will increase revenue, not just costs - but as I said,
that's for the FSF to decide.

FWIW, I would gladly buy a better manual in two volumes.

Ted

Re: emacs-Xtra

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Fri, 14 Apr 2006 09:39:42 -0400
> 
> On 14 Apr 2006, eliz@gnu.org wrote:
> 
> > Dividing the manual into 2 volumes doesn't solve the problem which is
> > the main cause for trying to keep the manual's size down.  The main
> > cause is that a larger manual increases the price of printing the
> > books, and thus makes it harder for the FSF to publish new versions.
> > (I'm guessing that publishing 2 volumes will increase the price even
> > more.)
> 
> By the same reasoning the FSF should not publish a two-part ELisp
> reference manual, because half of it could be online and it's cheaper
> to publish one book.

You are driving the arguments to absurd, which doesn't help to resolve
the issue in a reasonable way.

ELisp manual is larger than the Emacs user's manual because it needs
to cover more material.  It is impossible to make the ELisp manual
significantly shorter without omitting stuff that Lisp programmers
undoubtfully need to know.

The price of publishing is not the _only_ consideration.  The manual
is published first and foremost to cover the important parts of the
material; but it doesn't have to cover _everything_.  The distinction
between _enough_ and _everything_ is where the price comes into
consideration.  I'm sure you understand all this very well.

> I think that's false reasoning.

That's the reasoning I got from Richard, and I'll let him restate or
revise it (in the latter case, I apologize for possible confusion).

> If the price is prohibitive, let the FSF decide *that*, but Emacs
> certainly contains enough for two and even three manuals, so we
> should not start with the assumption that we have to have a smaller
> manual.

I didn't start with such an assumption, AFAIK the FSF has _already_
decided that the manuals should not grow too much.  We need to find a
practical way to include more stuff in the on-line manual, while not
enlarging the expenses of the printed version too much.

I hope the solution I suggested elsewhere in this thread will be
accepted as a reasonable compromise.

Re: emacs-Xtra

[Ted Zlatanov]

On 14 Apr 2006, eliz@gnu.org wrote:

>> From: Ted Zlatanov <tzz@lifelogs.com>

>> By the same reasoning the FSF should not publish a two-part ELisp
>> reference manual, because half of it could be online and it's cheaper
>> to publish one book.
>
> You are driving the arguments to absurd, which doesn't help to resolve
> the issue in a reasonable way.

Sorry if it seems that way, I thought it was a sensible analogy.
Absurd would be "the FSF should not publish anything because it's
cheapest" ;)

> That's the reasoning I got from Richard, and I'll let him restate or
> revise it (in the latter case, I apologize for possible confusion).

Fair enough.  I just wanted to make sure the goal was not mistakenly
set to be one thing (smaller manual) when the FSF really wants to
accomplish another (lower costs).  Obviously RMS and you have
discussed it, and I'll defer to your knowledge of the situation and
costs.

> I hope the solution I suggested elsewhere in this thread will be
> accepted as a reasonable compromise.

I have two more suggestions:

- decrease the font size in the published manuals.  ORA books and many
  others use a noticeably smaller font, and are quite readable.

- edit the manual to shorten it, without losing content.

The latter is not too hard.  There are many sentences that could be
shortened or reworded without loss, after a cursory look through the
manual.

Ted

Re: emacs-Xtra

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Fri, 14 Apr 2006 12:05:03 -0400
> 
> Absurd would be "the FSF should not publish anything because it's
> cheapest" ;)

I thought you were trying to say just that.

> - edit the manual to shorten it, without losing content.
> 
> The latter is not too hard.  There are many sentences that could be
> shortened or reworded without loss, after a cursory look through the
> manual.

I'm sure changes to achieve that will be gratefully accepted.

Re: emacs-Xtra

[Richard Stallman]

    - decrease the font size in the published manuals.  ORA books and many
      others use a noticeably smaller font, and are quite readable.

We will take a look at that.

    - edit the manual to shorten it, without losing content.

    The latter is not too hard.  There are many sentences that could be
    shortened or reworded without loss, after a cursory look through the
    manual.

I doubt that we would save more than a few pages this way in the
manual overall.  But it might be an improvement anyway.  So would you
like to look at a source file and propose such changes?

Re: emacs-Xtra

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

>     - decrease the font size in the published manuals.  ORA books and many
>       others use a noticeably smaller font, and are quite readable.
>
> We will take a look at that.

It might be also an idea to mark out "advanced" sections.  Then one
could either leave them out or render them with smaller fonts when
printing, on the assumption that people would be unlikely to read all
of them and ruin their eyes.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: emacs-Xtra

[Ted Zlatanov]

On 15 Apr 2006, rms@gnu.org wrote:

> I doubt that we would save more than a few pages this way in the
> manual overall.  But it might be an improvement anyway.  So would you
> like to look at a source file and propose such changes?

I can do that.  Do you want it done before the current release or
after?

Is there a style guide for the manual?  For instance, I prefer active
to passive voice when writing English because it makes for clear,
short sentences that don't sound tentative.

Ted

Re: emacs-Xtra

[Richard Stallman]

    I can do that.  Do you want it done before the current release or
    after?

As soon as you can do it, we can use it.

    Is there a style guide for the manual?  For instance, I prefer active
    to passive voice when writing English because it makes for clear,
    short sentences that don't sound tentative.

I agree about that.

To the extent we have a style guide, it is the GNU coding standards.

emacs doc changes (was: emacs-Xtra)

[Ted Zlatanov]

[-- Attachment #1: Type: text/plain, Size: 65 bytes --]

Attached is patch #1, covering emacs.texi and screen.texi.

Ted


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: emacs+screen.texi.patch --]
[-- Type: text/x-patch, Size: 20872 bytes --]

? emacs+screen.texi.patch
Index: emacs.texi
===================================================================
RCS file: /sources/emacs/emacs/man/emacs.texi,v
retrieving revision 1.126
diff -r1.126 emacs.texi
92,94c92,94
< If you never before used the Info documentation system, type @kbd{h},
< and Emacs will take you to a programmed instruction sequence for the
< Info commands.
---
> To learn more about the Info documentation system, type @kbd{h}, and
> Emacs will take you to a programmed instruction sequence for the Info
> commands.
870,872c870,872
< editor.  The reader is not expected to be a programmer; simple
< customizations do not require programming skill.  The user who is not
< interested in customizing can ignore the scattered customization hints.
---
> editor.  Simple Emacs customizations do not require you to be a
> programmer.  If you are not interested in customizing, you can ignore
> the scattered customization hints.
875,880c875,879
< primer.  For complete beginners, it is a good idea to start with the
< on-line, learn-by-doing tutorial, before reading the manual.  To run the
< tutorial, start Emacs and type @kbd{C-h t}.  This way you can learn
< Emacs by using Emacs on a specially designed file which describes
< commands, tells you when to try them, and then explains the results you
< see.
---
> primer.  You should start with the on-line, learn-by-doing tutorial,
> before reading the manual if you are just starting to use Emacs.  To
> run the tutorial, start Emacs and type @kbd{C-h t}.  The tutorial
> describes commands, tells you when to try them, and explains the
> results.
886,888c885,887
< should practice the commands there.  The next few chapters describe
< fundamental techniques and concepts that are used constantly.  You need
< to understand them thoroughly, experimenting with them if necessary.
---
> should practice the commands shown there.  The next few chapters
> describe fundamental techniques and concepts that are used constantly.
> You need to understand them thoroughly and experiment with them.
891,893c890,892
< useful for all kinds of editing.  Chapter 20 and following chapters
< describe features that you may or may not want to use; read those
< chapters when you need them.
---
> useful for many kinds of editing.  Chapter 20 and following chapters
> describe optional yet useful features; read those chapters when you
> need them.
896c895
< properly.  It explains how to cope with some common problems
---
> properly.  It explains how to cope with many common problems
900,902c899,901
<   To find the documentation on a particular command, look in the index.
< Keys (character commands) and command names have separate indexes.  There
< is also a glossary, with a cross reference for each term.
---
>   To find out more about a particular command, look in the index.
> Keys (character commands) and command names have separate indexes.
> There is also a glossary, with a cross reference for each term.
905,908c904,907
< The Info file is for on-line perusal with the Info program, which will
< be the principal way of viewing documentation on-line in the GNU system.
< Both the Info file and the Info program itself are distributed along
< with GNU Emacs.  The Info file and the printed book contain
---
> The Info file is for on-line perusal with the Info program, which is
> the principal way to access documentation on-line in the GNU system.
> Both the Emacs Info file and the Info program itself are distributed
> along with GNU Emacs.  The Info file and the printed book contain
910c909
< files, which are also distributed along with GNU Emacs.
---
> files, which are also distributed with GNU Emacs.
1065,1066c1064,1065
<   We say that Emacs is a @dfn{display} editor because normally the text
< being edited is visible on the screen and is updated automatically as you
---
>   Emacs is a @dfn{display} editor because normally the text being
> edited is visible on the screen and is updated automatically as you
1069c1068
<   We call it a @dfn{real-time} editor because the display is updated very
---
>   It is a @dfn{real-time} editor because the display is updated very
1074,1079c1073,1078
<   We call Emacs advanced because it provides facilities that go beyond
< simple insertion and deletion: controlling subprocesses; automatic
< indentation of programs; viewing two or more files at once; editing
< formatted text; and dealing in terms of characters, words, lines,
< sentences, paragraphs, and pages, as well as expressions and comments in
< several different programming languages.
---
>   Emacs is advanced because it provides much more than simple
> insertion and deletion.  It can control subprocesses, indent programs
> automatically, show two or more files at once, and edit formatted
> text.  Emacs can operate in terms of characters, words, lines,
> sentences, paragraphs, and pages, as well as expressions and comments
> in several different programming languages.
1086,1106c1085,1106
<   @dfn{Customizable} means that you can change the definitions of Emacs
< commands in little ways.  For example, if you use a programming language in
< which comments start with @samp{<**} and end with @samp{**>}, you can tell
< the Emacs comment manipulation commands to use those strings
< (@pxref{Comments}).  Another sort of customization is rearrangement of the
< command set.  For example, if you prefer the four basic cursor motion
< commands (up, down, left and right) on keys in a diamond pattern on the
< keyboard, you can rebind the keys that way.  @xref{Customization}.
< 
<   @dfn{Extensible} means that you can go beyond simple customization and
< write entirely new commands, programs in the Lisp language to be run by
< Emacs's own Lisp interpreter.  Emacs is an ``on-line extensible''
< system, which means that it is divided into many functions that call
< each other, any of which can be redefined in the middle of an editing
< session.  Almost any part of Emacs can be replaced without making a
< separate copy of all of Emacs.  Most of the editing commands of Emacs
< are written in Lisp; the few exceptions could have been written
< in Lisp but are written in C for efficiency.  Although only a programmer
< can write an extension, anybody can use it afterward.  @xref{Top,
< Emacs Lisp Intro, Preface, eintr, An Introduction to Programming in
< Emacs Lisp}, if you want to learn Emacs Lisp programming.
---
>   @dfn{Customizable} means that you can affect or redefine Emacs
> commands in little ways.  For example, if you use a programming
> language in which comments start with @samp{<**} and end with
> @samp{**>}, you can tell the Emacs comment manipulation commands to
> use those strings (@pxref{Comments}).  Another sort of customization
> is rearrangement of the command set.  For example, you can rebind the
> basic cursor motion commands (up, down, left and right) to any keys on
> the keyboard that you find comfortable.  @xref{Customization}.
> 
>   @dfn{Extensible} means that you can go beyond simple customization
> and write entirely new commands -- programs in the Lisp language to be
> run by Emacs's own Lisp interpreter.  Emacs is an ``on-line
> extensible'' system, which means that it is divided into many
> functions that call each other, any of which can be redefined in the
> middle of an editing session.  Almost any part of Emacs can be
> replaced without making a separate copy of all of Emacs.  Most of the
> editing commands of Emacs are written in Lisp; the few exceptions
> could have been written in Lisp but use C instead for efficiency.
> Although only a programmer can write an extension, anybody can use it
> afterwards.  @xref{Top, Emacs Lisp Intro, Preface, eintr, An
> Introduction to Programming in Emacs Lisp}, if you want to learn Emacs
> Lisp programming.
1109,1113c1109,1113
< and convenient handling of mouse buttons.  But Emacs provides many of
< the benefits of a graphical display even on a text-only terminal.  For
< instance, it can highlight parts of a file, display and edit several
< files at once, move text between files, and edit files while running
< shell commands.
---
> and convenient handling of mouse buttons.  In addition, Emacs provides
> many of the benefits of a graphical display even on a text-only
> terminal.  For instance, it can highlight parts of a file, display and
> edit several files at once, move text between files, and edit files
> while running shell commands.
Index: screen.texi
===================================================================
RCS file: /sources/emacs/emacs/man/screen.texi,v
retrieving revision 1.26
diff -r1.26 screen.texi
27,28c27,28
< prompts appear and where you enter information when Emacs asks for it.
< See following sections for more information about these special lines.
---
> prompts appear and you enter information when Emacs asks for it.  See
> following sections for more information about these special lines.
39,40c39,40
< (such as a hollow box).  On text terminals, which have just one
< cursor, that cursor always appears in the selected window.
---
> (such as a hollow box).  On text terminals, the cursor always appears
> in the selected window.
43,47c43,47
< window (though mouse commands generally operate on whatever window you
< click them in, whether selected or not).  The text in other windows is
< mostly visible for reference, unless/until you select them.  If you
< use multiple frames on a graphical display, then giving the input
< focus to a particular frame selects a window in that frame.
---
> window (mouse commands generally operate on whatever window you click
> them in, whether selected or not).  The text in unselected windows is
> mostly visible for reference.  If you use multiple frames on a
> graphical display, then giving the input focus to a particular frame
> selects a window in that frame.
50,52c50,52
< is going on in that window.  It appears in different color and/or a
< ``3D'' box, if the terminal supports that; its contents normally begin
< with @w{@samp{--:-- @ *scratch*}} when Emacs starts.  The mode line
---
> is going on in that window.  It appears in different color or a ``3D''
> box if the terminal supports either; its contents normally begin with
> @w{@samp{--:-- @ *scratch*}} when Emacs starts.  The mode line
92,93c92,93
< window, each window has its own position for point in that buffer, and
< (when possible) its own cursor.
---
> window, each window has its own point in that buffer, and (when
> possible) its own cursor.
95,101c95,100
<   A text-only terminal has just one cursor, so Emacs puts it
< in the selected window.  The other windows do not show a cursor, even
< though they do have a location of point.  When Emacs updates the
< screen on a text-only terminal, it has to put the cursor temporarily
< at the place the output goes.  This doesn't mean point is there,
< though.  Once display updating finishes, Emacs puts the cursor where
< point is.
---
>   A text-only terminal has just one cursor in the selected window.
> The other windows do not show a cursor, even though they do have a
> location of point.  When Emacs updates the screen on a text-only
> terminal, it has to put the cursor temporarily at the place the output
> goes.  This doesn't mean point is there, though.  Once display
> updating finishes, Emacs puts the cursor where point is.
168,179c167,179
<   The size of @samp{*Messages*} is limited to a certain number of lines.
< The variable @code{message-log-max} specifies how many lines.  Once the
< buffer has that many lines, each line added at the end deletes one line
< from the beginning.  @xref{Variables}, for how to set variables such as
< @code{message-log-max}.
< 
<   The echo area is also used to display the @dfn{minibuffer}, a window that
< is used for reading arguments to commands, such as the name of a file to be
< edited.  When the minibuffer is in use, the echo area begins with a prompt
< string that usually ends with a colon; also, the cursor appears in that line
< because it is the selected window.  You can always get out of the
< minibuffer by typing @kbd{C-g}.  @xref{Minibuffer}.
---
>   The size of @samp{*Messages*} is limited to a certain number of
> lines.  The variable @code{message-log-max} specifies how many lines.
> Once the buffer has that many lines, new lines at the end remove lines
> from the beginning to keep the size constant.  @xref{Variables}, for
> how to set variables such as @code{message-log-max}.
> 
>   The echo area is also used to display the @dfn{minibuffer}, a window
> where you can input arguments to commands, such as the name of a file
> to be edited.  When the minibuffer is in use, the echo area begins
> with a prompt string that usually ends with a colon; also, the cursor
> appears in that line because it is the selected window.  You can
> always get out of the minibuffer by typing @kbd{C-g}.
> @xref{Minibuffer}.
194,195c194,195
< window has a slightly different appearance than those of other
< windows; see @ref{Optional Mode Line}, for more about this.
---
> window is slightly different from the others; see @ref{Optional Mode
> Line}, for more information.
204,207c204,207
< This gives information about the buffer being displayed in the window: the
< buffer's name, what major and minor modes are in use, whether the buffer's
< text has been changed, and how far down the buffer you are currently
< looking.
---
> This is information about the window and the buffer it displays: the
> buffer's name, what major and minor modes are in use, whether the
> buffer's text has been changed, and how far down the buffer you are
> currently looking.
214,215c214,215
<   @var{fr} appears only on text-only terminals, to show the selected
< frame name.  @xref{Frames}.  The initial frame's name is @samp{F1}.
---
>   @var{fr} appears only on text-only terminals as the selected frame
> name.  @xref{Frames}.  The initial frame's name is @samp{F1}.
217,218c217,218
<   @var{buf} is the name of the window's @dfn{buffer}.  In most cases
< this is the same as the name of a file you are editing.  @xref{Buffers}.
---
>   @var{buf} is the name of the window's @dfn{buffer}.  Usually this is
> the same as the name of a file you are editing.  @xref{Buffers}.
220,223c220,223
<   The buffer displayed in the selected window (the window that the
< cursor is in) is the @dfn{current buffer}--the one that editing takes
< place in.  When we speak of what some command does to ``the buffer,''
< we mean it does those things to the current buffer.
---
>   The buffer displayed in the selected window (the window with the
> cursor) is the @dfn{current buffer}, where editing happens.  When a
> command's effect applies to ``the buffer,'' we mean it does those
> things to the current buffer.
235,238c235,238
< This is present when Line Number mode is enabled (which it normally is).
< You can optionally display the current column number too, by turning on
< Column Number mode (which is not enabled by default because it is
< somewhat slower).  @xref{Optional Mode Line}.
---
> This is present when Line Number mode is enabled (it normally is).
> You can display the current column number too, by turning on Column
> Number mode.  It is not enabled by default because it is somewhat
> slower.  @xref{Optional Mode Line}.
241,245c241,245
< buffer.  At any time, each buffer is in one and only one of the possible
< major modes.  The major modes available include Fundamental mode (the
< least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many
< others.  @xref{Major Modes}, for details of how the modes differ and how
< to select one.@refill
---
> buffer.  A buffer can only be in one major mode at a time.  The major
> modes available include Fundamental mode (the least specialized), Text
> mode, Lisp mode, C mode, Texinfo mode, and many others.  @xref{Major
> Modes}, for details of how the modes differ and how to select
> one.@refill
256,258c256,259
< @xref{Minor Modes}, for more information.  @samp{Narrow} means that
< the buffer being displayed has editing restricted to only a portion of
< its text.  (This is not really a minor mode, but is like one.)
---
> @xref{Minor Modes}, for more information.  
> 
>   @samp{Narrow} means that the buffer being displayed has editing
> restricted to only a portion of its text.  This is like a minor mode.
262,263c263,264
<   In addition, if Emacs is currently inside a recursive editing level,
< square brackets (@samp{[@dots{}]}) appear around the parentheses that
---
>   In addition, if Emacs is inside a recursive editing level, square
> brackets (@samp{[@dots{}]}) appear around the parentheses that
291,306c292,306
<   The colon after @var{cs} can change to another string in certain
< circumstances.  Emacs uses newline characters to separate lines in the buffer.
< Some files use different conventions for separating lines: either
< carriage-return linefeed (the MS-DOS convention) or just carriage-return
< (the Macintosh convention).  If the buffer's file uses carriage-return
< linefeed, the colon changes to either a backslash (@samp{\}) or
< @samp{(DOS)}, depending on the operating system.  If the file uses just
< carriage-return, the colon indicator changes to either a forward slash
< (@samp{/}) or @samp{(Mac)}.  On some systems, Emacs displays
< @samp{(Unix)} instead of the colon even for files that use newline to
< separate lines.
< 
<   @xref{Optional Mode Line}, for features that add other handy
< information to the mode line, such as the size of the buffer, the
< current column number of point, and whether new mail for you has
< arrived.
---
>   The colon after @var{cs} can change to another string sometimes.
> Emacs uses newline characters to separate lines in the buffer.  Some
> files use different conventions for separating lines: either
> carriage-return linefeed (the MS-DOS convention) or just
> carriage-return (the Macintosh convention).  If the buffer's file uses
> carriage-return linefeed, the colon changes to either a backslash
> (@samp{\}) or @samp{(DOS)}, depending on the operating system.  If the
> file uses just carriage-return, the colon indicator changes to either
> a forward slash (@samp{/}) or @samp{(Mac)}.  On some systems, Emacs
> displays @samp{(Unix)} instead of the colon even for files that use
> newline to separate lines.
> 
>   @xref{Optional Mode Line}, to add other handy information to the
> mode line, such as the size of the buffer, the current column number
> of point, and whether new mail for you has arrived.
309,310c309,310
< various parts of it, Emacs displays help text to say what a click in
< that place will do.  @xref{Mode Line Mouse}.
---
> various parts of it, you'll see help text to say what a click in that
> place will do.  @xref{Mode Line Mouse}.
317,318c317,318
< can use to perform certain common operations.  There's no need to list
< them here, as you can more easily see for yourself.
---
> can use to perform common operations.  There's no need to list them
> here, as you can more easily see them yourself.
324,327c324,327
< from the menu bar.  An arrow pointing right, after the menu item,
< indicates that the item leads to a subsidiary menu; @samp{...} at the
< end means that the command will read arguments (further input from
< you) before it actually does anything.
---
> from the menu bar.  When a menu item has an arrow pointing right, it
> leads to a subsidiary menu; @samp{...} at the end means that the
> command invoked will read arguments (further input from you) before it
> actually does anything.
335,344c335,343
< @code{tmm-menubar}).  This command enters a mode in which you can select
< a menu item from the keyboard.  A provisional choice appears in the echo
< area.  You can use the up and down arrow keys to move through the
< menu to different choices.  When you have found the choice you want,
< type @key{RET} to select it.
< 
<   Each menu item also has an assigned letter or digit which designates
< that item; it is usually the initial of some word in the item's name.
< This letter or digit is separated from the item name by @samp{=>}.  You
< can type the item's letter or digit to select the item.
---
> @code{tmm-menubar}).  This lets you select a menu item from the
> keyboard.  A provisional choice appears in the echo area.  You can use
> the up and down arrow keys to move through the menu to different
> items, and then you can type @key{RET} to select the item..
> 
>   You'll see that each menu item in the text-only menubar also has an
> assigned letter or digit which designates that item; it is usually the
> initial of some word in the item's name.  You can type the item's
> letter or digit to select it.
347,348c346
< well; if so, the menu lists one equivalent key binding in parentheses
< after the item itself.
---
> well; one binding will be in parentheses after the item itself.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: emacs doc changes

[Ted Zlatanov]

[-- Attachment #1: Type: text/plain, Size: 135 bytes --]

Attached is patch #2, covering commands.texi and entering.texi.  I
fixed some info regarding multibyte vs. unibyte data as well.

Ted


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: commands+entering.texi.patch --]
[-- Type: text/x-patch, Size: 17818 bytes --]

Index: commands.texi
===================================================================
RCS file: /sources/emacs/emacs/man/commands.texi,v
retrieving revision 1.22
diff -r1.22 commands.texi
9,11c9,11
< commands and for the contents of files, and also explains the concepts
< of @dfn{keys} and @dfn{commands}, which are fundamental for understanding
< how Emacs interprets your keyboard and mouse input.
---
> commands and for the contents of files and the fundamental concepts of
> @dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard
> and mouse input.
38,42c38,42
<   Some @acronym{ASCII} control characters have special names, and most terminals
< have special keys you can type them with: for example, @key{RET},
< @key{TAB}, @key{DEL} and @key{ESC}.  The space character is usually
< referred to below as @key{SPC}, even though strictly speaking it is a
< graphic character whose graphic happens to be blank.
---
>   Some @acronym{ASCII} control characters have special names, and most
> terminals have special keys you can type them with: for example,
> @key{RET}, @key{TAB}, @key{DEL} and @key{ESC}.  The space character is
> usually known as @key{SPC}, even though strictly speaking it is a
> blank graphic character.
54,56c54,56
<   But the Emacs character set has room for control variants of all
< printing characters, and for distinguishing between @kbd{C-a} and
< @kbd{C-A}.  Graphical terminals make it possible to enter all these
---
>   The Emacs character set has room for control variants of all
> printing characters, and knows @kbd{C-a} and @kbd{C-A} are not the
> same.  Graphical terminals make it possible to enter all these
109,112c109,112
< all: for example function keys and arrow keys.  Mouse buttons are also
< outside the gamut of characters.  However, you can modify these events
< with the modifier keys @key{CTRL}, @key{META}, @key{SUPER},
< @key{HYPER} and @key{ALT}, just as you can modify keyboard characters.
---
> all, such as function keys and arrow keys.  Mouse buttons are also not
> characters.  However, you can modify these events with the modifier
> keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and @key{ALT},
> just as you can modify keyboard characters.
124c124
< because the keyboard input routines recognize these special sequences
---
> because the keyboard input routines catch these special sequences
133,138c133,137
<   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
< events that are meaningful as a unit---as ``a single command.''  Some
< Emacs command sequences are just one character or one event; for
< example, just @kbd{C-f} is enough to move forward one character in the
< buffer.  But Emacs also has commands that take two or more events to
< invoke.
---
>   A @dfn{key sequence} (@dfn{key}, for short) is a meaningful sequence
> of input events---a ``single command.''  Some Emacs command sequences
> are invoked by just one character or one event; for example, just
> @kbd{C-f} moves forward one character in the buffer.  But Emacs also
> has commands that take two or more events to invoke.
161,165c160,164
<   By contrast, you can't add more events onto a complete key.  For
< example, the two-event sequence @kbd{C-f C-k} is not a key, because
< the @kbd{C-f} is a complete key in itself.  It's impossible to give
< @kbd{C-f C-k} an independent meaning as a command.  @kbd{C-f C-k} is two
< key sequences, not one.@refill
---
>   You can't add input events onto a complete key.  For example, the
> two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f}
> is a complete key in itself.  It's impossible to give @kbd{C-f C-k} an
> independent meaning as a command.  @kbd{C-f C-k} is two key sequences,
> not one.@refill
171,174c170,173
< aliases for @kbd{C-h} and @kbd{C-x 6}.)  But this list is not cast in
< concrete; it is just a matter of Emacs's standard key bindings.  If
< you customize Emacs, you can make new prefix keys, or eliminate some
< of the standard ones.  @xref{Key Bindings}.
---
> aliases for @kbd{C-h} and @kbd{C-x 6}.)  This list is only due to
> Emacs's standard key bindings.  If you customize Emacs, you can make
> new prefix keys, or eliminate some of the standard ones (not
> recommended for most users).  @xref{Key Bindings}.
176c175
<   If you do make or eliminate prefix keys, that changes the set of
---
>   If you make or eliminate prefix keys, that changes the set of
178,181c177,180
< prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you
< define that too as a prefix).  Conversely, if you remove the prefix
< definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4
< @var{anything}}) is no longer a key.
---
> prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless
> you define that too as a prefix).  Conversely, if you remove the
> prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4
> @var{anything}} are no longer keys.
187c186
< change.  But @key{F1} should work for all prefix keys.
---
> change.  @key{F1} works for all prefix keys.
200,201c199,200
<   Every command has a name chosen by a programmer.  The name is usually
< made of a few English words separated by dashes; for example,
---
>   Every command has a name chosen by a programmer.  The name is
> usually made of a few English words separated by dashes; for example,
203,209c202,207
< @dfn{function definition} which is a Lisp program; this is what makes
< the command do what it does.  In Emacs Lisp, a command is actually a
< special kind of Lisp function; one which specifies how to read arguments
< for it and call it interactively.  For more information on commands and
< functions, see @ref{What Is a Function,, What Is a Function, elisp, The
< Emacs Lisp Reference Manual}.  (The definition we use in this manual is
< simplified slightly.)
---
> @dfn{function definition} which is a Lisp program; this is how the
> command does work.  In Emacs Lisp, a command is a Lisp function with
> special options to read arguments and for interactive use.  For more
> information on commands and functions, see @ref{What Is a Function,,
> What Is a Function, elisp, The Emacs Lisp Reference Manual}.  (The
> definition here is simplified slightly.)
211,212c209,210
<   The bindings between keys and commands are recorded in various tables
< called @dfn{keymaps}.  @xref{Keymaps}.
---
>   The bindings between keys and commands are recorded in tables called
> @dfn{keymaps}.  @xref{Keymaps}.
215,220c213,218
< glossing over a distinction that is irrelevant in ordinary use but is vital
< in understanding how to customize Emacs.  It is the command
< @code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
< this effect @emph{because} it is bound to that command.  If you rebind
< @kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move
< forward by words instead.  Rebinding keys is a common method of
---
> glossing over a minor distinction that is irrelevant in ordinary use
> but is vital to Emacs customization.  The command @code{next-line}
> does a vertical move downward.  @kbd{C-n} has this effect
> @emph{because} it is bound to @code{next-line}.  If you rebind
> @kbd{C-n} to the command @code{forward-word}, then @kbd{C-n} will move
> forward one word instead.  Rebinding keys is common in
225,226c223
< commands, even though strictly speaking a key is bound to some
< command.  To give the information needed for customization, we state
---
> commands, even though the key is bound to a command.  Usually we state
230,231c227,228
< down,'' meaning that @code{next-line} is a command that moves
< vertically down, and @kbd{C-n} is a key that is normally bound to it.
---
> down,'' meaning that the command @code{next-line} moves vertically
> down, and @kbd{C-n} is a key that is normally bound to it.
233,243c230,239
<   While we are on the subject of information for customization only,
< it's a good time to tell you about @dfn{variables}.  Often the
< description of a command will say, ``To change this, set the variable
< @code{mumble-foo}.''  A variable is a name used to remember a value.
< Most of the variables documented in this manual exist just to facilitate
< customization: some command or other part of Emacs examines the variable
< and behaves differently according to the value that you set.  Until you
< are interested in customizing, you can ignore the information about
< variables.  When you are ready to be interested, read the basic
< information on variables, and then the information on individual
< variables will make sense.  @xref{Variables}.
---
>   Since we are discussing customization, you should know about
> @dfn{variables}.  Often the description of a command will say, ``To
> change this, set the variable @code{mumble-foo}.''  A variable is a
> name used to store a value.  Most of the variables documented in this
> manual are meant for customization: some command or other part of
> Emacs examines the variable and behaves differently according to the
> value that you set.  You can ignore the information about variables
> until you want to customize them.  When you are ready, read the basic
> information on variables, and then customizing individual variables
> will make sense.  @xref{Variables}.
249,254c245,252
<   Text in Emacs buffers is a sequence of 8-bit bytes.  Each byte can
< hold a single @acronym{ASCII} character.  Both @acronym{ASCII} control characters (octal
< codes 000 through 037, and 0177) and @acronym{ASCII} printing characters (codes
< 040 through 0176) are allowed; however, non-@acronym{ASCII} control characters
< cannot appear in a buffer.  The other modifier flags used in keyboard
< input, such as Meta, are not allowed in buffers either.
---
>   Text in Emacs buffers is a sequence of characters.  In the default
> Unibyte Mode, each character in an 8-bit byte that can hold a single
> @acronym{ASCII} character.  Both @acronym{ASCII} control characters
> (octal codes 000 through 037, and 0177) and @acronym{ASCII} printing
> characters (codes 040 through 0176) are allowed; however,
> non-@acronym{ASCII} control characters cannot appear in a buffer.  The
> other modifier flags used in keyboard input, such as Meta, are not
> allowed in buffers either.
270,271c268,269
< alphabet of non-@acronym{ASCII} characters, but they all fit in one byte.  They
< use codes 0200 through 0377.  @xref{Unibyte Mode}.
---
> alphabet of non-@acronym{ASCII} characters, which all fit in one byte.
> They use octal codes 0200 through 0377.  @xref{Unibyte Mode}.
Index: entering.texi
===================================================================
RCS file: /sources/emacs/emacs/man/entering.texi,v
retrieving revision 1.16
diff -r1.16 entering.texi
11,21c11,21
< @command{emacs}.  Emacs clears the screen and then displays an initial
< help message and copyright notice.  Some operating systems discard all
< type-ahead when Emacs starts up; they give Emacs no way to prevent
< this.  If you ever use those systems, learn the habit of waiting for
< Emacs to clear the screen before typing your first editing command.
< 
<   If you run Emacs from a shell window under the X Window System, run it
< in the background with @command{emacs&}.  This way, Emacs does not tie up
< the shell window, so you can use that to run other shell commands while
< Emacs operates its own X windows.  You can begin typing Emacs commands
< as soon as you direct your keyboard input to the Emacs frame.
---
> @command{emacs}.  Emacs clears the screen and displays an initial help
> message and copyright notice.  Some operating systems discard all your
> input while Emacs starts up; they give Emacs no way to prevent this.
> If you ever use those systems, wait for Emacs to clear the screen
> before you start typing.
> 
>   From a shell window under the X Window System, run Emacs in the
> background with @command{emacs&}.  This way, Emacs won't tie up the
> shell window, so you can use it to run other shell commands while
> Emacs is running.  You can type Emacs commands as soon as you direct
> your keyboard input to an Emacs frame.
25,28c25,28
< That's the buffer you start out in.  The @samp{*scratch*} buffer uses
< Lisp Interaction mode; you can use it to type Lisp expressions and
< evaluate them, or you can ignore that capability and just write notes
< in it.  (You can specify a different major mode for this buffer by
---
> That's the first buffer you'll see.  The @samp{*scratch*} buffer uses
> Lisp Interaction mode; that lets you type Lisp expressions and
> evaluate them.  You can ignore that capability and just write notes
> there.  You can specify a different major mode for this buffer by
30c30
< @xref{Init File}.)
---
> @xref{Init File}.
33,41c33,39
< loaded, and functions to be called, by giving Emacs arguments in the
< shell command line.  @xref{Emacs Invocation}.  But we don't recommend
< doing this.  The feature exists mainly for compatibility with other
< editors.
< 
<   Many other editors are designed to be started afresh each time you
< want to edit.  You edit one file and then exit the editor.  The next
< time you want to edit either another file or the same one, you must run
< the editor again.  With these editors, it makes sense to use a
---
> loaded, and functions to be called through Emacs command-line
> arguments.  @xref{Emacs Invocation}.  The feature exists mainly for
> compatibility with other editors, and is normally not recommended.
> 
>   Many other editors are designed so you edit one file and then exit
> the editor.  The next time you want to edit a file, you must run the
> editor again.  With these editors, it makes sense to use a
44,49c42,46
<   But starting a new Emacs each time you want to edit a different file
< does not make sense.  This would fail to take advantage of Emacs's
< ability to visit more than one file in a single editing session, and
< it would lose the other accumulated context, such as the kill ring,
< registers, undo history, and mark ring, that are useful for operating
< on multiple files or even one.
---
>   It's not smart to start a new Emacs for every edited file.  Emacs
> can visit more than one file in a single editing session, and upon
> exit Emacs loses valuable accumulated context, such as the kill ring,
> registers, undo history, and mark ring.  These features are useful for
> operating on multiple files or even one.
53,62c50,57
< Each time you want to edit a different file, you visit it with the
< existing Emacs, which eventually comes to have many files in it ready
< for editing.  Usually you do not kill the Emacs until you are about to
< log out.  @xref{Files}, for more information on visiting more than one
< file.
< 
<   If you want to edit a file from another program and already have
< Emacs running, you can use the @command{emacsclient} program to open a
< file in the already running Emacs.  @xref{Emacs Server}, for more
< information on editing files with Emacs from other programs.
---
> To edit a different file, you visit it with the existing Emacs, which
> eventually will have many files in it ready for editing.  Usually you
> do not kill Emacs until you are about to log out.  @xref{Files}, for
> more information on visiting more than one file.
> 
>   To edit a file from another program while Emacs is running, you can
> use the @command{emacsclient} helper program to open a file in the
> already running Emacs.  @xref{Emacs Server}.
76c71
<   There are two commands for exiting Emacs because there are three
---
>   There are two commands for exiting Emacs and three
113,117c108,112
< directly with the terminal, and Emacs waits until you exit the subshell.
< (The way to do that is probably with @kbd{C-d} or @command{exit}, but
< it depends on which shell you use.)  The only way on these systems to
< get back to the shell from which Emacs was run (to log out, for
< example) is to kill Emacs.
---
> directly with the terminal, and Emacs waits until you exit the
> subshell.  (The way to do that is probably with @kbd{C-d} or
> @command{exit}, but it depends on which shell you use.)  On these
> systems, you can only get back to the shell from which Emacs was run
> (to log out, for example) when you kill Emacs.
136,142c131,137
< (@code{save-buffers-kill-emacs}).  A two-character key is used for
< this to make it harder to type by accident.  This command first offers
< to save any modified file-visiting buffers.  If you do not save them
< all, it asks for reconfirmation with @kbd{yes} before killing Emacs,
< since any changes not saved will be lost forever.  Also, if any
< subprocesses are still running, @kbd{C-x C-c} asks for confirmation
< about them, since killing Emacs will also kill the subprocesses.
---
> (@code{save-buffers-kill-emacs}).  A two-character key is used to make
> it harder to type by accident.  This command first offers to save any
> modified file-visiting buffers.  If you do not save them all, it asks
> for confirmation with @kbd{yes} before killing Emacs, since any
> unsaved changes will be lost forever.  Also, if any subprocesses are
> still running, @kbd{C-x C-c} asks for confirmation about them, since
> killing Emacs will also kill the subprocesses.
153,157c148,151
<   There is no way to resume an Emacs session once you have killed it.
< You can, however, arrange for Emacs to record certain session
< information when you kill it, such as which files are visited, so that
< the next time you start Emacs it will try to visit the same files and
< so on.  @xref{Saving Emacs Sessions}.
---
>   You can't resume an Emacs session after Emacs is killed.  Emacs can,
> however, record certain session information when you kill it, such as
> which files you visited, so the next time you start Emacs it will try
> to visit the same files.  @xref{Saving Emacs Sessions}.

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: emacs doc changes (was: emacs-Xtra)

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Wed, 19 Apr 2006 12:34:29 -0400
> 
> Attached is patch #1, covering emacs.texi and screen.texi.

Thanks, but please resend them as context diffs ("diff -c").  It's
very hard to read the format you sent, and it's even harder to apply
with Patch (chances that Patch will fail are very high).

Re: emacs doc changes

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Ted Zlatanov <tzz@lifelogs.com>
>> Date: Wed, 19 Apr 2006 12:34:29 -0400
>> 
>> Attached is patch #1, covering emacs.texi and screen.texi.
>
> Thanks, but please resend them as context diffs ("diff -c").  It's
> very hard to read the format you sent, and it's even harder to apply
> with Patch (chances that Patch will fail are very high).

Is there a reason not to use unified diffs ("diff -u") when available?
Of course, not all diff programs can provide them, but GNU diff does,
and patch understands them just as well, and I find it quite more
human-readable (if I consider myself representative for a human, that
is).

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: emacs doc changes

[Ted Zlatanov]

On 19 Apr 2006, dak@gnu.org wrote:

> Is there a reason not to use unified diffs ("diff -u") when
> available?  Of course, not all diff programs can provide them, but
> GNU diff does, and patch understands them just as well, and I find
> it quite more human-readable (if I consider myself representative
> for a human, that is).

RMS has asked me for context diffs before, so I'm guessing unified
patches are less useful to Emacs maintainers...  I can provide -u as
well, since I would just do "cvs diff -u" instead of "cvs diff -c".

Ted

Re: emacs doc changes

[David Kastrup]

Ted Zlatanov <tzz@lifelogs.com> writes:

> On 19 Apr 2006, dak@gnu.org wrote:
>
>> Is there a reason not to use unified diffs ("diff -u") when
>> available?  Of course, not all diff programs can provide them, but
>> GNU diff does, and patch understands them just as well, and I find
>> it quite more human-readable (if I consider myself representative
>> for a human, that is).
>
> RMS has asked me for context diffs before, so I'm guessing unified
> patches are less useful to Emacs maintainers...

I am not sure about that: maybe it is just because not all diff
programs can deliver unified.  That's why I was asking Eli.

> I can provide -u as well, since I would just do "cvs diff -u"
> instead of "cvs diff -c".

Well, context diffs certainly are fine enough for use with "patch", so
there is little reason to post another batch because of that.  I was
more asking about a general policy.

I have actually customized `diff-switches' to "-u" myself, and it
would be interesting to hear whether that could cause trouble in any
way when cooperating with other people.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: emacs doc changes

[Giorgos Keramidas]

On 2006-04-19 20:15, David Kastrup <dak@gnu.org> wrote:
>Ted Zlatanov <tzz@lifelogs.com> writes:
>> On 19 Apr 2006, dak@gnu.org wrote:
>>> Is there a reason not to use unified diffs ("diff -u") when
>>> available?  Of course, not all diff programs can provide them, but
>>> GNU diff does, and patch understands them just as well, and I find
>>> it quite more human-readable (if I consider myself representative
>>> for a human, that is).
>>
>> RMS has asked me for context diffs before, so I'm guessing unified
>> patches are less useful to Emacs maintainers...
>
> I am not sure about that: maybe it is just because not all diff
> programs can deliver unified.  That's why I was asking Eli.
>
>> I can provide -u as well, since I would just do "cvs diff -u"
>> instead of "cvs diff -c".
>
> Well, context diffs certainly are fine enough for use with "patch", so
> there is little reason to post another batch because of that.  I was
> more asking about a general policy.
>
> I have actually customized `diff-switches' to "-u" myself, and it
> would be interesting to hear whether that could cause trouble in any
> way when cooperating with other people.

I think that `context diffs' (poorly named, since -u diffs have context
too, if you ask me), are preferable in some situations.  Mostly when
whole blocks of text change in ways that also include re-indenting
and/or re-formatting of the text.

In the FreeBSD source tree, we prefer seeing unified diffs, but we also
encourage people not to re-wrap or otherwise re-indent code unless
strictly necessary.  This can be harder to read when Elisp source code
changes are part of the diff though, i.e.

|    (when (memq t (mapcar (lambda (buffer)
|                            (with-current-buffer buffer
|                              show-paren-mode))
|                          (buffer-list)))
|      (setq show-paren-idle-timer (run-with-idle-timer
|-                                  show-paren-delay t
|-                                  'old-show-paren-function)))
|+                                  show-paren-delay nil
|+                                  'show-paren-function)))

I can easily think of unified diffs getting *very* ugly with lots of
changes around a loop with several nesting levels.  A "diff -c" patch
tends to group blocks of code in separate areas, marked with '!', so
this would be:

|    (when (memq t (mapcar (lambda (buffer)
|                            (with-current-buffer buffer
|                              show-paren-mode))
|                          (buffer-list)))
|      (setq show-paren-idle-timer (run-with-idle-timer
|!                                  show-paren-delay t
|!                                  'old-show-paren-function)))
|-----------
|    (when (memq t (mapcar (lambda (buffer)
|                            (with-current-buffer buffer
|                              show-paren-mode))
|                          (buffer-list)))
|      (setq show-paren-idle-timer (run-with-idle-timer
|+                                  show-paren-delay nil
|+                                  'show-paren-function)))

Being slightly more verbose, this patch lets one quickly look at the
entire "new loop" without having to mentally "context switch" between
reading only the '-' lines or only the '+' lines.

But I'm just guessing here at why Emacs people prefer "diff -c" patches.

- Giorgos

Re: emacs doc changes

[Stefan Monnier]

>> Well, context diffs certainly are fine enough for use with "patch", so
>> there is little reason to post another batch because of that.  I was
>> more asking about a general policy.

Let me also remind people that diff-mode.el provides diff-context->unified
and diff-unified->context commands.


        Stefan "who usually finds unified-diffs more readable, but
                occasionally changes a hunk to context-diff because these
                are more readable when the change is too large/complex"

Re: emacs doc changes

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 19 Apr 2006 16:44:43 -0400
> Cc: Ted Zlatanov <tzz@lifelogs.com>, emacs-devel@gnu.org
> 
> Let me also remind people that diff-mode.el provides diff-context->unified
> and diff-unified->context commands.

``Remind us''?  You mean, we were supposed to know that somehow?

The manual says almost nothing about diff-mode, which IMHO is a shame,
since it's a great time savior.  For example, yesterday I found out
(by sheer luck, simply because I typed a command in the wrong buffer)
that "C-x 4 a" does TRT in the diffs buffer, i.e. looks up the hunk's
function in the original file and generates a correct ChangeLog entry.
This feature exists since Oct 2000, but all that NEWS has to say about
diff-mode, since Emacs 21.1 until today, is this:

    *** diff-mode.el provides `diff-mode', a major mode for
    viewing/editing context diffs (patches).  It is selected for files
    with extension `.diff', `.diffs', `.patch' and `.rej'.

I think at least emacs-xtra.texi should include some decent
documentation for a feature which any serious programmer should be
using every day.

Re: emacs doc changes

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Date: Wed, 19 Apr 2006 16:44:43 -0400
>> Cc: Ted Zlatanov <tzz@lifelogs.com>, emacs-devel@gnu.org
>> 
>> Let me also remind people that diff-mode.el provides diff-context->unified
>> and diff-unified->context commands.
>
> ``Remind us''?  You mean, we were supposed to know that somehow?
>
> The manual says almost nothing about diff-mode, which IMHO is a shame,
> since it's a great time savior.  For example, yesterday I found out
> (by sheer luck, simply because I typed a command in the wrong buffer)
> that "C-x 4 a" does TRT in the diffs buffer, i.e. looks up the hunk's
> function in the original file and generates a correct ChangeLog
> entry.

So do C-x v v and other version control commands.  I use them quite
more often from the diff buffer than elsewhere.

> I think at least emacs-xtra.texi should include some decent
> documentation for a feature which any serious programmer should be
> using every day.

Wouldn't that be more important to mention in the version control
documentation?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: emacs doc changes

[Eli Zaretskii]

> Cc: Stefan Monnier <monnier@iro.umontreal.ca>,  keramida@ceid.upatras.gr,
> 	  tzz@lifelogs.com,  emacs-devel@gnu.org
> From: David Kastrup <dak@gnu.org>
> Date: Thu, 20 Apr 2006 11:58:29 +0200
> 
> > I think at least emacs-xtra.texi should include some decent
> > documentation for a feature which any serious programmer should be
> > using every day.
> 
> Wouldn't that be more important to mention in the version control
> documentation?

They should be mentioned in both of them, IMO.

Re: emacs doc changes

[Richard Stallman]

Would someone like to write a patch to document Diff mode?

Re: emacs doc changes

[Stefan Monnier]

> Would someone like to write a patch to document Diff mode?

Someone was working on it, but I can't find it in my local archive or via
Google and haven't heard from him any more.


        Stefan

Re: emacs doc changes

[Richard Stallman]

    > Would someone like to write a patch to document Diff mode?

    Someone was working on it, but I can't find it in my local archive or via
    Google and haven't heard from him any more.

Would you like to do it?

If you do a rough but accurate job, I will polish it up.

Re: emacs doc changes

[Stefan Monnier]

>> Would someone like to write a patch to document Diff mode?
>     Someone was working on it, but I can't find it in my local archive or
>     via Google and haven't heard from him any more.
> Would you like to do it?
> If you do a rough but accurate job, I will polish it up.

Actually I found the old thread, and it was in emacs-devel and you
participated in it.

The author was Aaron S. Hawley <Aaron.Hawley@uvm.edu>; the thred started
in emacs-devel with the following post:

   http://lists.gnu.org/archive/html/emacs-devel/2006-03/msg00358.html


-- Stefan

Re: emacs doc changes

[Richard Stallman]

    The author was Aaron S. Hawley <Aaron.Hawley@uvm.edu>; the thred started
    in emacs-devel with the following post:

       http://lists.gnu.org/archive/html/emacs-devel/2006-03/msg00358.html

Did that thread come up with some text that we could use?
If so, could you send it to me?

Re: emacs doc changes

[Stefan Monnier]

>     The author was Aaron S. Hawley <Aaron.Hawley@uvm.edu>; the thred started
>     in emacs-devel with the following post:

>        http://lists.gnu.org/archive/html/emacs-devel/2006-03/msg00358.html

> Did that thread come up with some text that we could use?
> If so, could you send it to me?

Here is a copy of the above link.  His message was followed by
6 replies/comments, so you may want to read the thread.


        Stefan


PS: The mailing-list archive messed up some of the @ thingies.  I don't know
    how to get at the raw rfc822-format text.


From: Aaron S. Hawley
Subject: diff-mode documentation
Date: Wed, 8 Mar 2006 12:07:43 -0500 (EST)

The commands and features of Diff mode aren't entirely documumented in the
Emacs manual.  The following is a patch to files.texi that would add some.
There may exist a more appropriate location in the manual (or Emacs) for
this all to go. Stefan Monnier, the author of Diff mode, has provided
helpful feedback to me on this patch.  However, any mistakes are my own.

I've tried adopting the style for command tables found elsewhere in the
manual.  The patch also adds discussion of Diff mode's brilliant feature
to interactively correct the patch after any manual edits by the user.

Hope this helps,
/a

----

  Differences between versions of files are often distributed as
patches, which are the output from the @command{diff} program.  You
can use the same Diff mode to operate on a patch by typing @kbd{M-x
diff-mode}.  Any manual edits you make to a patch with Diff mode will
automatically correct the hunk header including insert, delete and
file line numbers.  Also, the following commands help to navigate,
manipulate and apply patches in Diff mode:

@table @kbd
@item M-n
@findex diff-hunk-next
Move to the next hunk in the patch.

@item M-p
@findex diff-hunk-prev
Move to the previous hunk in the patch.

@item address@hidden
@findex diff-file-next
Move to the next file hunk in a multiple file patch.

@item address@hidden
@findex diff-file-prev
Move to the previous file hunk in a multiple file patch.

@item M-k
@findex diff-hunk-kill
Kill the current hunk at point.

@item M-K
@findex diff-file-kill
In a patch with multiple files, kill the current patch to a file.

@item C-c C-s
@findex diff-split-hunk
Split the hunk at point. This is useful when manually editing a patch
and only works with the unified diff format.

@item C-c C-r
@findex diff-refine-hunk
Recomputes the current hunk by ignoring changes in whitespace.

@item M-R
@findex diff-reverse-direction
Convert the patch to a patch that reverts.
@xref{Reversed Patches, Applying Reversed Patches, Patch, diff,
Comparing and Merging Files}.

@item M-U
@findex diff-context->unified
Convert the patch to the unified diff format.
@xref{Unified Format, Unified Format, Diff, diff,
Comparing and Merging Files}.

@item M-C
@findex diff-unified->context
Convert the patch back to context diff format.
@xref{Context Format, Context Format, Diff, diff,
Comparing and Merging Files}.

@item M-r
@findex diff-restrict-view
@findex widen
Restrict the view to the current hunk. @xref{Narrowing}.  With a
prefix argument of @kbd{C-u} restrict the view to the current patch of
a multiple file patch.  The view can be widened again with @kbd{M-W}.

@item C-c C-a
@findex diff-apply-hunk
Apply hunk to target file.  With a prefix argument of @kbd{C-u}, apply
the reverse of the hunk.

@item M-A
@findex diff-ediff-patch
Start an Ediff session with the patch.
@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.

@item C-x 4 a
Add a new entry to the change log for the current file.  @xref{Change
Log}.  This is useful for log entries for functions that are deleted
by the patch.

@end table

Re: emacs doc changes

[Richard Stallman]

I installed the docs for Diff mode, with some rewriting.
I also changed Diff mode to be more consistent with usual Emacs
key sequence conventions: using C-c rather than distinguishing
the case of a metafied letter, for the less common commands.

Re: emacs doc changes

[Aaron S. Hawley]

On Mon, 1 May 2006, Richard Stallman wrote:

> I installed the docs for Diff mode, with some rewriting.
> I also changed Diff mode to be more consistent with usual Emacs
> key sequence conventions: using C-c rather than distinguishing
> the case of a metafied letter, for the less common commands.

Looks good to me.  Thanks for doing this, Richard.  Sorry about "falling
off the face of the planet" for a bit there. /a

Re: emacs doc changes

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Wed, 19 Apr 2006 20:15:44 +0200
> Cc: emacs-devel@gnu.org
> 
> I have actually customized `diff-switches' to "-u" myself, and it
> would be interesting to hear whether that could cause trouble in any
> way when cooperating with other people.

I'm not aware of any trouble whatsoever, including with Patch.

Re: emacs doc changes

[Richard Stallman]

    Is there a reason not to use unified diffs ("diff -u") when available?

When sending patches to me, I want diff -c format, not diff -u.
I find I cannot understand a diff -u patch unless it is very simple.
When I try to read the lines and think about what they do,
I cannot keep track of which lines are old and which are new.

Re: emacs doc changes

[Jay Belanger]

Richard Stallman <rms@gnu.org> writes:
...
> When sending patches to me, I want diff -c format, not diff -u.
> I find I cannot understand a diff -u patch unless it is very simple.
> When I try to read the lines and think about what they do,
> I cannot keep track of which lines are old and which are new.

The meter's a bit off, and perhaps the second line should read
"I find I cannot understand a diff -u patch as much as I'd like to",
but otherwise a nice poem.

Jay

Re: emacs doc changes

[Eli Zaretskii]

> Cc: Ted Zlatanov <tzz@lifelogs.com>,  emacs-devel@gnu.org
> From: David Kastrup <dak@gnu.org>
> Date: Wed, 19 Apr 2006 19:57:32 +0200
> 
> Is there a reason not to use unified diffs ("diff -u") when available?

AFAIK, only one: that Richard asks for "diff -c".

Re: emacs doc changes

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> Cc: Ted Zlatanov <tzz@lifelogs.com>,  emacs-devel@gnu.org
>> From: David Kastrup <dak@gnu.org>
>> Date: Wed, 19 Apr 2006 19:57:32 +0200
>> 
>> Is there a reason not to use unified diffs ("diff -u") when available?
>
> AFAIK, only one: that Richard asks for "diff -c".

Ah, ok.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: emacs doc changes

[Ted Zlatanov]

[-- Attachment #1: Type: text/plain, Size: 319 bytes --]

On 19 Apr 2006, eliz@gnu.org wrote:

> Thanks, but please resend them as context diffs ("diff -c").  It's
> very hard to read the format you sent, and it's even harder to apply
> with Patch (chances that Patch will fail are very high).

Ah, sorry, I forgot.  Attached is a context patch for all I've done so
far.

Ted


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: emacs+screen+commands+entering.texi.patch --]
[-- Type: text/x-patch, Size: 60115 bytes --]

? commands+entering.texi.patch
? emacs+screen+commands+entering.texi.patch
? emacs+screen.texi.patch
Index: commands.texi
===================================================================
RCS file: /sources/emacs/emacs/man/commands.texi,v
retrieving revision 1.22
diff -c -r1.22 commands.texi
*** commands.texi	8 Feb 2006 02:25:09 -0000	1.22
--- commands.texi	19 Apr 2006 17:55:42 -0000
***************
*** 6,14 ****
  @chapter Characters, Keys and Commands
  
    This chapter explains the character sets used by Emacs for input
! commands and for the contents of files, and also explains the concepts
! of @dfn{keys} and @dfn{commands}, which are fundamental for understanding
! how Emacs interprets your keyboard and mouse input.
  @end iftex
  
  @ifnottex
--- 6,14 ----
  @chapter Characters, Keys and Commands
  
    This chapter explains the character sets used by Emacs for input
! commands and for the contents of files and the fundamental concepts of
! @dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard
! and mouse input.
  @end iftex
  
  @ifnottex
***************
*** 35,45 ****
  for short).  @kbd{C-a} gets its name from the fact that you type it by
  holding down the @key{CTRL} key while pressing @kbd{a}.
  
!   Some @acronym{ASCII} control characters have special names, and most terminals
! have special keys you can type them with: for example, @key{RET},
! @key{TAB}, @key{DEL} and @key{ESC}.  The space character is usually
! referred to below as @key{SPC}, even though strictly speaking it is a
! graphic character whose graphic happens to be blank.
  
    Emacs extends the @acronym{ASCII} character set with thousands more printing
  characters (@pxref{International}), additional control characters, and a
--- 35,45 ----
  for short).  @kbd{C-a} gets its name from the fact that you type it by
  holding down the @key{CTRL} key while pressing @kbd{a}.
  
!   Some @acronym{ASCII} control characters have special names, and most
! terminals have special keys you can type them with: for example,
! @key{RET}, @key{TAB}, @key{DEL} and @key{ESC}.  The space character is
! usually known as @key{SPC}, even though strictly speaking it is a
! blank graphic character.
  
    Emacs extends the @acronym{ASCII} character set with thousands more printing
  characters (@pxref{International}), additional control characters, and a
***************
*** 51,59 ****
  @kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
  distinguish them.
  
!   But the Emacs character set has room for control variants of all
! printing characters, and for distinguishing between @kbd{C-a} and
! @kbd{C-A}.  Graphical terminals make it possible to enter all these
  characters.  For example, @kbd{C--} (that's Control-Minus) and
  @kbd{C-5} are meaningful Emacs commands on a graphical terminal.
  
--- 51,59 ----
  @kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot
  distinguish them.
  
!   The Emacs character set has room for control variants of all
! printing characters, and knows @kbd{C-a} and @kbd{C-A} are not the
! same.  Graphical terminals make it possible to enter all these
  characters.  For example, @kbd{C--} (that's Control-Minus) and
  @kbd{C-5} are meaningful Emacs commands on a graphical terminal.
  
***************
*** 106,115 ****
  because the first one goes to work on the @kbd{C-x}.)
  
    Keyboard input includes keyboard keys that are not characters at
! all: for example function keys and arrow keys.  Mouse buttons are also
! outside the gamut of characters.  However, you can modify these events
! with the modifier keys @key{CTRL}, @key{META}, @key{SUPER},
! @key{HYPER} and @key{ALT}, just as you can modify keyboard characters.
  
  @cindex input event
    Input characters and non-character inputs are collectively called
--- 106,115 ----
  because the first one goes to work on the @kbd{C-x}.)
  
    Keyboard input includes keyboard keys that are not characters at
! all, such as function keys and arrow keys.  Mouse buttons are also not
! characters.  However, you can modify these events with the modifier
! keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and @key{ALT},
! just as you can modify keyboard characters.
  
  @cindex input event
    Input characters and non-character inputs are collectively called
***************
*** 121,127 ****
    @acronym{ASCII} terminals cannot really send anything to the computer except
  @acronym{ASCII} characters.  These terminals use a sequence of characters to
  represent each function key.  But that is invisible to the Emacs user,
! because the keyboard input routines recognize these special sequences
  and convert them to function key events before any other part of Emacs
  gets to see them.
  
--- 121,127 ----
    @acronym{ASCII} terminals cannot really send anything to the computer except
  @acronym{ASCII} characters.  These terminals use a sequence of characters to
  represent each function key.  But that is invisible to the Emacs user,
! because the keyboard input routines catch these special sequences
  and convert them to function key events before any other part of Emacs
  gets to see them.
  
***************
*** 130,141 ****
  
  @cindex key sequence
  @cindex key
!   A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input
! events that are meaningful as a unit---as ``a single command.''  Some
! Emacs command sequences are just one character or one event; for
! example, just @kbd{C-f} is enough to move forward one character in the
! buffer.  But Emacs also has commands that take two or more events to
! invoke.
  
  @cindex complete key
  @cindex prefix key
--- 130,140 ----
  
  @cindex key sequence
  @cindex key
!   A @dfn{key sequence} (@dfn{key}, for short) is a meaningful sequence
! of input events---a ``single command.''  Some Emacs command sequences
! are invoked by just one character or one event; for example, just
! @kbd{C-f} moves forward one character in the buffer.  But Emacs also
! has commands that take two or more events to invoke.
  
  @cindex complete key
  @cindex prefix key
***************
*** 158,190 ****
  sequences.  There's no limit to the length of a key sequence, but in
  practice people rarely use sequences longer than four events.
  
!   By contrast, you can't add more events onto a complete key.  For
! example, the two-event sequence @kbd{C-f C-k} is not a key, because
! the @kbd{C-f} is a complete key in itself.  It's impossible to give
! @kbd{C-f C-k} an independent meaning as a command.  @kbd{C-f C-k} is two
! key sequences, not one.@refill
  
    All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
  @kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x
  n}, @w{@kbd{C-x r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x
  6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}.  (@key{F1} and @key{F2} are
! aliases for @kbd{C-h} and @kbd{C-x 6}.)  But this list is not cast in
! concrete; it is just a matter of Emacs's standard key bindings.  If
! you customize Emacs, you can make new prefix keys, or eliminate some
! of the standard ones.  @xref{Key Bindings}.
  
!   If you do make or eliminate prefix keys, that changes the set of
  possible key sequences.  For example, if you redefine @kbd{C-f} as a
! prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you
! define that too as a prefix).  Conversely, if you remove the prefix
! definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4
! @var{anything}}) is no longer a key.
  
    Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key
  displays a list of the commands starting with that prefix.  There are
  a few prefix keys for which @kbd{C-h} does not work---for historical
  reasons, they define other meanings for @kbd{C-h} which are painful to
! change.  But @key{F1} should work for all prefix keys.
  
  @node Commands, Text Characters, Keys, Top
  @section Keys and Commands
--- 157,189 ----
  sequences.  There's no limit to the length of a key sequence, but in
  practice people rarely use sequences longer than four events.
  
!   You can't add input events onto a complete key.  For example, the
! two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f}
! is a complete key in itself.  It's impossible to give @kbd{C-f C-k} an
! independent meaning as a command.  @kbd{C-f C-k} is two key sequences,
! not one.@refill
  
    All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h},
  @kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x
  n}, @w{@kbd{C-x r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x
  6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}.  (@key{F1} and @key{F2} are
! aliases for @kbd{C-h} and @kbd{C-x 6}.)  This list is only due to
! Emacs's standard key bindings.  If you customize Emacs, you can make
! new prefix keys, or eliminate some of the standard ones (not
! recommended for most users).  @xref{Key Bindings}.
  
!   If you make or eliminate prefix keys, that changes the set of
  possible key sequences.  For example, if you redefine @kbd{C-f} as a
! prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless
! you define that too as a prefix).  Conversely, if you remove the
! prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4
! @var{anything}} are no longer keys.
  
    Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key
  displays a list of the commands starting with that prefix.  There are
  a few prefix keys for which @kbd{C-h} does not work---for historical
  reasons, they define other meanings for @kbd{C-h} which are painful to
! change.  @key{F1} works for all prefix keys.
  
  @node Commands, Text Characters, Keys, Top
  @section Keys and Commands
***************
*** 197,257 ****
  Emacs assigns meanings to named @dfn{commands}, and then gives keys
  their meanings by @dfn{binding} them to commands.
  
!   Every command has a name chosen by a programmer.  The name is usually
! made of a few English words separated by dashes; for example,
  @code{next-line} or @code{forward-word}.  A command also has a
! @dfn{function definition} which is a Lisp program; this is what makes
! the command do what it does.  In Emacs Lisp, a command is actually a
! special kind of Lisp function; one which specifies how to read arguments
! for it and call it interactively.  For more information on commands and
! functions, see @ref{What Is a Function,, What Is a Function, elisp, The
! Emacs Lisp Reference Manual}.  (The definition we use in this manual is
! simplified slightly.)
  
!   The bindings between keys and commands are recorded in various tables
! called @dfn{keymaps}.  @xref{Keymaps}.
  
    When we say that ``@kbd{C-n} moves down vertically one line'' we are
! glossing over a distinction that is irrelevant in ordinary use but is vital
! in understanding how to customize Emacs.  It is the command
! @code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
! this effect @emph{because} it is bound to that command.  If you rebind
! @kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move
! forward by words instead.  Rebinding keys is a common method of
  customization.@refill
  
    In the rest of this manual, we usually ignore this distinction to
  keep things simple.  We will often speak of keys like @kbd{C-n} as
! commands, even though strictly speaking a key is bound to some
! command.  To give the information needed for customization, we state
  the name of the command which really does the work in parentheses
  after mentioning the key that runs it.  For example, we will say that
  ``The command @kbd{C-n} (@code{next-line}) moves point vertically
! down,'' meaning that @code{next-line} is a command that moves
! vertically down, and @kbd{C-n} is a key that is normally bound to it.
  
!   While we are on the subject of information for customization only,
! it's a good time to tell you about @dfn{variables}.  Often the
! description of a command will say, ``To change this, set the variable
! @code{mumble-foo}.''  A variable is a name used to remember a value.
! Most of the variables documented in this manual exist just to facilitate
! customization: some command or other part of Emacs examines the variable
! and behaves differently according to the value that you set.  Until you
! are interested in customizing, you can ignore the information about
! variables.  When you are ready to be interested, read the basic
! information on variables, and then the information on individual
! variables will make sense.  @xref{Variables}.
  
  @node Text Characters, Entering Emacs, Commands, Top
  @section Character Set for Text
  @cindex characters (in text)
  
!   Text in Emacs buffers is a sequence of 8-bit bytes.  Each byte can
! hold a single @acronym{ASCII} character.  Both @acronym{ASCII} control characters (octal
! codes 000 through 037, and 0177) and @acronym{ASCII} printing characters (codes
! 040 through 0176) are allowed; however, non-@acronym{ASCII} control characters
! cannot appear in a buffer.  The other modifier flags used in keyboard
! input, such as Meta, are not allowed in buffers either.
  
    Some @acronym{ASCII} control characters serve special purposes in text, and have
  special names.  For example, the newline character (octal code 012) is
--- 196,255 ----
  Emacs assigns meanings to named @dfn{commands}, and then gives keys
  their meanings by @dfn{binding} them to commands.
  
!   Every command has a name chosen by a programmer.  The name is
! usually made of a few English words separated by dashes; for example,
  @code{next-line} or @code{forward-word}.  A command also has a
! @dfn{function definition} which is a Lisp program; this is how the
! command does work.  In Emacs Lisp, a command is a Lisp function with
! special options to read arguments and for interactive use.  For more
! information on commands and functions, see @ref{What Is a Function,,
! What Is a Function, elisp, The Emacs Lisp Reference Manual}.  (The
! definition here is simplified slightly.)
  
!   The bindings between keys and commands are recorded in tables called
! @dfn{keymaps}.  @xref{Keymaps}.
  
    When we say that ``@kbd{C-n} moves down vertically one line'' we are
! glossing over a minor distinction that is irrelevant in ordinary use
! but is vital to Emacs customization.  The command @code{next-line}
! does a vertical move downward.  @kbd{C-n} has this effect
! @emph{because} it is bound to @code{next-line}.  If you rebind
! @kbd{C-n} to the command @code{forward-word}, then @kbd{C-n} will move
! forward one word instead.  Rebinding keys is common in
  customization.@refill
  
    In the rest of this manual, we usually ignore this distinction to
  keep things simple.  We will often speak of keys like @kbd{C-n} as
! commands, even though the key is bound to a command.  Usually we state
  the name of the command which really does the work in parentheses
  after mentioning the key that runs it.  For example, we will say that
  ``The command @kbd{C-n} (@code{next-line}) moves point vertically
! down,'' meaning that the command @code{next-line} moves vertically
! down, and @kbd{C-n} is a key that is normally bound to it.
  
!   Since we are discussing customization, you should know about
! @dfn{variables}.  Often the description of a command will say, ``To
! change this, set the variable @code{mumble-foo}.''  A variable is a
! name used to store a value.  Most of the variables documented in this
! manual are meant for customization: some command or other part of
! Emacs examines the variable and behaves differently according to the
! value that you set.  You can ignore the information about variables
! until you want to customize them.  When you are ready, read the basic
! information on variables, and then customizing individual variables
! will make sense.  @xref{Variables}.
  
  @node Text Characters, Entering Emacs, Commands, Top
  @section Character Set for Text
  @cindex characters (in text)
  
!   Text in Emacs buffers is a sequence of characters.  In the default
! Unibyte Mode, each character in an 8-bit byte that can hold a single
! @acronym{ASCII} character.  Both @acronym{ASCII} control characters
! (octal codes 000 through 037, and 0177) and @acronym{ASCII} printing
! characters (codes 040 through 0176) are allowed; however,
! non-@acronym{ASCII} control characters cannot appear in a buffer.  The
! other modifier flags used in keyboard input, such as Meta, are not
! allowed in buffers either.
  
    Some @acronym{ASCII} control characters serve special purposes in text, and have
  special names.  For example, the newline character (octal code 012) is
***************
*** 267,274 ****
  with codes 128 through 255 can also appear in multibyte buffers.
  
    If you disable multibyte characters, then you can use only one
! alphabet of non-@acronym{ASCII} characters, but they all fit in one byte.  They
! use codes 0200 through 0377.  @xref{Unibyte Mode}.
  
  @ifnottex
  @lowersections
--- 265,272 ----
  with codes 128 through 255 can also appear in multibyte buffers.
  
    If you disable multibyte characters, then you can use only one
! alphabet of non-@acronym{ASCII} characters, which all fit in one byte.
! They use octal codes 0200 through 0377.  @xref{Unibyte Mode}.
  
  @ifnottex
  @lowersections
Index: emacs.texi
===================================================================
RCS file: /sources/emacs/emacs/man/emacs.texi,v
retrieving revision 1.126
diff -c -r1.126 emacs.texi
*** emacs.texi	12 Apr 2006 00:27:50 -0000	1.126
--- emacs.texi	19 Apr 2006 17:55:42 -0000
***************
*** 89,97 ****
  @value{EMACSVER}.
  
  @ifinfo
! If you never before used the Info documentation system, type @kbd{h},
! and Emacs will take you to a programmed instruction sequence for the
! Info commands.
  @end ifinfo
  
  For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The
--- 89,97 ----
  @value{EMACSVER}.
  
  @ifinfo
! To learn more about the Info documentation system, type @kbd{h}, and
! Emacs will take you to a programmed instruction sequence for the Info
! commands.
  @end ifinfo
  
  For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The
***************
*** 867,913 ****
  @unnumbered Preface
  
    This manual documents the use and simple customization of the Emacs
! editor.  The reader is not expected to be a programmer; simple
! customizations do not require programming skill.  The user who is not
! interested in customizing can ignore the scattered customization hints.
  
    This is primarily a reference manual, but can also be used as a
! primer.  For complete beginners, it is a good idea to start with the
! on-line, learn-by-doing tutorial, before reading the manual.  To run the
! tutorial, start Emacs and type @kbd{C-h t}.  This way you can learn
! Emacs by using Emacs on a specially designed file which describes
! commands, tells you when to try them, and then explains the results you
! see.
  
    On first reading, just skim chapters 1 and 2, which describe the
  notational conventions of the manual and the general appearance of the
  Emacs display screen.  Note which questions are answered in these
  chapters, so you can refer back later.  After reading chapter 4, you
! should practice the commands there.  The next few chapters describe
! fundamental techniques and concepts that are used constantly.  You need
! to understand them thoroughly, experimenting with them if necessary.
  
    Chapters 14 through 19 describe intermediate-level features that are
! useful for all kinds of editing.  Chapter 20 and following chapters
! describe features that you may or may not want to use; read those
! chapters when you need them.
  
    Read the Trouble chapter if Emacs does not seem to be working
! properly.  It explains how to cope with some common problems
  (@pxref{Lossage}), as well as when and how to report Emacs bugs
  (@pxref{Bugs}).
  
!   To find the documentation on a particular command, look in the index.
! Keys (character commands) and command names have separate indexes.  There
! is also a glossary, with a cross reference for each term.
  
    This manual is available as a printed book and also as an Info file.
! The Info file is for on-line perusal with the Info program, which will
! be the principal way of viewing documentation on-line in the GNU system.
! Both the Info file and the Info program itself are distributed along
! with GNU Emacs.  The Info file and the printed book contain
  substantially the same text and are generated from the same source
! files, which are also distributed along with GNU Emacs.
  
    GNU Emacs is a member of the Emacs editor family.  There are many
  Emacs editors, all sharing common principles of organization.  For
--- 867,912 ----
  @unnumbered Preface
  
    This manual documents the use and simple customization of the Emacs
! editor.  Simple Emacs customizations do not require you to be a
! programmer.  If you are not interested in customizing, you can ignore
! the scattered customization hints.
  
    This is primarily a reference manual, but can also be used as a
! primer.  You should start with the on-line, learn-by-doing tutorial,
! before reading the manual if you are just starting to use Emacs.  To
! run the tutorial, start Emacs and type @kbd{C-h t}.  The tutorial
! describes commands, tells you when to try them, and explains the
! results.
  
    On first reading, just skim chapters 1 and 2, which describe the
  notational conventions of the manual and the general appearance of the
  Emacs display screen.  Note which questions are answered in these
  chapters, so you can refer back later.  After reading chapter 4, you
! should practice the commands shown there.  The next few chapters
! describe fundamental techniques and concepts that are used constantly.
! You need to understand them thoroughly and experiment with them.
  
    Chapters 14 through 19 describe intermediate-level features that are
! useful for many kinds of editing.  Chapter 20 and following chapters
! describe optional yet useful features; read those chapters when you
! need them.
  
    Read the Trouble chapter if Emacs does not seem to be working
! properly.  It explains how to cope with many common problems
  (@pxref{Lossage}), as well as when and how to report Emacs bugs
  (@pxref{Bugs}).
  
!   To find out more about a particular command, look in the index.
! Keys (character commands) and command names have separate indexes.
! There is also a glossary, with a cross reference for each term.
  
    This manual is available as a printed book and also as an Info file.
! The Info file is for on-line perusal with the Info program, which is
! the principal way to access documentation on-line in the GNU system.
! Both the Emacs Info file and the Info program itself are distributed
! along with GNU Emacs.  The Info file and the printed book contain
  substantially the same text and are generated from the same source
! files, which are also distributed with GNU Emacs.
  
    GNU Emacs is a member of the Emacs editor family.  There are many
  Emacs editors, all sharing common principles of organization.  For
***************
*** 1062,1116 ****
  self-documenting, customizable, extensible real-time display editor Emacs.
  (The `G' in `GNU' is not silent.)
  
!   We say that Emacs is a @dfn{display} editor because normally the text
! being edited is visible on the screen and is updated automatically as you
  type your commands.  @xref{Screen,Display}.
  
!   We call it a @dfn{real-time} editor because the display is updated very
  frequently, usually after each character or pair of characters you
  type.  This minimizes the amount of information you must keep in your
  head as you edit.  @xref{Basic,Real-time,Basic Editing}.
  
!   We call Emacs advanced because it provides facilities that go beyond
! simple insertion and deletion: controlling subprocesses; automatic
! indentation of programs; viewing two or more files at once; editing
! formatted text; and dealing in terms of characters, words, lines,
! sentences, paragraphs, and pages, as well as expressions and comments in
! several different programming languages.
  
    @dfn{Self-documenting} means that at any time you can type a special
  character, @kbd{Control-h}, to find out what your options are.  You can
  also use it to find out what any command does, or to find all the commands
  that pertain to a topic.  @xref{Help}.
  
!   @dfn{Customizable} means that you can change the definitions of Emacs
! commands in little ways.  For example, if you use a programming language in
! which comments start with @samp{<**} and end with @samp{**>}, you can tell
! the Emacs comment manipulation commands to use those strings
! (@pxref{Comments}).  Another sort of customization is rearrangement of the
! command set.  For example, if you prefer the four basic cursor motion
! commands (up, down, left and right) on keys in a diamond pattern on the
! keyboard, you can rebind the keys that way.  @xref{Customization}.
! 
!   @dfn{Extensible} means that you can go beyond simple customization and
! write entirely new commands, programs in the Lisp language to be run by
! Emacs's own Lisp interpreter.  Emacs is an ``on-line extensible''
! system, which means that it is divided into many functions that call
! each other, any of which can be redefined in the middle of an editing
! session.  Almost any part of Emacs can be replaced without making a
! separate copy of all of Emacs.  Most of the editing commands of Emacs
! are written in Lisp; the few exceptions could have been written
! in Lisp but are written in C for efficiency.  Although only a programmer
! can write an extension, anybody can use it afterward.  @xref{Top,
! Emacs Lisp Intro, Preface, eintr, An Introduction to Programming in
! Emacs Lisp}, if you want to learn Emacs Lisp programming.
  
     When running on a graphical display, Emacs provides its own menus
! and convenient handling of mouse buttons.  But Emacs provides many of
! the benefits of a graphical display even on a text-only terminal.  For
! instance, it can highlight parts of a file, display and edit several
! files at once, move text between files, and edit files while running
! shell commands.
  
  @include screen.texi
  @include commands.texi
--- 1061,1116 ----
  self-documenting, customizable, extensible real-time display editor Emacs.
  (The `G' in `GNU' is not silent.)
  
!   Emacs is a @dfn{display} editor because normally the text being
! edited is visible on the screen and is updated automatically as you
  type your commands.  @xref{Screen,Display}.
  
!   It is a @dfn{real-time} editor because the display is updated very
  frequently, usually after each character or pair of characters you
  type.  This minimizes the amount of information you must keep in your
  head as you edit.  @xref{Basic,Real-time,Basic Editing}.
  
!   Emacs is advanced because it provides much more than simple
! insertion and deletion.  It can control subprocesses, indent programs
! automatically, show two or more files at once, and edit formatted
! text.  Emacs can operate in terms of characters, words, lines,
! sentences, paragraphs, and pages, as well as expressions and comments
! in several different programming languages.
  
    @dfn{Self-documenting} means that at any time you can type a special
  character, @kbd{Control-h}, to find out what your options are.  You can
  also use it to find out what any command does, or to find all the commands
  that pertain to a topic.  @xref{Help}.
  
!   @dfn{Customizable} means that you can affect or redefine Emacs
! commands in little ways.  For example, if you use a programming
! language in which comments start with @samp{<**} and end with
! @samp{**>}, you can tell the Emacs comment manipulation commands to
! use those strings (@pxref{Comments}).  Another sort of customization
! is rearrangement of the command set.  For example, you can rebind the
! basic cursor motion commands (up, down, left and right) to any keys on
! the keyboard that you find comfortable.  @xref{Customization}.
! 
!   @dfn{Extensible} means that you can go beyond simple customization
! and write entirely new commands -- programs in the Lisp language to be
! run by Emacs's own Lisp interpreter.  Emacs is an ``on-line
! extensible'' system, which means that it is divided into many
! functions that call each other, any of which can be redefined in the
! middle of an editing session.  Almost any part of Emacs can be
! replaced without making a separate copy of all of Emacs.  Most of the
! editing commands of Emacs are written in Lisp; the few exceptions
! could have been written in Lisp but use C instead for efficiency.
! Although only a programmer can write an extension, anybody can use it
! afterwards.  @xref{Top, Emacs Lisp Intro, Preface, eintr, An
! Introduction to Programming in Emacs Lisp}, if you want to learn Emacs
! Lisp programming.
  
     When running on a graphical display, Emacs provides its own menus
! and convenient handling of mouse buttons.  In addition, Emacs provides
! many of the benefits of a graphical display even on a text-only
! terminal.  For instance, it can highlight parts of a file, display and
! edit several files at once, move text between files, and edit files
! while running shell commands.
  
  @include screen.texi
  @include commands.texi
Index: entering.texi
===================================================================
RCS file: /sources/emacs/emacs/man/entering.texi,v
retrieving revision 1.16
diff -c -r1.16 entering.texi
*** entering.texi	5 Feb 2006 22:41:30 -0000	1.16
--- entering.texi	19 Apr 2006 17:55:42 -0000
***************
*** 8,65 ****
  @cindex starting Emacs
  
    The usual way to invoke Emacs is with the shell command
! @command{emacs}.  Emacs clears the screen and then displays an initial
! help message and copyright notice.  Some operating systems discard all
! type-ahead when Emacs starts up; they give Emacs no way to prevent
! this.  If you ever use those systems, learn the habit of waiting for
! Emacs to clear the screen before typing your first editing command.
! 
!   If you run Emacs from a shell window under the X Window System, run it
! in the background with @command{emacs&}.  This way, Emacs does not tie up
! the shell window, so you can use that to run other shell commands while
! Emacs operates its own X windows.  You can begin typing Emacs commands
! as soon as you direct your keyboard input to the Emacs frame.
  
  @vindex initial-major-mode
    When Emacs starts up, it creates a buffer named @samp{*scratch*}.
! That's the buffer you start out in.  The @samp{*scratch*} buffer uses
! Lisp Interaction mode; you can use it to type Lisp expressions and
! evaluate them, or you can ignore that capability and just write notes
! in it.  (You can specify a different major mode for this buffer by
  setting the variable @code{initial-major-mode} in your init file.
! @xref{Init File}.)
  
    It is possible to specify files to be visited, Lisp files to be
! loaded, and functions to be called, by giving Emacs arguments in the
! shell command line.  @xref{Emacs Invocation}.  But we don't recommend
! doing this.  The feature exists mainly for compatibility with other
! editors.
! 
!   Many other editors are designed to be started afresh each time you
! want to edit.  You edit one file and then exit the editor.  The next
! time you want to edit either another file or the same one, you must run
! the editor again.  With these editors, it makes sense to use a
  command-line argument to say which file to edit.
  
!   But starting a new Emacs each time you want to edit a different file
! does not make sense.  This would fail to take advantage of Emacs's
! ability to visit more than one file in a single editing session, and
! it would lose the other accumulated context, such as the kill ring,
! registers, undo history, and mark ring, that are useful for operating
! on multiple files or even one.
  
    The recommended way to use GNU Emacs is to start it only once, just
  after you log in, and do all your editing in the same Emacs session.
! Each time you want to edit a different file, you visit it with the
! existing Emacs, which eventually comes to have many files in it ready
! for editing.  Usually you do not kill the Emacs until you are about to
! log out.  @xref{Files}, for more information on visiting more than one
! file.
! 
!   If you want to edit a file from another program and already have
! Emacs running, you can use the @command{emacsclient} program to open a
! file in the already running Emacs.  @xref{Emacs Server}, for more
! information on editing files with Emacs from other programs.
  
  @ifnottex
  @raisesections
--- 8,60 ----
  @cindex starting Emacs
  
    The usual way to invoke Emacs is with the shell command
! @command{emacs}.  Emacs clears the screen and displays an initial help
! message and copyright notice.  Some operating systems discard all your
! input while Emacs starts up; they give Emacs no way to prevent this.
! If you ever use those systems, wait for Emacs to clear the screen
! before you start typing.
! 
!   From a shell window under the X Window System, run Emacs in the
! background with @command{emacs&}.  This way, Emacs won't tie up the
! shell window, so you can use it to run other shell commands while
! Emacs is running.  You can type Emacs commands as soon as you direct
! your keyboard input to an Emacs frame.
  
  @vindex initial-major-mode
    When Emacs starts up, it creates a buffer named @samp{*scratch*}.
! That's the first buffer you'll see.  The @samp{*scratch*} buffer uses
! Lisp Interaction mode; that lets you type Lisp expressions and
! evaluate them.  You can ignore that capability and just write notes
! there.  You can specify a different major mode for this buffer by
  setting the variable @code{initial-major-mode} in your init file.
! @xref{Init File}.
  
    It is possible to specify files to be visited, Lisp files to be
! loaded, and functions to be called through Emacs command-line
! arguments.  @xref{Emacs Invocation}.  The feature exists mainly for
! compatibility with other editors, and is normally not recommended.
! 
!   Many other editors are designed so you edit one file and then exit
! the editor.  The next time you want to edit a file, you must run the
! editor again.  With these editors, it makes sense to use a
  command-line argument to say which file to edit.
  
!   It's not smart to start a new Emacs for every edited file.  Emacs
! can visit more than one file in a single editing session, and upon
! exit Emacs loses valuable accumulated context, such as the kill ring,
! registers, undo history, and mark ring.  These features are useful for
! operating on multiple files or even one.
  
    The recommended way to use GNU Emacs is to start it only once, just
  after you log in, and do all your editing in the same Emacs session.
! To edit a different file, you visit it with the existing Emacs, which
! eventually will have many files in it ready for editing.  Usually you
! do not kill Emacs until you are about to log out.  @xref{Files}, for
! more information on visiting more than one file.
! 
!   To edit a file from another program while Emacs is running, you can
! use the @command{emacsclient} helper program to open a file in the
! already running Emacs.  @xref{Emacs Server}.
  
  @ifnottex
  @raisesections
***************
*** 73,79 ****
  @cindex leaving Emacs
  @cindex quitting Emacs
  
!   There are two commands for exiting Emacs because there are three
  kinds of exiting: @dfn{suspending} Emacs, @dfn{Iconifying} Emacs, and
  @dfn{killing} Emacs.
  
--- 68,74 ----
  @cindex leaving Emacs
  @cindex quitting Emacs
  
!   There are two commands for exiting Emacs and three
  kinds of exiting: @dfn{suspending} Emacs, @dfn{Iconifying} Emacs, and
  @dfn{killing} Emacs.
  
***************
*** 110,120 ****
  Emacs.  You can resume Emacs with the shell command @command{%emacs}
  in most common shells.  On systems that don't support suspending
  programs, @kbd{C-z} starts an inferior shell that communicates
! directly with the terminal, and Emacs waits until you exit the subshell.
! (The way to do that is probably with @kbd{C-d} or @command{exit}, but
! it depends on which shell you use.)  The only way on these systems to
! get back to the shell from which Emacs was run (to log out, for
! example) is to kill Emacs.
  
    Suspending can fail if you run Emacs under a shell that doesn't
  support suspending programs, even if the system itself does support
--- 105,115 ----
  Emacs.  You can resume Emacs with the shell command @command{%emacs}
  in most common shells.  On systems that don't support suspending
  programs, @kbd{C-z} starts an inferior shell that communicates
! directly with the terminal, and Emacs waits until you exit the
! subshell.  (The way to do that is probably with @kbd{C-d} or
! @command{exit}, but it depends on which shell you use.)  On these
! systems, you can only get back to the shell from which Emacs was run
! (to log out, for example) when you kill Emacs.
  
    Suspending can fail if you run Emacs under a shell that doesn't
  support suspending programs, even if the system itself does support
***************
*** 133,145 ****
  @kindex C-x C-c
  @findex save-buffers-kill-emacs
    To exit and kill Emacs, type @kbd{C-x C-c}
! (@code{save-buffers-kill-emacs}).  A two-character key is used for
! this to make it harder to type by accident.  This command first offers
! to save any modified file-visiting buffers.  If you do not save them
! all, it asks for reconfirmation with @kbd{yes} before killing Emacs,
! since any changes not saved will be lost forever.  Also, if any
! subprocesses are still running, @kbd{C-x C-c} asks for confirmation
! about them, since killing Emacs will also kill the subprocesses.
  
  @vindex confirm-kill-emacs
    If the value of the variable @code{confirm-kill-emacs} is
--- 128,140 ----
  @kindex C-x C-c
  @findex save-buffers-kill-emacs
    To exit and kill Emacs, type @kbd{C-x C-c}
! (@code{save-buffers-kill-emacs}).  A two-character key is used to make
! it harder to type by accident.  This command first offers to save any
! modified file-visiting buffers.  If you do not save them all, it asks
! for confirmation with @kbd{yes} before killing Emacs, since any
! unsaved changes will be lost forever.  Also, if any subprocesses are
! still running, @kbd{C-x C-c} asks for confirmation about them, since
! killing Emacs will also kill the subprocesses.
  
  @vindex confirm-kill-emacs
    If the value of the variable @code{confirm-kill-emacs} is
***************
*** 150,160 ****
  function @code{yes-or-no-p}.  The default value of
  @code{confirm-kill-emacs} is @code{nil}.
  
!   There is no way to resume an Emacs session once you have killed it.
! You can, however, arrange for Emacs to record certain session
! information when you kill it, such as which files are visited, so that
! the next time you start Emacs it will try to visit the same files and
! so on.  @xref{Saving Emacs Sessions}.
  
    The operating system usually listens for certain special characters
  whose meaning is to kill or suspend the program you are running.
--- 145,154 ----
  function @code{yes-or-no-p}.  The default value of
  @code{confirm-kill-emacs} is @code{nil}.
  
!   You can't resume an Emacs session after Emacs is killed.  Emacs can,
! however, record certain session information when you kill it, such as
! which files you visited, so the next time you start Emacs it will try
! to visit the same files.  @xref{Saving Emacs Sessions}.
  
    The operating system usually listens for certain special characters
  whose meaning is to kill or suspend the program you are running.
Index: screen.texi
===================================================================
RCS file: /sources/emacs/emacs/man/screen.texi,v
retrieving revision 1.26
diff -c -r1.26 screen.texi
*** screen.texi	5 Feb 2006 22:41:31 -0000	1.26
--- screen.texi	19 Apr 2006 17:55:42 -0000
***************
*** 24,31 ****
  you click on them.  Below this, the window begins, often with a
  @dfn{scroll bar} on one side.  Below the window comes the last line of
  the frame, a special @dfn{echo area} or @dfn{minibuffer window}, where
! prompts appear and where you enter information when Emacs asks for it.
! See following sections for more information about these special lines.
  
    You can subdivide the window horizontally or vertically to make
  multiple text windows, each of which can independently display some
--- 24,31 ----
  you click on them.  Below this, the window begins, often with a
  @dfn{scroll bar} on one side.  Below the window comes the last line of
  the frame, a special @dfn{echo area} or @dfn{minibuffer window}, where
! prompts appear and you enter information when Emacs asks for it.  See
! following sections for more information about these special lines.
  
    You can subdivide the window horizontally or vertically to make
  multiple text windows, each of which can independently display some
***************
*** 36,55 ****
    At any time, one window is the @dfn{selected window}.  On graphical
  terminals, the selected window normally shows a more prominent cursor
  (usually solid and blinking) while other windows show a weaker cursor
! (such as a hollow box).  On text terminals, which have just one
! cursor, that cursor always appears in the selected window.
  
    Most Emacs commands implicitly apply to the text in the selected
! window (though mouse commands generally operate on whatever window you
! click them in, whether selected or not).  The text in other windows is
! mostly visible for reference, unless/until you select them.  If you
! use multiple frames on a graphical display, then giving the input
! focus to a particular frame selects a window in that frame.
  
    Each window's last line is a @dfn{mode line}, which describes what
! is going on in that window.  It appears in different color and/or a
! ``3D'' box, if the terminal supports that; its contents normally begin
! with @w{@samp{--:-- @ *scratch*}} when Emacs starts.  The mode line
  displays status information such as what buffer is being displayed
  above it in the window, what major and minor modes are in use, and
  whether the buffer contains unsaved changes.
--- 36,55 ----
    At any time, one window is the @dfn{selected window}.  On graphical
  terminals, the selected window normally shows a more prominent cursor
  (usually solid and blinking) while other windows show a weaker cursor
! (such as a hollow box).  On text terminals, the cursor always appears
! in the selected window.
  
    Most Emacs commands implicitly apply to the text in the selected
! window (mouse commands generally operate on whatever window you click
! them in, whether selected or not).  The text in unselected windows is
! mostly visible for reference.  If you use multiple frames on a
! graphical display, then giving the input focus to a particular frame
! selects a window in that frame.
  
    Each window's last line is a @dfn{mode line}, which describes what
! is going on in that window.  It appears in different color or a ``3D''
! box if the terminal supports either; its contents normally begin with
! @w{@samp{--:-- @ *scratch*}} when Emacs starts.  The mode line
  displays status information such as what buffer is being displayed
  above it in the window, what major and minor modes are in use, and
  whether the buffer contains unsaved changes.
***************
*** 89,104 ****
  currently displayed remembers its point location in case you display
  it again later.  When Emacs displays multiple windows, each window has
  its own point location.  If the same buffer appears in more than one
! window, each window has its own position for point in that buffer, and
! (when possible) its own cursor.
  
!   A text-only terminal has just one cursor, so Emacs puts it
! in the selected window.  The other windows do not show a cursor, even
! though they do have a location of point.  When Emacs updates the
! screen on a text-only terminal, it has to put the cursor temporarily
! at the place the output goes.  This doesn't mean point is there,
! though.  Once display updating finishes, Emacs puts the cursor where
! point is.
  
    On graphical terminals, Emacs shows a cursor in each window; the
  selected window's cursor is solid and blinking, and the other cursors
--- 89,103 ----
  currently displayed remembers its point location in case you display
  it again later.  When Emacs displays multiple windows, each window has
  its own point location.  If the same buffer appears in more than one
! window, each window has its own point in that buffer, and (when
! possible) its own cursor.
  
!   A text-only terminal has just one cursor in the selected window.
! The other windows do not show a cursor, even though they do have a
! location of point.  When Emacs updates the screen on a text-only
! terminal, it has to put the cursor temporarily at the place the output
! goes.  This doesn't mean point is there, though.  Once display
! updating finishes, Emacs puts the cursor where point is.
  
    On graphical terminals, Emacs shows a cursor in each window; the
  selected window's cursor is solid and blinking, and the other cursors
***************
*** 165,182 ****
  are often collapsed into one in that buffer.)
  
  @vindex message-log-max
!   The size of @samp{*Messages*} is limited to a certain number of lines.
! The variable @code{message-log-max} specifies how many lines.  Once the
! buffer has that many lines, each line added at the end deletes one line
! from the beginning.  @xref{Variables}, for how to set variables such as
! @code{message-log-max}.
! 
!   The echo area is also used to display the @dfn{minibuffer}, a window that
! is used for reading arguments to commands, such as the name of a file to be
! edited.  When the minibuffer is in use, the echo area begins with a prompt
! string that usually ends with a colon; also, the cursor appears in that line
! because it is the selected window.  You can always get out of the
! minibuffer by typing @kbd{C-g}.  @xref{Minibuffer}.
  
  @node Mode Line
  @section The Mode Line
--- 164,182 ----
  are often collapsed into one in that buffer.)
  
  @vindex message-log-max
!   The size of @samp{*Messages*} is limited to a certain number of
! lines.  The variable @code{message-log-max} specifies how many lines.
! Once the buffer has that many lines, new lines at the end remove lines
! from the beginning to keep the size constant.  @xref{Variables}, for
! how to set variables such as @code{message-log-max}.
! 
!   The echo area is also used to display the @dfn{minibuffer}, a window
! where you can input arguments to commands, such as the name of a file
! to be edited.  When the minibuffer is in use, the echo area begins
! with a prompt string that usually ends with a colon; also, the cursor
! appears in that line because it is the selected window.  You can
! always get out of the minibuffer by typing @kbd{C-g}.
! @xref{Minibuffer}.
  
  @node Mode Line
  @section The Mode Line
***************
*** 191,198 ****
  On a text-mode display, the mode line is in inverse video if the
  terminal supports that; on a graphics display, the mode line has a 3D
  box appearance to help it stand out.  The mode line of the selected
! window has a slightly different appearance than those of other
! windows; see @ref{Optional Mode Line}, for more about this.
  
    Normally, the mode line looks like this:
  
--- 191,198 ----
  On a text-mode display, the mode line is in inverse video if the
  terminal supports that; on a graphics display, the mode line has a 3D
  box appearance to help it stand out.  The mode line of the selected
! window is slightly different from the others; see @ref{Optional Mode
! Line}, for more information.
  
    Normally, the mode line looks like this:
  
***************
*** 201,226 ****
  @end example
  
  @noindent
! This gives information about the buffer being displayed in the window: the
! buffer's name, what major and minor modes are in use, whether the buffer's
! text has been changed, and how far down the buffer you are currently
! looking.
  
    @var{ch} contains two stars @samp{**} if the text in the buffer has
  been edited (the buffer is ``modified''), or @samp{--} if the buffer has
  not been edited.  For a read-only buffer, it is @samp{%*} if the buffer
  is modified, and @samp{%%} otherwise.
  
!   @var{fr} appears only on text-only terminals, to show the selected
! frame name.  @xref{Frames}.  The initial frame's name is @samp{F1}.
  
!   @var{buf} is the name of the window's @dfn{buffer}.  In most cases
! this is the same as the name of a file you are editing.  @xref{Buffers}.
  
!   The buffer displayed in the selected window (the window that the
! cursor is in) is the @dfn{current buffer}--the one that editing takes
! place in.  When we speak of what some command does to ``the buffer,''
! we mean it does those things to the current buffer.
  
    @var{pos} tells you whether there is additional text above the top of
  the window, or below the bottom.  If your buffer is small and it is all
--- 201,226 ----
  @end example
  
  @noindent
! This is information about the window and the buffer it displays: the
! buffer's name, what major and minor modes are in use, whether the
! buffer's text has been changed, and how far down the buffer you are
! currently looking.
  
    @var{ch} contains two stars @samp{**} if the text in the buffer has
  been edited (the buffer is ``modified''), or @samp{--} if the buffer has
  not been edited.  For a read-only buffer, it is @samp{%*} if the buffer
  is modified, and @samp{%%} otherwise.
  
!   @var{fr} appears only on text-only terminals as the selected frame
! name.  @xref{Frames}.  The initial frame's name is @samp{F1}.
  
!   @var{buf} is the name of the window's @dfn{buffer}.  Usually this is
! the same as the name of a file you are editing.  @xref{Buffers}.
  
!   The buffer displayed in the selected window (the window with the
! cursor) is the @dfn{current buffer}, where editing happens.  When a
! command's effect applies to ``the buffer,'' we mean it does those
! things to the current buffer.
  
    @var{pos} tells you whether there is additional text above the top of
  the window, or below the bottom.  If your buffer is small and it is all
***************
*** 232,248 ****
  well.  @xref{Optional Mode Line}.
  
    @var{line} is @samp{L} followed by the current line number of point.
! This is present when Line Number mode is enabled (which it normally is).
! You can optionally display the current column number too, by turning on
! Column Number mode (which is not enabled by default because it is
! somewhat slower).  @xref{Optional Mode Line}.
  
    @var{major} is the name of the @dfn{major mode} in effect in the
! buffer.  At any time, each buffer is in one and only one of the possible
! major modes.  The major modes available include Fundamental mode (the
! least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many
! others.  @xref{Major Modes}, for details of how the modes differ and how
! to select one.@refill
  
    Some major modes display additional information after the major mode
  name.  For example, Rmail buffers display the current message number and
--- 232,248 ----
  well.  @xref{Optional Mode Line}.
  
    @var{line} is @samp{L} followed by the current line number of point.
! This is present when Line Number mode is enabled (it normally is).
! You can display the current column number too, by turning on Column
! Number mode.  It is not enabled by default because it is somewhat
! slower.  @xref{Optional Mode Line}.
  
    @var{major} is the name of the @dfn{major mode} in effect in the
! buffer.  A buffer can only be in one major mode at a time.  The major
! modes available include Fundamental mode (the least specialized), Text
! mode, Lisp mode, C mode, Texinfo mode, and many others.  @xref{Major
! Modes}, for details of how the modes differ and how to select
! one.@refill
  
    Some major modes display additional information after the major mode
  name.  For example, Rmail buffers display the current message number and
***************
*** 253,266 ****
  turned on at the moment in the window's chosen buffer.  For example,
  @samp{Fill} means that Auto Fill mode is on.  @samp{Abbrev} means that
  Word Abbrev mode is on.  @samp{Ovwrt} means that Overwrite mode is on.
! @xref{Minor Modes}, for more information.  @samp{Narrow} means that
! the buffer being displayed has editing restricted to only a portion of
! its text.  (This is not really a minor mode, but is like one.)
  @xref{Narrowing}.  @samp{Def} means that a keyboard macro is being
  defined.  @xref{Keyboard Macros}.
  
!   In addition, if Emacs is currently inside a recursive editing level,
! square brackets (@samp{[@dots{}]}) appear around the parentheses that
  surround the modes.  If Emacs is in one recursive editing level within
  another, double square brackets appear, and so on.  Since recursive
  editing levels affect Emacs globally, not just one buffer, the square
--- 253,267 ----
  turned on at the moment in the window's chosen buffer.  For example,
  @samp{Fill} means that Auto Fill mode is on.  @samp{Abbrev} means that
  Word Abbrev mode is on.  @samp{Ovwrt} means that Overwrite mode is on.
! @xref{Minor Modes}, for more information.  
! 
!   @samp{Narrow} means that the buffer being displayed has editing
! restricted to only a portion of its text.  This is like a minor mode.
  @xref{Narrowing}.  @samp{Def} means that a keyboard macro is being
  defined.  @xref{Keyboard Macros}.
  
!   In addition, if Emacs is inside a recursive editing level, square
! brackets (@samp{[@dots{}]}) appear around the parentheses that
  surround the modes.  If Emacs is in one recursive editing level within
  another, double square brackets appear, and so on.  Since recursive
  editing levels affect Emacs globally, not just one buffer, the square
***************
*** 288,330 ****
  all.  @xref{Enabling Multibyte}.
  
  @cindex end-of-line conversion, mode-line indication
!   The colon after @var{cs} can change to another string in certain
! circumstances.  Emacs uses newline characters to separate lines in the buffer.
! Some files use different conventions for separating lines: either
! carriage-return linefeed (the MS-DOS convention) or just carriage-return
! (the Macintosh convention).  If the buffer's file uses carriage-return
! linefeed, the colon changes to either a backslash (@samp{\}) or
! @samp{(DOS)}, depending on the operating system.  If the file uses just
! carriage-return, the colon indicator changes to either a forward slash
! (@samp{/}) or @samp{(Mac)}.  On some systems, Emacs displays
! @samp{(Unix)} instead of the colon even for files that use newline to
! separate lines.
! 
!   @xref{Optional Mode Line}, for features that add other handy
! information to the mode line, such as the size of the buffer, the
! current column number of point, and whether new mail for you has
! arrived.
  
    The mode line is mouse-sensitive; when you move the mouse across
! various parts of it, Emacs displays help text to say what a click in
! that place will do.  @xref{Mode Line Mouse}.
  
  @node Menu Bar
  @section The Menu Bar
  @cindex menu bar
  
    Each Emacs frame normally has a @dfn{menu bar} at the top which you
! can use to perform certain common operations.  There's no need to list
! them here, as you can more easily see for yourself.
  
  @kindex M-`
  @kindex F10
  @findex tmm-menubar
    On a graphical terminal, you can use the mouse to choose a command
! from the menu bar.  An arrow pointing right, after the menu item,
! indicates that the item leads to a subsidiary menu; @samp{...} at the
! end means that the command will read arguments (further input from
! you) before it actually does anything.
  
    To view the full command name and documentation for a menu item, type
  @kbd{C-h k}, and then select the menu bar with the mouse in the usual
--- 289,330 ----
  all.  @xref{Enabling Multibyte}.
  
  @cindex end-of-line conversion, mode-line indication
!   The colon after @var{cs} can change to another string sometimes.
! Emacs uses newline characters to separate lines in the buffer.  Some
! files use different conventions for separating lines: either
! carriage-return linefeed (the MS-DOS convention) or just
! carriage-return (the Macintosh convention).  If the buffer's file uses
! carriage-return linefeed, the colon changes to either a backslash
! (@samp{\}) or @samp{(DOS)}, depending on the operating system.  If the
! file uses just carriage-return, the colon indicator changes to either
! a forward slash (@samp{/}) or @samp{(Mac)}.  On some systems, Emacs
! displays @samp{(Unix)} instead of the colon even for files that use
! newline to separate lines.
! 
!   @xref{Optional Mode Line}, to add other handy information to the
! mode line, such as the size of the buffer, the current column number
! of point, and whether new mail for you has arrived.
  
    The mode line is mouse-sensitive; when you move the mouse across
! various parts of it, you'll see help text to say what a click in that
! place will do.  @xref{Mode Line Mouse}.
  
  @node Menu Bar
  @section The Menu Bar
  @cindex menu bar
  
    Each Emacs frame normally has a @dfn{menu bar} at the top which you
! can use to perform common operations.  There's no need to list them
! here, as you can more easily see them yourself.
  
  @kindex M-`
  @kindex F10
  @findex tmm-menubar
    On a graphical terminal, you can use the mouse to choose a command
! from the menu bar.  When a menu item has an arrow pointing right, it
! leads to a subsidiary menu; @samp{...} at the end means that the
! command invoked will read arguments (further input from you) before it
! actually does anything.
  
    To view the full command name and documentation for a menu item, type
  @kbd{C-h k}, and then select the menu bar with the mouse in the usual
***************
*** 332,351 ****
  
    On text-only terminals with no mouse, you can use the menu bar by
  typing @kbd{M-`} or @key{F10} (these run the command
! @code{tmm-menubar}).  This command enters a mode in which you can select
! a menu item from the keyboard.  A provisional choice appears in the echo
! area.  You can use the up and down arrow keys to move through the
! menu to different choices.  When you have found the choice you want,
! type @key{RET} to select it.
! 
!   Each menu item also has an assigned letter or digit which designates
! that item; it is usually the initial of some word in the item's name.
! This letter or digit is separated from the item name by @samp{=>}.  You
! can type the item's letter or digit to select the item.
  
    Some of the commands in the menu bar have ordinary key bindings as
! well; if so, the menu lists one equivalent key binding in parentheses
! after the item itself.
  
  @ignore
     arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f
--- 332,349 ----
  
    On text-only terminals with no mouse, you can use the menu bar by
  typing @kbd{M-`} or @key{F10} (these run the command
! @code{tmm-menubar}).  This lets you select a menu item from the
! keyboard.  A provisional choice appears in the echo area.  You can use
! the up and down arrow keys to move through the menu to different
! items, and then you can type @key{RET} to select the item..
! 
!   You'll see that each menu item in the text-only menubar also has an
! assigned letter or digit which designates that item; it is usually the
! initial of some word in the item's name.  You can type the item's
! letter or digit to select it.
  
    Some of the commands in the menu bar have ordinary key bindings as
! well; one binding will be in parentheses after the item itself.
  
  @ignore
     arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: emacs doc changes

[Richard Stallman]

I like most of your changes; I've done some editing in parts, and will
install.

Re: emacs-Xtra

[Richard Stallman]

    FWIW, I would gladly buy a better manual in two volumes.

Yes, but the bigger it is, the more it will cost, and fewer people
will buy it.  We are trying to raise money by selling this manual.

Please don't argue with our goals.  They are already decided.

Re: emacs-Xtra

[Richard Stallman]

    Why not just volumes 1 and 2, like the ELisp reference manual?

If we sold them together, it would probably increase printing costs,
not decrease them.  (It might increase convenience.)

If we sold them separately, then this is really just a different description
of the previous proposal to split the manual.

Re: emacs-Xtra

[Richard Stallman]

     > If this means splitting the Emacs Manual into two manuals, both of which
     > we would print, maybe that is a good idea--but how would we split it?

    In such a way that that fairly self contained topics like VC stay together.

That isn't a suggestion, just a criterion.

Finding a sensible way to split it seems very hard;
I do not see a way.
Do you?

Re: emacs-Xtra

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Thu, 13 Apr 2006 09:41:18 +1200
> 
> I think emacs-Xtra is becoming a bit of a dog's breakfast

I tend to agree.

> (possibly an ms-dog's breakfast!).

I don't understand this part, especially since most of the MS-DOS info
is still in an appendix to the main manual.

> If I want to find something out about VC, I don't want
> to have to search through *two* manuals to find it because I can't guess
> where the arbitrary split has been made.
> 
> I think the all the documentation for VC should be in one manual.

I agree.  And the same goes for Calendar.

On top of that, whoever split portions of msdog.texi into emacs-xtra,
managed to remove from the main manual important information about
setting up printing on Windows.

> I have two suggestions:
> 
> 1) VC has its own manual like PCL-CVS does.
> 
> 2) All the programming/development topics are moved to a separate manual
>    (Emacs IDE?) and only the obscure stuff is left in emacs-Xtra.

I have a 3rd suggestion (which I think I already made in the past):

  3) Have those ``extra'' sections be part of the on-line manual, but
     not of the printed manual.  In the printed manual, replace the
     extra sections with an xref to the extra manual.  The Texinfo
     @ifinfo facility should do the trick.

This should be a good solution to the original problem, which is that
the FSF wants the printed manuals it sells to not be too large.

Re: emacs-Xtra

[Glenn Morris]

Eli Zaretskii wrote:

>> I think the all the documentation for VC should be in one manual.
>
> I agree.  And the same goes for Calendar.

Just to comment that the Calendar manual has never (AFAIK) been in one
place. The stuff that is in the xtra manual at present used to be in
the Emacs Lisp Reference Manual (which doesn't make much sense as a
home to me) for years.

So putting it all in the main manual (since it's already been
established previously that it should not all be removed from there)
would mean that the introduction of emacs-xtra would have the effect
of _increasing_ the size of the main manual in this area, the opposite
of the intent. Yay.

Re: emacs-Xtra

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: Nick Roberts <nickrob@snap.net.nz>,  emacs-devel@gnu.org
> Date: Thu, 13 Apr 2006 14:40:20 -0400
> 
> 
> Eli Zaretskii wrote:
> 
> >> I think the all the documentation for VC should be in one manual.
> >
> > I agree.  And the same goes for Calendar.
> 
> Just to comment that the Calendar manual has never (AFAIK) been in one
> place.

The fact that this problem always existed doesn't mean we shouldn't
try to fix it.

> So putting it all in the main manual (since it's already been
> established previously that it should not all be removed from there)
> would mean that the introduction of emacs-xtra would have the effect
> of _increasing_ the size of the main manual in this area, the opposite
> of the intent.

The intent is to make the _printed_ manual smaller (because this makes
FSF's publishing costs higher).  The on-line version's size matters
much less, especially since we now compress it at "make install" time.

Re: emacs-Xtra

[Richard Stallman]

    > (possibly an ms-dog's breakfast!).

    I don't understand this part, especially since most of the MS-DOS info
    is still in an appendix to the main manual.

The info about Windows is still in the Emacs Manual.
The parts relevant only to MS-DOS have been moved out.

    On top of that, whoever split portions of msdog.texi into emacs-xtra,
    managed to remove from the main manual important information about
    setting up printing on Windows.

That was a mistake.  Could you move that part back into the main
manual?

Re: emacs-Xtra

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: nickrob@snap.net.nz, emacs-devel@gnu.org
> Date: Fri, 14 Apr 2006 00:18:54 -0400
> 
>     On top of that, whoever split portions of msdog.texi into emacs-xtra,
>     managed to remove from the main manual important information about
>     setting up printing on Windows.
> 
> That was a mistake.  Could you move that part back into the main
> manual?

Will do.

Re: emacs-Xtra

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: nickrob@snap.net.nz, emacs-devel@gnu.org
> Date: Fri, 14 Apr 2006 00:18:54 -0400
> 
>     On top of that, whoever split portions of msdog.texi into emacs-xtra,
>     managed to remove from the main manual important information about
>     setting up printing on Windows.
> 
> That was a mistake.  Could you move that part back into the main
> manual?

Done.

I also added a new section about the HOME directory on Windows.

Re: emacs-Xtra

[Richard Stallman]

    Done.

    I also added a new section about the HOME directory on Windows.

Thanks.

Re: emacs-Xtra

[Richard Stallman]

      3) Have those ``extra'' sections be part of the on-line manual, but
	 not of the printed manual.  In the printed manual, replace the
	 extra sections with an xref to the extra manual.  The Texinfo
	 @ifinfo facility should do the trick.

    This should be a good solution to the original problem, which is that
    the FSF wants the printed manuals it sells to not be too large.

This might be a good approach, as a replacement for emacs-xtra.
If we do not find a good way to split the manual in two, we could
do this instead.

Would someone like to work on this and verify that it really works?