Mail Archives: djgpp-workers/2000/05/30/06:44:07
On Tue, 30 May 2000, Martin Stromberg wrote:
> > One of your earlier versions included an FSEXT hook for _llseek, while
> > this version does not. Isn't it a good idea to have such a hook?
>
> Yes. (I wonder where that went?)
One of your previous submissions indicates that you #ifdef'ed that part
away at some point, and then deleted it (I could still see it in a diff
of llseek.c~ that inadvertently crept into your patches sent a few months
ago ;-).
> > > + @ignore end
> >
> > The last line should say "@end ignore". (Did you build the library
> > with these changes? If not, I think you should: it prevents you from
> > breaking the library build due to some minor syntax problems, such as
> > this one.)
>
> Hmmm. Strange. I surely built it like that. Perhaps the build process
> doesn't stop on errors?
It depends on makeinfo: errors that cause it to return a non-zero exit
status surely stop the build in its tracks. But if makeinfo merely emits
a warning, you have to be there to see it, or else you won't know.
> Or perhaps it just @ignored away some
> functions until a correct @end ignore showed up?
Yes, I think this is what happened (looking at the sources of makeinfo).
Hmm... probably should add some diagnostics to makeinfo to avoid such
silent failures.
> > > + int _get_fs_type( const int drive
> > > + , char *const result_str
> > > + );
> > > + @end example
> >
> > Why this strange format?
>
> It's very good patch-wise.
But it looks ugly (IMHO), both in the Info file and in the printed
version, since an @example block isn't filled.
> > Btw, it looks like there's a whole slew of functions that can be used
> > to find out the filesystem properties, in particular whether it is or
> > isn't FAT32. How about adding cross-references between them, and some
> > short discussion of their relative merits? Some user might become
> > really confused when faced with a decision which function(s) to use.
>
> Ok. Where should this short discussion be put?
I suggest to put it with one of the functions, and make a cross-reference
from others to that function.
> Regarding detecting FAT32, I don't follow you. For FAT32 you should
> use _is_fat32().
_get_fat_size and _get_fs_type seem to have similar functionality, no?
They surely return enough info to be able to distinguish FAT32 disks from
the others, at least as far as I follow the docs.
> Ooops! I've only used one space everywhere while writing the texinfo
> files.
Yes, I know; it's typical for European culture. I usually don't comment
on that, and instead correct it silently. However, since you are now an
official libc maintainer...
> Where are such _crucial_ things documented?
In the Texinfo manual, of course.
You really should invest an evening or two reading it, and then look up
each feature (using the `i' command) when you use it. The Texinfo manual
is one of the best manuals I saw: complete, clearly written, and
extensively indexed. So you also get good examples of how to write
documentation, simply by looking at the manual, in addition to learning.
- Raw text -