Update to switch FAQ from texinfo to DocBook.

12 files changed, 3987 insertions, 25 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 98e880b..274b9c5 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,17 @@
+2005-08-05  Joshua Daniel Franklin  <joshuadfranklin@yahoo.com>
+
+	* cygwin.dsl: Add default DOCTYPE and output filename.
+	* Makefile: Update to switch FAQ from texinfo to DocBook.
+	* faq.xml: New file.
+	* faq-api.xml: New file.
+	* faq-problems.xml: New file.
+	* faq-programming.xml: New file.
+	* faq-resources.xml: New file.
+	* faq-sections.xml: New file.
+	* faq-setup.xml: New file.
+	* faq-using.xml: New file.
+	* faq-what.xml: New file.
+
 2005-07-10  Joshua Daniel Franklin  <joshuadfranklin@yahoo.com>
 
 	* cygwinenv.sgml: Update tty section to mention rxvt and xterm.
diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in
index 45a0a40..5313ed9 100644
--- a/winsup/doc/Makefile.in
+++ b/winsup/doc/Makefile.in
@@ -30,24 +30,25 @@ TEXI2HTML:=texi2html
 include $(srcdir)/../Makefile.common
 
 TOCLEAN:=faq.txt ./*.html readme.txt doctool.o doctool.exe *.junk \
-	 cygwin-ug.sgml cygwin-ug \
+	 cygwin-ug.sgml cygwin-ug cygwin-ug-net.html.gz \
 	 cygwin-ug-net.sgml cygwin-ug-net cygwin-ug-net.html \
-	 cygwin-api.sgml cygwin-api cygwin-api-int.sgml cygwin-api-int
+	 cygwin-api.sgml cygwin-api cygwin-api-int.sgml cygwin-api-int \
+	 faq
 
 .SUFFIXES:
 
 all : \
 	cygwin-ug-net/cygwin-ug-net.html \
-	cygwin-ug-net.html \
+	cygwin-ug-net/cygwin-ug-net.html.gz \
 	cygwin-api/cygwin-api.html \
-	$(HTMLDOC)
+	faq/faq.html faq/faq-nochunks.html
 
 clean:
 	rm -Rf $(TOCLEAN)
 
 install:	all
 
-cygwin-ug-net.html : cygwin-ug-net.sgml doctool
+cygwin-ug-net/cygwin-ug-net.html.gz : cygwin-ug-net.sgml doctool
 	-xmlto html-nochunks -m $(srcdir)/cygwin.dsl $<
 	-cp cygwin-ug-net.html cygwin-ug-net/cygwin-ug-net-nochunks.html
 	-rm -f cygwin-ug-net/cygwin-ug-net-nochunks.html.gz
@@ -55,18 +56,22 @@ cygwin-ug-net.html : cygwin-ug-net.sgml doctool
 
 cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.sgml doctool
 	-xmlto html -o cygwin-ug-net/ -m $(srcdir)/cygwin.dsl $<
-	-mv cygwin-ug-net/index.html cygwin-ug-net/cygwin-ug-net.html
 
 cygwin-ug-net.sgml : cygwin-ug-net.in.sgml ./doctool Makefile
 	-./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
 
 cygwin-api/cygwin-api.html : cygwin-api.sgml
 	-xmlto html -o cygwin-api/ -m $(srcdir)/cygwin.dsl $<
-	-mv cygwin-api/index.html cygwin-api/cygwin-api.html
 
 cygwin-api.sgml : cygwin-api.in.sgml ./doctool Makefile
 	-./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
 
+faq/faq.html :
+	-xmlto html -o faq -m $(srcdir)/cygwin.dsl $(srcdir)/faq-sections.xml
+
+faq/faq-nochunks.html :
+	-xmlto html -o faq -m $(srcdir)/cygwin.dsl $(srcdir)/faq.xml
+
 ./doctool : doctool.c
 	gcc -g $< -o $@
 
@@ -95,24 +100,24 @@ readme.txt: $(srcdir)/readme.texinfo $(srcdir)/*.texinfo
 	-$(MAKEINFO) -I$(srcdir) --no-split --no-headers $< -o - |\
 	sed '/^Concept Index/,$$d' > $@
 
-faq0.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
-	-rm -f faq_toc.html; \
-	for i in $(srcdir)/*.texinfo ; do \
-		sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
-	    -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
-	$(TEXI2HTML) -monolithic ./faq.texinfo; \
-	rm -f *.texinfo; \
-	sed -e 's;"faq.html;"faq0.html;g' faq.html > faq0.html; \
-	rm -f faq.html; exit 0
-
-faq.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
-	-rm -f faq_toc.html; \
-	for i in $(srcdir)/*.texinfo ; do \
-		sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
-	    -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
-	$(TEXI2HTML) -split_chapter ./faq.texinfo; \
-	rm -f *.texinfo; \
-	[ -r faq_toc.html ] && mv faq_toc.html faq.html; exit 0
+#faq0.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
+#	-rm -f faq_toc.html; \
+#	for i in $(srcdir)/*.texinfo ; do \
+#		sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
+#	    -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
+#	$(TEXI2HTML) -monolithic ./faq.texinfo; \
+#	rm -f *.texinfo; \
+#	sed -e 's;"faq.html;"faq0.html;g' faq.html > faq0.html; \
+#	rm -f faq.html; exit 0
+#
+#faq.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
+#	-rm -f faq_toc.html; \
+#	for i in $(srcdir)/*.texinfo ; do \
+#		sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
+#	    -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
+#	$(TEXI2HTML) -split_chapter ./faq.texinfo; \
+#	rm -f *.texinfo; \
+#	[ -r faq_toc.html ] && mv faq_toc.html faq.html; exit 0
 
 TBFILES = cygwin-ug-net.dvi cygwin-ug-net.rtf cygwin-ug-net.ps \
 	  cygwin-ug-net.pdf cygwin-ug-net.sgml \
diff --git a/winsup/doc/cygwin.dsl b/winsup/doc/cygwin.dsl
index 8c16471..35156d7 100644
--- a/winsup/doc/cygwin.dsl
+++ b/winsup/doc/cygwin.dsl
@@ -4,8 +4,11 @@
                 version='1.0'>
 
 <!-- See /usr/share/docbook-xsl/params/ -->
+<xsl:param name="chunker.output.doctype-public" 
+  select="'-//W3C//DTD HTML 4.01 Transitional//EN'" />
 <xsl:param name="html.stylesheet" select="'docbook.css'"/>
 <xsl:param name="use.id.as.filename" select="1" />
+<xsl:param name="root.filename" select="@id" />
 
 <!-- TODO: make URLs and paths wrap with PDF output -->
 
diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml
new file mode 100644
index 0000000..1a9c6c5
--- /dev/null
+++ b/winsup/doc/faq-api.xml
@@ -0,0 +1,348 @@
+<!-- faq-api.xml --> 
+<qandaentry id="faq.api.everything">
+<question><para>How does everything work?</para></question>
+<answer>
+
+<para>There's a C library which provides a Unix-style API.  The
+applications are linked with it and voila - they run on Windows.
+</para>
+<para>The aim is to add all the goop necessary to make your apps run on
+Windows into the C library.  Then your apps should run on Unix and
+Windows with no changes at the source level.
+</para>
+<para>The C library is in a DLL, which makes basic applications quite small.
+And it allows relatively easy upgrades to the Win32/Unix translation
+layer, providing that DLL changes stay backward-compatible.
+</para>
+<para>For a good overview of Cygwin, you may want to read the paper on Cygwin
+published by the Usenix Association in conjunction with the 2d Usenix NT
+Symposium in August 1998.  It is available in HTML format on the project
+WWW site.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.snapshots">
+<question><para>Are development snapshots for the Cygwin library available?</para></question>
+<answer>
+
+<para>Yes.  They're made whenever anything interesting happens inside the
+Cygwin library (usually roughly on a nightly basis, depending on how much
+is going on).  They are only intended for those people who wish to
+contribute code to the project.  If you aren't going to be happy
+debugging problems in a buggy snapshot, avoid these and wait for a real
+release.  The snapshots are available from
+<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.cr-lf">
+<question><para>How is the DOS/Unix CR/LF thing handled?</para></question>
+<answer>
+
+<para>Let's start with some background.
+</para>
+<para>In UNIX, a file is a file and what the file contains is whatever the
+program/programmer/user told it to put into it.  In Windows, a file is
+also a file and what the file contains depends not only on the
+program/programmer/user but also the file processing mode.
+</para>
+<para>When processing in text mode, certain values of data are treated
+specially.  A \n (new line) written to the file will prepend a \r
+(carriage return) so that if you `printf("Hello\n") you in fact get
+"Hello\r\n".  Upon reading this combination, the \r is removed and the
+number of bytes returned by the read is 1 less than was actually read.
+This tends to confuse programs dependent on ftell() and fseek().  A
+Ctrl-Z encountered while reading a file sets the End Of File flags even
+though it truly isn't the end of file.
+</para>
+<para>One of Cygwin's goals is to make it possible to easily mix Cygwin-ported
+Unix programs with generic Windows programs.  As a result, Cygwin opens
+files in text mode as is normal under Windows.  In the accompanying
+tools, tools that deal with binaries (e.g. objdump) operate in Unix
+binary mode and tools that deal with text files (e.g. bash) operate in
+text mode.
+</para>
+<para>Some people push the notion of globally setting the default processing
+mode to binary via mount point options or by setting the CYGWIN
+environment variable.  But that creates a different problem.  In
+binary mode, the program receives all of the data in the file, including
+a \r.  Since the programs will no longer deal with these properly for
+you, you would have to remove the \r from the relevant text files,
+especially scripts and startup resource files.  This is a porter "cop
+out", forcing the user to deal with the \r for the porter.
+</para>
+<para>It is rather easy for the porter to fix the source code by supplying the
+appropriate file processing mode switches to the open/fopen functions.
+Treat all text files as text and treat all binary files as binary.  To be
+specific, you can select binary mode by adding <literal>O_BINARY</literal> to
+the second argument of an <literal>open</literal> call, or
+<literal>"b"</literal> to second argument of an <literal>fopen</literal> call.
+You can also call <literal>setmode (fd, O_BINARY)</literal>.
+</para>
+<para>Note that because the open/fopen switches are defined by ANSI, they
+exist under most flavors of Unix; open/fopen will just ignore the switch
+since they have no meaning to UNIX.
+</para>
+<para>Explanation adapted from mailing list email by Earnie Boyd
+&lt;earnie_boyd (at) yahoo.com&gt;.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.threads">
+<question><para>Is the Cygwin library multi-thread-safe?</para></question>
+<answer>
+
+<para>Yes.
+</para>
+<para>There is also extensive support for 'POSIX threads', see the file
+<literal>cygwin.din</literal> for the list of POSIX thread functions provided.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.winnt">
+<question><para>Why is some functionality only supported in Windows NT?</para></question>
+<answer>
+
+<para>Windows 9x: n.
+32 bit extensions and a graphical shell for a 16 bit patch to an
+8 bit operating system originally coded for a 4 bit microprocessor,
+written by a 2 bit company that can't stand 1 bit of competition.
+</para>
+<para>But seriously, Windows 9x lacks most of the security-related calls and
+has several other deficiencies with respect to its version of the Win32
+API.  See the calls.texinfo document for more information as to what
+is not supported in Win 9x.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.fork">
+<question><para>How is fork() implemented?</para></question>
+<answer>
+
+<para>Cygwin fork() essentially works like a non-copy on write version
+of fork() (like old Unix versions used to do).  Because of this it
+can be a little slow.  In most cases, you are better off using the
+spawn family of calls if possible.
+</para>
+<para>Here's how it works:
+</para>
+<para>Parent initializes a space in the Cygwin process table for child.
+Parent creates child suspended using Win32 CreateProcess call, giving
+the same path it was invoked with itself.  Parent calls setjmp to save
+its own context and then sets a pointer to this in the Cygwin shared
+memory area (shared among all Cygwin tasks).  Parent fills in the child's
+.data and .bss subsections by copying from its own address space into
+the suspended child's address space.  Parent then starts the child.
+Parent waits on mutex for child to get to safe point.  Child starts and
+discovers if has been forked and then longjumps using the saved jump
+buffer.  Child sets mutex parent is waiting on and then blocks on
+another mutex waiting for parent to fill in its stack and heap.  Parent
+notices child is in safe area, copies stack and heap from itself into
+child, releases the mutex the child is waiting on and returns from the
+fork call.  Child wakes from blocking on mutex, recreates any mmapped
+areas passed to it via shared area and then returns from fork itself.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.globbing">
+<question><para>How does wildcarding (globbing) work?</para></question>
+<answer>
+
+<para>If the DLL thinks it was invoked from a DOS style prompt, it runs a
+`globber' over the arguments provided on the command line.  This means
+that if you type <literal>LS *.EXE</literal> from DOS, it will do what you might
+expect.
+</para>
+<para>Beware: globbing uses <literal>malloc</literal>.  If your application defines
+<literal>malloc</literal>, that will get used.  This may do horrible things to you.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.symlinks">
+<question><para>How do symbolic links work?</para></question>
+<answer>
+
+<para>Cygwin knows of two ways to create symlinks.
+</para>
+<para>The old method is the only valid one up to but not including version 1.3.0.
+If it's enabled (from 1.3.0 on by setting `nowinsymlinks' in the environment
+variable CYGWIN) Cygwin generates link files with a magic header.  When you
+open a file or directory that is a link to somewhere else, it opens the file
+or directory listed in the magic header.  Because we don't want to have to
+open every referenced file to check symlink status, Cygwin marks symlinks
+with the system attribute.  Files without the system attribute are not
+checked.  Because remote samba filesystems do not enable the system
+attribute by default, symlinks do not work on network drives unless you
+explicitly enable this attribute.
+</para>
+<para>The new method which is introduced with Cygwin version 1.3.0 is enabled
+by default or if `winsymlinks' is set in the environment variable CYGWIN.
+Using this method, Cygwin generates symlinks by creating Windows shortcuts.
+Cygwin created shortcuts have a special header (which is in that way never
+created by Explorer) and the R/O attribute set.  A DOS path is stored in
+the shortcut as usual and the description entry is used to store the POSIX
+path.  While the POSIX path is stored as is, the DOS path has perhaps to be
+rearranged to result in a valid path.  This may result in a divergence
+between the DOS and the POSIX path when symlinks are moved crossing mount
+points.  When a user changes the shortcut, this will be detected by Cygwin
+and it will only use the DOS path then.  While Cygwin shortcuts are shown
+without the ".lnk" suffix in `ls' output, non-Cygwin shortcuts are shown
+with the suffix.  However, both are treated as symlinks.
+</para>
+<para>Both, the old and the new symlinks can live peacefully together since Cygwin
+treats both as symlinks regardless of the setting of `(no)winsymlinks' in
+the environment variable CYGWIN.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.executables">
+<question><para>Why do some files, which are not executables have the 'x' type.</para></question>
+<answer>
+
+<para>When working out the Unix-style attribute bits on a file, the library
+has to fill out some information not provided by the WIN32 API.  
+</para>
+<para>It guesses that files ending in .exe and .bat are executable, as are
+ones which have a "#!" as their first characters.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.secure">
+<question><para>How secure is Cygwin in a multi-user environment?</para></question>
+<answer>
+
+<para>As of version 1.5.13, the Cygwin developers are not aware of any feature
+in the cygwin dll that would allow users to gain privileges or to access
+objects to which they have no rights under Windows. However there is no
+guarantee that Cygwin is as secure as the Windows it runs on.  Cygwin
+processes share some variables and are thus easier targets of denial of
+service type of attacks.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.net-functions">
+<question><para>How do the net-related functions work?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>The network support in Cygwin is supposed to provide the Unix API, not
+the Winsock API.
+</para>
+<para>There are differences between the semantics of functions with the same
+name under the API.
+</para>
+<para>E.g., the select system call on Unix can wait on a standard file handles
+and handles to sockets.  The select call in Winsock can only wait on
+sockets.  Because of this, cygwin.dll does a lot of nasty stuff behind
+the scenes, trying to persuade various Winsock/win32 functions to do what
+a Unix select would do.
+</para>
+<para>If you are porting an application which already uses Winsock, then
+using the net support in Cygwin is wrong.
+</para>
+<para>But you can still use native Winsock, and use Cygwin.  The functions
+which cygwin.dll exports are called 'cygwin_&lt;name&gt;'.  There
+are a load of defines which map the standard Unix names to the names
+exported by the DLL-- check out include/netdb.h:
+</para>
+<screen>
+..etc..
+void		cygwin_setprotoent (int);
+void		cygwin_setservent (int);
+void		cygwin_setrpcent (int);
+..etc..
+#ifndef __INSIDE_CYGWIN_NET__
+#define endprotoent cygwin_endprotoent 
+#define endservent cygwin_endservent 
+#define endrpcent  cygwin_endrpcent  
+..etc..
+</screen>
+
+<para>The idea is that you'll get the Unix-&gt;Cygwin mapping if you include
+the standard Unix header files.  If you use this, you won't need to
+link with libwinsock.a - all the net stuff is inside the DLL.
+</para>
+<para>The mywinsock.h file is a standard winsock.h which has been hacked to
+remove the bits which conflict with the standard Unix API, or are
+defined in other headers.  E.g., in mywinsock.h, the definition of
+struct hostent is removed.  This is because on a Unix box, it lives in
+netdb.  It isn't a good idea to use it in your applications.
+</para>
+<para>As of the b19 release, this information may be slightly out of date.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.winsock">
+<question><para>I don't want Unix sockets, how do I use normal Win32 winsock?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>To use the vanilla Win32 winsock, you just need to #define Win32_Winsock
+and #include "windows.h" at the top of your source file(s).  You'll also
+want to add -lwsock32 to the compiler's command line so you link against
+libwsock32.a.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.versions">
+<question><para>What version numbers are associated with Cygwin?</para></question>
+<answer>
+
+<para>Cygwin versioning is relatively complicated because of its status as a
+shared library.  First of all, since October 1998 every Cygwin DLL has
+been named <literal>cygwin1.dll</literal> and has a 1 in the release name.
+Additionally, there are DLL major and minor numbers that correspond to
+the name of the release, and a release number. In other words,
+cygwin-1.5.10-2 is <literal>cygwin1.dll</literal>, major version 5, minor version
+10, release 2.
+</para>
+<para>The <literal>cygwin1.dll</literal> major version number gets incremented only when a
+change is made that makes existing software incompatible. For example,
+the first major version 5 release, cygwin-1.5.0-1, added 64-bit file I/O
+operations, which required many libraries to be recompiled and relinked.
+The minor version changes every time we make a new backward compatible
+Cygwin release available.  There is also a <literal>cygwin1.dll</literal> release
+version number.  The release number is only incremented if we update an
+existing release in a way that does not effect the DLL (like a missing
+header file).
+</para>
+<para>There are also Cygwin API major and minor numbers.  The major number
+tracks important non-backward-compatible interface changes to the API.
+An executable linked with an earlier major number will not be compatible
+with the latest DLL.  The minor number tracks significant API additions
+or changes that will not break older executables but may be required by
+newly compiled ones.
+</para>
+<para>Then there is a shared memory region compatibility version number.  It is
+incremented when incompatible changes are made to the shared memory
+region or to any named shared mutexes, semaphores, etc.  Finally there
+is a mount point registry version number which keeps track
+of non-backwards-compatible changes to the registry mount table layout.
+This has been <literal>mounts v2</literal> for a long time. For more exciting Cygwin
+version number details, check out the <literal>/usr/include/cygwin/version.h</literal>
+file.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.timezone">
+<question><para>Why isn't _timezone set correctly?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>Did you explicitly call tzset() before checking the value of _timezone?
+If not, you must do so.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.mouse">
+<question><para>Is there a mouse interface?</para></question>
+<answer>
+
+<para>There is no way to capture mouse events from Cygwin.  There are
+currently no plans to add support for this.
+</para>
+</answer></qandaentry>
+
diff --git a/winsup/doc/faq-problems.xml b/winsup/doc/faq-problems.xml
new file mode 100644
index 0000000..07c6b07
--- /dev/null
+++ b/winsup/doc/faq-problems.xml
@@ -0,0 +1,44 @@
+<!-- faq-problems.xml --> 
+<para>Aware of the problem, no solution known.</para>
+
+<qandaentry id="faq.known-problems.hyperthreading">
+<question><para>Hangs with Hyperthreaded Processor</para></question>
+<answer>
+
+<para>Some users using processors with Intel's Hyperthreading turned on have
+reported hangs that do not appear with Hyperthreading off. So far
+the Cygwin developers have not been able to reproduce this problem.
+See <ulink url="http://www.cygwin.com/ml/cygwin/2004-07/msg01100.html">http://www.cygwin.com/ml/cygwin/2004-07/msg01100.html</ulink> and
+related messages for details.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.known-problems.pipe-key">
+<question><para>Pipe key (<literal>|</literal>) doesn't work on non-US keyboards in Win9x/ME</para></question>
+<answer>
+
+<para>This might get fixed someday, but meanwhile, just use rxvt, which does
+not have this problem.  This is no real loss, because rxvt has many
+other advantages.  (Do not attempt to use the "broken" pipe key
+(<literal>&brokenpipe;</literal>) as a substitute, it is a different character.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.known-problems.win9x-tape">
+<question><para>Cannot access tape devices with mt on Win9x</para></question>
+<answer>
+
+<para>Win9x does not support the API used by the Cygwin fhandler_dev_tape
+class.  Details at
+<ulink url="http://sources.redhat.com/ml/cygwin/2000-12/msg00331.html">http://sources.redhat.com/ml/cygwin/2000-12/msg00331.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.known-problems.win9x-scp">
+<question><para>On Win9x, scp leaves ssh processes running.</para></question>
+<answer>
+<para>
+You can stop them by hand with the Task Manager.
+</para>
+</answer></qandaentry>
+
diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml
new file mode 100644
index 0000000..cc3639c
--- /dev/null
+++ b/winsup/doc/faq-programming.xml
@@ -0,0 +1,861 @@
+<!-- faq-programming.xml -->
+
+<qandaentry id="faq.programming.packages">
+<question><para>How do I contribute a package?</para></question>
+<answer>
+
+<para>If you are willing to be a package maintainer, great!  We urgently need
+volunteers to prepare and maintain packages, because the priority of the
+Cygwin Team is Cygwin itself.
+</para>
+<para>The Cygwin Package Contributor's Guide at
+<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink> details everything you need to know
+about being a package maintainer. The quickest way to get started is to
+read the <emphasis>Initial packaging procedure, script-based</emphasis> section on
+that page.  The <literal>generic-build-script</literal> found there works well for
+most packages. 
+</para>
+<para>For questions about package maintenance, use the cygwin-apps mailing
+list (start at <ulink url="http://cygwin.com/lists.html">http://cygwin.com/lists.html</ulink>) <emphasis>after</emphasis>
+searching and browsing the cygwin-apps list archives, of course.  Be
+sure to look at the <emphasis>Submitting a package</emphasis> checklist at
+<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink> before sending an ITP (Intent To
+Package) email to cygwin-apps.
+</para>
+<para>You should also announce your intentions to the general cygwin list, in
+case others were thinking the same thing.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.contribute">
+<question><para>How do I contribute to Cygwin?</para></question>
+<answer>
+
+<para>If you want to contribute to Cygwin itself, see
+<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.huge-executables">
+<question><para>Why are compiled executables so huge?!?</para></question>
+<answer>
+
+<para>By default, gcc compiles in all symbols.  You'll also find that gcc
+creates large executables on UNIX.
+</para>
+<para>If that bothers you, just use the 'strip' program, part of the binutils
+package.  Or compile with the <literal>-s</literal> option to gcc.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.glibc">
+<question><para>Where is glibc?</para></question>
+<answer>
+
+<para>Cygwin does not provide glibc.  It uses newlib instead, which provides
+much (but not all) of the same functionality.  Porting glibc to Cygwin
+would be difficult.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.objective-c">
+<question><para>Where is Objective C?</para></question>
+<answer>
+
+<para>Objective C is not distributed with the Cygwin version of gcc, and there
+are no plans to do so.  The gcc package maintainer had difficulty
+building it, and once built there were problems using it.  It appears
+that there is only minimal support for the Objective C front-end in the
+main GCC distribution, anyway.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.make-execvp">
+<question><para>Why does my make fail on Cygwin with an execvp error? </para></question>
+<answer>
+
+<para>First of all, if you are using <literal>make -j[N]</literal>, then stop.  It doesn't
+work well. Also beware of using non-portable shell features in your
+Makefiles (see tips at <ulink url="http://cygwin.com/faq/faq_3.html#SEC46">http://cygwin.com/faq/faq_3.html#SEC46</ulink>).
+</para>
+<para>Errors of <literal>make: execvp: /bin/sh: Illegal Argument</literal> or 
+<literal>make: execvp: /bin/sh: Argument list too long</literal> are often
+caused by the command-line being to long for the Windows execution model.
+To circumvent this, mount the path of the executable using the -X switch
+to enable cygexec for all executables in that folder; you will also need
+to exclude non-cygwin executables with the -x switch. Enabling cygexec
+causes cygwin executables to talk directly to one another, which increases
+the command-line limit. To enable cygexec for <literal>/bin</literal> and 
+<literal>/usr/bin</literal>, you can use these commands in a batch file:
+</para>
+<screen>
+mount -X -b -f c:\cygwin\bin /bin
+mount -X -b -f c:\cygwin\bin /usr/bin
+mount -x -b -f c:\cygwin\bin\strace.exe /usr/bin/strace.exe
+mount -x -b -f c:\cygwin\bin\strace.exe /bin/strace.exe
+mount -x -b -f c:\cygwin\bin\cygcheck.exe /usr/bin/cygcheck.exe
+mount -x -b -f c:\cygwin\bin\cygcheck.exe /bin/cygcheck.exe
+</screen>
+
+<para>Note that you must specifically exclude <literal>strace</literal> and <literal>cygcheck</literal>,
+which are not linked to the Cygwin DLL.
+</para>
+<para>(See <ulink url="http://www.cygwin.com/cygwin-ug-net/using-utils.html#mount">http://www.cygwin.com/cygwin-ug-net/using-utils.html#mount</ulink> 
+for more information.)
+</para>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.winmain">
+<question><para>Why the undefined reference to <literal>WinMain@16</literal>?</para></question>
+<answer>
+
+<para>If you're using <literal>gcc</literal>, try adding an empty main() function to one
+of your sources.  Or, perhaps you have <literal>-lm</literal> too early in the
+link command line.  It should be at the end:
+</para>
+<screen>
+    bash$ gcc hello.c -lm
+    bash$ ./a.exe
+    Hello World!
+</screen>
+
+<para>works, but
+</para>
+<screen>
+    bash$  gcc -lm hello.c
+    /c/TEMP/ccjLEGlU.o(.text+0x10):hello.c: multiple definition of `main'
+    /usr/lib/libm.a(libcmain.o)(.text+0x0):libcmain.c: first defined here
+    /usr/lib/libm.a(libcmain.o)(.text+0x6a):libcmain.c: undefined reference to `WinMain@16'
+    collect2: ld returned 1 exit status
+</screen>
+
+<para>If you're using GCJ, you need to pass a "--main" flag:
+</para>
+<screen>
+gcj --main=Hello Hello.java
+</screen>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.win32-api">
+<question><para>How do I use Win32 API calls?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>It's pretty simple actually.  Cygwin tools require that you explicitly
+link the import libraries for whatever Win32 API functions that you
+are going to use, with the exception of kernel32, which is linked
+automatically (because the startup and/or built-in code uses it).
+</para>
+<para>For example, to use graphics functions (GDI) you must link
+with gdi32 like this:
+</para>
+<para>gcc -o foo.exe foo.o bar.o -lgdi32
+</para>
+<para>or (compiling and linking in one step):
+</para>
+<para>gcc -o foo.exe foo.c bar.c -lgdi32
+</para>
+<para>The following libraries are available for use in this way:
+</para>
+<para>advapi32  largeint  ole32     scrnsave  vfw32
+cap       lz32      oleaut32  shell32   win32spl
+comctl32  mapi32    oledlg    snmp      winmm
+comdlg32  mfcuia32  olepro32  svrapi    winserve
+ctl3d32   mgmtapi   opengl32  tapi32    winspool
+dlcapi    mpr       penwin32  th32      winstrm
+gdi32     msacm32   pkpd32    thunk32   wow32
+glaux     nddeapi   rasapi32  url       wsock32
+glu32     netapi32  rpcdce4   user32    wst
+icmp      odbc32    rpcndr    uuid
+imm32     odbccp32  rpcns4    vdmdbg
+kernel32  oldnames  rpcrt4    version
+</para>
+<para>The regular setup allows you to use the option -mwindows on the
+command line to include a set of the basic libraries (and also
+make your program a GUI program instead of a console program),
+including user32, gdi32 and, IIRC, comdlg32.
+</para>
+<para>Note that you should never include -lkernel32 on your link line
+unless you are invoking ld directly.  Do not include the same import
+library twice on your link line.  Finally, it is a good idea to
+put import libraries last on your link line, or at least after
+all the object files and static libraries that reference them.
+</para>
+<para>The first two are related to problems the linker has (as of b18 at least)
+when import libraries are referenced twice.  Tables get messed up and
+programs crash randomly.  The last point has to do with the fact that
+gcc processes the files listed on the command line in sequence and
+will only resolve references to libraries if they are given after
+the file that makes the reference.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.win32-no-cygwin">
+<question><para>How do I compile a Win32 executable that doesn't use Cygwin?</para></question>
+<answer>
+
+<para>The -mno-cygwin flag to gcc makes gcc link against standard Microsoft
+DLLs instead of Cygwin.  This is desirable for native Windows programs
+that don't need a UNIX emulation layer.
+</para>
+<para>This is not to be confused with 'MinGW' (Minimalist GNU for Windows),
+which is a completely separate effort.  That project's home page is
+<ulink url="http://www.mingw.org/index.shtml">http://www.mingw.org/index.shtml</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.static-linking">
+<question><para>Can I build a Cygwin program that does not require cygwin1.dll at runtime?</para></question>
+<answer>
+
+<para>No.  If your program uses the Cygwin API, then your executable cannot
+run without cygwin1.dll.  In particular, it is not possible to
+statically link with a Cygwin library to obtain an independent,
+self-contained executable.
+</para>
+<para>If this is an issue because you intend to distribute your Cygwin
+application, then you had better read and understand
+<ulink url="http://cygwin.com/licensing.html">http://cygwin.com/licensing.html</ulink>, which explains the licensing
+options.  Unless you purchase a special commercial license from Red
+Hat, then your Cygwin application must be Open Source.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.msvcrt-and-cygwin">
+<question><para>Can I link with both MSVCRT*.DLL and cygwin1.dll?</para></question>
+<answer>
+
+<para>No, you must use one or the other, they are mutually exclusive.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.no-console-window">
+<question><para>How do I make the console window go away?</para></question>
+<answer>
+
+<para>The default during compilation is to produce a console application.
+It you are writing a GUI program, you should either compile with
+-mwindows as explained above, or add the string
+"-Wl,--subsystem,windows" to the GCC command line.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.make-spaces">
+<question><para>Why does make complain about a "missing separator"?</para></question>
+<answer>
+
+<para>This problem usually occurs as a result of someone editing a Makefile
+with a text editor that replaces tab characters with spaces.  Command
+lines must start with tabs.  This is not specific to Cygwin.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.win32-headers">
+<question><para>Why can't we redistribute Microsoft's Win32 headers?</para></question>
+<answer>
+
+<para>Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks
+like it says that one may not "permit further redistribution of the
+Redistributables to their end users".  We take this to mean that we can
+give them to you, but you can't give them to anyone else, which is
+something that Red Hat can't agree to.  Fortunately, we
+have our own Win32 headers which are pretty complete.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.msvs-mingw">
+<question><para>How do I use <literal>cygwin1.dll</literal> with Visual Studio or MinGW?</para></question>
+<answer>
+
+<para>Before you begin, note that Cygwin is licensed under the GNU GPL (as
+indeed are all other Cygwin-based libraries).  That means that if your
+code links against the cygwin dll (and if your program is calling
+functions from Cygwin, it must, as a matter of fact, be linked against
+it), you must apply the GPL to your source as well.  Of course, this
+only matters if you plan to distribute your program in binary form.  For
+more information, see <ulink url="http://gnu.org/licenses/gpl-faq.html">http://gnu.org/licenses/gpl-faq.html</ulink>.  If
+that is not a problem, read on.
+</para>
+<para>If you want to load the DLL dynamically, read
+<literal>winsup/cygwin/how-cygtls-works.txt</literal> and the sample code in
+<literal>winsup/testsuite/cygload</literal> to understand how this works.
+The short version is:
+</para>
+<orderedlist><listitem><para>Make sure you have 4K of scratch space at the bottom of your stack.
+</para></listitem>
+<listitem><para>Invoke <literal>cygwin_dll_init()</literal>:
+<screen>
+HMODULE h = LoadLibrary("cygwin1.dll");
+void (*init)() = GetProcAddress(h, "cygwin_dll_init");
+init();
+</screen>
+</para></listitem>
+</orderedlist>
+
+<para>If you want to link statically from Visual Studio, to my knowledge
+none of the Cygwin developers have done this, but we have this report
+from the mailing list that it can be done this way:
+</para>
+<orderedlist><listitem><para>Use the impdef program to generate a .def file for the cygwin1.dll
+(if you build the cygwin dll from source, you will already have a def
+file)
+</para>
+<screen>
+impdef cygwin1.dll &gt; cygwin1.def
+</screen>
+
+</listitem>
+<listitem><para>Use the MS VS linker (lib) to generate an import library
+</para>
+<screen>
+lib /def=cygwin1.def /out=cygwin1.lib
+</screen>
+
+</listitem>
+<listitem><para>Create a file "my_crt0.c" with the following contents
+</para>
+<screen>
+#include &lt;sys/cygwin.h&gt;
+#include &lt;stdlib.h&gt;
+
+typedef int (*MainFunc) (int argc, char *argv[], char **env);
+
+void
+  my_crt0 (MainFunc f)
+  {
+    cygwin_crt0(f);
+  }
+</screen>
+
+</listitem>
+<listitem><para>Use gcc in a Cygwin prompt to build my_crt0.c into a DLL
+       (e.g. my_crt0.dll). Follow steps 1 and 2 to generate .def and
+       .lib files for the DLL.
+</para>
+</listitem>
+<listitem><para>Download crt0.c from the cygwin website and include it in
+       your sources. Modify it to call my_crt0() instead of
+       cygwin_crt0().  
+</para>
+</listitem>
+<listitem><para>Build your object files using the MS VC compiler cl.
+</para>
+</listitem>
+<listitem><para>Link your object files, cygwin1.lib, and my_crt0.lib (or
+       whatever you called it) into the executable.
+</para></listitem>
+</orderedlist>
+
+<para>Note that if you are using any other Cygwin based libraries
+that you will probably need to build them as DLLs using gcc and
+then generate import libraries for the MS VC linker.
+</para>
+<para>Thanks to Alastair Growcott (alastair dot growcott at bakbone dot co
+dot uk) for this tip.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.linking-lib">
+<question><para>How do I link against a <literal>.lib</literal> file?</para></question>
+<answer>
+
+<para>If your <literal>.lib</literal> file is a normal static or import library with
+C-callable entry points, you can list <literal>foo.lib</literal> as an object file for
+gcc/g++, just like any <literal>*.o</literal> file. Otherwise, here are some steps:
+</para>
+<orderedlist><listitem><para>Build a C file with a function table.  Put all functions you intend
+to use in that table.  This forces the linker to include all the object
+files from the .lib.  Maybe there is an option to force LINK.EXE to
+include an object file.
+</para></listitem>
+<listitem><para>Build a dummy 'LibMain'.
+</para></listitem>
+<listitem><para>Build a .def with all the exports you need.
+</para></listitem>
+<listitem><para>Link with your .lib using link.exe.
+</para></listitem>
+</orderedlist>
+
+<para>or
+</para>
+<orderedlist><listitem><para>Extract all the object files from the .lib using LIB.EXE.
+</para></listitem>
+<listitem><para>Build a dummy C file referencing all the functions you need, either
+      with a direct call or through an initialized function pointer.
+</para></listitem>
+<listitem><para>Build a dummy LibMain.
+</para></listitem>
+<listitem><para>Link all the objects with this file+LibMain.
+</para></listitem>
+<listitem><para>Write a .def.
+</para></listitem>
+<listitem><para>Link.
+</para></listitem>
+</orderedlist>
+
+<para>You can use these methods to use MSVC (and many other runtime libs)
+with Cygwin development tools.
+</para>
+<para>Note that this is a lot of work (half a day or so), but much less than
+rewriting the runtime library in question from specs...
+</para>
+<para>Thanks to Jacob Navia (root at jacob dot remcomp dot fr) for this explanation.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.building-cygwin">
+<question><para>How do I build Cygwin on my own?</para></question>
+<answer>
+
+<para>First, you need to get the Cygwin source.  Ideally, you should check out
+what you need from CVS (<ulink url="http://cygwin.com/cvs.html">http://cygwin.com/cvs.html</ulink>).  This is the
+<emphasis>preferred method</emphasis> for acquiring the sources.  Otherwise, you can
+install the cygwin source package from the distribution.
+</para>
+<para>If you are trying to duplicate a cygwin release then you should just
+download the corresponding source package and use "tar xjf" to unpack
+it.  This will unpack the sources into a directory named cygwin-x.y.z-n,
+where x.y.z-n correspond to the version numbering of the tar.bz2
+package.
+</para>
+<screen>
+tar xjf cygwin-1.5.12-1-src.tar.bz2
+cd cygwin-1.5.12-1
+</screen>
+
+<para>You <emphasis>must</emphasis> build cygwin in a separate directory from the source,
+so create something like a <literal>build/</literal> directory.  You will also want
+to install to a temporary location:
+</para>
+<screen>
+mkdir build
+mkdir /install 
+cd build
+(../configure --prefix=/install -v; make) &gt;&amp; make.out
+make install &gt; install.log 2&gt;&amp;1
+</screen>
+
+<para>Normally, this procedure ignore errors in building the documentation.
+which requires the <literal>docbook-xml</literal>, <literal>docbook-xsl</literal>, and
+<literal>xmlto</literal> packages.  For more information on building the
+documentation, see the README included in the cygwin-doc package.
+</para>
+<para>To check a cygwin1.dll, run "make check" in the winsup/testsuite
+directory.  If that works, install everything <emphasis>except</emphasis> the dll (if
+you can).  Then, close down all cygwin programs (including bash windows,
+inetd, etc.), save your old dll, and copy the new dll to the correct
+place.  Then start up a bash window, or  run a cygwin program from the
+Windows command prompt, and see what happens.
+</para>
+<para>If you get the error "shared region is corrupted" it means that two
+different versions of cygwin1.dll are running on your machine at the
+same time. Remove all but one. 
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.debugging-cygwin">
+<question><para>I may have found a bug in Cygwin, how can I debug it (the symbols in gdb look funny)?</para></question>
+<answer>
+
+<para>Debugging symbols are stripped from distibuted Cygwin binaries, so any
+symbols that you see in gdb are basically meaningless. It is also a good
+idea to use the latest code in case the bug has been fixed, so we
+recommend trying the latest snapshot from
+<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink> or build the DLL from CVS.
+</para>
+<para>To build a debugging version of the Cygwin DLL, you will need to follow
+the instructions at <ulink url="http://cygwin.com/faq/faq_3.html#SEC102">http://cygwin.com/faq/faq_3.html#SEC102</ulink>. You
+can also contact the mailing list for pointers (a simple test case that
+demonstrates the bug is always welcome).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.compiling-unsupported">
+<question><para>How can I compile Cygwin for an unsupported platform (PowerPC, Alpha, ARM, Itanium)?</para></question>
+<answer>
+
+<para>Unfortunately, this will be difficult.  Exception handling and signals
+support semantics and args have been designed for x86 so you would need
+to write specific support for your platform.  We don't know of any other
+incompatibilities. Please send us patches if you do this work!
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.adjusting-heap">
+<question><para>How can I adjust the heap/stack size of an application?</para></question>
+<answer>
+
+<para>If you need to change the maximum amount of memory available to Cygwin, see
+<ulink url="http://cygwin.com/cygwin-ug-net/setup-maxmem.html">http://cygwin.com/cygwin-ug-net/setup-maxmem.html</ulink>. Otherwise,
+just pass heap/stack linker arguments to gcc.  To create foo.exe with
+a heap size of 1024 and a stack size of 4096, you would invoke
+gcc as:
+</para>
+<para><literal>gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c</literal>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.dll-cygcheck">
+<question><para>How can I find out which DLLs are needed by an executable?</para></question>
+<answer>
+
+<para><literal>objdump -p</literal> provides this information, but is rather verbose.
+</para>
+<para><literal>cygcheck</literal> will do this much more concisely, and operates
+recursively, provided the command is in your path.
+</para>
+<para>Note there is currently a bug in cygcheck in that it will not report
+on a program in a Windows system dir (e.g., C:\Windows or C:\WINNT) even
+if it's in your path.  To work around this, supply the full Win32 path
+to the executable, including the .exe extension:
+</para>
+<screen>
+cygcheck c:\\winnt\\system32\\cmd.exe
+</screen>
+
+<para>(Note the windows path separator must be escaped if this is typed in
+bash.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.dll-building">
+<question><para>How do I build a DLL?</para></question>
+<answer>
+
+<para>There's documentation that explains the process in the Cygwin User's
+Guide here: <ulink url="http://cygwin.com/cygwin-ug-net/dll.html">http://cygwin.com/cygwin-ug-net/dll.html</ulink>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.breakpoint">
+<question><para>How can I set a breakpoint at MainCRTStartup?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>Set a breakpoint at *0x401000 in gdb and then run the program in
+question.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.dll-relocatable">
+<question><para>How can I build a relocatable dll?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.  However, there was a discussion on the cygwin mailing list recently that addresses this issue.  Read <ulink url="http://cygwin.com/ml/cygwin/2000-06/msg00688.html">http://cygwin.com/ml/cygwin/2000-06/msg00688.html</ulink> and related messages.)</emphasis>
+</para>
+<para>You must execute the following sequence of five commands, in this
+order:
+</para>
+<screen>
+$(LD) -s --base-file BASEFILE --dll -o DLLNAME OBJS LIBS -e ENTRY
+
+$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \
+        --base-file BASEFILE --output-exp EXPFILE
+
+$(LD) -s --base-file BASEFILE EXPFILE -dll -o DLLNAME OBJS LIBS -e ENTRY
+
+$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \
+	--base-file BASEFILE --output-exp EXPFILE
+
+$(LD) EXPFILE --dll -o DLLNAME OBJS LIBS -e ENTRY
+</screen>
+
+<para>In this example, $(LD) is the linker, ld.
+</para>
+<para>$(DLLTOOL) is dlltool.
+</para>
+<para>$(AS) is the assembler, as.
+</para>
+<para>DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll.
+</para>
+<para>OBJS is the list of object files you want to put into the DLL.
+</para>
+<para>LIBS is the list of libraries you want to link the DLL against.  For
+example, you may or may not want -lcygwin.  You may want -lkernel32.
+Tcl links against -lcygwin -ladvapi32 -luser32 -lgdi32 -lcomdlg32
+-lkernel32.
+</para>
+<para>DEFFILE is the name of your definitions file.  A simple DEFFILE would
+consist of ``EXPORTS'' followed by a list of all symbols which should
+be exported from the DLL.  Each symbol should be on a line by itself.
+Other programs will only be able to access the listed symbols.
+</para>
+<para>BASEFILE is a temporary file that is used during this five stage
+process, e.g., tcl.base.
+</para>
+<para>EXPFILE is another temporary file, e.g., tcl.exp.
+</para>
+<para>ENTRY is the name of the function which you want to use as the entry
+point.  This function should be defined using the WINAPI attribute,
+and should take three arguments:
+        int WINAPI startup (HINSTANCE, DWORD, LPVOID)
+</para>
+<para>This means that the actual symbol name will have an appended @12, so if
+your entry point really is named <literal>startup</literal>, the string you should
+use for ENTRY in the above examples would be <literal>startup@12</literal>.
+</para>
+<para>If your DLL calls any Cygwin API functions, the entry function will need
+to initialize the Cygwin impure pointer.  You can do that by declaring
+a global variable <literal>_impure_ptr</literal>, and then initializing it in the
+entry function.  Be careful not to export the global variable
+<literal>_impure_ptr</literal> from your DLL; that is, do not put it in DEFFILE.
+</para>
+<screen>
+/* This is a global variable.  */
+struct _reent *_impure_ptr;
+extern struct _reent *__imp_reent_data;
+
+int entry (HINSTANT hinst, DWORD reason, LPVOID reserved)
+{
+  _impure_ptr = __imp_reent_data;
+  /* Whatever else you want to do.  */
+}
+</screen>
+
+<para>You may put an optional `--subsystem windows' on the $(LD) lines.  The
+Tcl build does this, but I admit that I no longer remember whether
+this is important.  Note that if you specify a --subsytem &lt;x&gt; flag to ld,
+the -e entry must come after the subsystem flag, since the subsystem flag
+sets a different default entry point.
+</para>
+<para>You may put an optional `--image-base BASEADDR' on the $(LD) lines.
+This will set the default image base.  Programs using this DLL will
+start up a bit faster if each DLL occupies a different portion of the
+address space.  Each DLL starts at the image base, and continues for
+whatever size it occupies.
+</para>
+<para>Now that you've built your DLL, you may want to build a library so
+that other programs can link against it.  This is not required: you
+could always use the DLL via LoadLibrary.  However, if you want to be
+able to link directly against the DLL, you need to create a library.
+Do that like this:
+</para>
+<para>$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE
+</para>
+<para>$(DLLTOOL), $(AS), DLLNAME, and DEFFILE are the same as above.  Make
+sure you use the same DLLNAME and DEFFILE, or things won't work right.
+</para>
+<para>LIBFILE is the name of the library you want to create, e.g.,
+libtcl80.a.  You can then link against that library using something
+like -ltcl80 in your linker command.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.debug">
+<question><para>How can I debug what's going on?</para></question>
+<answer>
+
+<para>You can debug your application using <literal>gdb</literal>.  Make sure you
+compile it with the -g flag!  If your application calls functions in
+MS DLLs, gdb will complain about not being able to load debug information
+for them when you run your program.  This is normal since these DLLs
+don't contain debugging information (and even if they did, that debug
+info would not be compatible with gdb).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.system-trace">
+<question><para>Can I use a system trace mechanism instead?</para></question>
+<answer>
+
+<para>Yes.  You can use the <literal>strace.exe</literal> utility to run other cygwin
+programs with various debug and trace messages enabled.  For information
+on using <literal>strace</literal>, see the Cygwin User's Guide or the file
+<literal>winsup/utils/utils.sgml</literal>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.gdb-signals">
+<question><para>Why doesn't gdb handle signals?</para></question>
+<answer>
+
+<para>Unfortunately, there is only minimal signal handling support in gdb
+currently.  Signal handling only works with Windows-type signals.
+SIGINT may work, SIGFPE may work, SIGSEGV definitely does.  You cannot
+'stop', 'print' or 'nopass' signals like SIGUSR1 or SIGHUP to the
+process being debugged.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.linker">
+<question><para>The linker complains that it can't find something.</para></question>
+<answer>
+
+<para>A common error is to put the library on the command line before
+the thing that needs things from it.
+</para>
+<para>This is wrong <literal>gcc -lstdc++ hello.cc</literal>.
+This is right <literal>gcc hello.cc -lstdc++</literal>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.undeclared-functions">
+<question><para>I use a function I know is in the API, but I still get a link error.</para></question>
+<answer>
+
+<para>The function probably isn't declared in the header files, or
+the UNICODE stuff for it isn't filled in.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.libc">
+<question><para>Can you make DLLs that are linked against libc ?</para></question>
+<answer>
+
+<para>Yes.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.malloc-h">
+<question><para>Where is malloc.h?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>Include stdlib.h instead of malloc.h.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.own-malloc">
+<question><para>Can I use my own malloc?</para></question>
+<answer>
+
+<para>If you define a function called <literal>malloc</literal> in your own code, and link
+with the DLL, the DLL <emphasis>will</emphasis> call your <literal>malloc</literal>.  Needless to
+say, you will run into serious problems if your malloc is buggy.
+</para>
+<para>If you run any programs from the DOS command prompt, rather than from in
+bash, the DLL will try and expand the wildcards on the command line.
+This process uses <literal>malloc</literal> <emphasis>before</emphasis> your main line is started.
+If you have written your own <literal>malloc</literal> to need some initialization
+to occur after <literal>main</literal> is called, then this will surely break.
+</para>
+<para>Moreover, there is an outstanding issue with <literal>_malloc_r</literal> in
+<literal>newlib</literal>.  This re-entrant version of <literal>malloc</literal> will be called
+directly from within <literal>newlib</literal>, by-passing your custom version, and
+is probably incompatible with it.  But it may not be possible to replace
+<literal>_malloc_r</literal> too, because <literal>cygwin1.dll</literal> does not export it and
+Cygwin does not expect your program to replace it.  This is really a
+newlib issue, but we are open to suggestions on how to deal with it.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.msvc-gcc-objects">
+<question><para>Can I mix objects compiled with msvc++ and gcc?</para></question>
+<answer>
+
+<para>Yes, but only if you are combining C object files.  MSVC C++ uses a
+different mangling scheme than GNU C++, so you will have difficulties
+combining C++ objects.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.gdb-msvc">
+<question><para>Can I use the gdb debugger to debug programs built by VC++?</para></question>
+<answer>
+
+<para>No, not for full (high level source language) debugging.
+The Microsoft compilers generate a different type of debugging
+symbol information, which gdb does not understand.
+</para>
+<para>However, the low-level (assembly-type) symbols generated by
+Microsoft compilers are coff, which gdb DOES understand.
+Therefore you should at least be able to see all of your
+global symbols; you just won't have any information about
+data types, line numbers, local variables etc.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.x86-assembly">
+<question><para>Where can I find info on x86 assembly?</para></question>
+<answer>
+
+<para>CPU reference manuals for Intel's current chips are available in
+downloadable PDF form on Intel's web site:
+</para>
+<para><ulink url="http://developer.intel.com/design/pro/manuals/">http://developer.intel.com/design/pro/manuals/</ulink>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.make-scripts">
+<question><para>Shell scripts aren't running properly from my makefiles?</para></question>
+<answer>
+
+<para>If your scripts are in the current directory, you must have <literal>.</literal>
+(dot) in your $PATH.  (It is not normally there by default.)  Otherwise,
+you would need to add /bin/sh in front of each and every shell script
+invoked in your Makefiles.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.preprocessor">
+<question><para>What preprocessor do I need to know about?</para></question>
+<answer>
+
+<para>We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for
+access to the Cygwin environment provided by the dll.
+</para>
+<para>We chose _WIN32 because this is what Microsoft defines in VC++ and
+we thought it would be a good idea for compatibility with VC++ code
+to follow their example.  We use _MFC_VER to indicate code that should
+be compiled with VC++.
+</para>
+<para>_WIN32 is only defined when you use either the -mno-cygwin or -mwin32
+gcc command line options.  This is because Cygwin is supposed to be a
+Unix emulation environment and defining _WIN32 confuses some programs
+which think that they have to make special concessions for a Windows
+environment which Cygwin handles automatically.
+</para>
+<para>Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to
+tell which compiler (or settings) you're running.
+Check this out in detail by running, for example
+</para>
+<screen>
+       $ gcc  -dM -E -xc /dev/null &gt;gcc.txt
+       $ gcc -mno-cygwin -dM -E -xc /dev/null &gt;gcc-mno-cygwin.txt
+       $ gcc -mwin32 -dM -E -xc /dev/null &gt;gcc-mwin32.txt
+</screen>
+<para>Then use the diff and grep utilities to check
+what the difference is.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.unix-gui">
+<question><para>How should I port my Unix GUI to Windows?</para></question>
+<answer>
+
+<para>There are two basic strategies for porting Unix GUIs to Windows.
+</para>
+<para>The first is to use a portable graphics library such as tcl/tk, X11, or
+V (and others?).  Typically, you will end up with a GUI on Windows that
+requires some runtime support.  With tcl/tk, you'll want to include the
+necessary library files and the tcl/tk DLLs.  In the case of X11, you'll
+need everyone using your program to have an X11 server installed.
+</para>
+<para>The second method is to rewrite your GUI using Win32 API calls (or MFC
+with VC++).  If your program is written in a fairly modular fashion, you
+may still want to use Cygwin if your program contains a lot of shared
+(non-GUI-related) code.  That way you still gain some of the portability
+advantages inherent in using Cygwin.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.djgpp">
+<question><para>Why not use DJGPP ?</para></question>
+<answer>
+
+<para>DJGPP is a similar idea, but for DOS instead of Win32.  DJGPP uses a
+"DOS extender" to provide a more reasonable operating interface for its
+applications.   The Cygwin toolset doesn't have to do this since all of
+the applications are native WIN32.   Applications compiled with the
+Cygwin tools can access the Win32 API functions, so you can write
+programs which use the Windows GUI.
+</para>
+<para>You can get more info on DJGPP by following
+<ulink url="http://www.delorie.com/">http://www.delorie.com/</ulink>.
+</para></answer></qandaentry>
+
diff --git a/winsup/doc/faq-resources.xml b/winsup/doc/faq-resources.xml
new file mode 100644
index 0000000..29ffb5f
--- /dev/null
+++ b/winsup/doc/faq-resources.xml
@@ -0,0 +1,151 @@
+<!-- faq-resources.xml -->
+<qandaentry id="faq.resources.documentation">
+<question><para>Where's the documentation?</para></question>
+<answer>
+
+<para>If you have installed Cygwin, you can find lots of documentation in
+<literal>/usr/share/doc/</literal>.  Some packages have Cygwin specific
+instructions in a file
+<literal>/usr/share/doc/Cygwin/<replaceable>package_name</replaceable>.README</literal>.
+In addition, many packages ship with standard documentation, which you can
+find in
+<literal>/usr/share/doc/<replaceable>package_name</replaceable></literal> or
+by using the <literal>man</literal> or <literal>info</literal> tools. (Hint:
+use <literal>cygcheck -l <replaceable>package_name</replaceable></literal> to
+list what man pages the package includes.)  Some older packages still keep
+their documentation in <literal>/usr/doc/</literal>
+instead of <literal>/usr/share/doc/</literal>.
+</para>
+<para>There are links to quite a lot of documentation on the main Cygwin
+project web page, <ulink url="http://cygwin.com/">http://cygwin.com/</ulink>,
+including this FAQ.  Be sure to at least read any 'Release Notes' or 'Readme'
+or 'read this' links on the main web page, if there are any.
+</para>
+<para>There is a comprehensive Cygwin User's Guide at <ulink
+url="http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html">http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html</ulink>
+and an API Reference at <ulink
+url="http://cygwin.com/cygwin-api/cygwin-api.html">http://cygwin.com/cygwin-api/cygwin-api.html</ulink>.
+</para>
+<para>You can find documentation for the individual GNU tools at <ulink
+url="http://www.fsf.org/manual/">http://www.fsf.org/manual/</ulink>.  (You
+should read GNU manuals from a local mirror, check <ulink
+url="http://www.fsf.org/server/list-mirrors.html">http://www.fsf.org/server/list-mirrors.html</ulink>
+for a list of them.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.resources.mailing-lists">
+<question><para>What Cygwin mailing lists can I join?</para></question>
+<answer>
+
+<para>Comprehensive information about the Cygwin mailing lists can be found at
+<ulink url="http://cygwin.com/lists.html">http://cygwin.com/lists.html</ulink>.
+</para>
+<para>To subscribe to the main list, send a message to
+cygwin-subscribe@cygwin.com.  To unsubscribe from the 
+main list, send a message to cygwin-unsubscribe@cygwin.com.
+In both cases, the subject and body of the message are ignored.
+</para>
+<para>Similarly, to subscribe to the Cygwin announcements list, send a message
+to cygwin-announce-subscribe@cygwin.com.  To unsubscribe,
+send a message to cygwin-announce-unsubscribe@cygwin.com.
+</para>
+<para>If you want to contribe to Cygwin tools &amp; applications, rather than
+the library itself, then you should subscribe to cygwin-apps. There
+is also a low-volume list called cygwin-developers which is reserved
+for knowledgeable people who regularly contribute to the Cygwin DLL.
+Please do not ask for read-only access to this mailing list.  Both
+cygwin-developers and cygwin-apps are by-approval lists.  The same
+mechanism as described for the first two lists works for these as
+well.  
+</para>
+<para>There is a searchable archive of the main mailing list at
+<ulink url="http://cygwin.com/ml/cygwin/">http://cygwin.com/ml/cygwin/</ulink>.  There is an alternate
+archive, also searchable, at <ulink url="http://www.delorie.com/archives/">http://www.delorie.com/archives/</ulink>.
+You can also search at <ulink url="http://www.google.com/">http://www.google.com/</ulink> and include
+"cygwin" in the list of search terms.
+</para>
+<para>Cygwin mailing lists are not gatewayed to USENET, so anti-spam measures
+in your email address are neither required nor appreciated.  Also, avoid
+sending HTML content to Cygwin mailing lists.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.resources.posting">
+<question><para>Posting Guidelines (Or: Why won't you/the mailing list answer my questions?)</para></question>
+<answer>
+
+<para>If you follow these guidelines, you are much more likely to get a
+helpful response from the Cygwin developers and/or the Cygwin community at
+large:
+</para>
+<itemizedlist><listitem><para>Read the User's Guide and the FAQ first.
+</para></listitem>
+<listitem><para>Check the mailing list archives.  Your topic may have come up
+before.  (It may even have been answered!)  Use the search facilities
+at the links above.  Try the alternate site if the main archive is not
+producing search results.
+</para></listitem>
+<listitem><para>Explain your problem carefully and completely.  "I installed Blah
+and it doesn't work!" wastes everybody's time.  It provides no
+information for anyone to help you with your problem.  You should
+provide:
+</para>
+<itemizedlist><listitem><para>A problem statement:  How does it behave, how do you think it
+should behave, and what makes you think it's broken?  (Oh yeah, and what
+is <emphasis>"it"</emphasis>?)
+</para></listitem>
+<listitem><para>Information about your Windows OS ("Win95 OSR2" or "NT4/SP3" or
+"Win2K" or "Win98 SE" or ...).
+</para></listitem>
+<listitem><para>Details about your installation process, or attempts at same.  (Internet or
+Directory install?  If the former, exactly when and from what mirror?
+If the latter, which packages did you download?  Which version of
+setup.exe?  Any subsequent updates?)
+</para></listitem>
+<listitem><para>Details about your Cygwin setup, accomplished by <emphasis>attaching</emphasis>
+the output of 'cygcheck -s -v -r' to your message.  (Do not paste the
+output into your message.)
+</para></listitem>
+<listitem><para>A valid return address, so that a reply doesn't require manual editing of
+the 'To:' header.
+</para></listitem>
+</itemizedlist>
+
+</listitem>
+<listitem><para>Your message must be relevant to the list.  Messages that are
+<emphasis>not</emphasis> directly related to Cygwin are considered off-topic and are
+unwelcome.  For example, the following are off-topic:
+</para>
+<itemizedlist><listitem><para>General programming language questions
+</para></listitem>
+<listitem><para>General Windows programming questions
+</para></listitem>
+<listitem><para>General UNIX shell programming questions
+</para></listitem>
+<listitem><para>General application usage questions
+</para></listitem>
+<listitem><para>How to make millions by working at home
+</para></listitem>
+<listitem><para>Announcements from LaserJet toner cartridge suppliers
+</para></listitem>
+</itemizedlist>
+
+</listitem>
+<listitem><para>Read and obey ``How To Ask Questions The Smart Way'' by Eric
+S. Raymond, at <ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">http://www.catb.org/~esr/faqs/smart-questions.html</ulink>.
+</para>
+</listitem>
+</itemizedlist>
+
+<para>If you do not follow the above guidelines, you may still elicit a
+response, but you may not appreciate it!
+</para>
+<para>For inquiries about support contracts and commercial licensing, visit
+<ulink url="http://www.redhat.com/software/cygwin/">http://www.redhat.com/software/cygwin/</ulink>.
+</para>
+<para>Beyond that, perhaps nobody has time to answer your question.  Perhaps
+nobody knows the answer.
+</para>
+</answer></qandaentry>
+
diff --git a/winsup/doc/faq-sections.xml b/winsup/doc/faq-sections.xml
new file mode 100644
index 0000000..93a758e
--- /dev/null
+++ b/winsup/doc/faq-sections.xml
@@ -0,0 +1,460 @@
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+      <!-- see http://www.unicode.org/charts/PDF/U0080.pdf -->
+	<!ENTITY pound      "&#x00A3;">
+	<!ENTITY brokenpipe "&#x00A6;">
+
+      <!-- all the files -->
+      <!ENTITY FAQ-WHAT SYSTEM "faq-what.xml">
+      <!ENTITY FAQ-SETUP SYSTEM "faq-setup.xml">
+      <!ENTITY FAQ-RESOURCES SYSTEM "faq-resources.xml">
+      <!ENTITY FAQ-USING SYSTEM "faq-using.xml">
+      <!ENTITY FAQ-API SYSTEM "faq-api.xml">
+      <!ENTITY FAQ-PROGRAMMING SYSTEM "faq-programming.xml">
+      <!ENTITY FAQ-PROBLEMS SYSTEM "faq-problems.xml">
+]>
+
+<article id="faq" lang="en">
+  <articleinfo>
+    <title>Cygwin FAQ</title>
+  </articleinfo>
+
+<sect1  id="faq.about">
+<title>About Cygwin</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-WHAT;
+</qandaset></sect1>
+
+<sect1  id="faq.setup">
+<title>Setting up Cygwin</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-SETUP;
+</qandaset></sect1>
+
+<sect1  id="faq.resources">
+<title>Further Resources</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-RESOURCES;
+</qandaset></sect1>
+
+<sect1  id="faq.using">
+<title>Using Cygwin</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-USING;
+</qandaset></sect1>
+
+<sect1  id="faq.api">
+<title>Cygwin API Questions</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-API;
+</qandaset></sect1>
+
+<sect1  id="faq.programming">
+<title>Programming Questions</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-PROGRAMMING;
+</qandaset></sect1>
+
+<sect1  id="faq.known-problems">
+<title>Known Problems in the Latest Net Release</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-PROBLEMS;
+</qandaset></sect1>
+
+<sect1  id="faq.copyright">
+<title>Copyright</title>
+<qandaset><?dbhtml toc="1"?>
+
+
+<qandaentry id="faq.what.copyright">
+<question><para>What are the copyrights ?</para></question>
+<answer>
+
+<para>The general idea</para>
+
+<para>Most of the tools are covered by the GNU General Public License (GPL),
+although some are public domain, and others have a X11-style
+copyright.  To cover the GNU GPL requirements, the basic rule is if
+you give out any binaries, you must also make the source available.
+For the full details, be sure to read the text of the GNU GPL which
+follows.
+</para>
+<para>The Cygwin API library found in the winsup subdirectory of the source
+code is also covered by the GNU GPL.  By default, all executables link
+against this library (and in the process include GPL'd Cygwin glue
+code).  This means that unless you modify the tools so that compiled
+executables do not make use of the Cygwin library, your compiled
+programs will also have to be free software distributed under the GPL
+with source code available to all.
+</para>
+<para>Cygwin is currently available for proprietary use only through a
+proprietary-use license.  Please see
+<ulink url="http://www.redhat.com/software/cygwin/">http://www.redhat.com/software/cygwin/</ulink> for more information
+about the Red Hat Cygwin Product.
+</para>
+<para>In accordance with section 10 of the GPL, Red Hat, Inc. permits
+programs whose sources are distributed under a license that complies
+with the Open Source definition to be linked with libcygwin.a without
+libcygwin.a itself causing the resulting program to be covered by the
+GNU GPL.
+</para>
+<para>This means that you can port an Open Source(tm) application to cygwin,
+and distribute that executable as if it didn't include a copy of
+libcygwin.a linked into it.  Note that this does not apply to the
+cygwin DLL itself.  If you distribute a (possibly modified) version of
+the DLL you must adhere to the terms of the GPL, i.e., you must
+provide sources for the cygwin DLL.
+</para>
+<para>See <ulink url="http://www.opensource.org/docs/definition_plain.html">http://www.opensource.org/docs/definition_plain.html</ulink> for
+the precise Open Source Definition referenced above.
+</para>
+
+<para>GNU GENERAL PUBLIC LICENSE</para>
+<screen>
+		   GNU GENERAL PUBLIC LICENSE
+		      Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                          675 Mass Ave, Cambridge, MA 02139, USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	Appendix: How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    &lt;one line to give the program's name and a brief idea of what it does.&gt;
+    Copyright (C) 19yy  &lt;name of author&gt;
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) 19yy name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  &lt;signature of Ty Coon&gt;, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+</screen>
+
+</answer></qandaentry>
+</qandaset></sect1>
+
+</article>
diff --git a/winsup/doc/faq-setup.xml b/winsup/doc/faq-setup.xml
new file mode 100644
index 0000000..61a9e6e
--- /dev/null
+++ b/winsup/doc/faq-setup.xml
@@ -0,0 +1,465 @@
+<!-- faq-setup.xml -->
+<qandaentry id="faq.setup.setup">
+<question><para>What is the recommended installation procedure?</para></question>
+<answer>
+
+<para>There is only one recommended way to install Cygwin, which is to use the GUI
+installer ``Cygwin Setup''.  It is flexible and easy to use.  
+You can pick and choose the packages you wish to install, and update
+them individually.  Full source code is available for all packages and
+tools.  More information on using Cygwin Setup may be found at
+<ulink url="http://cygwin.com/cygwin-ug-net/setup-net.html">http://cygwin.com/cygwin-ug-net/setup-net.html</ulink>.
+</para>
+<para>If you do it any other way, you're on your own!  That said, keep in mind
+that the GUI installer is a "work in progress", so there might be a few
+difficulties, especially if you are behind a firewall or have other
+specific requirements.  If something doesn't work right for you, and
+it's not covered here or in the latest development snapshot at
+<ulink url="http://cygwin.com/setup/">http://cygwin.com/setup/</ulink>, then by all means report it to the
+mailing list.
+</para>
+<para>For a searchable list of packages that can be installed with Cygwin,
+see <ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.c">
+<question><para>Why not install in C:\?</para></question>
+<answer>
+
+<para>The Cygwin Setup program will prompt you for a "root" directory.
+The default is <literal>C:\cygwin</literal>, but you can change it.  You are urged not to
+choose something like <literal>C:\</literal> (the root directory on the system drive) for
+your Cygwin root.  If you do, then critical Cygwin system directories
+like <literal>etc</literal>, <literal>lib</literal> and <literal>bin</literal> could easily be corrupted by
+other (non-Cygwin) applications or packages that use <literal>\etc</literal>,
+<literal>\lib</literal> or <literal>\bin</literal>.  Perhaps there is no conflict now, but who
+knows what you might install in the future?  It's also just good common
+sense to segregate your Cygwin "filesystems" from the rest of your
+Windows system disk.
+</para>
+<para>(In the past, there had been genuine bugs that would cause problems
+for people who installed in <literal>C:\</literal>, but we believe those are gone
+now.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.old-versions">
+<question><para>Can I use Cygwin Setup to get old versions of packages (like gcc-2.95)?</para></question>
+<answer>
+
+<para>Cygwin Setup can be used to install any packages that are on a
+Cygwin mirror, which usually includes one version previous to the
+current one. The complete list may be searched at 
+<ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>.  There is no complete archive of
+older packages. If you have a problem with the current version of
+a Cygwin package, please report it to the mailing list using the 
+guidelines at <ulink url="http://cygwin.com/problems.html">http://cygwin.com/problems.html</ulink>.
+</para>
+<para>That said, if you really need an older package, you may be able to find
+an outdated or archival mirror by searching the web for an old package
+version (for example, <literal>gcc2-2.95.3-10-src.tar.bz2</literal>), but keep in
+mind that this older version will not be supported by the mailing list
+and that installing the older version will not help improve Cygwin.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.virus">
+<question><para>Is Cygwin Setup, or one of the packages, infected with a virus?</para></question>
+<answer>
+
+<para>Unlikely.  Unless you can confirm it, please don't report it to the
+mailing list.  Anti-virus products have been known to detect false
+positives when extracting compressed tar archives.  If this causes
+problems for you, consider disabling your anti-virus software when
+running <literal>setup</literal>.  Read the next entry for a fairly safe way to do
+this.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.hang">
+<question><para>My computer hangs when I run Cygwin Setup!</para></question>
+<answer>
+
+<para>Both Network Associates (formerly McAfee) and Norton anti-virus
+products have been reported to "hang" when extracting Cygwin tar
+archives.  If this happens to you, consider disabling your anti-virus
+software when running Cygwin Setup.  The following procedure should be
+a fairly safe way to do that:
+</para>
+<orderedlist><listitem><para>Download <literal>setup.exe</literal> and scan it explicitly.
+</para>
+</listitem>
+<listitem><para>Turn off the anti-virus software.
+</para>
+</listitem>
+<listitem><para>Run setup to download and extract all the tar files.
+</para>
+</listitem>
+<listitem><para>Re-activate your anti-virus software and scan everything
+in C:\cygwin (or wherever you chose to install), or your entire hard
+disk if you are paranoid.
+</para>
+</listitem>
+</orderedlist>
+
+<para>This should be safe, but only if Cygwin Setup is not substituted by
+something malicious, and no mirror has been compromised.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.what-packages">
+<question><para>What packages should I download? Where are 'make', 'gcc', 'vi', etc?  </para></question>
+<answer>
+<para>When using Cygwin Setup for the first time, the default is to install
+a minimal subset of packages.  If you want anything beyond that, you
+will have to select it explicitly.  See
+<ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink> for a searchable list of available
+packages.
+</para>
+<para>If you want to build programs, of course you'll need <literal>gcc</literal>,
+<literal>binutils</literal>, <literal>make</literal> and probably other packages from the
+``Devel'' category. Text editors can be found under ``Editors''.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.everything">
+<question><para>How do I just get everything?</para></question>
+<answer>
+
+<para>Long ago, the default was to install everything, much to the
+irritation of most users.  Now the default is to install only a basic
+core of packages.  Cygwin Setup is designed to make it easy to browse
+categories and select what you want to install or omit from those
+categories.  It's also easy to install everything:
+</para>
+<orderedlist>
+<listitem><para>At the ``Select Packages'' screen, in ``Categories'' view, at the line 
+marked ``All'', click on the word ``default'' so that it changes to
+``install''.  (Be patient, there is some computing to do at this step.
+It may take a second or two to register the change.)  This tells Setup
+to install <emphasis>everything</emphasis>, not just what it thinks you should have
+by default.
+</para>
+</listitem>
+<listitem><para>Now click on the ``View'' button (twice) until you get the
+``Partial'' view.  This shows exactly which packages are about to be
+downloaded and installed.
+</para>
+</listitem>
+</orderedlist>
+
+<para>This procedure only works for packages that are currently available.
+There is no way to tell Cygwin Setup to install all packages by
+default from now on.  As new packages become available that would not
+be installed by default, you have to repeat the above procedure to get
+them.
+</para>
+<para>In general, a better method (in my opinion), is to:
+</para>
+<orderedlist>
+<listitem><para>First download &amp; install all packages that would normally be
+installed by default.  This includes fundamental packages and any
+updates to what you have already installed.  Then...
+</para>
+</listitem>
+<listitem><para>Run Cygwin Setup again, and apply the above technique to get all
+new packages that would not be installed by default.  You can check
+the list in the Partial View before proceeding, in case there's
+something you really <emphasis>don't</emphasis> want.
+</para>
+</listitem>
+<listitem><para>In the latest version of Cygwin Setup, if you click the ``View''
+button (twice) more, it shows packages not currently installed.  You
+ought to check whether you <emphasis>really</emphasis> want to install everything!
+</para>
+</listitem>
+</orderedlist>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.disk-space">
+<question><para>How much disk space does Cygwin require?</para></question>
+<answer>
+
+<para>That depends, obviously, on what you've chosen to download and
+install.  A full installation today is probably larger than 800MB
+installed, not including the package archives themselves nor the source
+code.
+</para>
+<para>After installation, the package archives remain in your ``Local
+Package Directory'', by default the location of <literal>setup.exe</literal>.  You
+may conserve disk space by deleting the subdirectories there.  These
+directories will have very weird looking names, being encoded with
+their URLs.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.what-upgraded">
+<question><para>How do I know which version I upgraded from?</para></question>
+<answer>
+
+<para>Detailed logs of the most recent Cygwin Setup session can be found in
+<literal>/var/log/setup.log.full</literal> and less verbose information about
+prior actions is in <literal>/var/log/setup.log</literal>.
+</para>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.setup-fails">
+<question><para>What if setup fails?</para></question>
+<answer>
+
+<para>First, make sure that you are using the latest version of Cygwin Setup.
+The latest version is always available from the 'Install Cygwin now' link on
+the Cygwin Home Page at <ulink
+url="http://cygwin.com/">http://cygwin.com/</ulink>.  </para>
+<para>If you are downloading from the Internet, setup will fail if it cannot
+download the list of mirrors at <ulink
+url="http://cygwin.com/mirrors.html">http://cygwin.com/mirrors.html</ulink>.
+It could be that the network is too busy.  Something similar could be the
+cause of a download site not working.  Try another mirror, or try again
+later.
+</para>
+<para>If setup refuses to download a package that you know needs to be
+upgraded, try deleting that package's entry from /etc/setup.  If you are
+reacting quickly to an announcement on the mailing list, it could be
+that the mirror you are using doesn't have the latest copy yet.  Try
+another mirror, or try again tomorrow.
+</para>
+<para>If setup has otherwise behaved strangely, check the files
+<literal>setup.log</literal> and <literal>setup.log.full</literal> in
+<literal>/var/log</literal> (<literal>C:\cygwin\var\log</literal> by
+default).  It may provide some clues as to what went wrong and why.
+</para>
+<para>If you're still baffled, search the Cygwin mailing list for clues.
+Others may have the same problem, and a solution may be posted there.
+If that search proves fruitless, send a query to the Cygwin mailing
+list.  You must provide complete details in your query: version of
+setup, options you selected, contents of setup.log and setup.log.full,
+what happened that wasn't supposed to happen, etc.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.name-with-space">
+<question><para>My Windows logon name has a space in it, will this cause problems?</para></question>
+<answer>
+
+<para>Most definitely yes!  UNIX shells (and thus Cygwin) use the space
+character as a word delimiter.  Under certain circumstances, it is
+possible to get around this with various shell quoting mechanisms, but
+you are much better off if you can avoid the problem entirely.
+</para>
+<para>On Windows NT/2000/XP you have two choices:
+</para><orderedlist>
+<listitem><para>You can rename the user in the Windows User Manager GUI and then
+run mkpasswd.
+</para>
+</listitem>
+<listitem><para>You can simply edit the /etc/passwd file and change the Cygwin user name 
+(first field). It's also a good idea to avoid spaces in the home directory.
+</para>
+</listitem>
+</orderedlist>
+
+<para>On Windows 95/98/ME you can create a new user and run mkpasswd, 
+or you can delete the offending entry from /etc/passwd. 
+Cygwin will then use the name in the default entry with uid 500.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.home">
+<question><para>My <literal>HOME</literal> environment variable is not what I want.</para></question>
+<answer>
+
+<para>When starting Cygwin from Windows, <literal>HOME</literal> is determined as follows
+in order of decreasing priority:
+</para>
+<orderedlist>
+<listitem><para><literal>HOME</literal> from the Windows environment, translated to POSIX form.
+</para>
+</listitem>
+<listitem><para>The entry in /etc/passwd
+</para>
+</listitem>
+<listitem><para><literal>HOMEDRIVE</literal> and <literal>HOMEPATH</literal> from the Windows environment
+</para>
+</listitem>
+<listitem><para>/
+</para>
+</listitem>
+</orderedlist>
+
+<para>When using Cygwin from the network (telnet, ssh,...), <literal>HOME</literal> is set 
+from /etc/passwd.
+</para>
+<para>If your <literal>HOME</literal> is set to a value such as /cygdrive/c, it is likely 
+that it was set in Windows. Start a DOS Command Window and type 
+"set HOME" to verify if this is the case.
+</para>
+<para>Access to shared drives is often restricted when starting from the network,
+thus Domain users may wish to have a different <literal>HOME</literal> in the 
+Windows environment (on shared drive) than in /etc/passwd (on local drive).
+Note that ssh only considers /etc/passwd, disregarding <literal>HOME</literal>. 
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.uninstall-packages">
+<question><para>How do I uninstall individual packages?</para></question>
+<answer>
+
+<para>Run Cygwin Setup as you would to install packages.  In the list of
+packages to install, browse the relevant category or click on the
+``View'' button to get a full listing.  Click on the cycle glyph until
+the action reads ``Uninstall''.  Proceed by clicking ``Next''.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.uninstall-all">
+<question><para>How do I uninstall <emphasis role='bold'>all</emphasis> of Cygwin?</para></question>
+<answer>
+
+<para>Setup has no automatic uninstall facility.  The recommended method to remove all 
+of Cygwin is as follows:
+</para>
+<orderedlist>
+<listitem><para>Remove all Cygwin services.  If a service is currently running, it must 
+first be stopped with <literal>cygrunsrv -E name</literal>, where <literal>name</literal> 
+is the name of the service.  Then use <literal>cygrunsrv -R name</literal> to uninstall the 
+service from the registry.  Repeat this for all services that you installed.  
+Common services that might have been installed are <literal>sshd</literal>, <literal>cron</literal>, 
+<literal>cygserver</literal>, <literal>inetd</literal>, <literal>apache</literal>, and so on.
+</para>
+</listitem>
+<listitem><para>Stop the X11 server if it is running, and terminate any Cygwin programs 
+that might be running in the background.  Remove all mount information by typing 
+<literal>umount -A</literal> and then exit the command prompt and ensure that no Cygwin 
+processes remain.  Note: If you want to save your mount points for a later 
+reinstall, first save the output of <literal>mount -m</literal> as described at 
+<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">http://cygwin.com/cygwin-ug-net/using-utils.html#mount</ulink>.
+</para>
+</listitem>
+<listitem><para>Delete the Cygwin root folder and all subfolders.  If you get an error 
+that an object is in use, then ensure that you've stopped all services and 
+closed all Cygwin programs.  If you get a 'Permission Denied' error then you 
+will need to modify the permissions and/or ownership of the files or folders 
+that are causing the error.  For example, sometimes files used by system 
+services end up owned by the SYSTEM account and not writable by regular users.  
+</para>
+<para>The quickest way to delete the entire tree if you run into this problem is to 
+change the ownership of all files and folders to your account.  To do this in 
+Windows Explorer, right click on the root Cygwin folder, choose Properties, then 
+the Security tab.  Select Advanced, then go to the Owner tab and make sure your 
+account is listed as the owner.  Select the 'Replace owner on subcontainers and 
+objects' checkbox and press Ok.  After Explorer applies the changes you should 
+be able to delete the entire tree in one operation.  Note that you can also 
+achieve this in Cygwin by typing <literal>chown -R user /</literal> or by using other tools 
+such as CACLS.EXE.
+</para>
+</listitem>
+<listitem><para>Delete the Cygwin shortcuts on the Desktop and Start Menu, and anything 
+left by setup.exe in the download directory.  However, if you plan to reinstall 
+Cygwin it's a good idea to keep your setup.exe download directory since you can 
+reinstall the packages left in its cache without redownloading them.
+</para>
+</listitem>
+<listitem><para>If you added Cygwin to your system path, you should remove it unless you 
+plan to reinstall Cygwin to the same location.  Similarly, if you set your 
+CYGWIN environment variable system-wide and don't plan to reinstall, you should 
+remove it.
+</para>
+</listitem>
+<listitem><para>Finally, if you want to be thorough you can delete the registry tree 
+<literal>Software\Cygnus Solutions</literal> under <literal>HKEY_LOCAL_MACHINE</literal> and/or 
+<literal>HKEY_CURRENT_USER</literal>.  However, if you followed the directions above you 
+will have already removed all the mount information which is typically the only 
+thing stored in the registry.
+</para>
+</listitem>
+</orderedlist>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.snapshots">
+<question><para>How do I install snapshots?</para></question>
+<answer>
+
+<para>First, are you sure you want to do this?  Snapshots are risky.  They
+have not been tested.  Use them <emphasis role='bold'>only</emphasis> if there is a feature or
+bugfix that you need to try, and you are willing to deal with any
+problems.
+</para>
+<para>Before installing a snapshot, you must first Close <emphasis role='bold'>all</emphasis> Cygwin
+applications, including shells and services (e.g. inetd, sshd), before
+updating <literal>cygwin1.dll</literal>.  You may have to restart Windows to clear
+the DLL from memory.
+</para>
+<para>You cannot use Setup to install a snapshot.
+</para>
+<para>You should generally install the full
+<literal>cygwin-inst-YYYYMMDD.tar.bz2</literal> update, rather than just the DLL,
+otherwise some components may be out of sync.  Cygwin tar won't be
+able to update <literal>/usr/bin/cygwin1.dll</literal>, but it should succeed with
+everything else.
+</para>
+<orderedlist>
+<listitem><para>Download the snapshot, and run:
+<screen>
+	cd /
+        tar jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 --exclude=usr/bin/cygwin1.dll
+        cd /tmp
+        tar jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 usr/bin/cygwin1.dll
+</screen>
+</para>
+</listitem>
+<listitem><para>After closing all Cygwin apps (see above), use Explorer or the
+Windows command shell to move <literal>C:\cygwin\tmp\usr\bin\cygwin1.dll</literal>
+to <literal>C:\cygwin\bin\cygwin1.dll</literal>.
+</para>
+</listitem>
+</orderedlist>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.mirror">
+<question><para>Can Cygwin Setup maintain a ``mirror''?</para></question>
+<answer>
+
+<para>NO.  Cygwin Setup cannot do this for you.  Use a tool designed for
+this purpose.  See <ulink url="http://rsync.samba.org/">http://rsync.samba.org/</ulink>,
+<ulink url="http://wget.sunsite.dk/">http://wget.sunsite.dk/</ulink> for utilities that can do this for you.
+For more information on setting up a custom Cygwin package server, see
+the Cygwin Setup homepage at
+<ulink url="http://sources.redhat.com/cygwin-apps/setup.html">http://sources.redhat.com/cygwin-apps/setup.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.cd">
+<question><para>How can I make my own portable Cygwin on CD?</para></question>
+<answer>
+
+<para>While some users have successfully done this, for example Indiana
+University's XLiveCD <ulink url="http://xlivecd.indiana.edu/">http://xlivecd.indiana.edu/</ulink>, there is no
+easy way to do it. Full instructions for constructing a porttable Cygwin
+on CD by hand can be found on the mailing list at
+<ulink url="http://www.cygwin.com/ml/cygwin/2003-07/msg01117.html">http://www.cygwin.com/ml/cygwin/2003-07/msg01117.html</ulink>.  (Thanks
+to fergus at bonhard dot uklinux dot net for these instructions.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.registry">
+<question><para>How do I save, restore, delete, or modify the Cygwin information stored in the registry?</para></question>
+<answer>
+
+<para>Currently Cygwin stores its mount table information in the registry.  It
+is recommended that you use the <literal>mount</literal> and <literal>umount</literal> commands
+to manipulate the mount information instead of directly modifying the
+registry.
+</para>
+<para>To save the mount information to a file for later restoration, use
+<literal>mount -m &gt; mounts.bat</literal> To remove all mount information use
+<literal>umount -A</literal>.  To reincorporate saved mount information just run the
+batch file. For more information on using <literal>mount</literal>, see
+<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">http://cygwin.com/cygwin-ug-net/using-utils.html#mount</ulink>.
+</para></answer></qandaentry>
+
diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml
new file mode 100644
index 0000000..ce66c9d
--- /dev/null
+++ b/winsup/doc/faq-using.xml
@@ -0,0 +1,951 @@
+<!-- faq-problems.xml -->
+<qandaentry id="faq.using.missing-dlls">
+<question><para>Why can't my application locate cygncurses5.dll?  or cygintl.dll?  or cygreadline5.dll?  or ...?</para></question>
+<answer>
+
+<para>If you upgraded recently, and suddenly vim (or some other Cygwin
+application) cannot find <literal>cygncurses5.dll</literal>, it probably means that you did
+not follow these instructions properly:
+<ulink url="http://cygwin.com/ml/cygwin-announce/2001/msg00124.html">http://cygwin.com/ml/cygwin-announce/2001/msg00124.html</ulink>.  To
+repair the damage, you must run Cygwin Setup again, and re-install the
+<literal>libncurses5</literal> package.
+</para>
+<para>Note that Cygwin Setup won't show this option by default.  In the
+``Select packages to install'' dialog, click on the <literal>Full/Part</literal>
+button.  This lists all packages, even those that are already
+installed.  Scroll down to locate the <literal>libncurses5</literal> package.
+Click on the ``cycle'' glyph until it says ``Reinstall''.  Continue
+with the installation.
+</para>
+<para>Similarly, if something cannot find <literal>cygintl.dll</literal>, then run
+Cygwin Setup and re-install the <literal>libintl</literal> and <literal>libintl1</literal>
+packages.
+</para>
+<para>For a detailed explanation of the general problem, and how to extend
+it to other missing DLLs (like cygreadline5.dll) and identify their
+containing packages, see
+<ulink url="http://cygwin.com/ml/cygwin/2002-01/msg01619.html">http://cygwin.com/ml/cygwin/2002-01/msg01619.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.slow">
+<question><para>Why is Cygwin suddenly <emphasis>so</emphasis> slow?</para></question>
+<answer>
+
+<para>If you recently upgraded and suddenly <emphasis>every</emphasis> command takes a
+<emphasis>very</emphasis> long time, then something is probably attempting to 
+access a network share.  You may have the obsolete <literal>//c</literal>
+notation in your PATH or startup files.  This now means the
+<emphasis>network share</emphasis> <literal>c</literal>, which will slow things down
+tremendously if it does not exist.  
+</para>
+<para>Using //c (for C:) doesn't work anymore.  (Similarly for any drive
+letter, e.g. <literal>//z</literal> for <literal>Z:</literal>) This ``feature'' has long been
+deprecated, and no longer works at all in the latest release.  As of
+release 1.3.3, <literal>//c</literal> now means the <emphasis>network share</emphasis> <literal>c</literal>.
+For a detailed discussion of why this change was made, and how deal
+with it now, refer to
+<ulink url="http://sources.redhat.com/ml/cygwin/2001-09/msg00014.html">http://sources.redhat.com/ml/cygwin/2001-09/msg00014.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.services">
+<question><para>Why don't my services work (or access network shares)?</para></question>
+<answer>
+
+<para>Most Windows services run as a special user called <literal>SYSTEM</literal>.  If you
+installed Cygwin for "Just Me", the <literal>SYSTEM</literal> user won't see your
+Cygwin mount table.  You need to re-mount all of your mounts as
+"system" for services to work. You can re-run <literal>setup.exe</literal> and
+select "Install for All Users", or this script will do the trick:
+</para>
+<screen>
+eval "`mount -m | sed -e 's/ -u / -s /g' -e 's/$/;/'`"
+</screen>
+
+<para>The <literal>SYSTEM</literal> user cannot access network shares that require
+authentication.  For more information, see
+<ulink url="http://cygwin.com/cygwin-ug-net/ntsec.html">http://cygwin.com/cygwin-ug-net/ntsec.html</ulink>.
+</para>
+<para>Workarounds include using public network share that does not require
+authentication (for non-critical files), or running the service as
+your own user with <literal>cygrunsrv -u</literal> (see 
+<literal>/usr/share/doc/Cygwin/cygrunsrv.README</literal> for more information).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.path">
+<question><para>How should I set my PATH?</para></question>
+<answer>
+
+<para>This is done for you in the file /etc/profile, which is sourced by bash
+when you start it from the Desktop or Start Menu shortcut, created by
+<literal>setup.exe</literal>.  The line is
+</para>
+<screen>
+	PATH="/usr/local/bin:/usr/bin:/bin:$PATH"
+</screen>
+
+<para>Effectively, this <emphasis role='bold'>prepends</emphasis> /usr/local/bin and /usr/bin to your
+Windows system path.  If you choose to reset your PATH, say in
+$HOME/.bashrc, or by editing etc/profile directly, then you should
+follow this rule.  You <emphasis role='bold'>must</emphasis> have <literal>/usr/bin</literal> in your PATH
+<emphasis role='bold'>before</emphasis> any Windows system directories.  (And you must not omit
+the Windows system directories!)  Otherwise you will likely encounter
+all sorts of problems running Cygwin applications.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.not-found">
+<question><para>Bash says "command not found", but it's right there!</para></question>
+<answer>
+
+<para>If you compile a program, you might find that you can't run it:
+</para>
+<screen>
+	bash$ gcc -o hello hello.c
+        bash$ hello
+        bash: hello: command not found
+</screen>
+
+<para>Unlike Windows, bash does not look for programs in <literal>.</literal> (the current
+directory) by default.  You can add <literal>.</literal> to your PATH (see above),
+but this is not recommended (at least on UNIX) for security reasons.
+Just tell bash where to find it, when you type it on the command line:
+</para>
+<screen>
+	bash$ gcc -o hello hello.c
+        bash$ ./hello
+        Hello World!
+</screen>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.using.converting-paths">
+<question><para>How do I convert between Windows and UNIX paths?</para></question>
+<answer>
+
+<para>Use the 'cygpath' utility.  Type '<literal>cygpath --help</literal>' for
+information.  For example (on my installation):
+<screen>
+	bash$ cygpath --windows ~/.bashrc
+        D:\starksb\.bashrc
+        bash$ cygpath --unix C:/cygwin/bin/cygwin.bat
+        /usr/bin/cygwin.bat
+        bash$ cygpath --unix C:\\cygwin\\bin\\cygwin.bat
+        /usr/bin/cygwin.bat
+</screen>
+Note that bash interprets the backslash '\' as an escape character, so
+you must type it twice in the bash shell if you want it to be recognized
+as such.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.bashrc">
+<question><para>Why doesn't bash read my .bashrc file on startup?</para></question>
+<answer>
+
+<para>Your .bashrc is read from your home directory specified by the HOME
+environment variable.  It uses /.bashrc if HOME is not set.  So you need
+to set HOME correctly, or move your .bashrc to the top of the drive
+mounted as / in Cygwin.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.bash-insensitive">
+<question><para>How can I get bash filename completion to be case insensitive?</para></question>
+<answer>
+
+<para>Add the following to your <literal>~/.bashrc</literal> file:
+</para>
+<screen>
+	shopt -s nocaseglob
+</screen>
+
+<para>and add the following to your <literal>~/.inputrc</literal> file:
+</para>
+<screen>
+	set completion-ignore-case on
+</screen>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.using.filename-spaces">
+<question><para>Can I use paths/filenames containing spaces in them?</para></question>
+<answer>
+
+<para>Cygwin does support spaces in filenames and paths.  That said, some
+utilities that use the library may not, since files don't typically
+contain spaces in Unix.  If you stumble into problems with this, you
+will need to either fix the utilities or stop using spaces in filenames
+used by Cygwin tools.
+</para>
+<para>In particular, bash interprets space as a word separator.  You would have
+to quote a filename containing spaces, or escape the space character.
+For example:
+<screen>
+	bash-2.03$ cd '/cygdrive/c/Program Files'
+</screen>
+or
+<screen>
+	bash-2.03$ cd /cygdrive/c/Program\ Files
+</screen>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.shortcuts">
+<question><para>Why can't I cd into a shortcut to a directory?</para></question>
+<answer>
+
+<para>Cygwin versions &lt; 1.3.0 do not follow MS Windows Explorer Shortcuts
+(*.lnk files).  It sees a shortcut as a regular file and this you
+cannot "cd" into it.
+</para>
+<para>Since version 1.3.0, Cygwin uses shortcuts as symlinks by default.
+</para>
+<para>Cygwin shortcuts are different from shortcuts created by native Windows
+applications.  Windows applications can usually make use of Cygwin
+shortcuts but not vice versa.  This is by choice.  The reason is that
+Windows shortcuts may contain a bunch of extra information which would
+get lost, if, for example, Cygwin tar archives and extracts them as
+symlinks.
+</para>
+<para>Changing a Cygwin shortcut in Windows Explorer usually changes a Cygwin
+shortcut into a Windows native shortcut.  Afterwards, Cygwin will not
+recognize it as symlink anymore.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.find">
+<question><para>I'm having basic problems with find.  Why?</para></question>
+<answer>
+
+<para>Make sure you are using the find that came with Cygwin and that you
+aren't picking up the Win32 find command instead.  You can verify that
+you are getting the right one by doing a "type find" in bash.
+</para>
+<para>If the path argument to find, including current directory (default), is
+itself a symbolic link, then find will not traverse it unless you
+specify the <literal>-follow</literal> option.  This behavior is different than most
+other UNIX implementations, but is not likely to change.
+</para>
+<para>If find does not seem to be producing enough results, or seems to be
+missing out some directories, you may be experiencing a problem with one
+of find's optimisations.  The absence of <literal>.</literal> and <literal>..</literal>
+directories on some filesystems, such as DVD-R UDF, can confuse find.
+See the documentation for the option <literal>-noleaf</literal> in the man page.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.su">
+<question><para>Why doesn't <literal>su</literal> work?</para></question>
+<answer>
+
+<para>The <literal>su</literal> command has been in and out of Cygwin distributions, but
+it has not been ported to Cygwin and has never worked.  It is
+currently installed as part of the sh-utils, but again, it does not work.
+</para>
+<para>You may be able to use <literal>login</literal> instead, but you should read
+<ulink url="http://www.cygwin.com/ml/cygwin/2001-03/msg00337.html">http://www.cygwin.com/ml/cygwin/2001-03/msg00337.html</ulink> first.
+</para>
+<para>For some technical background into why <literal>su</literal> doesn't work, read
+<ulink url="http://www.cygwin.com/ml/cygwin/2003-06/msg00897.html">http://www.cygwin.com/ml/cygwin/2003-06/msg00897.html</ulink> and
+related messages.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.man">
+<question><para>Why doesn't man (or apropos) work?</para></question>
+<answer>
+
+<para>Before you can use <literal>man -k</literal> or <literal>apropos</literal>, you
+must create the whatis database.  Just run the command
+</para>
+<screen>
+	/usr/sbin/makewhatis
+</screen>
+
+<para>(it may take a minute to complete).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.chmod">
+<question><para>Why doesn't chmod work?</para></question>
+<answer>
+
+<para><literal>ntsec</literal> will allow UNIX permissions in Windows NT on NTFS file
+systems.  This is on by default (a recent change).
+</para>
+<para><literal>ntea</literal> works on NTFS <emphasis>and</emphasis> FAT but it creates a huge,
+<emphasis role='bold'>undeletable</emphasis> file on FAT filesystems.
+</para>
+<para>(The <literal>ntsec</literal> and <literal>ntea</literal> settings are values for the
+<literal>CYGWIN</literal> environment variable.  See the Cygwin User's Guide at
+<ulink url="http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html">http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html</ulink> for more
+information on this variable and its settings.)
+</para>
+<para>There is no solution at all for Windows 9x.
+</para>
+<para>If you have an application that requires a certain permission mode on a
+file, you may be able to work around this requirement by modifying the
+application's source code.  For a hint, based on work done by Corinna
+Vinschen for OpenSSH, see this message from the cygwin mailing list:
+<ulink url="http://cygwin.com/ml/cygwin/2000-11/msg01176.html">http://cygwin.com/ml/cygwin/2000-11/msg01176.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.mkdir-network">
+<question><para>Why doesn't <literal>mkdir -p</literal> work on a network share?</para></question>
+<answer>
+
+<para>Starting with <literal>coreutils-5.3.0-6</literal> and <literal>cygwin-1.5.17</literal>, you can
+do something like this:
+</para>
+<screen>
+bash$ mkdir -p //MACHINE/Share/path/to/new/dir
+</screen>
+
+<para>However, coreutils expects Unix path names, so something like
+<literal>mkdir -p \\\\machine\\share\\path</literal> will fail. 
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.shell-scripts">
+<question><para>Why doesn't my shell script work?</para></question>
+<answer>
+
+<para>There are two basic problems you might run into.  One is the fact that
+<command>/bin/sh</command> is really <command>bash</command> (prior to
+<command>bash-3.0-6</command>, <command>/bin/sh</command> was ash).  and is
+missing some features you might expect in <command>/bin/sh</command>,
+particularly if you are used to <command>/bin/sh</command> actually being
+<command>zsh</command> (MacOS X "Panther") or <command>ksh</command> (Tru64).  
+</para>
+
+<para>Or, it could be a permission problem, and Cygwin doesn't understand that your script is executable.  Because <literal>chmod</literal> may not work (see FAQ entry above), Cygwin must read the contents of files to determine if
+they are executable.  If your script does not start with
+</para>
+<screen>
+	#! /bin/sh
+</screen>
+
+<para>(or any path to a script interpreter, it does not have to be /bin/sh)
+then Cygwin will not know it is an executable script.  The Bourne shell
+idiom
+</para>
+<screen>
+	:
+	# This is the 2nd line, assume processing by /bin/sh
+</screen>
+
+<para>also works.
+</para>
+<para>Note that you can use <literal>mount -x</literal> to force Cygwin to treat all files
+under the mount point as executable.  This can be used for individual
+files as well as directories.  Then Cygwin will not bother to read files
+to determine whether they are executable.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.printing">
+<question><para>How do I print under Cygwin?</para></question>
+<answer>
+
+<para>There is no working lp or lpr system as you would find on UNIX.
+</para>
+<para>Jason Tishler has written a couple of messages that explain how to use
+a2ps (for nicely formatted text in PostScript) and ghostscript (to print
+PostScript files on non-PostScript Windows printers).  Start at
+<ulink url="http://cygwin.com/ml/cygwin/2001-04/msg00657.html">http://cygwin.com/ml/cygwin/2001-04/msg00657.html</ulink>.  Note that the
+<literal>file</literal> command is now available as part of Cygwin setup.
+</para>
+<para>Alternatively, on NT, you can use the Windows <literal>print</literal> command.  (It
+does not seem to be available on Win9x.)  Type
+</para>
+<screen>
+	bash$ print /\?
+</screen>
+
+<para>for usage instructions (note the <literal>?</literal> must be escaped from the
+shell).
+</para>
+<para>Finally, you can simply <literal>cat</literal> the file to the printer's share name:
+</para>
+<screen>
+	bash$ cat myfile &gt; //host/printer
+</screen>
+
+<para>You may need to press the formfeed button on your printer or append the
+formfeed character to your file.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.unicode">
+<question><para>Why don't international (Unicode) characters work?</para></question>
+<answer>
+
+<para>Internationalization is a complex issue. The short answer is that
+Cygwin is not Unicode-aware, so things that might work in Linux will
+not necessarily work on Cygwin. However, some things do work. To type
+international characters (&pound;&auml;&ouml;) in <literal>bash</literal>, add the following
+lines to your <literal>~/.inputrc</literal> file and restart <literal>bash</literal>:
+</para>
+<screen>
+	set meta-flag on 
+        set convert-meta off 
+        set output-meta on 
+	set input-meta on
+	set kanji-code sjis
+	set meta-flag on
+</screen>
+
+<para>These are options to the <literal>readline</literal> library, which you can read
+about in the <literal>bash(1)</literal> and <literal>readline(3)</literal> man pages. Other
+tools that do not use <literal>readline</literal> for display, such as <literal>less</literal>
+and <literal>ls</literal>, require additional settings, which could be put in your
+<literal>~/.bashrc</literal>:
+<screen>
+alias less='/bin/less -r'
+alias ls='/bin/ls -F --color=tty --show-control-chars'
+export LANG="ja_JP.SJIS"
+export OUTPUT_CHARSET="sjis"
+</screen>
+These examples use the Japanese Shift-JIS character set, obviously
+you will want to change them for your own locale. 
+</para>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.using.cursor">
+<question><para>Why don't cursor keys work under Win95/Win98?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>Careful examination shows that they not just non-functional, but
+rather behave strangely, for example, with NumLock off, keys on numeric
+keyboard work, until you press usual cursor keys, when even numeric
+stop working, but they start working again after hitting alphanumeric
+key, etc. This reported to happen on localized versions of Win98 and
+Win95, and not specific to Cygwin; there are known cases of Alt+Enter
+(fullscreen/windowed toggle) not working and shifts sticking with
+other programs. The cause of this problem is Microsoft keyboard
+localizer which by default installed in 'autoexec.bat'. Corresponding
+line looks like:
+</para>
+<screen>
+keyb ru,,C:\WINDOWS\COMMAND\keybrd3.sys
+</screen>
+
+<para>(That's for russian locale.) You should comment that line if you want
+your keys working properly. Of course, this will deprive you of your
+local alphabet keyboard support, so you should think about
+another localizer. ex-USSR users are of course knowledgeable of Keyrus
+localizer, and it might work for other locales too, since it has keyboard
+layout editor. But it has russian messages and documentation ;-(
+Reference URL is http://www.hnet.ru/software/contrib/Utils/KeyRus/
+(note the you may need to turn off Windows logo for Keyrus to operate
+properly).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.multiple-copies">
+<question><para>Is it OK to have multiple copies of the DLL?</para></question>
+<answer>
+
+<para>You should only have one copy of the Cygwin DLL on your system.  If you
+have multiple versions, they will conflict and cause problems.
+</para>
+<para>If you get the error "shared region is corrupted" or "shared region
+version mismatch" it means you have multiple versions of cygwin1.dll
+running at the same time.  This could happen, for example, if you update
+cygwin1.dll without exiting <emphasis>all</emphasis> Cygwin apps (including inetd)
+beforehand.
+</para>
+<para>The only DLL that is sanctioned by the Cygwin project is the one that
+you get by running <ulink url="http://cygwin.com/setup.exe">http://cygwin.com/setup.exe</ulink>, installed in the
+directory controlled by this program.  If you have other versions on
+your system and desire help from the cygwin project, you should delete
+or rename all DLLs that are not installed by <filename>setup.exe</filename>.
+</para>
+<para>If you're trying to find multiple versions of the DLL that are causing
+this problem, reboot first, in case DLLs still loaded in memory are the
+cause.  Then use the Windows System find utility to search your whole
+machine, not just components in your PATH (as 'type' would do) or
+cygwin-mounted filesystems (as Cygwin 'find' would do).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.missing-packages">
+<question><para>Why isn't package XYZ available in Cygwin?</para></question>
+<answer>
+
+<para>Probably because there is nobody willing or able to maintain it.  It
+takes time, and the priority for the Cygwin Team is the Cygwin package.
+The rest is a volunteer effort.  Want to contribute?  See
+<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.old-packages">
+<question><para>Why is the Cygwin package of XYZ so out of date?</para></question>
+<answer>
+
+<para>(Also: Why is the version of package XYZ older than the version that I
+can download from the XYZ web site?  Why is the version of package XYZ
+older than the version that I installed on my linux system?  Is there
+something special about Cygwin which requires that only an older version
+of package XYZ will work on it?)
+</para>
+<para>Every package in the Cygwin distribution has a maintainer who is
+responsible for sending out updates of the package.  This person is a
+volunteer who is rarely the same person as the official developer of the
+package.  If you notice that a version of a package seems to be out of
+date, the reason is usually pretty simple -- the person who is
+maintaining the package hasn't gotten around to updating it yet. Rarely,
+the newer package actually requires complex changes that the maintainer
+is working out. 
+</para>
+<para>If you urgently need an update, sending a polite message to the cygwin
+mailing list pinging the maintainer is perfectly acceptable.  There are
+no guarantees that the maintainer will have time to update the package
+or that you'll receive a response to your request, however.
+</para>
+<para>Remeber that the operative term here is "volunteer".
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.accessing-drives">
+<question><para>How can I access other drives?</para></question>
+<answer>
+
+<para>You have some flexibility here.
+</para>
+<para>Cygwin has a builtin "cygdrive prefix" for drives that are not mounted.
+You can access any drive, say Z:, as '/cygdrive/z/'.
+</para>
+<para>In some applications (notably bash), you can use the familiar windows
+&lt;drive&gt;:/path/, using posix forward-slashes ('/') instead of Windows
+backward-slashes ('\').  (But see the warning below!)  This maps in the
+obvious way to the Windows path, but will be converted internally to use
+the Cygwin path, following mounts (default or explicit).  For example:
+<screen>
+	bash$ cd C:/Windows
+	bash$ pwd
+        /cygdrive/c/Windows
+</screen>
+and
+<screen>
+	bash$ cd C:/cygwin
+	bash$ pwd
+        /
+</screen>
+for a default setup.  You could also use backward-slashes in the
+Windows path, but these would have to be escaped from the shell.
+</para>
+<para><emphasis role='bold'>Warning:</emphasis> There is some ambiguity in going from a Windows path
+to the posix path, because different posix paths, through different
+mount points, could map to the same Windows directory.  This matters
+because different mount points may be binmode or textmode, so the
+behavior of Cygwin apps will vary depending on the posix path used to
+get there.
+</para>
+<para>You can avoid the ambiguity of Windows paths, and avoid typing
+"/cygdrive", by explicitly mounting drives to posix paths.  For example:
+<screen>
+	bash$ mkdir /c
+	bash$ mount c:/ /c
+	bash$ ls /c
+</screen>
+Then <literal>/cygdrive/c/Windows</literal> becomes <literal>/c/Windows</literal> which is a
+little less typing.
+</para>
+<para>Note that you only need to mount drives once.  The mapping is kept
+in the registry so mounts stay valid pretty much indefinitely.
+You can only get rid of them with umount, or the registry editor.
+</para>
+<para>The '-b' option to mount mounts the mountpoint in binary mode
+("binmode") where text and binary files are treated equivalently.  This
+should only be necessary for badly ported Unix programs where binary
+flags are missing from open calls.  It is also the setting for /,
+/usr/bin and /usr/lib in a default Cygwin installation.  The default for
+new mounts is text mode ("textmode"), which is also the mode for all
+"cygdrive" mounts.
+</para>
+<para>You can change the default <literal>cygdrive</literal> prefix and whether it is
+binmode or textmode using the <literal>mount</literal> command.  For example,
+<screen>
+	bash$ mount -b --change-cygdrive-prefix cygdrive
+</screen>
+will change all <literal>/cygdrive/...</literal> mounts to binmode.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.copy-and-paste">
+<question><para>How can I copy and paste into Cygwin console windows?</para></question>
+<answer>
+
+<para>First, consider using rxvt instead of the standard console window.  In
+rxvt, selecting with the left-mouse also copies, and middle-mouse
+pastes.  It couldn't be easier!
+</para>
+<para>Under Windows NT, open the properties dialog of the console window.
+The options contain a toggle button, named "Quick edit mode".  It must
+be ON.  Save the properties.
+</para>
+<para>Under Windows 9x, open the properties dialog of the console window.
+Select the Misc tab.  Uncheck Fast Pasting.  Check QuickEdit.
+</para>
+<para>You can also bind the insert key to paste from the clipboard by adding 
+the following line to your .inputrc file: 
+<screen>
+	"\e[2~": paste-from-clipboard 
+</screen>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.firewall">
+<question><para>What firewall should I use with Cygwin? </para></question>
+<answer>
+
+<para>We have had good reports about Kerio Personal Firewall, ZoneLabs
+Integrity Desktop, and the built-in firewall in Windows XP. Other
+well-known products including ZoneAlarm and Norton Internet Security have
+caused problems for some users but work fine for others. At last report,
+Agnitum Outpost did not work with Cygwin.  If you are having strange
+connection-related problems, disabling the firewall is a good
+troubleshooting step (as is closing or disabling all other running
+applications, especially resource-intensive processes such as indexed
+search).
+</para>
+<para>On the whole, Cygwin doesn't care which firewall is used.  The few rare
+exceptions have to do with socket code.
+Cygwin uses sockets to implement many of its functions, such as IPC.
+Some overzealous firewalls install themselves deeply into the winsock
+stack (with the 'layered service provider' API) and install hooks
+throughout.  Sadly the mailing list archives are littered with examples
+of poorly written firewall-type software that causes things to break.
+Note that with many of these products, simply disabling the firewall
+does not remove these changes; it must be completely uninstalled.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.sharing-files">
+<question><para>How can I share files between Unix and Windows?</para></question>
+<answer>
+
+<para>During development, we have both Linux boxes running Samba and Windows
+machines.  We often build with cross-compilers under Linux and copy
+binaries and source to the Windows system or just toy with them
+directly off the Samba-mounted partition.  On dual-boot NT/Windows 9x
+machines, we usually use the FAT filesystem so we can also access the
+files under Windows 9x.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.case-sensitive">
+<question><para>Is Cygwin case-sensitive? What are managed mounts?</para></question>
+<answer>
+
+<para>Several Unix programs expect to be able to use to filenames
+spelled the same way, but with different case.  A prime example
+of this is perl's configuration script, which wants <literal>Makefile</literal> and
+<literal>makefile</literal>.  WIN32 can't tell the difference between files with
+just different case, so the configuration fails.
+</para>
+<para>To help with this problem, starting in <literal>cygwin-1.5.0</literal> it is
+possible to have a case sensitive Cygwin managed mount. This is an
+experimental feature and should be used with caution. You should only
+use it for directories that are initially unpopulated and are due to
+be completely managed by cygwin (hence the name).  So, the best use
+would be to create an empty directory, mount it, and then add files to
+it:  
+</para>
+<screen>
+mkdir /managed-dir
+mount -o managed c:/cygwin/managed-dir /managed-dir
+cd /managed-dir/
+touch makefile
+touch Makefile
+</screen>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.using.dos-filenames">
+<question><para>What about DOS special filenames?</para></question>
+<answer>
+
+<para>Files cannot be named com1, lpt1, or aux (to name a few); either as
+the root filename or as the extension part.  If you do, you'll have
+trouble.  Unix programs don't avoid these names which can make things
+interesting.  E.g., the perl distribution has a file called
+<literal>aux.sh</literal>.  The perl configuration tries to make sure that
+<literal>aux.sh</literal> is there, but an operation on a file with the magic
+letters 'aux' in it will hang.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.hangs">
+<question><para>When it hangs, how do I get it back?</para></question>
+<answer>
+
+<para>If something goes wrong and the tools hang on you for some reason (easy
+to do if you try and read a file called aux.sh), first try hitting ^C to
+return to bash or the cmd prompt.
+</para>
+<para>If you start up another shell, and applications don't run, it's a good
+bet that the hung process is still running somewhere.  Use the Task
+Manager, pview, or a similar utility to kill the process.
+</para>
+<para>And, if all else fails, there's always the reset button/power switch.
+This should never be necessary under Windows NT.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.directory-structure">
+<question><para>Why the weird directory structure?</para></question>
+<answer>
+
+<para>Why do /lib and /usr/lib (and /bin, /usr/bin) point to the same thing?
+</para>
+<para>Why use mounts instead of symbolic links?
+</para>
+<para>Can I use a disk root (e.g., C:\) as Cygwin root?  Why is this discouraged?
+</para>
+<para>After a new installation in the default location, your mount points will
+look something like this:
+</para>
+<screen>
+	bash$ mount
+	C:\cygwin\bin on /usr/bin type system (binmode)
+	C:\cygwin\lib on /usr/lib type system (binmode)
+	C:\cygwin on / type system (binmode)
+</screen>
+
+<para>(Exactly what you see depends on what options you gave to <literal>setup.exe</literal>.)
+</para>
+<para>Note that /bin and /usr/bin point to the same location, as do /lib and
+/usr/lib.  This is intentional, and you should not undo these mounts
+unless you <emphasis>really</emphasis> know what you are doing.
+</para>
+<para>Various applications and packages may expect to be installed in /lib or
+/usr/lib (similarly /bin or /usr/bin).  Rather than distinguish between
+them and try to keep track of them (possibly requiring the occasional
+duplication or symbolic link), it was decided to maintain only one
+actual directory, with equivalent ways to access it.
+</para>
+<para>Symbolic links had been considered for this purpose, but were dismissed
+because they do not always work on Samba drives.  Also, mounts are
+faster to process because no disk access is required to resolve them.
+</para>
+<para>Note that non-cygwin applications will not observe Cygwin mounts (or
+symlinks for that matter).  For example, if you use WinZip to unpack the
+tar distribution of a Cygwin package, it may not get installed to the
+correct Cygwin path.  <emphasis>So don't do this!</emphasis>
+</para>
+<para>It is strongly recommended not to make the Cygwin root directory the
+same as your drive's root directory, unless you know what you are doing
+and are prepared to deal with the consequences.  It is generally easier
+to maintain the Cygwin hierarchy if it is isolated from, say, C:\.  For
+one thing, you avoid possible collisions with other (non-cygwin)
+applications that may create (for example) \bin and \lib directories.
+(Maybe you have nothing like that installed now, but who knows about
+things you might add in the future?)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.anti-virus">
+<question><para>How do anti-virus programs like Cygwin?</para></question>
+<answer>
+
+<para>Users have reported that NAI (formerly McAfee) VirusScan for NT (and
+others?) is incompatible with Cygwin.  This is because it tries to scan
+the newly loaded shared memory in cygwin1.dll, which can cause fork() to
+fail, wreaking havoc on many of the tools.  (It is not confirmed that
+this is still a problem, however.)
+</para>
+<para>There have been several reports of NAI VirusScan causing the system to
+hang when unpacking tar.gz archives.  This is surely a bug in VirusScan,
+and should be reported to NAI.  The only workaround is to disable
+VirusScan when accessing these files.  This can be an issue during
+setup, and is discussed in that FAQ entry.
+</para>
+<para>Some users report a significant performance hit using Cygwin when their
+anti-virus software is enabled.  Rather than disable the anti-virus
+software completely, it may be possible to specify directories whose
+contents are exempt from scanning.  In a default installation, this
+would be <literal>C:\cygwin\bin</literal>.  Obviously, this could be
+exploited by a hostile non-Cygwin program, so do this at your own risk.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.emacs">
+<question><para>Is there a Cygwin port of GNU Emacs?</para></question>
+<answer>
+
+<para>Yes!  It uses the X11 (<ulink url="http://cygwin.com/xfree/">http://cygwin.com/xfree/</ulink>) Windows
+interface.  From a remote login shell, this ``emacs -nw'' works fine.
+There is also a non-X11 version which just provides the text-only
+terminal interface.  Use Cygwin Setup to install either one (or both).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.ntemacs">
+<question><para>What about NT Emacs?</para></question>
+<answer>
+
+<para>If you want GNU Emacs with a native Microsoft Windows interface, but
+without X, then you must use the native Windows port, commonly known
+as ``NT Emacs''.  You get NT Emacs from any GNU mirror.  It is not
+available from Cygwin Setup.
+</para>
+<para>NT Emacs uses the Windows command shell by default.  Since it is not a
+Cygwin application, it has no knowledge of Cygwin mounts.  With those
+points in mind, you need to add the following code to your ~/.emacs
+(or ~/_emacs) file in order to use Cygwin bash.  This is particularly useful
+for the JDEE package (<ulink url="http://jdee.sunsite.dk/">http://jdee.sunsite.dk/</ulink>).  The following
+settings are for Emacs 21.1:
+</para>
+<screen>
+	;; This assumes that Cygwin is installed in C:\cygwin (the
+	;; default) and that C:\cygwin\bin is not already in your
+	;; Windows Path (it generally should not be).
+	;;
+	(setq exec-path (cons "C:/cygwin/bin" exec-path))
+	(setenv "PATH" (concat "C:\\cygwin\\bin;" (getenv "PATH")))
+	;;
+	;; NT-emacs assumes a Windows command shell, which you change
+	;; here.
+	;;
+	(setq process-coding-system-alist '(("bash" . undecided-unix)))
+	(setq shell-file-name "bash")
+	(setenv "SHELL" shell-file-name) 
+	(setq explicit-shell-file-name shell-file-name) 
+	;;
+	;; This removes unsightly ^M characters that would otherwise
+	;; appear in the output of java applications.
+	;;
+	(add-hook 'comint-output-filter-functions
+	          'comint-strip-ctrl-m)
+</screen>
+
+<para>If you want NT Emacs to understand Cygwin paths, get
+cygwin-mount.el from <ulink url="http://www.emacswiki.org/elisp/index.html">http://www.emacswiki.org/elisp/index.html</ulink>.
+</para>
+<para>Note that all of this ``just works'' if you use the Cygwin port of
+Emacs from Cygwin Setup.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.xemacs">
+<question><para>What about XEmacs?</para></question>
+<answer>
+
+<para>For a concise description of the current situation with XEmacs, see
+this message from the Cygwin mailing list:
+<ulink url="http://cygwin.com/ml/cygwin/2002-11/msg00609.html">http://cygwin.com/ml/cygwin/2002-11/msg00609.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.console-window">
+<question><para>Is there a better alternative to the standard console window?</para></question>
+<answer>
+
+<para>Yes!  Use rxvt instead.  It's an optional package in Cygwin Setup.
+You can use it with or without X11.  You can resize it easily by
+dragging an edge or corner.  Copy and paste is easy with the left and
+middle mouse buttons, respectively.  It will honor settings in your
+~/.Xdefaults file, even without X.
+</para>
+<para>Don't invoke as simply ``rxvt'' because that will run /bin/sh (really
+ash) which is not a good interactive shell.  For details see
+<literal>/usr/doc/Cygwin/rxvt-&lt;ver&gt;.README</literal>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.info-error">
+<question><para>info error "dir: No such file or directory"</para></question>
+<answer>
+
+<para>Cygwin packages install their info documentation in the
+<literal>/usr/share/info</literal> directory.  But you need to create a <literal>dir</literal>
+file there before the standalone info program (probably
+<literal>/usr/bin/info</literal>) can be used to read those info files.  This is how
+you do it:
+<screen>
+	bash$ cd /usr/share/info
+	bash$ for f in *.info ; do install-info $f dir ; done
+</screen>
+This may generate warnings:
+<screen>
+	install-info: warning: no info dir entry in `gzip.info'
+	install-info: warning: no info dir entry in `time.info'
+</screen>
+The <literal>install-info</literal> command cannot parse these files, so you will
+have to add their entries to <literal>/usr/share/info/dir</literal> by hand.
+</para>
+<para>Even if the dir file already exists, you may have to update it when
+you install new Cygwin packages.  Some packages update the dir file
+for you, but many don't.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.out-of-queue">
+<question><para>Why do I get a message saying Out of Queue slots?</para></question>
+<answer>
+
+<para>"Out of queue slots!" generally occurs when you're trying to remove
+many files that you do not have permission to remove (either because
+you don't have permission, they are opened exclusively, etc).  What
+happens is Cygwin queues up these files with the supposition that it
+will be possible to delete these files in the future.  Assuming that
+the permission of an affected file does change later on, the file will
+be deleted as requested.  However, if too many requests come in to
+delete inaccessible files, the queue overflows and you get the message
+you're asking about.  Usually you can remedy this with a quick chmod,
+close of a file, or other such thing.  (Thanks to Larry Hall for
+this explanation).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.symlinks-samba">
+<question><para>Why don't symlinks work on samba-mounted filesystems?</para></question>
+<answer>
+
+<para>Symlinks are marked with "system" file attribute.  Samba does not
+enable this attribute by default.  To enable it, consult your Samba
+documentation and then add these lines to your samba configuration
+file:
+</para>
+<screen>
+	map system = yes
+	create mask = 0775
+</screen>
+
+<para>Note that the 0775 can be anything as long as the 0010 bit is set.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.df-incorrect">
+<question><para>Why does df report sizes incorrectly.</para></question>
+<answer>
+
+<para>There is a bug in the Win32 API function GetFreeDiskSpace that
+makes it return incorrect values for disks larger than 2 GB in size.
+Perhaps that may be your problem?
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.using.tcl-tk">
+<question><para>Why doesn't Cygwin tcl/tk understand Cygwin paths?</para></question>
+<answer>
+
+<para>The versions of Tcl/Tk distributed with Cygwin (e.g. cygtclsh80.exe,
+cygwish80.exe) are not actually "Cygwin versions" of those tools.
+They are built with the <literal>-mno-cygwin</literal> option to <literal>gcc</literal>, which
+means they do not understand Cygwin mounts or symbolic links.
+</para>
+<para>See the entry "How do I convert between Windows and UNIX paths?"
+elsewhere in this FAQ.
+</para></answer></qandaentry>
+
diff --git a/winsup/doc/faq-what.xml b/winsup/doc/faq-what.xml
new file mode 100644
index 0000000..fb6c41a
--- /dev/null
+++ b/winsup/doc/faq-what.xml
@@ -0,0 +1,204 @@
+<!-- faq-what.xml -->
+<qandaentry id="faq.what">
+<question><para>What is it?</para></question>
+<answer>
+
+<para>The Cygwin tools are ports of the popular GNU development tools for
+Microsoft Windows.  They run thanks to the Cygwin library which
+provides the UNIX system calls and environment these programs expect.
+</para>
+<para>With these tools installed, it is possible to write Win32 console or
+GUI applications that make use of the standard Microsoft Win32 API
+and/or the Cygwin API.  As a result, it is possible to easily
+port many significant Unix programs without the need
+for extensive changes to the source code.  This includes configuring
+and building most of the available GNU software (including the packages
+included with the Cygwin development tools themselves).  Even if
+the development tools are of little to no use to you, you may have
+interest in the many standard Unix utilities provided with the package.
+They can be used both from the bash shell (provided) or from the
+standard Windows command shell.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.supported">
+<question><para>What versions of Windows are supported?</para></question>
+<answer>
+
+<para>Wait a minute... Cygwin is only <emphasis>supported</emphasis> if you are paying for
+it, such as through a support contract with Red Hat.  For information
+about getting a Red Hat support contract, see
+<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/</ulink>.
+</para>
+<para>That said, Cygwin can be expected to run on all modern 32 bit versions of
+Windows, except Windows CE.  This includes Windows 95/98/ME/NT/2000/XP.
+</para>
+<para>Keep in mind that Cygwin can only do as much as the underlying OS
+supports.  Because of this, Cygwin will behave differently, and
+exhibit different limitations, on the various versions of Windows.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.where">
+<question><para>Where can I get it?</para></question>
+<answer>
+
+<para>The home page for the Cygwin project is <ulink url="http://cygwin.com/">http://cygwin.com/</ulink>.
+There you should find everything you need for Cygwin, including links
+for download and setup, a current list of mirror sites, a User's
+Guide, an API Reference, mailing lists and archives, and additional
+ported software.
+</para>
+<para>You can find documentation for the individual GNU tools at
+<ulink url="http://www.fsf.org/manual/">http://www.fsf.org/manual/</ulink>.  (You should read GNU manuals from a
+local mirror.  Check <ulink url="http://www.fsf.org/server/list-mirrors.html">http://www.fsf.org/server/list-mirrors.html</ulink>
+for a list of them.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.free">
+<question><para>Is it free software?</para></question>
+<answer>
+
+<para>Yes.  Parts are GNU software (gcc, gas, ld, etc...), parts are covered
+by the standard X11 license, some of it is public domain, some of
+it was written by Cygnus and placed under the GPL.  None of it is
+shareware.  You don't have to pay anyone to use it but you should be
+sure to read the copyright section of the FAQ for more information on
+how the GNU General Public License may affect your use of these tools.
+</para>
+<para>In particular, if you intend to port a proprietary (non-GPL'd)
+application using Cygwin, you will need the proprietary-use license 
+for the Cygwin library.  This is available for purchase; please visit
+<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/</ulink> for more information.
+All other questions should be sent to the project
+mailing list cygwin@cygwin.com.
+</para>
+<para>Note that when we say "free" we mean freedom, not price.  The goal of
+such freedom is that the people who use a given piece of software
+should be able to change it to fit their needs, learn from it, share
+it with their friends, etc.  The Cygwin license allows you those
+freedoms, so it is free software.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.version">
+<question><para>What version of Cygwin <emphasis>is</emphasis> this, anyway?</para></question>
+<answer>
+
+<para>To find the version of the Cygwin DLL installed, you can use
+<filename>uname</filename> as on Linux or <filename>cygcheck</filename>. Refer to each command's
+<literal>--help</literal> output and the <ulink url='http://cygwin.com/cygwin-ug-net/'>Cygwin User's Guide</ulink> for more information.
+</para>
+<para>If you are looking for the version number for the whole Cygwin
+release, there is none. Each package in the Cygwin release has its own
+version.  The packages in Cygwin are continually improving, thanks to
+the efforts of net volunteers who maintain the Cygwin binary ports.
+Each package has its own version numbers and its own release process.
+</para>
+<para>So, how do you get the most up-to-date version of Cygwin?  Easy.  Just
+download the Cygwin Setup program from
+<ulink url='http://cygwin.com/setup.exe'>http://cygwin.com/setup.exe</ulink>.  This program will handle the task
+of updating the packages on your system to the latest version. For
+more information about using Cygwin's <filename>setup.exe</filename>, see 
+<ulink url='http://cygwin.com/cygwin-ug-net/setup-net.html'>Setting Up Cygwin</ulink>
+in the Cygwin User's Guide. 
+</para></answer></qandaentry>
+
+<qandaentry id="faq.what.history">
+<question><para>History</para></question>
+<answer>
+<para>See <ulink url="http://cygwin.com/history.html">http://cygwin.com/history.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.who">
+<question><para>Who's behind the project?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note that if you have cygwin-specific questions, all of these people will appreciate it if you use the cygwin mailing lists rather than sending personal email.)</emphasis>
+</para>
+<para>Chris Faylor is behind many of the recent changes in Cygwin.  Prior to
+joining Cygnus, he contributed significant fixes to the process control
+and environ code, reworked the strace mechanism, and rewrote the
+signal-related code from scratch as a Net contributor.  In addition to
+continuing to make technical contributions, Chris is also currently the
+group's manager.
+</para>
+<para>Corinna Vinschen has contributed several useful fixes to the path
+handling code, console support, improved security handling, and raw
+device support.  Corinna is currently employed by Red Hat as a
+GDB/Cygwin engineer.
+</para>
+<para>DJ Delorie has done important work in profiling Cygwin,
+worked on the Dejagnu automated testing framework, merged the dlltool
+functionality into ld, wrote a good deal of the Cygwin Users' Guide,
+authored the cygcheck utility, and made automated snapshots available
+from our project WWW page.  DJ is currently employed by Red Hat as
+a GCC engineer.
+</para>
+<para>Egor Duda has contributed many useful fixes.  He is responsible for
+Cygwin's ability to start a debugger on detection of a fatal error
+as well as produce core dumps.
+</para>
+<para>Robert Collins has contributed many improvements to thread handling
+as well as generic fixes to cygwin itself.
+</para>
+<para>Kazuhiro Fujieda has contributed many bug fixes and bug reports.
+</para>
+<para>Earnie Boyd has contributed many bug fixes and is the mingw and w32api
+maintainer.
+</para>
+<para>David Starks-Browning is our dedicated FAQ maintainer.
+</para>
+<para>Geoffrey Noer took over the Cygwin project from its initial author Steve
+Chamberlain in mid-1996.  As maintainer, he produced Net releases beta
+16 through 20; made the development snapshots; worked with Net
+contributors to fix bugs; made many various code improvements himself;
+wrote a paper on Cygwin for the 1998 Usenix NT Symposium; authored the
+project WWW pages, FAQ, README; etc.  Geoffrey is not currently employed
+by Red Hat.
+</para>
+<para>Steve Chamberlain designed and implemented
+Cygwin in 1995-1996 while working for Cygnus.  He worked with the Net
+to improve the technology, ported/integrated many of the user tools
+for the first time to Cygwin, and produced all of the releases up to
+beta 14.  Steve is not currently employed by Red Hat.
+</para>
+<para>Marco Fuykschot and Peter Boncz of Data Distilleries contributed nearly
+all of the changes required to make Cygwin thread-safe.  They also
+provided the pthreads interface.
+</para>
+<para>Sergey Okhapkin has been an invaluable Net contributor.  He implemented
+the tty/pty support, has played a significant role in revamping signal
+and exception handling, and has made countless contributions throughout
+the library.  He also provided binaries of the development snapshots to
+the Net after the beta 19 release.
+</para>
+<para>Mumit Khan has been most helpful on the EGCS end of things, providing
+quite a large number of stabilizing patches to the compiler tools for
+the B20 release.
+</para>
+<para>Philippe Giacinti contributed the implementation of dlopen, dlclose,
+dlsym, dlfork, and dlerror in Cygwin.
+</para>
+<para>Ian Lance Taylor did a much-needed rework of the path handling code for
+beta 18, and has made many assorted fixes throughout the code.  Jeremy
+Allison made significant contributions in the area of file handling and
+process control, and rewrote select from scratch.  Doug Evans rewrote
+the path-handling code in beta 16, among other things.  Kim Knuttila and
+Michael Meissner put in many long hours working on the now-defunct
+PowerPC port.  Jason Molenda and Mark Eichin have also made important
+contributions.
+</para>
+<para>Please note that all of us working on Cygwin try to
+be as responsive as possible and deal with patches and questions as we
+get them, but realistically we don't have time to answer all of the
+email that is sent to the main mailing list.  Making Net releases of the
+Win32 tools and helping people on the Net out is not our primary job
+function, so some email will have to go unanswered.
+</para>
+<para>Many thanks to everyone using the tools for their many contributions in
+the form of advice, bug reports, and code fixes.  Keep them coming!
+</para></answer></qandaentry>
+
diff --git a/winsup/doc/faq.xml b/winsup/doc/faq.xml
new file mode 100644
index 0000000..58dfbd5
--- /dev/null
+++ b/winsup/doc/faq.xml
@@ -0,0 +1,456 @@
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
+                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+      <!-- see http://www.unicode.org/charts/PDF/U0080.pdf -->
+	<!ENTITY pound      "&#x00A3;">
+	<!ENTITY brokenpipe "&#x00A6;">
+
+      <!-- all the files -->
+      <!ENTITY FAQ-WHAT SYSTEM "faq-what.xml">
+      <!ENTITY FAQ-SETUP SYSTEM "faq-setup.xml">
+      <!ENTITY FAQ-RESOURCES SYSTEM "faq-resources.xml">
+      <!ENTITY FAQ-USING SYSTEM "faq-using.xml">
+      <!ENTITY FAQ-API SYSTEM "faq-api.xml">
+      <!ENTITY FAQ-PROGRAMMING SYSTEM "faq-programming.xml">
+      <!ENTITY FAQ-PROBLEMS SYSTEM "faq-problems.xml">
+]>
+
+<article id="faq-nochunks" lang="en">
+  <articleinfo>
+    <title>Cygwin FAQ</title>
+  </articleinfo>
+
+<qandaset>
+<?dbhtml toc="1"?>
+
+<qandadiv id="faq.about">
+<title>About Cygwin</title>
+&FAQ-WHAT;
+</qandadiv>
+
+<qandadiv id="faq.setup">
+<title>Setting up Cygwin</title>
+&FAQ-SETUP;
+</qandadiv>
+
+<qandadiv id="faq.resources">
+<title>Further Resources</title>
+&FAQ-RESOURCES;
+</qandadiv>
+
+<qandadiv id="faq.using">
+<title>Using Cygwin</title>
+&FAQ-USING;
+</qandadiv>
+
+<qandadiv id="faq.api">
+<title>Cygwin API Questions</title>
+&FAQ-API;
+</qandadiv>
+
+<qandadiv id="faq.programming">
+<title>Programming Questions</title>
+&FAQ-PROGRAMMING;
+</qandadiv>
+
+<qandadiv id="faq.known-problems">
+<title>Known Problems in the Latest Net Release</title>
+&FAQ-PROBLEMS;
+</qandadiv>
+
+<qandadiv id="faq.copyright">
+<title>Copyright</title>
+
+
+<qandaentry id="faq.what.copyright">
+<question><para>What are the copyrights ?</para></question>
+<answer>
+
+<para>The general idea</para>
+
+<para>Most of the tools are covered by the GNU General Public License (GPL),
+although some are public domain, and others have a X11-style
+copyright.  To cover the GNU GPL requirements, the basic rule is if
+you give out any binaries, you must also make the source available.
+For the full details, be sure to read the text of the GNU GPL which
+follows.
+</para>
+<para>The Cygwin API library found in the winsup subdirectory of the source
+code is also covered by the GNU GPL.  By default, all executables link
+against this library (and in the process include GPL'd Cygwin glue
+code).  This means that unless you modify the tools so that compiled
+executables do not make use of the Cygwin library, your compiled
+programs will also have to be free software distributed under the GPL
+with source code available to all.
+</para>
+<para>Cygwin is currently available for proprietary use only through a
+proprietary-use license.  Please see
+<ulink url="http://www.redhat.com/software/cygwin/">http://www.redhat.com/software/cygwin/</ulink> for more information
+about the Red Hat Cygwin Product.
+</para>
+<para>In accordance with section 10 of the GPL, Red Hat, Inc. permits
+programs whose sources are distributed under a license that complies
+with the Open Source definition to be linked with libcygwin.a without
+libcygwin.a itself causing the resulting program to be covered by the
+GNU GPL.
+</para>
+<para>This means that you can port an Open Source(tm) application to cygwin,
+and distribute that executable as if it didn't include a copy of
+libcygwin.a linked into it.  Note that this does not apply to the
+cygwin DLL itself.  If you distribute a (possibly modified) version of
+the DLL you must adhere to the terms of the GPL, i.e., you must
+provide sources for the cygwin DLL.
+</para>
+<para>See <ulink url="http://www.opensource.org/docs/definition_plain.html">http://www.opensource.org/docs/definition_plain.html</ulink> for
+the precise Open Source Definition referenced above.
+</para>
+
+<para>GNU GENERAL PUBLIC LICENSE</para>
+<screen>
+		   GNU GENERAL PUBLIC LICENSE
+		      Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+                          675 Mass Ave, Cambridge, MA 02139, USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	Appendix: How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    &lt;one line to give the program's name and a brief idea of what it does.&gt;
+    Copyright (C) 19yy  &lt;name of author&gt;
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) 19yy name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  &lt;signature of Ty Coon&gt;, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+</screen>
+
+</answer></qandaentry>
+</qandadiv>
+</qandaset>
+
+</article>