Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.340
diff -u -p -r1.340 gdb.texinfo
--- doc/gdb.texinfo	21 Jun 2006 13:57:21 -0000	1.340
+++ doc/gdb.texinfo	7 Jul 2006 19:02:26 -0000
@@ -5033,6 +5033,40 @@ To add other directories, use the @code{
 The search path is used to find both program source files and @value{GDBN}
 script files (read using the @samp{-command} option and @samp{source} command).
 
+In addition to the source path, @value{GDBN} provides a set of commands
+that manage a source path substitution rule.  A @dfn{substitution rule}
+specifies how to rewrite source directories stored in the program's
+debug information in case the sources were moved to a different
+directory between compilation and debugging.  @value{GDBN} does a simple
+string replacement of the first occurrence of @var{from} with @var{to}
+in the directory part of the source file name, and uses the result
+instead of the original file name to look up the sources.
+
+Using the previous example, suppose the @file{foo-1.0} tree has been
+moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell
+GDB to replace @file{/usr/src} in all source path names with
+@file{/mnt/cross}.  The first lookup will then be
+@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location
+of @file{/usr/src/foo-1.0/lib/foo.c}.  To define a source path
+substitution rule, use the @ref{set substitute-path} command.
+
+In many cases, you can achieve the same result using the @code{directory}
+command.  However, @code{set substitute-path} can be more efficient in
+the case where the sources are organized in a complex tree with multiple
+subdirectories.  With the @code{directory} command, you need to add each
+subdirectory of your project.  If you moved the entire tree while
+preserving its internal organization, then @code{set substitute-path}
+allows you to direct the debugger to all the sources with one single
+command.
+
+However, @code{set substitute-path} is also more than just a shortcut
+command.  The source path is only used if the file at the original
+location no longer exists.  On the other hand, @code{set substitute-path}
+modifies the debugger behavior to look at the rewritten location
+instead.  So, if for any reason a source file that is not relevant to
+your executable is located at the original location, the substitution
+rule is the only method available to point GDB at the new location.
+
 @table @code
 @item directory @var{dirname} @dots{}
 @item dir @var{dirname} @dots{}
@@ -5068,6 +5102,34 @@ Reset the source path to its default val
 @item show directories
 @kindex show directories
 Print the source path: show which directories it contains.
+
+@anchor{set substitute-path}
+@item set substitute-path @var{FROM} @var{TO}
+@kindex set substitute-path
+Define a source path substitution rule.  The new substitution rule
+replaces any rule previously defined.
+
+For example, if the file @file{/foo/bar/baz.c} was moved to
+@file{/mnt/cross/baz.c}, then the command
+
+@smallexample
+(@value{GDBP}) set substitute-path /usr/src /mnt/cross
+@end smallexample
+
+@noindent
+will tell @value{GDBN} to replace @samp{/usr/src} with
+@samp{/mnt/cross}, which will allow @value{GDBN} to find the file
+@file{baz.c} even though it was moved.
+
+@item unset substitute-path
+@kindex unset substitute-path
+If a source path substitution rule is active, then cancel it.
+This command has no effect otherwise.
+
+@item show substitute-path
+@kindex show substitute-path
+Print the source path substitution rule if defined.
+
 @end table
 
 If your source path is cluttered with directories that are no longer of