From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 12877 invoked by alias); 25 Nov 2002 19:01:36 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 12841 invoked from network); 25 Nov 2002 19:01:34 -0000 Received: from unknown (HELO freya.inter.net.il) (192.114.186.14) by sources.redhat.com with SMTP; 25 Nov 2002 19:01:34 -0000 Received: from zaretsky (adsl-ayalon-pc-129-185.inter.net.il [213.8.129.185]) by freya.inter.net.il (Mirapoint Messaging Server MOS 3.2.1-GA) with ESMTP id BZF71737; Mon, 25 Nov 2002 21:01:32 +0200 (IST) Date: Mon, 25 Nov 2002 11:01:00 -0000 From: "Eli Zaretskii" To: gdb-patches@sources.redhat.com Message-Id: <2110-Mon25Nov2002210126+0200-eliz@is.elta.co.il> In-reply-to: <20021125115158.C27250@cygbert.vinschen.de> (message from Corinna Vinschen on Mon, 25 Nov 2002 11:51:58 +0100) Subject: Re: [RFA]: File-I/O patch, Documentation Reply-to: Eli Zaretskii References: <20021121100443.U24928@cygbert.vinschen.de> <7458-Sat23Nov2002130204+0200-eliz@is.elta.co.il> <20021125115158.C27250@cygbert.vinschen.de> X-SW-Source: 2002-11/txt/msg00601.txt.bz2 > Date: Mon, 25 Nov 2002 11:51:58 +0100 > From: Corinna Vinschen > > > > +* 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.