Re: PATCH: copy-edit File-I/O section of manual

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Sat, 13 May 2006 10:29:33 -0400
> From: Sandra Loosemore <sandra@codesourcery.com>
> 
> 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  <sandra@codesourcery.com>
> 	* 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.