Re: [RFA] New substitute-path commands

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 6 Jul 2006 22:22:19 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> Added bonus, I included a documentation patch for review.

Thanks.  My comments are below.

> -     A non valid file descriptor is returned. ( the return value is negitive ) 
> +     A non valid file descriptor is returned. ( the return value is negative ) 

"non valid"?  Is that correct English?  I think "invalid" is better.

> +Add a source path substitution rule. If a substitution rule was previously\n\
                                      ^^^
Two spaces here, please.

> +Remove the current source path substitution rule.  Has no effect\n\
> +if no path substitution rule was previously specified."),

"This has no effect" is better, I think.

> +In addition to the source path, @value{GDBN} provides a set of commands
> +that manage a source path substitution rule.

The term "substitution rule" should be explained somewhere.  I think
the best place to do so is where the command "set substitute-path" is
described (see below), in which case you should add here a
cross-reference to that description.

>                                                  Instead of attempting to
> +locate the source file using the original source path as described above,
> +it will first apply the substitution rule to that source path, and use
> +the resulting path instead.

If this was meant to explain what is a substitution rule, then it
doesn't explain enough.

> +were compiled. To define a source path substitution rule, use the
> +@code{set substitute-path} command.

A cross-reference here would be a good idea.

> +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}.

This is a start, but it lacks the "set substitute-path" command to go
with the example.

> +@item set substitute-path @var{FROM} @var{TO}

The arguments of @var{} should not be in UPPER case.  They are
automatically upcased by makeinfo when it produces the Info manual,
but in other formats they come out in italics, so having them in upper
case in the source will produce less optimal results.

> +@kindex set substitute-path
> +Define a source path substitution rule.  The new substitution rule
> +replaces any rule previously defined.

As I said above, an explanation of what is a substitution rule is in
order here.  Something like this:

  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 each
  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.

  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.