2005-07-10 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>

	* cygwinenv.sgml: Update tty section to mention rxvt and xterm.
	* how-programming.texinfo: Update GPL section of VS FAQ.
	* how-using.texinfo: Expand FAQ about out of date pacakages.
	* setup-net.sgml: Add troubleshooting setup.exe section.

5 files changed, 70 insertions, 16 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index aaf1abd..5ca85a9 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,10 @@
+2005-07-10  Joshua Daniel Franklin  <joshuadfranklin@yahoo.com>
+
+	* cygwinenv.sgml: Update tty section to mention rxvt and xterm.
+	* how-programming.texinfo: Update GPL section of VS FAQ. 
+	* how-using.texinfo: Expand FAQ about out of date pacakages.
+	* setup-net.sgml: Add troubleshooting setup.exe section.
+
 2005-07-08  Corinna Vinschen  <corinna@vinschen.de>
 
 	* how-using.texinfo: Fix typos.
diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml
index 7449275..77e9d4b 100644
--- a/winsup/doc/cygwinenv.sgml
+++ b/winsup/doc/cygwinenv.sgml
@@ -175,13 +175,15 @@ switched on.  So, use at your own risk.</para>
 </listitem>
 <listitem>
 <para><envar>(no)tty</envar> - if set, Cygwin enables extra support
-(i.e., termios) for UNIX-like ttys. 
+(i.e., termios) for UNIX-like ttys in the Windows console. 
 It is not compatible with some Windows programs.
 Defaults to not set, in which case the tty is opened in text mode.
 Note that this has been changed such that ^D works as
 expected instead of ^Z, and is settable via <command>stty</command>.
 This option must be specified before starting a Cygwin shell 
-and it cannot be changed in the shell.</para>
+and it cannot be changed in the shell.  It should not be set when using
+other terminals (i.e., rxvt or xterm). 
+</para>
 </listitem>
 <listitem>
 <para><envar>(no)winsymlinks</envar> - if set, Cygwin creates
diff --git a/winsup/doc/how-programming.texinfo b/winsup/doc/how-programming.texinfo
index a7dc8df..bd9b82d 100644
--- a/winsup/doc/how-programming.texinfo
+++ b/winsup/doc/how-programming.texinfo
@@ -213,6 +213,15 @@ have our own Win32 headers which are pretty complete.
 
 @subsection How do I use @samp{cygwin1.dll} with Visual Studio or MinGW?
 
+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 @file{http://gnu.org/licenses/gpl-faq.html}.  If
+that is not a problem, read on.
+
 If you want to load the DLL dynamically, read
 @code{winsup/cygwin/how-cygtls-works.txt} and the sample code in
 @code{winsup/testsuite/cygload} to understand how this works.
@@ -268,9 +277,7 @@ void
 
 @item  Download crt0.c from the cygwin website and include it in
        your sources. Modify it to call my_crt0() instead of
-       cygwin_crt0().  Since you are using Cygwin source code, your
-       resulting program will be licensed under the GNU GPL. For more
-       information, see @file{http://gnu.org/licenses/gpl-faq.html}.  
+       cygwin_crt0().  
 
 @item  Build your object files using the MS VC compiler cl.
 
diff --git a/winsup/doc/how-using.texinfo b/winsup/doc/how-using.texinfo
index a27bac7..b04bbc1 100644
--- a/winsup/doc/how-using.texinfo
+++ b/winsup/doc/how-using.texinfo
@@ -418,16 +418,36 @@ 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).
 
-@subsection Where can I find "more"?
-
-If you are looking for the "more" pager, you should use the "less" pager
-instead.
-
-@subsection Why isn't package XXXX available in Cygwin?  (Or, why is your package so out of date?)
+@subsection Why isn't package XYZ available in Cygwin?
 
 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 below.
+The rest is a volunteer effort.  Want to contribute?  See
+@file{http://cygwin.com/setup.html}.
+
+@subsection Why is the Cygwin package of XYZ so out of date?
+
+(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?)
+
+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. 
+
+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.
+
+Remeber that the operative term here is "volunteer".
 
 @subsection How can I access other drives?
 
@@ -515,10 +535,15 @@ the following line to your .inputrc file:
 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. If you are
-having strange connection-related problems, disabling the firewall is a
-good troubleshooting step.
-
+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).
+
+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
diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml
index dcbdffd..c098c32 100644
--- a/winsup/doc/setup-net.sgml
+++ b/winsup/doc/setup-net.sgml
@@ -236,6 +236,19 @@ Relevant documentation can be found in the <literal>/usr/doc/Cygwin/</literal>
 or <literal>/usr/share/doc/Cygwin/</literal> directory.
 </para>
 </sect2>
+<sect2><title>Troubleshooting</title>
+<para>
+Unfortunately, the complex setup process means that odd problems can
+occur. If you're having trouble downloading packages, it may be network
+congestion, so try a different mirror and/or a different protocol (i.e.,
+HTTP instead of FTP).  If you notice something is not working after
+running setup, you can check the <command>setup.exe</command> log file
+at <literal>/var/log/setup.log.full</literal>. Make a backup of this
+file before running <command>setup.exe</command> again, and follow the
+steps for <ulink url="http://cygwin.com/problems.html">Reporting
+Problems with Cygwin</ulink>.
+</para>
+</sect2>
 
 </sect1>