[RFA 01/12] Fix help and documentation for inferior commands

[Tom Tromey <tom@tromey.com>]

This changes inferior.c to add Usage lines for all commands, and to
change how "metasyntactic variables" are written to conform to GNU
style.

While doing this I noticed that the manual doesn't document the
argument to "info inferiors", so I've added that as well.

ChangeLog
2018-04-27  Tom Tromey  <tom@tromey.com>

	* inferior.c (initialize_inferiors): Update help strings.

doc/ChangeLog
2018-04-27  Tom Tromey  <tom@tromey.com>

	* gdb.texinfo (Inferiors and Programs): Document argument to "info
	inferiors".
---
 gdb/ChangeLog       |  4 ++++
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/gdb.texinfo |  4 +++-
 gdb/inferior.c      | 18 ++++++++++++------
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 28f083f96e..a25ada6e28 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2708,9 +2708,11 @@ To find out what inferiors exist at any moment, use @w{@code{info
 inferiors}}:
 
 @table @code
-@kindex info inferiors
+@kindex info inferiors [ @var{ID}@dots{} ]
 @item info inferiors
 Print a list of all inferiors currently being managed by @value{GDBN}.
+By default all inferiors are printed, but an argument can be used to
+limit the display to just the requested inferiors.
 
 @value{GDBN} displays for each inferior (in this order):
 
diff --git a/gdb/inferior.c b/gdb/inferior.c
index d7122fcfad..ec2f985919 100644
--- a/gdb/inferior.c
+++ b/gdb/inferior.c
@@ -996,12 +996,15 @@ initialize_inferiors (void)
   /* The architecture will be initialized shortly, by
      initialize_current_architecture.  */
 
-  add_info ("inferiors", info_inferiors_command, 
-	    _("IDs of specified inferiors (all inferiors if no argument)."));
+  add_info ("inferiors", info_inferiors_command,
+	    _("Print a list of inferiors being managed.\n\
+Usage: info inferiors [ID]...\n\
+If IDs are specified, the list is limited to just those inferiors.\n\
+By default all inferiors are displayed."));
 
   c = add_com ("add-inferior", no_class, add_inferior_command, _("\
 Add a new inferior.\n\
-Usage: add-inferior [-copies <N>] [-exec <FILENAME>]\n\
+Usage: add-inferior [-copies N] [-exec FILENAME]\n\
 N is the optional number of inferiors to add, default is 1.\n\
 FILENAME is the file name of the executable to use\n\
 as main program."));
@@ -1013,22 +1016,25 @@ Usage: remove-inferiors ID..."));
 
   add_com ("clone-inferior", no_class, clone_inferior_command, _("\
 Clone inferior ID.\n\
-Usage: clone-inferior [-copies <N>] [ID]\n\
+Usage: clone-inferior [-copies N] [ID]\n\
 Add N copies of inferior ID.  The new inferior has the same\n\
 executable loaded as the copied inferior.  If -copies is not specified,\n\
 adds 1 copy.  If ID is not specified, it is the current inferior\n\
 that is cloned."));
 
   add_cmd ("inferiors", class_run, detach_inferior_command, _("\
-Detach from inferior ID (or list of IDS)."),
+Detach from inferior ID (or list of IDS).\n\
+Usage; detach inferiors ID..."),
 	   &detachlist);
 
   add_cmd ("inferiors", class_run, kill_inferior_command, _("\
-Kill inferior ID (or list of IDs)."),
+Kill inferior ID (or list of IDs).\n\
+Usage: kill inferiors ID..."),
 	   &killlist);
 
   add_cmd ("inferior", class_run, inferior_command, _("\
 Use this command to switch between inferiors.\n\
+Usage: inferior ID\n\
 The new inferior ID must be currently known."),
 	   &cmdlist);
 
-- 
2.13.6