Mon Mar 31 19:51:40 CST 2003
Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

cygwin-doc
------------------------------------------
History:

2003-02-24 Joshua Daniel Franklin
	-version 1.3-7

	Thanks to

	(Igor Pechtchanski <pechtcha at cs dot nyu dot edu>)
	* add how to find the version number to FAQ
	<http://www.cygwin.com/ml/cygwin/2004-02/msg00950.html>
	
	("Alex Vinokur" <alexvn at connect dot to>)
	* correct clock_t documentation (newlib)
	<http://cygwin.com/ml/cygwin/2003-10/msg00849.html>
	
	("Hannu E K Nevalainen" <garbage_collector at telia dot com>)
	(Larry Hall <cygwin-lh at cygwin dot com>)
	* update intro man pages with /usr/share/
	<http://cygwin.com/ml/cygwin/2003-11/msg01034.html>
	<http://cygwin.com/ml/cygwin/2003-11/msg01044.html>
	
	("Dave Korn" <dk at artimi dot com>)
	* default values of CYGWIN=(no)ntsec (no)export error_start
	<http://www.cygwin.com/ml/cygwin/2004-01/msg00111.html>
	
	("Gary L. Feldman" <gaf_ml_01 at comcast dot net>)
	* add reminder to not unselect any Base category packages
	<http://cygwin.com/ml/cygwin/2003-08/msg00668.html>
	
	("Hannu E K Nevalainen" <garbage_collector at telia dot com>)
	* how-programming.texinfo: Add some words about -mno-cygwin,
	the difference with regard to preprocessor symbols and how to
	investigate it further.
	<http://www.cygwin.com/ml/cygwin/2003-10/msg01052.html>
	
	(linda w <cygwin at tlinx dot org>)
	* add /proc discussion to User's Guide
	<http://cygwin.com/ml/cygwin/2003-12/msg00716.html>
	
	("Roy Clemmons" <roy_clemmons at hotmail dot com>)
	* add discussion of cyg prefix to dll section
	<http://cygwin.com/ml/cygwin/2003-12/msg00839.html>


2003-09-04 Joshua Daniel Franklin
	-version 1.3-6

	-(Joshua Daniel Franklin)
	Move docs to /usr/share/* to conform to FHS

2003-08-27 Joshua Daniel Franklin
	-version 1.3-5

	-(Joshua Daniel Franklin)
	Add section "Using Cygwin Effectively with Windows"

2003-05-08 Joshua Daniel Franklin
	-version 1.3-4

	-(Joshua Daniel Franklin)
	Add one-HTML-file and PDF versions of the User's Guide
	
	-(Pierre Humblet) 
	* utils.sgml: Update mkpasswd and mkgroup documentation
	<http://cygwin.com/ml/cygwin-patches/2003-q2/msg00017.html>

	-(BB)
	* gcc.sgml: Add hellogui.c sample program
	<http://cygwin.com/ml/cygwin/2003-04/msg00692.html>

	-(Joshua Daniel Franklin)
	Add .SH NAME section in man pages.
	Thanks to Andy Lindsay <andy_cyg at ananam dot com>
	<http://cygwin.com/ml/cygwin/2003-04/msg01224.html>

2003-03-31 Joshua Daniel Franklin
	-version 1.3-3

	-(Joshua Daniel Franklin) 
	* setup-net.sgml: Add documentation for setup.exe
	Thanks to Rob Collins, Christopher Faylor, Pierre Humblet, Elfyn 
	McBratney, Hannu E K Nevalainen, Igor Pechtchanski, and Randall Schulz
	<http://www.cygwin.com/ml/cygwin/2003-03/msg01569.html>

	-Generate info files with docbook2X on Debian (see cygwin-info/README)

	-(Christopher Faylor) Fix typo in 'mount' documentation
	Thanks to Dwight Wilcox for noticing this.
	<http://cygwin.com/ml/cygwin/2003-03/msg00831.html>

	-(Joshua Daniel Franklin) 
	* setup-net.sgml: Add "setup-maxmem" section 
	* setup2.sgml: New section "setup-maxmem" to document heap_chunk_in_mb
	<http://cygwin.com/ml/cygwin-patches/2003-q1/msg00168.html>

	-(Pierre A. Humblet) Document '-c' option to mkgroup and mkpasswd
	<http://cygwin.com/ml/cygwin-patches/2003-q1/msg00310.html

	-(Joshua Daniel Franklin) 
        * cygwinenv.sgml: Add section for "CYGWIN codepage:[ansi|oem]"
        * dll.sgml: Add pointer to GCC website for more information
        * utils.sgml: Update regtool for -K,--key-separator option
	<http://cygwin.com/ml/cygwin-patches/2003-q1/msg00125.html>

2003-01-20 Joshua Daniel Franklin
	-version 1.3-2
	-fixed postinstall script bug (refered to version 1.2 instead of 1.3)
2003-01-13 Joshua Daniel Franklin
	-version 1.3-1
	-updated from latest cygwin CVS
	-easier build configuration
2002-10-17 Joshua Daniel Franklin
	-version 1.2-1
	-added texinfo versions of the User's Guide and API Reference
	-began using bzip2 compression on installed files
2002-08-04 Joshua Daniel Franklin
	-version 1.1-2
	-fixed typos in install scripts 
2002-07-31 Joshua Daniel Franklin
	-version 1.1-1
	-first inclusion of newlib-man and cygwin-users-guide
2002-04-13 Joshua Daniel Franklin
	-version 1.0-1
	-first release, cygwin-man only

-------------------------------------------

The cygwin-doc package has 4 separate and mutually exclusive parts:
cygwin-info, cygwin-man, cygwin-users-guide, and newlib-man. 
Each has a separate directory. They build separately. With the exception
of cygwin-users-guide (for reasons described below), everything you
need to build custom versions is contained in this package or in the
build requirements listed below. See the individual README files for
more information.

-------------------------------------------
Wed Oct 16 22:15:42  2002 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

(cygwin-info)
BUILD REQUIREMENTS:

ash
cygwin
gzip
make
texinfo

BUILD INSTRUCTIONS:

Type 'make' or 'make all' to build.  To install, 'make install'.

The cygwin.texi file was written by hand to provide an entry point.
The other texi files were produced with docbook2X from the official
Cygwin SGML DocBook found in CVS. I have not been able to get a 
working docbook2X installation on Cygwin, so currently I convert
the files on a machine running Debian GNU/Linux 3.0. If you do not
need to create info files from the latest CVS, the texi files found
in this directory will work fine. Otherwise, read below.

INSTALLING docbook2X ON DEBIAN GNU/LINUX 3.0 AND CONVERTING CYGWIN SGML

1. Install the following packages (available via apt-get):

libwww-perl
libxml-parser-perl
libxml-writer-perl
libxml-catalog-perl
libxml-perl
libsgmls-perl
libxml-dom-perl
libxml-libxslt-perl
libxslt1-dev
docbook-xml

2. Download the latest docbook2X package from 
<http://docbook2x.sourceforge.net/> or download version 0.70 (which I use) from
<http://ns1.iocc.com/~joshua/cygwin/docbook/non-cygwin/docbook2X-0.7.0.tar.gz>
This is a source distribution (no binaries are available) so you need to
have a build environment installed (gcc, etc.). Unpack the docbook2X tarball
and run './configure' to find dependencies. Unfortunately due (I believe) 
to changes in the perl XML::Parser module since docbook2X was written the 
docbook2X documentation no longer builds cleanly, so in the top-level Makefile 
I replaced the SUBDIRS line: 

#SUBDIRS = . charmaps dtd patches xslt perl libxslt utf8trans doc testdocs
SUBDIRS = . charmaps dtd patches xslt perl libxslt utf8trans testdocs

After this change 'make' and 'make install' work correctly (other than the
resulting lack of documentation).

3. Create a directory in which to convert the files.  You need to copy the
latest CVS sgml to this directory, convert, and copy the resulting texi files
back. I use a samba-mounted network share in order to make moving files easier. 
I do this using the commands in the 'upgrade' section of the Makefile in this
directory and the following Makefile in the samba-mounted /h/convert directory
on the Debian GNU/Linux 3.0 machine (if you cut-and-paste, be sure to replace
the TABs properly):

## Begin /h/convert Makefile 
all:    api ug

api:
	perl -i -p -e 's/&copy;/(c)/' cygwin-api.sgml
	sgml2xml -x lower cygwin-api.sgml > cygwin-api.xml
	docbook2texixml cygwin-api.xml >cygwin-api.txml
	db2x_texixml cygwin-api.txml
#	makeinfo cygwin-api.texi

ug:
	perl -i -p -e 's/&copy;/(c)/' cygwin-ug-net.sgml
	sgml2xml -x lower cygwin-ug-net.sgml > cygwin-ug.xml
	docbook2texixml cygwin-ug.xml >cygwin-ug.txml
	db2x_texixml cygwin-ug.txml
#	makeinfo cygwin-ug.texi

clean:
	rm -f core *xml

## End /h/convert Makefile

Note that the SGML DocBook -> texi translation lists many many warnings.
Wed Oct 16 21:41:22  2002 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

(cygwin-man)
BUILD REQUIREMENTS:

ash
cygwin
fileutils
gzip
make
perl 
textutils

BUILD INSTRUCTIONS:

Type 'make' or 'make all' to build the man pages. If you only want to
build one section, try 'make man1' or 'make man3'. To install, 
'make install'. That's all you really need to know.

If you have the cygwin CVS on your machine, you can edit the 
CYGWIN_SRC line in the Makefile and run 'make upgrade'. This will 
_replace_ the SGML files with ones from the your copy of the CVS.

The two intro pages (intro.1 and intro.3) were written by hand by me.
The rest of the cygwin man pages are autogenerated from the SGML files
found in CVS. I wrote perl scripts do this in my spare time over a few
evenings. They are not robust. They will not work for other SGML files.
(In fact, note that separate scripts are necessary for the API man pages
and the utils.) Changes to the SGML files will probably break the scripts.

Wed Oct 16 21:39:48  2002 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

(newlib-man)
BUILD REQUIREMENTS:

ash
bzip2
cygwin
fileutils
make
perl 

BUILD INSTRUCTIONS:

Type 'make' or 'make all' to build the man pages. All the pages are in
section 3. To install, 'make install'.

If you have updated versions of the lib?.info* files on your machine, 
such as from the newlib CVS, you can edit the appropriate lines in 
getnewlibinfo.pl and run 'make upgrade'. This will _replace_ the info files
with ones from your copy of the CVS.

I wrote the perl scripts do this in my spare time over a few
evenings. They are not robust. They will not work for other info files.
They will probably kill your pets and cause earthquakes. You are warned.
Wed Feb 25 16:56:33 PST 2004
Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

(cygwin-users-guide)
The packages required to build the Cygwin user's guide are unfortunately
not yet part of the Cygwin distribution. For a time, there were testing
packages available for DocBook on Cygwin, but they are no longer available.

If you have a working DocBook installation, you can use the files in
this directory to create your own formats. Note that the originals are
in CVS, however, so if you want to improve the Cygwin documentation I
recommend downloading the Cygwin CVS and following the instructions
below to get a working documentation build system.

To create the one-HTML-file, try this:

jade -d cygwin.dsl -t sgml -i html -V nochunks cygwin-ug-net.sgml >cygwin-ug-net-nochunks.html

For PDF creation, you can use pdfjadetex on an machine with it. You need
to run it several times to get the Table of Contents correct:

jade -t tex -d cygwin.dsl cygwin-ug-net.sgml
pdfjadetex cygwin-ug-net.tex 
pdfjadetex cygwin-ug-net.tex 
pdfjadetex cygwin-ug-net.tex 

---Getting a working documentation build system---

To build the documentation from Cygwin CVS, you need to have all the
normal build tools (gcc,make,etc) and a couple you might not--
libxml2 and rpm. Before the letters "R" "P" "M" scare people, let
me digress. Up until now the Cygwin documentation has been built
either on Linux or with custom Cygwin packages. (Note to you and
to future list readers, this hopefully will change very soon--maybe 
as soon as we get Nicholas' openjade patches and can get it and the
various DTD and stylesheets in the distribution.)

The problem with installing custom packages is that you can get them
confused with real ones and create a dependency mess as you attempt
to move from custom to official packages. Right now on Cygwin all we
have is custom packages for SGML docbook (which is what the Users' Guide 
and API Reference are written in).  Just to be clear here, RPM is not
becoming an official Cygwin installation method, and most RPMs you find
on the Web will *NOT* work in Cygwin.

That said, I've put up my hacked-together RPMs at:

<http://ns1.iocc.com/~joshua/cygwin/RPMS/>

Note that RPM has many features such as dependency management that I've
deliberately ripped out of these, so don't get too excited. 
Note also that there is an openjade-1.3.1-1.tar.bz2 there. This was 
packaged about two years ago before there was trouble building openjade, 
so it's quite old, but works for our purposes:

--------------------------snip---------------------------------------
# 1. Get the files
cd /tmp 
wget -m -np -nH --cut-dirs=3 http://ns1.iocc.com/~joshua/cygwin/RPMS/

# 2. Never do this again--it's a very bad idea
cd /
tar jxvf /tmp/openjade-1.3-1.1.tar.bz2

# 3. Install the hacked-together "dependencies" rpms
rpm -Uhv /tmp/*rpm

# 4. Install the actual docbook packages
rpm -Uhv /tmp/docbook/*rpm

# 5. Remove everything you've installed with rpm with one easy step
#    onces we've got Cygwin packages together--no mess!
rpm -e $(rpm -qa)
--------------------------snip---------------------------------------

Once you've got that, all you should need to do it type "make" in the
winsup/doc folder of your Cygwin build tree. There are a couple of other
things you might want to do:

-comment out (with -- before and after) the "DTDDECL" statement in 
/usr/share/sgml/docbook/dsssl-stylesheets/catalog
This version of jade just hates the DTDDECL and complains loudly. 

-Change /usr/bin/db2html's shebang to "#!/bin/bash" since it uses 
bash-specific artithmetic syntax.
