[PATCH] misc.texi, files.texi

[PATCH] misc.texi, files.texi

[Nick Roberts]

The recenty added node "Diff Mode" overlaps slightly and lacks cohesion
with the existing node "Comparing Files".  This patch attempts to address
that.

OK to apply?

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


*** misc.texi	03 May 2006 10:22:09 +1200	1.82
--- misc.texi	03 May 2006 10:46:49 +1200	
***************
*** 1830,1835 ****
--- 1830,1836 ----
  @node Diff Mode, Two-Column, Narrowing, Top
  @section Diff Mode
  @cindex Diff mode
+ @findex diff-mode
  
    Diff mode is useful for editing patches and comparisons produced by
  the @command{diff} program.  You can select Diff mode by typing
***************
*** 1901,1906 ****
--- 1902,1911 ----
  (@code{diff-refine-hunk}).
  @end table
  
+   You can also use @kbd{C-x `} to visit successive changed locations
+ in the two source files, as in Compilation mode (@pxref{Compilation
+ Mode}.)
+ 
    @kbd{C-x 4 a} in Diff mode operates on behalf of the target file,
  but gets the function name from the patch itself.  @xref{Change Log}.
  This is useful for making log entries for functions that are deleted


*** files.texi	13 Apr 2006 09:12:42 +1200	1.139
--- files.texi	03 May 2006 10:48:23 +1200	
***************
*** 2159,2164 ****
--- 2159,2166 ----
  running the @code{diff} program, using options taken from the variable
  @code{diff-switches}.  The value of @code{diff-switches} should be a
  string; the default is @code{"-c"} to specify a context diff.
+ The @samp{*diff*} buffer uses Diff mode (@pxref{Diff Mode}).
+ 
  
  @findex diff-backup
    The command @kbd{M-x diff-backup} compares a specified file with its most
***************
*** 2166,2180 ****
  @code{diff-backup} compares it with the source file that it is a backup
  of.
  
- @findex diff-goto-source
- @findex diff-mode
- @cindex Diff mode
-   The @samp{*diff*} buffer uses Diff mode, which enables you to use
- @kbd{C-x `} to visit successive changed locations in the two source
- files, as in Compilation mode (@pxref{Compilation Mode}.)  You can
- also move to a particular hunk of changes and type @kbd{C-c C-c}
- (@code{diff-goto-source}) to visit the corresponding source location.
- 
  @cindex patches
    Differences between versions of files are often distributed as
  patches, which are the output from the @command{diff} program.  You
--- 2168,2173 ----

Re: [PATCH] misc.texi, files.texi

[Richard Stallman]

I had forgotten about the Comparing Files node.  I moved the new Diff
Mode node just after that one.

Re: [PATCH] misc.texi, files.texi

[Nick Roberts]

 > I had forgotten about the Comparing Files node.  I moved the new Diff
 > Mode node just after that one.

Fine, except the node "Diff Mode" now references itself:


    @node Diff Mode
    @section Diff Mode
    @cindex Diff mode
    @findex diff-mode
    @cindex patches, editing
    
      The @samp{*diff*} buffer uses Diff mode (@pxref{Diff Mode}).  Diff

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

Re: [PATCH] misc.texi, files.texi

[Nick Roberts]

 > I had forgotten about the Comparing Files node.  I moved the new Diff
 > Mode node just after that one.

I also see you removed:

     You can also use @kbd{C-x `} to visit successive changed locations
   in the two source files, as in Compilation mode (@pxref{Compilation
   Mode}.)

Perhaps it should say "in the source file" but it's not obvious (to me,
anyway) that next-error works in diff-mode, so why remove this paragraph?

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

Re: [PATCH] misc.texi, files.texi

[Richard Stallman]

    I also see you removed:

	 You can also use @kbd{C-x `} to visit successive changed locations
       in the two source files, as in Compilation mode (@pxref{Compilation
       Mode}.)

I removed this because it is a property of Diff mode rather than those
specific commands; but I overlooked that this wasn't documented in the
Diff Mode node either.  I will make this change:


*** files.texi	05 May 2006 16:57:47 -0400	1.142
--- files.texi	05 May 2006 20:19:10 -0400	
***************
*** 2225,2232 ****
    One general feature of Diff mode is that manual edits to the patch
  automatically correct line numbers, including those in the hunk
  header, so that you can actually apply the edited patch.  Diff mode
! also provides the following commands to navigate, manipulate and apply
! parts of patches:
  
  @table @kbd
  @item M-n
--- 2225,2234 ----
    One general feature of Diff mode is that manual edits to the patch
  automatically correct line numbers, including those in the hunk
  header, so that you can actually apply the edited patch.  Diff mode
! treats each hunk location as an ``error message'', so that you can use
! commands such as @kbd{C-x '} to visit the corresponding source
! locations.  It also provides the following commands to navigate,
! manipulate and apply parts of patches:
  
  @table @kbd
  @item M-n

Re: [PATCH] misc.texi, files.texi

[Nick Roberts]

 >     I also see you removed:
 > 
 > 	 You can also use @kbd{C-x `} to visit successive changed locations
 >        in the two source files, as in Compilation mode (@pxref{Compilation
 >        Mode}.)
 > 
 > I removed this because it is a property of Diff mode rather than those
 > specific commands; but I overlooked that this wasn't documented in the
 > Diff Mode node either.  I will make this change:
 > ...

Yes this looks good.  At least three modes use next-error (compile, grep
and diff-mode).  At some stage. not now, it might be a good idea to for
it to have its own node.  AFAICS grep currently resides in building.texi
just because it uses next-error, when it really belongs to files.texi.

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