Mailing-List: contact cygwin-developers-help AT sourceware DOT cygnus DOT com; run by ezmlm
List-Subscribe: <mailto:cygwin-developers-subscribe AT sources DOT redhat DOT com>
List-Archive: <http://sources.redhat.com/ml/cygwin-developers/>
List-Post: <mailto:cygwin-developers AT sources DOT redhat DOT com>
List-Help: <mailto:cygwin-developers-help AT sources DOT redhat DOT com>, <http://sources.redhat.com/ml/#faqs>
Sender: cygwin-developers-owner AT sources DOT redhat DOT com
Delivered-To: mailing list cygwin-developers AT sources DOT redhat DOT com
X-Apparently-From: <tailbert AT yahoo DOT com>
From: "edward" <tailbert AT yahoo DOT com>
To: "DJ Delorie" <dj AT delorie DOT com>
Cc: "Cygwin Developers List" <cygwin-developers AT sources DOT redhat DOT com>
Subject: RE: winsup/doc layout change?
Date: Thu, 7 Dec 2000 13:11:43 -0500
Message-ID: <FMEOJCMLNIMPBKAPFPIHGEFKCFAA.tailbert@yahoo.com>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3 (Normal)
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2910.0)
In-Reply-To: <200012071730.MAA04970@envy.delorie.com>
X-Mimeole: Produced By Microsoft MimeOLE V5.50.4133.2400
Importance: Normal

Hi DJ.

-----Original Message-----
From: DJ Delorie [mailto:dj AT delorie DOT com]
Sent: Thursday, December 07, 2000 12:30 PM
To: tailbert AT yahoo DOT com
Cc: cygwin-developers AT sources DOT redhat DOT 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