Re: [PATCH 4/7] gdb: process startup files and startup command line options

[Eli Zaretskii via Gdb-patches <gdb-patches@sourceware.org>]

> From: Andrew Burgess <andrew.burgess@embecosm.com>
> Date: Wed,  7 Oct 2020 21:05:08 +0100
> Cc: Tom Tromey <tom@tromey.com>
> 
> Adds the ability to process commands at a new phase during GDB's
> startup.  This phase is earlier than the current initialisation file
> processing, before GDB has produced any output.

Thanks.  Some comments about the documentation parts below.

> diff --git a/gdb/NEWS b/gdb/NEWS
> index c64dda7bbcb..bd3aca84d51 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -21,6 +21,17 @@
>    $HOME/.gdbinit.  On Apple hosts the search order is instead:
>    $HOME/Library/Preferences/gdb/gdbinit, $HOME/.gdbinit.
>  
> +* GDB will now load and process commands from
> +  ~/.config/gdb/gdbstartup, ~/.gdbstartup, or a local file
> +  ./.gdbstartup if these files are present.  These files are processed
> +  earlier than any of the previous initialization files and can effect
                                                                   ^^^^^^
"affect"

> +  parts of GDB's startup that previously had already been completed
> +  before the initialization files were read.

This begs the question: such as?...  Can we at least say something
about that here?

> +* GDB now has two new options "--startup-command" and
> +  "--startup-eval-command" with corresponding short options "-sx" and
> +  "-sex" that allow startup options to be passed on the command line.

What are "startup options" for this matter?  Perhaps an example will
be enough to explain that.

> +@item
> +@cindex startup file
> +Reads startup options from the startup file (if any) in your home
> +directory, followed by any startup options contained in a startup file
> +(if any) in the local directory as long as @samp{set auto-load
> +local-gdbinit} is set to @samp{on} (@pxref{Init File in the Current
> +Directory}), @pxref{Local directory startup file}.
> +
> +@item
> +Any startup command line options (@samp{startup-command} and
> +@samp{startup-eval-command}) are processed.

The previous @item uses the style of others in the list ("Reads ..."),
but this item suddenly switches to a different style.  Suggest to
reword:

  Processes any startup command-line options ...

> +The files processed are split into two categories @dfn{startup files}
> +and @dfn{initialization files}.  The startup files are loaded as
> +early as possible during @value{GDBN}'s startup and allow a limited
> +set of settings to be configured that can affect how the rest of
> +@value{GDBN} starts up.  The more general initialization files are
> +processed later after @value{GDBN} has finished its own internal
> +startup process, any commands can be used in these files.

This again leaves unexplained the practical difference between these
two classes.  I as a reader am left wondering what kind of commands
and settings would I need to put in the startup files, and why.

Please add some text that explains this, preferably with a couple of
examples.

> +On non-Apple hosts the locations searched are:
> +@table @file
> +@item $XDG_CONFIG_HOME/gdb/gdbstartup
> +@item $HOME/.config/gdb/gdbstartup
> +@item $HOME/.gdbstartup
> +@end table

This should be @itemize, not @table.  Also, I wonder whether it is
wise to use the $FOO notation here, as that is a Posix shell-ism.  How
about something like this instead:

  @item
  The @file{gdb/gdbstartup} subdirectory of the directory pointed to
  by the environment variable @env{XDG_CONFIG_HOME}, if it is defined.

> +While on Apple hosts the locations searched are:
> +@table @file
> +@item $HOME/Library/Preferences/gdb/gdbstartup
> +@item $HOME/.gdbstartup
> +@end table

I wonder why we make special case for Apple system, but not for
MS-Windows (which also has its own conventions for user-private
settings directories).

> +@anchor{Local directory startup file}
> +@subsubsection Local directory startup file

Instead of @anchor, how about using @node (here and elsewhere)?

> +@value{GDBN} will check the current directory for a file called
> +@file{./.gdbstartup}.

I think the "./" part is redundant here, you already say that the file
is looked up in the current directory.