From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13803 invoked by alias); 30 Mar 2012 07:20:25 -0000 Received: (qmail 13795 invoked by uid 22791); 30 Mar 2012 07:20:23 -0000 X-SWARE-Spam-Status: No, hits=-1.5 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,RCVD_IN_NIX_SPAM,SPF_SOFTFAIL,TW_BJ X-Spam-Check-By: sourceware.org Received: from mtaout22.012.net.il (HELO mtaout22.012.net.il) (80.179.55.172) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 30 Mar 2012 07:20:09 +0000 Received: from conversion-daemon.a-mtaout22.012.net.il by a-mtaout22.012.net.il (HyperSendmail v2007.08) id <0M1O00100RX0W600@a-mtaout22.012.net.il> for gdb-patches@sourceware.org; Fri, 30 Mar 2012 10:19:03 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.127.102.72]) by a-mtaout22.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0M1O001XMSBQWO10@a-mtaout22.012.net.il>; Fri, 30 Mar 2012 10:19:03 +0300 (IDT) Date: Fri, 30 Mar 2012 07:20:00 -0000 From: Eli Zaretskii Subject: Re: [patch#2 2/6] set auto-load * main part In-reply-to: <20120329091121.GC25449@host2.jankratochvil.net> To: Jan Kratochvil Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83iphm1rq1.fsf@gnu.org> References: <20120329091121.GC25449@host2.jankratochvil.net> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2012-03/txt/msg01039.txt.bz2 > Date: Thu, 29 Mar 2012 11:11:21 +0200 > From: Jan Kratochvil > > 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).