From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10983 invoked by alias); 9 Jun 2006 19:43:08 -0000 Received: (qmail 10958 invoked by uid 22791); 9 Jun 2006 19:43:06 -0000 X-Spam-Check-By: sourceware.org Received: from nitzan.inter.net.il (HELO nitzan.inter.net.il) (192.114.186.20) by sourceware.org (qpsmtpd/0.31) with ESMTP; Fri, 09 Jun 2006 19:42:59 +0000 Received: from HOME-C4E4A596F7 (IGLD-80-230-209-89.inter.net.il [80.230.209.89]) by nitzan.inter.net.il (MOS 3.7.3-GA) with ESMTP id DRE31341 (AUTH halo1); Fri, 9 Jun 2006 22:42:55 +0300 (IDT) Date: Fri, 09 Jun 2006 19:43:00 -0000 Message-Id: From: Eli Zaretskii To: Sandra Loosemore CC: gdb-patches@sourceware.org In-reply-to: <4465ED4D.4020505@codesourcery.com> (message from Sandra Loosemore on Sat, 13 May 2006 10:29:33 -0400) Subject: Re: PATCH: copy-edit File-I/O section of manual Reply-to: Eli Zaretskii References: <4465ED4D.4020505@codesourcery.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2006-06/txt/msg00107.txt.bz2 > Date: Sat, 13 May 2006 10:29:33 -0400 > From: Sandra Loosemore > > When I was implementing the File-I/O protocol recently, I noticed a lot of > spelling and grammatical mistakes in that section of the manual. Here's a patch > to clean it up. > > 2006-05-13 Sandra Loosemore > * gdb.texinfo (File-I/O remote protocol extension): General > copy-editing to fix spelling, grammar, formatting issues. > Moved a few paragraphs around to more logical places. Thanks. I finally found time to review this. I have some minor comments and suggestions: > @node The Ctrl-C message > @subsection The Ctrl-C message > @cindex ctrl-c message, in file-i/o protocol > > ! If the @var{Ctrl-C flag} is set in the @value{GDBN} The @var markup is inappropriate here. I think we should just remove the markup, and maybe add an @pxref to the section where this flag is described (in case the reader needs to consult the context). > ! @table @asis > ! @item Synopsis: > ! @code{int open(const char *pathname, int flags);}@* > ! @code{int open(const char *pathname, int flags, mode_t mode);} > > ! @item Request: > ! @code{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}} I agree that the original's playing with @exdent was egregious, and that @table is better. But why not have the code samples in @smallexample? That's what it's for. Plus, you won't need the @* thingies then. > ! writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be > truncated to length 0. ^^^^^^^^ "zero length" is better, I think. > ! @var{mode} is the bitwise or of the following values: Perhaps "@code{OR}" is better than just "or". > ! In case @code{/bin/sh} could not be executed, 127 is returned. "/bin/sh" should have the @file markup, not @code. > + to the target. Basically, the only signal transmitted back is @code{EINTR} This text is confusingly inaccurate: signals aren't transmitted back, they cause an errno value to be transmitted back. Here, the SIGINT signal causes EINTR to be put into the return value. I suggest to rephrase this. > + @item show remote system-call-allowed > + @kindex show remote system-call-allowed > + Show the current setting of system calls for the remote File I/O > + protocol. I think this is better: Show whether the @code{system} calls are allowed in the File I/O protocol. > ! @item st_uid > ! No valid meaning for the target. Transmitted unchanged. > > ! @itemx st_gid > ! No valid meaning for the target. Transmitted unchanged. > > ! @item st_rdev > ! No valid meaning for the target. Transmitted unchanged. Isn't it better to group these together (with @itemx)? > ! @item st_atime, st_mtime, st_ctime These _definitely_ should use @itemx, instead of having them all on the same line. Do you have write access to the CVS repository? If so, please commit after you take care of these comments, but please make the ChangeLog entries more detailed (every node in which a change is made should be mentioned). Thanks again for taking time to fix these blunders.