Message-Id:	<200006091855.VAA20958@alpha.netvision.net.il>
Date:	Fri, 09 Jun 2000 21:54:32 +0200
X-Mailer:	Emacs 20.6 (via feedmail 8.1.emacs20_6 I) and Blat ver 1.8.5b
From:	"Eli Zaretskii" <eliz AT is DOT elta DOT co DOT il>
To:	Martin Str|mberg <ams AT ludd DOT luth DOT se>
CC:	djgpp-workers AT delorie DOT com
In-reply-to:	<200006091807.UAA13129@father.ludd.luth.se> (message from Martin
	Str|mberg on Fri, 9 Jun 2000 20:07:05 +0200 (MET DST))
Subject:	Re: LONG: fat32 diff in cvs
References:	<200006091807 DOT UAA13129 AT father DOT ludd DOT luth DOT se>
Reply-To:	djgpp-workers AT delorie DOT com
Errors-To:	nobody AT delorie DOT com
X-Mailing-List:	djgpp-workers AT delorie DOT com
X-Unsubscribes-To:	listserv AT delorie DOT com

> From: Martin Str|mberg <ams AT ludd DOT luth DOT se>
> Date: Fri, 9 Jun 2000 20:07:05 +0200 (MET DST)
>
> > Well, the above is the explanation that I think will help users to
> > understand what function to use in which case.  That's what I thought
> > was missing from the current docs.
> 
> Hmm. I'm not sure how or where I should put that in.

One way of doing this would be to put that on one of the functions'
descriptions, and then xref from the others.

> As a matter of fact, thinking about it, I think it would be better to
> improve each function's description so the user would know if a
> certain function is what he wants. Wouldn't it?

That is certainly another possibility.

> Meanwhile you can look at the diff of wc204.txi. I'm open to
> suggestions to make it better.

I have some ;-)

> ! @findex _creat AT r{, FAT32}

I suggest ", and FAT32" or ", on FAT32 volumes".  Try to imagine how
the entry will look like in the index itself, that usually helps to
find the best wording.

> ! @findex _creatnew AT r{, FAT32}
> ! @findex _open AT r{, FAT32}
> ! Set extended size flag in interrupt calls to be able to create files
> ! with size up to 2^32-1.

And here you have the opposite problem: the index entries are stripped
and don't appear in the Info file, so the user is left with a sentence
that doesn't really explain to what it refers:

  Set extended size flag in interrupt calls to be able to create files
  with size up to 2^32-1.

I suggest this instead:

  The functions @code{_creat}, @code{_creatnew}, and @code{_open} now
  set extended size flag in DOS calls to be able to create files with
  size up to 2^32-1, supported on FAT32 volumes.

The other entries have the same problems: if you take away the index
entries, they become unclear.

- Raw text -