[RFA] Improve help set/unset/show substitute-path

[RFA] Improve help set/unset/show substitute-path

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 550 bytes --]

Hello,

As promised to Daniel, hopefully the following patch will make the help
text of the vaious substitute-path commands a bit better. Anyone either
wanting to refresh his memory about the usage should now be able to
use the help text for that. It's also easier to use the command without
having read the documentation.

2007-01-12  Joel Brobecker  <brobecker@adacore.com>

        * source.c (_initialize_source): Improve the help text of
        the substitute-path commands.

Tested on x86-linux, no regression.
OK to commit?

Thanks,
-- 
Joel

[-- Attachment #2: help.diff --]
[-- Type: text/plain, Size: 1704 bytes --]

Index: source.c
===================================================================
RCS file: /cvs/src/src/gdb/source.c,v
retrieving revision 1.76
diff -u -p -r1.76 source.c
--- source.c	8 Aug 2006 22:06:06 -0000	1.76
+++ source.c	12 Jan 2007 06:32:06 -0000
@@ -1997,16 +2007,26 @@ Show number of source lines gdb will lis
 
   add_cmd ("substitute-path", class_files, set_substitute_path_command,
            _("\
-Add a source path substitution rule.  If a substitution rule was previously\n\
-set, it is overridden."), &setlist);
+set substitute-path FROM TO\n\
+Add a source path substitution rule replacing FROM into TO in source paths.\n\
+If a substitution rule was previously set for FROM, the old rule is replaced\n\
+by the new one."),
+           &setlist);
 
   add_cmd ("substitute-path", class_files, unset_substitute_path_command,
            _("\
-Remove the current source path substitution rule.  This has no effect\n\
-if no path substitution rule was previously specified."),
+unset substitute-path [FROM]\n\
+If a path is specified (FROM), delete the associated rule from the current\n\
+list of substitution rules.  A warning is emmitted by the debugger if\n\
+no rule could be found.\n\
+If no path is specified, then all substitution rules are deleted."),
            &unsetlist);
 
   add_cmd ("substitute-path", class_files, show_substitute_path_command,
-           _("Show the current source path substitution rule."),
+           _("\
+show substitute-path [FROM]\n\
+If a path is specified (FROM), print the source path substitution rule which\n\
+would rewrite that path.\n\
+If no path is specified, print all source path substitution rules."),
            &showlist);
 }

Re: [RFA] Improve help set/unset/show substitute-path

[Eli Zaretskii]

> Date: Fri, 12 Jan 2007 11:13:23 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> 
> As promised to Daniel, hopefully the following patch will make the help
> text of the vaious substitute-path commands a bit better. Anyone either
> wanting to refresh his memory about the usage should now be able to
> use the help text for that. It's also easier to use the command without
> having read the documentation.

Thanks!

> +set substitute-path FROM TO\n\

I think it is better to say "Usage: set substitute-path FROM TO".

> +Add a source path substitution rule replacing FROM into TO in source paths.\n\

GNU standards dislike such usage of the word ``path''.  We should use
``file name'' instead.  (``Path'' is reserved for lists of directories,
such the values of $PATH and $MANPATH environment variables.)

> +unset substitute-path [FROM]\n\
> +If a path is specified (FROM), delete the associated rule from the current\n\
> +list of substitution rules.  A warning is emmitted by the debugger if\n\
> +no rule could be found.\n\
> +If no path is specified, then all substitution rules are deleted."),

I suggest to say this instead:

  Delete the rule for substituting FROM in source file names.  If FROM
  is not specified, all substituting rules are deleted.
  If the debugger cannot find a rule for FROM, it will display a
  warning.

> +show substitute-path [FROM]\n\
> +If a path is specified (FROM), print the source path substitution rule which\n\

Same here.

Re: [RFA] Improve help set/unset/show substitute-path

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 327 bytes --]

Thanks for the feedback, Eli. With your help, I think this second version
is a huge improvement.

2007-01-13  Joel Brobecker  <brobecker@adacore.com>

        * source.c (_initialize_source): Improve the help text of
        the substitute-path commands.

Tested on x86-linux, no regression.
OK to commit?

Thank you,
-- 
Joel

[-- Attachment #2: help.diff --]
[-- Type: text/plain, Size: 1616 bytes --]

Index: source.c
===================================================================
RCS file: /cvs/src/src/gdb/source.c,v
retrieving revision 1.77
diff -u -p -r1.77 source.c
--- source.c	9 Jan 2007 17:58:58 -0000	1.77
+++ source.c	13 Jan 2007 14:00:42 -0000
@@ -1997,16 +1997,24 @@ Show number of source lines gdb will lis
 
   add_cmd ("substitute-path", class_files, set_substitute_path_command,
            _("\
-Add a source path substitution rule.  If a substitution rule was previously\n\
-set, it is overridden."), &setlist);
+Usage: set substitute-path FROM TO\n\
+Add a substitution rule replacing FROM into TO in source file names.\n\
+If a substitution rule was previously set for FROM, the old rule\n\
+is replaced by the new one."),
+           &setlist);
 
   add_cmd ("substitute-path", class_files, unset_substitute_path_command,
            _("\
-Remove the current source path substitution rule.  This has no effect\n\
-if no path substitution rule was previously specified."),
+Usage: unset substitute-path [FROM]\n\
+Delete the rule for substituting FROM in source file names.  If FROM\n\
+is not specified, all substituting rules are deleted.\n\
+If the debugger cannot find a rule for FROM, it will display a warning."),
            &unsetlist);
 
   add_cmd ("substitute-path", class_files, show_substitute_path_command,
-           _("Show the current source path substitution rule."),
+           _("\
+Usage: show substitute-path [FROM]\n\
+Print the rule for substituting FROM in source file names. If FROM\n\
+is not specified, print all substitution rules."),
            &showlist);
 }

Re: [RFA] Improve help set/unset/show substitute-path

[Eli Zaretskii]

> Date: Sat, 13 Jan 2007 18:03:20 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> Thanks for the feedback, Eli. With your help, I think this second version
> is a huge improvement.
> 
> 2007-01-13  Joel Brobecker  <brobecker@adacore.com>
> 
>         * source.c (_initialize_source): Improve the help text of
>         the substitute-path commands.
> 
> Tested on x86-linux, no regression.
> OK to commit?

This version is fine with me, thanks.

Re: [RFA] Improve help set/unset/show substitute-path

[Joel Brobecker]

> > 2007-01-13  Joel Brobecker  <brobecker@adacore.com>
> > 
> >         * source.c (_initialize_source): Improve the help text of
> >         the substitute-path commands.
> > 
> > Tested on x86-linux, no regression.
> > OK to commit?
> 
> This version is fine with me, thanks.

Thank you, checked in.

-- 
Joel