[doc RFA] New option -nh

[doc RFA] New option -nh

[dje]

Hi.

This needs a doc RFA.

Previous discussion is here:
http://sourceware.org/ml/gdb-patches/2012-09/msg00415.html

2012-10-02  Doug Evans  <dje@google.com>

	New option -nh: inhibit loading of ~/.gdbinit.
	* NEWS: Mention -nh.
	* main.c (captured_main): Recognize and process -nh.
	(print_gdb_help): Mention -nh.

	doc/
	* gdb.texinfo (Mode Options): Document -nh.

Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.546
diff -u -p -r1.546 NEWS
--- NEWS	21 Sep 2012 01:46:42 -0000	1.546
+++ NEWS	2 Oct 2012 17:39:53 -0000
@@ -3,6 +3,10 @@
 
 *** Changes since GDB 7.5
 
+* New command line options:
+
+-nh     Like -nx, but only disable auto-loading of ~/.gdbinit.
+
 * Python scripting
 
   ** Vectors can be created with gdb.Type.vector.
Index: main.c
===================================================================
RCS file: /cvs/src/src/gdb/main.c,v
retrieving revision 1.113
diff -u -p -r1.113 main.c
--- main.c	29 Aug 2012 19:17:16 -0000	1.113
+++ main.c	2 Oct 2012 17:39:53 -0000
@@ -273,6 +273,7 @@ captured_main (void *data)
   char **argv = context->argv;
   static int quiet = 0;
   static int set_args = 0;
+  static int inhibit_home_gdbinit = 0;
 
   /* Pointers to various arguments from command line.  */
   char *symarg = NULL;
@@ -415,6 +416,7 @@ captured_main (void *data)
       {"quiet", no_argument, &quiet, 1},
       {"q", no_argument, &quiet, 1},
       {"silent", no_argument, &quiet, 1},
+      {"nh", no_argument, &inhibit_home_gdbinit, 1},
       {"nx", no_argument, &inhibit_gdbinit, 1},
       {"n", no_argument, &inhibit_gdbinit, 1},
       {"batch-silent", no_argument, 0, 'B'},
@@ -845,7 +847,7 @@ captured_main (void *data)
      global parameters, which are independent of what file you are
      debugging or what directory you are in.  */
 
-  if (home_gdbinit && !inhibit_gdbinit)
+  if (home_gdbinit && !inhibit_gdbinit && !inhibit_home_gdbinit)
     catch_command_errors (source_script, home_gdbinit, 0, RETURN_MASK_ALL);
 
   /* Process '-ix' and '-iex' options early.  */
@@ -1066,9 +1068,12 @@ Options:\n\n\
   fputs_unfiltered (_("\
   -l TIMEOUT         Set timeout in seconds for remote debugging.\n\
   --nw		     Do not use a window interface.\n\
-  --nx               Do not read "), stream);
+  --nx               Do not read any "), stream);
   fputs_unfiltered (gdbinit, stream);
-  fputs_unfiltered (_(" file.\n\
+  fputs_unfiltered (_(" files.\n\
+  --nh               Do not read "), stream);
+  fputs_unfiltered (gdbinit, stream);
+  fputs_unfiltered (_(" file from home directory.\n\
   --quiet            Do not print version number on startup.\n\
   --readnow          Fully read symbol files on first access.\n\
 "), stream);
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.1012
diff -u -p -r1.1012 gdb.texinfo
--- doc/gdb.texinfo	21 Sep 2012 01:46:42 -0000	1.1012
+++ doc/gdb.texinfo	2 Oct 2012 17:39:53 -0000
@@ -1048,6 +1048,13 @@ Do not execute commands found in any ini
 options and arguments have been processed.  @xref{Command Files,,Command
 Files}.
 
+@anchor{-nh}
+@item -nh
+@cindex @code{--nh}
+Do not execute commands found in @file{~/.gdbinit}, the init file
+in your home directory.
+@xref{Startup}.
+
 @item -quiet
 @itemx -silent
 @itemx -q

Re: [doc RFA] New option -nh

[Eli Zaretskii]

> Date: Tue, 02 Oct 2012 10:46:15 -0700
> From: dje@google.com
> 
> This needs a doc RFA.

Here goes:

> +* New command line options:
> +
> +-nh     Like -nx, but only disable auto-loading of ~/.gdbinit.

I'd suggest to mention in parentheses what -nx does that -nh doesn't.

> +@anchor{-nh}
> +@item -nh
> +@cindex @code{--nh}
> +Do not execute commands found in @file{~/.gdbinit}, the init file
> +in your home directory.
> +@xref{Startup}.

Likewise here.  The previous paragraph, that describes -nx, says:

  @itemx -n
  @cindex @code{--nx}
  @cindex @code{-n}
  Do not execute commands found in any initialization files.  Normally,
  @value{GDBN} executes the commands in these files after all the command
  options and arguments have been processed.  @xref{Command Files,,Command
  Files}.

There's almost nothing in common between this verbiage and what you
suggested for -nh.  The reader will have hard time figuring out that
-nh does a subset of what -nx does.

I see 2 possible ways to make the relations between these 2 switches
clear (and I'm okay with either one of them):

 . rewrite the -nx documentation to explicitly mention ~/.gdbinit,
   site-wide gdbinit etc., in the same style as you described -nh;
   then you can leave the -nh description alone, or

 . Add a sentence to your -nh description which says something like
   "Unlike @code{--nx}, ..." and go on to describe what -nx does, but
   -nh does not.

Makes sense?

Re: [doc RFA] New option -nh

[Sergio Durigan Junior]

On Tuesday, October 02 2012, dje@google.com wrote:

> 2012-10-02  Doug Evans  <dje@google.com>
>
> 	New option -nh: inhibit loading of ~/.gdbinit.
> 	* NEWS: Mention -nh.
> 	* main.c (captured_main): Recognize and process -nh.
> 	(print_gdb_help): Mention -nh.
>
> 	doc/
> 	* gdb.texinfo (Mode Options): Document -nh.

Do you intend to patch gdb/gdb.1 (manpage)?  I know it is really
outdated compared to the info page, but it exists and people use it, so
I would vote for documenting this new option there as well.

Thanks,

-- 
Sergio

Re: [doc RFA] New option -nh

[dje]

Eli Zaretskii writes:
 > > +* New command line options:
 > > +
 > > +-nh     Like -nx, but only disable auto-loading of ~/.gdbinit.
 > 
 > I'd suggest to mention in parentheses what -nx does that -nh doesn't.

This is a just NEWS item.
Adding all that extra text worsens the S/N ratio IMO.

 > > +@anchor{-nh}
 > > +@item -nh
 > > +@cindex @code{--nh}
 > > +Do not execute commands found in @file{~/.gdbinit}, the init file
 > > +in your home directory.
 > > +@xref{Startup}.
 > 
 > Likewise here.  The previous paragraph, that describes -nx, says:
 > 
 >   @itemx -n
 >   @cindex @code{--nx}
 >   @cindex @code{-n}
 >   Do not execute commands found in any initialization files.  Normally,
 >   @value{GDBN} executes the commands in these files after all the command
 >   options and arguments have been processed.  @xref{Command Files,,Command
 >   Files}.
 > 
 > There's almost nothing in common between this verbiage and what you
 > suggested for -nh.  The reader will have hard time figuring out that
 > -nh does a subset of what -nx does.
 > 
 > I see 2 possible ways to make the relations between these 2 switches
 > clear (and I'm okay with either one of them):
 > 
 >  . rewrite the -nx documentation to explicitly mention ~/.gdbinit,
 >    site-wide gdbinit etc., in the same style as you described -nh;
 >    then you can leave the -nh description alone, or
 > 
 >  . Add a sentence to your -nh description which says something like
 >    "Unlike @code{--nx}, ..." and go on to describe what -nx does, but
 >    -nh does not.

Sergio Durigan Junior writes:
 > Do you intend to patch gdb/gdb.1 (manpage)?  I know it is really
 > outdated compared to the info page, but it exists and people use it, so
 > I would vote for documenting this new option there as well.

How about this?

2012-10-04  Doug Evans  <dje@google.com>

	New option -nh: inhibit loading of ~/.gdbinit.
	* NEWS: Mention -nh.
	* main.c (captured_main): Recognize and process -nh.
	(print_gdb_help): Mention -nh.
	* gdb.1: Mention -nh.  Remove erroneous docs on -nx behavior.

	doc/
	* gdb.texinfo (Mode Options): Document -nh.
	Elaborate on docs for -nx.

Index: NEWS
===================================================================
RCS file: /cvs/src/src/gdb/NEWS,v
retrieving revision 1.546
diff -u -p -r1.546 NEWS
--- NEWS	21 Sep 2012 01:46:42 -0000	1.546
+++ NEWS	4 Oct 2012 17:10:59 -0000
@@ -3,6 +3,10 @@
 
 *** Changes since GDB 7.5
 
+* New command line options:
+
+-nh     Like -nx, but only disable auto-loading of ~/.gdbinit.
+
 * Python scripting
 
   ** Vectors can be created with gdb.Type.vector.
Index: gdb.1
===================================================================
RCS file: /cvs/src/src/gdb/gdb.1,v
retrieving revision 1.9
diff -u -p -r1.9 gdb.1
--- gdb.1	14 Sep 2012 12:10:23 -0000	1.9
+++ gdb.1	4 Oct 2012 17:10:59 -0000
@@ -9,6 +9,7 @@ gdb \- The GNU Debugger
 .TP
 .B gdb
 .RB "[\|" \-help "\|]"
+.RB "[\|" \-nh "\|]"
 .RB "[\|" \-nx "\|]"
 .RB "[\|" \-q "\|]"
 .RB "[\|" \-batch "\|]"
@@ -283,14 +284,16 @@ Add \c
 .PP
 
 .TP
+.B \-nh
+Do not execute commands from ~/.gdbinit.
+
+.TP
 .B \-nx
 .TP
 .B \-n
 Do not execute commands from any `\|\c
 .B .gdbinit\c
 \&\|' initialization files.
-Normally, the commands in these files are executed after all the
-command options and arguments have been processed.
 
 
 .TP
Index: main.c
===================================================================
RCS file: /cvs/src/src/gdb/main.c,v
retrieving revision 1.113
diff -u -p -r1.113 main.c
--- main.c	29 Aug 2012 19:17:16 -0000	1.113
+++ main.c	4 Oct 2012 17:10:59 -0000
@@ -273,6 +273,7 @@ captured_main (void *data)
   char **argv = context->argv;
   static int quiet = 0;
   static int set_args = 0;
+  static int inhibit_home_gdbinit = 0;
 
   /* Pointers to various arguments from command line.  */
   char *symarg = NULL;
@@ -415,6 +416,7 @@ captured_main (void *data)
       {"quiet", no_argument, &quiet, 1},
       {"q", no_argument, &quiet, 1},
       {"silent", no_argument, &quiet, 1},
+      {"nh", no_argument, &inhibit_home_gdbinit, 1},
       {"nx", no_argument, &inhibit_gdbinit, 1},
       {"n", no_argument, &inhibit_gdbinit, 1},
       {"batch-silent", no_argument, 0, 'B'},
@@ -845,7 +847,7 @@ captured_main (void *data)
      global parameters, which are independent of what file you are
      debugging or what directory you are in.  */
 
-  if (home_gdbinit && !inhibit_gdbinit)
+  if (home_gdbinit && !inhibit_gdbinit && !inhibit_home_gdbinit)
     catch_command_errors (source_script, home_gdbinit, 0, RETURN_MASK_ALL);
 
   /* Process '-ix' and '-iex' options early.  */
@@ -1066,9 +1068,12 @@ Options:\n\n\
   fputs_unfiltered (_("\
   -l TIMEOUT         Set timeout in seconds for remote debugging.\n\
   --nw		     Do not use a window interface.\n\
-  --nx               Do not read "), stream);
+  --nx               Do not read any "), stream);
   fputs_unfiltered (gdbinit, stream);
-  fputs_unfiltered (_(" file.\n\
+  fputs_unfiltered (_(" files.\n\
+  --nh               Do not read "), stream);
+  fputs_unfiltered (gdbinit, stream);
+  fputs_unfiltered (_(" file from home directory.\n\
   --quiet            Do not print version number on startup.\n\
   --readnow          Fully read symbol files on first access.\n\
 "), stream);
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.1012
diff -u -p -r1.1012 gdb.texinfo
--- doc/gdb.texinfo	21 Sep 2012 01:46:42 -0000	1.1012
+++ doc/gdb.texinfo	4 Oct 2012 17:11:00 -0000
@@ -1043,10 +1043,37 @@ batch mode or quiet mode.
 @itemx -n
 @cindex @code{--nx}
 @cindex @code{-n}
-Do not execute commands found in any initialization files.  Normally,
-@value{GDBN} executes the commands in these files after all the command
-options and arguments have been processed.  @xref{Command Files,,Command
-Files}.
+Do not execute commands found in any initialization file.
+There are three init files, loaded in the following order:
+
+@table @code
+@item @file{system.gdbinit}
+This is the system-wide init file.
+Its location is specified with the @code{--with-system-gdbinit}
+configure option (@pxref{System-wide configuration}).
+It is loaded first when gdb starts, before command line options
+have been processed.
+@item @file{~/.gdbinit}
+This is the init file in your home directory.
+It is loaded next, after @file{system.gdbinit}, and before
+command options have been processed.
+@item @file{./.gdbinit}
+This is the init file in the current directory.
+It is loaded last, after command line options other than @code{-x} and
+@code{-ex} have been processed.  Command line options @code{-x} and
+@code{-ex} are processed last, after @file{./.gdbinit} has been loaded.
+@end table
+
+For further documentation on startup processing, @xref{Startup}.
+For documentation on how to write command files,
+@xref{Command Files,,Command Files}.
+
+@anchor{-nh}
+@item -nh
+@cindex @code{--nh}
+Do not execute commands found in @file{~/.gdbinit}, the init file
+in your home directory.
+@xref{Startup}.
 
 @item -quiet
 @itemx -silent

Re: [doc RFA] New option -nh

[Eli Zaretskii]

> Date: Thu, 4 Oct 2012 10:21:25 -0700
> Cc: gdb-patches@sourceware.org,
> From: dje@google.com
> 
> Eli Zaretskii writes:
>  > > +* New command line options:
>  > > +
>  > > +-nh     Like -nx, but only disable auto-loading of ~/.gdbinit.
>  > 
>  > I'd suggest to mention in parentheses what -nx does that -nh doesn't.
> 
> This is a just NEWS item.
> Adding all that extra text worsens the S/N ratio IMO.

Not if you get it right ;-)  How about this:

 -nh   Disables auto-loading of ~/.gdbinit, but still executes all the
       other initialization files, unlike -nx which disables all of them.

> +It is loaded first when gdb starts, before command line options
                           ^^^
@value{GDBN}

OK with this correction.

Thanks.

Re: [doc RFA] New option -nh

[Sergio Durigan Junior]

On Thursday, October 04 2012, dje@google.com wrote:

> Sergio Durigan Junior writes:
>  > Do you intend to patch gdb/gdb.1 (manpage)?  I know it is really
>  > outdated compared to the info page, but it exists and people use it, so
>  > I would vote for documenting this new option there as well.
>
> How about this?

Sorry for the delay.  Thanks, it's fine by me.

-- 
Sergio