Re: [RFA] New substitute-path commands

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 9 Jul 2006 22:40:27 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
> > I suggested to have this text after the command description.  In that
> > context, @var{from} and @var{to} refer to the command's arguments.
> > But you moved the description higher in the text, which made those
> > reference dangling.  So this needs to be reworded in some way.
> 
> You're right. It didn't work that way at all. You'll see my attempt
> at fixing it in this version of the patch.

This version is okay to go in, provided that you fix these small
gotchas:

> +In the @ref{set substitute-path} command description, these two
> +parts are named respectively @var{from} and @var{to}.  @value{GDBN}

@ref needs some punctuation after the closing brace (makeinfo should
have griped about that).  In addition, @ref produces something like
"Section X.YZ [Foo Bar]" in the printed version of the manual, so this
sentence will look awkwardly non-English there ("In the Section X.YZ
[Source Path], p.123 command description, these two...").

So please reword, e.g. like this:

  In @ref{set substitute-path}, we name these two parts @var{from} and
  @var{to}, respectively ...

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

Such usage of @ref produces bad results, for the 2nd reason mentioned
above.  You should use @pxref here:

  To define a source path substitution rule, use the @code{set
  substitute-path} command (@pxref{set substitute-path}).