Re: [RFA]: File-I/O patch, Documentation

[Corinna Vinschen <vinschen at redhat dot com>]

On Sat, Nov 23, 2002 at 01:02:05PM +0300, Eli Zaretskii wrote:
> Sorry for the delay; this is a signifcant patch, and I'm hard pressed
> for free time lately.

No worries.  Thanks for reviewing this mess ;-)

I applied most of your hints and suggestions.  However, a few comments
are left, which I'd like to clarify:

> > +* The @code{F} request packet::
> > +* The @code{F} reply packet::

I changed that and the corresponding @node-s to

  * The `F' request packet::
  * The `F' reply packet::

Is that ok?

> > +* The isatty(3) call::
> > +* The system(3) call::

Here I just dropped the "(3)" part.

> > +@smallexample
> > +(gdb) continue
>    ^^^^^
> This should be @value{GDBP}...

Should it?  That's the GDB prompt.  It's used plain text in other
examples in the text as well so I assumed that being correct here.

> > +@item @code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}
> 
> This is okay, but you don't need to repeat @code all that much, just
> include everything in a @code to begin with.  I think the following
> will produce the same effect as what you did:
> 
>  @item @code{F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}}
> 

No, the effect is different:

   `F'RETCODE`,'ERRNO`,'CTRL-C FLAG`;'CALL SPECIFIC ATTACHMENT

Your version:

   `FRETCODE,ERRNO,CTRL-C FLAG;CALL SPECIFIC ATTACHMENT'

> > +These two states can be distinguished by the target by the value of the
> > +returned errno.  If it's the protocol representation of EINTR, the system
> 
> "errno" should be in @code, and so should be "EINTR" and any other
> possible values of `errno'.

I did the same with SIGINT.

What about all the constants used in the descriptions of the calls?
Should I rewrite all

  Request:      Fopen,pathptr/len,flags,mode

    `flags' is the bitwise or of the following values:

    O_CREAT     If the file does not exist it will be created.  The host
		rules apply as far as file ownership and time stamps
		are concerned.
    [...]
    Errors:

    EEXIST      pathname already exists and O_CREAT and O_EXCL were used.

to

  Request:      Fopen,pathptr/len,flags,mode

    `flags' is the bitwise or of the following values:

    @code{O_CREAT}     If the file does not exist it will be created.  The host
                rules apply as far as file ownership and time stamps
                are concerned.
    [...]
    Errors:

    @code{EEXIST}      pathname already exists and O_CREAT and O_EXCL were used.

?


> > +All values are given in hexadecimal representation.
> > +
> > +@smallexample
> > +  O_RDONLY        0
> > +  O_WRONLY        1
> > +  O_RDWR          2
> > +  O_APPEND        8
> > +  O_CREAT       200
> > +  O_TRUNC       400
> > +  O_EXCL        800
> > +@end smallexample
> > +
> > +@node mode_t values
> > +@unnumberedsubsubsec mode_t values
> > +
> > +All values are given in octal representation.
> 
> Is it really necessary to use hexadecimal representation for the
> former and octal representation for the latter?  Can we use the same
> representation for both, to avoid confusion?

The used representation is the one used in most header files.  Open modes
are most easy to read in hex, permission bits in octal.  That's the reasoning.

What about prepending the hex numbers with a leading '0x', the octals
with a leading '0'?

Corinna
> Finally, please add @cindex entries to allow for efficient searches
> of relevant issues.  As a minimum, please consider adding a @cindex
> for section/subsection whose name is the same as the section name,

Section name?  Not node name?  What about

  @node The `F' request packet
  @subsection The @code{F} request packet

Especially the Uppercase F?  Wouldn't

  @cindex the file-i/o request package

be the way to go?

Again, thanks for reviewing,
Corinna

-- 
Corinna Vinschen
Cygwin Developer
Red Hat, Inc.
mailto:vinschen@redhat.com