From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 24109 invoked by alias); 3 Apr 2009 15:06:38 -0000 Received: (qmail 23980 invoked by uid 22791); 3 Apr 2009 15:06:36 -0000 X-SWARE-Spam-Status: No, hits=0.6 required=5.0 tests=AWL,BAYES_50,J_CHICKENPOX_37,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout3.012.net.il (HELO mtaout3.012.net.il) (84.95.2.7) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 03 Apr 2009 15:06:29 +0000 Received: from conversion-daemon.i_mtaout3.012.net.il by i_mtaout3.012.net.il (HyperSendmail v2004.12) id <0KHJ00D005TDP900@i_mtaout3.012.net.il> for gdb-patches@sourceware.org; Fri, 03 Apr 2009 18:06:26 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.127.171.54]) by i_mtaout3.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0KHJ00KS45YMK3L0@i_mtaout3.012.net.il>; Fri, 03 Apr 2009 18:06:26 +0300 (IDT) Date: Fri, 03 Apr 2009 15:06:00 -0000 From: Eli Zaretskii Subject: Re: Python pretty-printing [2/6] In-reply-to: To: Tom Tromey Cc: bauerman@br.ibm.com, gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: References: <1238711355.3236.51.camel@localhost.localdomain> 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: 2009-04/txt/msg00065.txt.bz2 > Cc: gdb-patches@sourceware.org > From: Tom Tromey > Date: Thu, 02 Apr 2009 18:47:16 -0600 > > 2009-04-01 Tom Tromey > Thiago Jung Bauermann > Phil Muldoon > > * gdb.texinfo (Python API): Update. > (Auto-loading): New node. > (Objfiles In Python): New node. Thanks. I have several comments about the docs part: > +@node Auto-loading > +@subsubsection Auto-loading Suggest a @cindex entry here, something like "auto-loading, Python". > +When a new object file (@pxref{Objfiles In Python}) is read (for Is the cross-reference to "Objfiles in Python" really useful here? Loading object files has nothing to do with Python; the section you refer to describes Python-specific features related to object files, but those features seem to have nothing to do with auto-loading. Did I miss something? If there no real relation between these two sections, I'd prefer to remove the xref. When I read a manual and it gives me a cross-reference, I always assume that the cross-reference is important, and go there to see what it says. If it says nothing appropriate, my time and attention are lost. > + @value{GDBN} will look for a file named by > +adding @samp{-gdb.py} to the object file's real name (the name formed > +after following all symlinks and resolving @code{.} and @code{..} > +components). I suggest to rephrase this as follows: @value{GDBN} will look for a file named @file{@var{objfile}-gdb.py}, where @var{objfile} is the object file's real name, formed by following all symlinks and resolving @file{.} and @file{..} components. This tells the reader what the file name is, instead of explaining how it is constructed. I think the result is more clear. Btw, the above description of what ``real name'' is seems inaccurate, because the code actually calls `gdb_realpath', so the result is actually an absolute file name, right? > +If this file does not exist, and if the parameter > +@code{debug-file-directory} is set, then @value{GDBN} will append the > +object file's real name to the value of this parameter, and try again. Again, I think it's better not to explain how the file's name is created, but give its form and tell what are the components. There's another instance of that below. Could you rephrase them all along the above lines? Also, what is debug-file-directory? If it is documented somewhere, a cross-reference here would be beneficial. > +Finally, if this file does not exist, then @value{GDBN} will look in > +subdirectory of @code{gdb_datadir} (whose value is available from > +@code{maint show gdb_datadir}). ^^^^^^^^^^^^^^^^^^^^^^ Please add a cross-reference to where you describe this command. > Specifically, @value{GDBN} will take > +the value of @code{gdb_datadir}, append @samp{python/auto-load}, and > +then append the object file's real name. Please use @file for files, not @samp. > +Also, if a separate debug file is used, Please add another cross-reference, to where we describe separate debug file. > @value{GDBN} will look for the > +@samp{-gdb.py} file both in the directory associated with the > +application and the directory associated with the separate debug file. Is this true for all 3 file names GDB tries, or only for some (the first one?)? Either way, I think we should tell that explicitly. > +When reading a @samp{-gdb.py} file, @value{GDBN} sets the ``current > +objfile''. This is available via the @code{gdb.current_objfile} > +function. This can be useful for registering objfile-specific > +pretty-printers. Now, _this_ is where the cross-reference to "Objfiles in Python" would be handy. Also, you use "@samp{-gdb.py} file" quite a lot, so I think we should invent a special term for it. How about "autoloaded Python file"? > +This feature is useful for supplying application-specific debugging > +commands and scripts. It can be disabled using @code{maint set python > +auto-load}. A cross-reference here, to where the command is documented would be good. Or maybe just document it here ('cause I don't think it's documented anywhere else in your patches). > +@cindex python objfiles There are no "python objfiles", right? I think it's better to use something like "objfiles, access from Python". > +@tindex gdb.Objfile > +@tindex Objfile We still don't have a @syncodeindex for @tindex, so if you want to use it, please add that directive. > +@value{GDBN} loads symbols for an inferior from various > +symbol-containing files. These include the primary executable file, > +any shared libraries used by the inferior, and any separate debug info > +files. @value{GDBN} calls these symbol-containing files > +@dfn{objfiles}. It would be good to have cross-reference here to where the related GDB features are described. > +@defivar Objfile pretty_printers > +The @code{pretty_printers} attribute is used to look up > +pretty-printers by type. This is a dictionary which maps regular > +expressions (strings) to pretty-printing objects. I think we want a cross-reference here to where pretty-printing is described.