RE: winsup/doc layout change?

["edward" <tailbert at yahoo dot com>]

Hi DJ.

-----Original Message-----
From: DJ Delorie [mailto:dj@delorie.com]
Sent: Thursday, December 07, 2000 12:30 PM
To: tailbert@yahoo.com
Cc: cygwin-developers@sources.redhat.com
Subject: Re: winsup/doc layout change?



> 	cygwin-api/
> 	cygwin-api-int/

edward> As of now, there doesn't seem to be any difference in the -int
edward> vs regular, because none of the sgml files have the int-* or
edward> add-* tags. So the way I have it at the moment, cygwin-api-int
edward> reuses the files in cygwin-api, and just outputs it into a
edward> a different directory. A bit overkill at the moment, but no harm
edward> done.

> 	cygwin-ug/
> 	cygwin-ug-net/

The *-net variants are derived from the base variant.  There shouldn't be
any need to keep the two separate, and jade puts the output files in
separate subdirectories anyway.

edward> Well, jade doesn't do that. The Makefile that's currently there
edward> does that. Again, most of the files are reused in the way I have
edward> it set up, from the cygwin-ug directory. There's only one sgml
edward> file in the -net directory I've setup (cygwin-ug-net.in.sgml).

> 	doctool/		<- source for doctool.exe

A whole directory for one source file?

edward> The only argument I have for keeping that in a separate directory
edward> is that it keeps the makefile very, very simple. However, it's
edward> trivial enough so it doesn't matter.

> 	sgml/			<- sgml sources
> 	texinfo/		<- texinfo sources

Sources for what?  If they're part of the api, ug, or faq docs then
they'd already be elsewhere.

edward> At the moment, I don't have any files in there. It's just a place
edward> holder for random files. Ideally, they don't exist.

> 	text/			<- random text files until we have real docs

Those could just stay in the doc/ directory.

> 	utils/		<- sgml files for the apps in utils

I'd rather keep those with the utils.  DJGPP history has shown that
keeping doc files adjacent to source files promotes doc writing.  The
whole point of doctool is to put the documentation *in* the sources,
to push this concept even further.

edward> Sounds good to me.

edward> So in summary, keep the simple files (doctool.* and the text files)
in
edward> the doc directory. Anything reasonably complicated gets its own
directory.

edward> Keep the util sgml files near the source.

edward> So far so good. Any comments about going to automake/autoconf in at
edward> at least the doc directory? Or starting to switch files from *.texi
and
edward> *.txt to *.sgml?

cheers,
edward


_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com