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

["Eli Zaretskii" <eliz at is dot elta dot co dot il>]

> Date: Mon, 25 Nov 2002 11:51:58 +0100
> From: Corinna Vinschen <vinschen@redhat.com>
> 
> > > +* 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?

Yes.  To be absolutely sure, generate an Info manual from the Texinfo
sources, then fire up an Info reader of your choice, go to these menu
lines and press [Enter].  If this works, everything's okay.

> > > +* The isatty(3) call::
> > > +* The system(3) call::
> 
> Here I just dropped the "(3)" part.

Fine, thanks.

> > > +@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.

Well, gdbint.texinfo indeed didn't use @value{GDBN} and @value{GDBP}
until very recently, unlike gdb.texinfo.  I think the decision was to
use them in both manuals, but I might be mistaken.  Andrew?

> > > +@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'

Well, I think my result is more accurate ;-)  Those `' around F and
such are not really there in the packet, right?

But if you think your result is better, I won't insist.

> 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

No, you don't need to do that, since @smallexample already typesets
everything in the same typeface as @code.

Btw, theere's a disadvantage of using @smallexample here: the other
text, such as the verbal descriptions of the O_* flags and errno
values, is also typeset in fixed-size typewriter face, so the flag and
errno names don't stand out.  For that reason, I generally recommend
to use a @table instead of @smallexample, like this:

@node open
@unnumberedsubsubsec open

@smallexample
Synopsis:     int open(const char *pathname, int flags);
              int open(const char *pathname, int flags, mode_t mode);

Request:      Fopen,pathptr/len,flags,mode
@end smallexample

@noindent
where @code{flags} is the bitwise or of the following values:

@table @code
@item 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.

@item O_EXCL
When used with O_CREAT, if the file already exists it is
an error and open() fails.
...
@end table

This typesets the flag names in fixed font, but the rest of the text
is typeset in the usual roman typeface.

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

This is IMHO better than having '0' in both.

> > 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?

Section name is usually better, since its language is more natural
(node name is just a label, and is not generally meant for humans to
read), and since index entries do allow @-commands such as @code while
node names don't.

>  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?

Either will do, so in this case it's up to you.  Actually, I could
make an argument for having both ;-)

When writing @cindex entries, what I generally do is pretend to be a
person who is looking for some material described in this section, and
then ask myself: what phrase would I try to look for in the index?

However, if you do use the latter, please leave the "the" part out:
index entries should not have them, just the terms themselves.
(Otherwise, many entries will begin with "the".)

> Again, thanks for reviewing,

And thank _you_ for doing the actual work.