Date: Sat, 25 Nov 2000 09:26:17 +0200
From: "Eli Zaretskii" <eliz AT is DOT elta DOT co DOT il>
Sender: halo1 AT zahav DOT net DOT il
To: "Peter J. Farley III" <pjfarley AT banet DOT net>
Message-Id: <3405-Sat25Nov2000092616+0200-eliz@is.elta.co.il>
X-Mailer: Emacs 20.6 (via feedmail 8.3.emacs20_6 I) and Blat ver 1.8.6
CC: djgpp-workers AT delorie DOT com
In-reply-to: <5.0.1.4.0.20001125013858.00a5dcc0@pop5.banet.net>
	(pjfarley AT banet DOT net)
Subject: Re: How are include/*.h headers maintained?
References:  <5 DOT 0 DOT 1 DOT 4 DOT 0 DOT 20001125013858 DOT 00a5dcc0 AT pop5 DOT banet DOT net>
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
Precedence: bulk

> Date: Sat, 25 Nov 2000 01:52:54 -0500
> From: "Peter J. Farley III" <pjfarley AT banet DOT net>
> 
> Warning:  I have changed several wrap settings in my mail program, so 
> this message may or may not wrap well.

Can't really judge that, since you forgot to attach the code ;-)

> In devising a better test for the locking fcntl() code (coming soon, 
> with a corrected version of fcntl() too), I wanted to use the 
> dosexterr() function to tell me what error DOS last saw, but 
> dosexterr() only returns numeric values, not the string meaning of 
> those values.

Why do you need the string descriptions of DOS errors?  Isn't it
enough to pass the DOS error code to __doserr_to_errno and then use
strerror or perror?

> I developed a set of new DOS-only functions patterned 
> after strerror() to produce the strings describing the four values 
> returned by dosexterr().  To integrate it into the libc source tree 
> properly, I believe I need to add these four functions to the 
> include/dos.h header, where dosexterr() is defined.  I would propose 
> putting these new functions in the libc/dos/compat directory where 
> dosexterr() resides.

I think it's fine to add such functions in these places.

> Is the correct way to change include/dos.h to directly modify it, or is 
> there an automated process that maintains it from some other source?

dos.h is an original file, not a derived file.  You alter it directly
and then send the diffs, like you do with library source files.

> I also realize that I must write a *.txh file to document the new 
> functions

Yes.  Also, please add a short paragraph to src/docs/kb/wc204.txi.
If you wish, you could add the descriptions of the new functions to
the existing .txh file in the directory where you add the functions.
Having one .txh file per function is not a mandatory requirement.

> but it looks to me like those are just for documentation, 
> not for building *.h files.

??? *.txh files are used to build libc.info, so you need to write up
the docs, but what does that have to do with building .h files?  The
only connection is that if the .h file defines some symbols or macros
that users should know about, they, too, should be described in the
.txh file.