Re: [RFA] New substitute-path commands

Eli Zaretskii
2006-07-10T19:53:58Z

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