This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [patch#2 2/6] set auto-load * main part


> Date: Thu, 29 Mar 2012 11:11:21 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> 
> this is the main part.

Thanks.

> --- a/gdb/NEWS
> +++ b/gdb/NEWS

This part is OK.

> +  fprintf_filtered (file, _("Current directory .gdbinit script "
> +			    "auto-loading is %s.\n"),

I would suggest

  Auto-loading of .gdbinit script from current directory is %s.

And similar reordering of words for other options.

> +Auto-loading specific settings\n\

There should be a period at the end of the text.

> +Configure various auto-load-specific variables such as\n\
> +automatic loading of Python scripts"),

Same here.

> +Show auto-loading specific settings\n\
> +Show configuration of various auto-load-specific variables such as\n\
> +automatic loading of Python scripts"),

And here (2 instances).  There are more such omissions in other doc
strings.

> +    add_prefix_cmd ("auto-load", class_info, info_auto_load_cmd, _("\
> +Print current status of auto-loaded files\n\
> +Print whether various files like Python scripts or .gdbinit files have been\n\
> +found and/or loaded"),

"Print" or "display"? or maybe "show"?  The latter 2 is more accurate,
but if we generally use "print" elsewhere, I'm fine with that, for
consistency.

> +Enable or disable auto-loading canned sequences of commands scripts."), _("\
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"auto-loading of canned sequences", the "of" part is required.

> +@node Auto-loading
> +@section Automatically loading associated files

"@cindex auto-loading" would be good here.  In general, it is
frequently a good idea to have a @cindex entry at the beginning of
each node whose wording is the name of the node or the section.

> +
> +As @value{GDBN} reads some of the files automatically, without being explicitly
> +told so by the user, it may bring some unexpected @value{GDBN} behavior or even
> +security risks if some files come from untrusted sources.

That begs the question: if this is so bad, why do you give us this
risky feature?

So I would rephrase this as follows:

  @value{GDBN} sometimes reads files with commands and settings
  automatically, without being explicitly told so by the user.  We
  call this feature @dfn{auto-loading}.  While auto-loading is useful
  for automatically adapting @value{GDBN} to the needs of your
  project, it can sometimes produce unexpected results or introduce
  security risks (e.g., if the file comes from untrusted sources).

  For these reasons, @value{GDBN} includes commands and options to let
  you control when to auto-load files and which files should be
  auto-loaded.

> +Globally disable any auto-loading @samp{auto-load} sub-command file(s).

This sounds awkward.  How about

  Globally disable loading of all auto-loaded files.

> +Be aware system init file (@pxref{System-wide configuration})
           ^
"that" is missing at this spot.

> +and @ref{Home Directory Init File} still get read (as they come from generally

Please don't use HTML-style references, as they don't work well in
Info.  This is better:

  ... and init files from your home directory (@pxref{Home Directory
  Init File}) still get read ...

>                 You should use also the @ref{-nx} option to forbid
> +reading very every auto-loaded file.

I don't understand the "should" part.  Did you mean "could"?

Also, there's a typo ("very every").  I suggest "... to prevent
@value{GDBN} from reading any auto-loaded files" instead.

> +Show whether auto-loading of each specific @samp{auto-load} sub-command file(s)
> +is enabled or disabled.

I would drop the "sub-command" part, it only adds confusion, but no
real information.

> +@item info auto-load
> +Print whether each specific @samp{auto-load} sub-command file(s) have been
> +auto-loaded or not.                          ^^^^^^^^^^^

Same here.

> +
> +@smallexample
> +(gdb) info auto-load
> +gdb-scripts:  Loaded  Script                                                                 
> +Yes     /home/user/gdb/gdb-gdb.rc                         

This is a strange layout, and I'm quite sure it will look wrong in
Info (as the trailing whitespace won't do what you think).  Can you
show how this display is supposed to look like on the screen?

> +@multitable {@xref{dotdebug_gdb_scripts section}.} {See @ref{set auto-load python-scripts}}
> +@item @xref{objfile-gdb.py file}.
> +@tab See @ref{set auto-load python-scripts}.

Does this table with 2 cross-references on each line look good in the
Info manual?

> +@menu
> +* Current Directory Init File::  @samp{set/show/info auto-load local-gdbinit}
> +* libthread_db.so.1 file::       @samp{set/show/info auto-load libthread-db}
> +* objfile-gdb.rc file::          @samp{set/show/info auto-load gdb-script}
> +@xref{Python Auto-loading}.

Do the node names with periods work well in the stand-alone Info
reader?  I think the Texinfo manual discourages the use of periods in
node names, because the stand-alone reader cannot cope with them.  But
if it can, I'm fine with this.

> +@node Current Directory Init File
> +@subsection Automatically loading current directory init file

"init file in the current directory" is better, both in the node name
and in the section name.

> +@value{GDBN} reads and executes the canned sequences of commands from init file
> +(if any) in the current working directory,

I would prepend "By default," to this sentence, since you are about to
tell how to disable that.

> +@node libthread_db.so.1 file
> +@subsection Automatically loading thread debugging library
> +
> +This feature is currently present only on @sc{gnu}/Linux native hosts.
> +
> +@value{GDBN} reads and executes the canned sequences of commands from init file
> +(if any) in the current working directory,
> +see @ref{Current Directory Init File during Startup}.

The last sentence seems to be a copy/paste from another place...

> +
> +@table @code
> +@anchor{set auto-load libthread-db}
> +@kindex set auto-load libthread-db
> +@item set auto-load libthread-db [yes|no]
> +Enable or disable the auto-loading of canned sequences of commands
> +(@pxref{Sequences}) found in init file in the current directory.
> +
> +@anchor{show auto-load libthread-db}
> +@kindex show auto-load libthread-db
> +@item show auto-load libthread-db
> +Show whether auto-loading of canned sequences of commands from init file in the
> +current directory is enabled or disabled.
> +
> +@anchor{info auto-load libthread-db}
> +@kindex info auto-load libthread-db
> +@item info auto-load libthread-db
> +Print whether canned sequences of commands from init file in the
> +current directory have been auto-loaded.
> +@end table

And likewise the text in this @table (although the @item text was
edited correctly).


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]