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

[Corinna Vinschen <vinschen@redhat.com>]

On Mon, Nov 25, 2002 at 09:01:26PM +0300, Eli Zaretskii wrote:
> > From: Corinna Vinschen <vinschen@redhat.com>
> > > > +@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?

Aaandrew?

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

Ok, I will use my version.  My reasoning is that in an info reader it's
pretty hard to distinguish between the fixed parts like the leading `F'
and the variable parts as "retcode".

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

I like the idea and I'd like to use it.  However, there is one problem
I don't know how to solve correctly.  The "Synopsis", "Request" etc.
are unfortunately indented due to the usage of smallexample.  I tried
using @noindent but that has no influence in a smallexample.  Using
a @table @samp doesn't work either because it quotes the headlines
and
 
``Synopsis:''
    int open ...

doesn't look that nice.

How can I get the typical typeset for the "Synopsis" etc. paragraphs but
without the indenting of smallexample?

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

Ok, I added two more @cindex.

Corinna

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