Update to switch FAQ from texinfo to DocBook.

1 files changed, 465 insertions, 0 deletions

diff --git a/winsup/doc/faq-setup.xml b/winsup/doc/faq-setup.xml
new file mode 100644
index 000000000..61a9e6efd
--- /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>
+