FAQ Proposed Updates Summary and Preview Diff

FAQ Proposed Updates Summary and Preview Diff

[Brian Inglis]

[-- Attachment #1: Type: text/plain, Size: 1336 bytes --]

Just want to get feedback on how these FAQ changes should be packaged as patches
(separate, series, single) and whether some of the changes should not be applied
at all.

Summary

General:

change setup references to use the Cygwin Setup program;
change Win32 references to Windows;
reword net release or distribution references;
emphasize 64-bit Cygwin and setup-x86_64 over 32-bit;
change see <ulink/> to place links around available wording;
change <literal> for <filename> or <command> where appropriate;
change bash .{ext1,ext2} usage to .ext1/.ext2;
trim trailing spaces highlighted by git diff.

Files:

winsup/doc/faq-api.xml: add to timezone FAQ "Why isn't time zone set correctly?"

winsup/doc/faq-programming.xml

winsup/doc/faq-setup.xml: update setup-x86/_64 --help options for
"Does the Cygwin Setup program accept command-line arguments?";
update compressed setup file types;
remove install everything instructions and provide total size info, time
required, and 32-bit Cygwin address space limitations;
 winsup/doc/faq-using.xml

winsup/doc/faq-what.xml

Preview diff attached.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in IEC units and prefixes, physical quantities in SI.]

[-- Attachment #2: faq.diff --]
[-- Type: text/plain, Size: 70158 bytes --]

diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml
index 313f15d37c..8b149cd76f 100644
--- a/winsup/doc/faq-api.xml
+++ b/winsup/doc/faq-api.xml
@@ -5,7 +5,7 @@
 <qandadiv id="faq.api">
 <title>Cygwin API Questions</title>
 
-<!-- faq-api.xml --> 
+<!-- faq-api.xml -->
 <qandaentry id="faq.api.everything">
 <question><para>How does everything work?</para></question>
 <answer>
@@ -18,7 +18,7 @@ Windows into the C library.  Then your apps should (ideally) run on POSIX
 systems (Unix/Linux) 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/POSIX translation
+And it allows relatively easy upgrades to the Windows/POSIX translation
 layer, providing that DLL changes stay backward-compatible.
 </para>
 <para>For a good overview of Cygwin, you may want to read the Cygwin
@@ -140,7 +140,7 @@ spawn family of calls if possible.
 <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
+Parent creates child suspended using Windows 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
@@ -326,7 +326,7 @@ name under the API.
 <para>E.g., the POSIX select system call can wait on a standard file handles
 and handles to sockets.  The select call in Winsock can only wait on
 sockets.  Because of this, the Cygwin dll does a lot of nasty stuff behind
-the scenes, trying to persuade various Winsock/Win32 functions to do what
+the scenes, trying to persuade various Winsock/Windows functions to do what
 a Unix select would do.
 </para>
 <para>If you are porting an application which already uses Winsock, then
@@ -337,11 +337,11 @@ direct calls to Winsock functions.  If you use Cygwin, use the POSIX API.
 </answer></qandaentry>
 
 <qandaentry id="faq.api.winsock">
-<question><para>I don't want Unix sockets, how do I use normal Win32 winsock?</para></question>
+<question><para>I don't want Unix sockets, how do I use normal Windows winsock?</para></question>
 <answer>
 
 <para>You don't.  Look for the Mingw-w64 project to port applications using
-native Win32/Winsock functions.  Cross compilers packages to build Mingw-w64
+native Windows/Winsock functions.  Cross compilers packages to build Mingw-w64
 targets are available in the Cygwin distro.
 </para>
 </answer></qandaentry>
@@ -385,13 +385,34 @@ Cygwin version number details, check out the
 </answer></qandaentry>
 
 <qandaentry id="faq.api.timezone">
-<question><para>Why isn't timezone set correctly?</para></question>
+<question><para>Why isn't time zone 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?
+<para>Did you explicitly call tzset() before checking the value of time zone?
 If not, you must do so.
+Time zone settings are updated by changes to the tzdata package included in all
+Cygwin installations.
+Have you run the Cygwin Setup program recently to update at least the
+<filename>tzdata</filename>
+package to include the latest current daylight saving (summer time) rules
+for dates of changes, hour offsets from UTC of time zones, and the
+geographic regions to which those rules and offsets apply.
+</para>
+<para>These changes are decided on by politicians, and announced
+by government officials, sometimes with short or no notice, so
+<filename>tzdata</filename>
+package updates are released at least a few, and sometimes several,
+times a year.
+As details of changes are not known until they are announced publicly by
+officials, often in foreign languages, and those details then have to be
+noticed, possibly translated, passed to, and picked up by the official
+<filename>tzdata</filename>
+source package maintainers, subsequently released in an update to the
+<filename>tzdata</filename>
+source package, and then those changes have to be picked up on and applied
+to the Cygwin
+<filename>tzdata</filename>
+package, which has to be updated, built, tested, and released publicly.
 </para>
 </answer></qandaentry>
 
diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml
index 5920ca8c44..b6d2a9c909 100644
--- a/winsup/doc/faq-programming.xml
+++ b/winsup/doc/faq-programming.xml
@@ -76,7 +76,7 @@ sizeof(void*)       4        8        8
 </screen>
 
 <para>This difference can result in interesting problems, especially when
-using Win32 functions, especially when using pointers to Windows
+using Windows functions using pointers to Windows
 datatypes like LONG, ULONG, DWORD.  Given that Windows is LLP64, all of
 the aforementioned types are 4 byte in size, on 32 as well as on 64 bit
 Windows, while `long' on 64 bit Cygwin is 8 bytes.</para>
@@ -102,7 +102,7 @@ in size.  But since ReadFile expects a pointer to a 4 byte type, the function
 will only change the lower 4 bytes of number_of_bytes_read on return, while
 the content of the upper 4 bytes stays undefined.</para>
 
-<para>Here are a few <emphasis>donts</emphasis> which should help porting
+<para>Here are a few <emphasis>don'ts</emphasis> which should help porting
 applications from the known ILP32 data model of 32 bit Cygwin, to the LP64
 data model of 64 bit Cygwin.  Note that these are not Cygwin-only problems.
 Many Linux applications suffered the same somewhat liberal handling of
@@ -189,10 +189,10 @@ string pointer given to printf is missing the upper 4 bytes.
 </para></listitem>
 
 <listitem><para>
-<emphasis>Don't</emphasis> use C base types together with Win32 functions.
+<emphasis>Don't</emphasis> use C base types together with Windows functions.
 Keep in mind that DWORD, LONG, ULONG are <emphasis>not</emphasis> the same
-as long and unsigned long.  Try to use only Win32 datatypes in conjunction
-with Win32 API function calls to avoid type problems.  See the above
+as long and unsigned long.  Try to use only Windows datatypes in conjunction
+with Windows API function calls to avoid type problems.  See the above
 ReadFile example.  Windows functions in printf calls should be treated
 carefully as well.  This code is common for 32 bit code, but probably prints
 the wrong value on 64 bit:
@@ -359,14 +359,14 @@ package at runtime.
 <para>Beware of using non-portable shell features in your Makefiles (see tips
 at <ulink url="https://cygwin.com/faq/faq.html#faq.using.shell-scripts"/>).
 </para>
-<para>Errors of <literal>make: execvp: /bin/sh: Illegal Argument</literal> or 
+<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 
+the command-line limit. To enable cygexec for <literal>/bin</literal> and
 <literal>/usr/bin</literal>, you can add or change these entries in /etc/fstab:
 </para>
 <screen>
@@ -385,7 +385,7 @@ done
 </screen>
 
 <para>
-See <ulink url="https://cygwin.com/cygwin-ug-net/using.html#mount-table"/> 
+See <ulink url="https://cygwin.com/cygwin-ug-net/using.html#mount-table"/>
 for more information on using mount.
 </para>
 
@@ -397,9 +397,9 @@ error?</para></question>
 <answer>
 
 <para>
-Try running cygserver.  Read 
+Try running cygserver.  Read
 <ulink url="https://cygwin.com/cygwin-ug-net/using-cygserver.html"/>. If you're
-trying to use PostgreSQL, also read 
+trying to use PostgreSQL, also read
 <literal>/usr/share/doc/Cygwin/postgresql-*.README</literal>.
 </para>
 
@@ -438,11 +438,11 @@ gcj --main=Hello Hello.java
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.win32-api">
-<question><para>How do I use Win32 API calls?</para></question>
+<question><para>How do I use Windows API calls?</para></question>
 <answer>
 
 <para>Cygwin tools require that you explicitly link the import libraries
-for whatever Win32 API functions that you are going to use, with the exception
+for whatever Windows 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>
@@ -464,7 +464,7 @@ including user32, gdi32 and comdlg32.
 or at least after all the object files and static libraries that reference them.
 </para>
 
-<note><para>There are a few restrictions for calls to the Win32 API.
+<note><para>There are a few restrictions for calls to the Windows API.
 For details, see the User's Guide section
 <ulink url="https://cygwin.com/cygwin-ug-net/setup-env.html#setup-env-win32">Restricted Win32 environment</ulink>,
 as well as the User's Guide section
@@ -472,7 +472,7 @@ as well as the User's Guide section
 </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>
+<question><para>How do I compile a Windows executable that doesn't use Cygwin?</para></question>
 <answer>
 
 <para>The compilers provided by the <literal>mingw64-i686-gcc</literal> and
@@ -528,7 +528,7 @@ lines must start with tabs.  This is not specific to Cygwin.
 </answer></qandaentry>
 
 <qandaentry id="faq.programming.win32-headers">
-<question><para>Why can't we redistribute Microsoft's Win32 headers?</para></question>
+<question><para>Why can't we redistribute Microsoft's Windows headers?</para></question>
 <answer>
 
 <para>Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks
@@ -536,7 +536,7 @@ 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 we can't agree to.  Fortunately, we
-have our own Win32 headers which are pretty complete.
+have our own Windows headers which are pretty complete.
 </para>
 </answer></qandaentry>
 
@@ -603,7 +603,7 @@ void
 </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().  
+       cygwin_crt0().
 </para>
 </listitem>
 <listitem><para>Build your object files using the MS VC compiler cl.
@@ -702,7 +702,7 @@ need from Git (<ulink url="https://cygwin.com/git.html"/>).  This is the
 <emphasis>preferred method</emphasis> for acquiring the sources.  Otherwise,
 if you are trying to duplicate a cygwin release then you should download the
 corresponding source package
-(<literal>cygwin-x.y.z-n-src.tar.bz2</literal>). </para> 
+(<literal>cygwin-x.y.z-n-src.tar.bz2</literal>). </para>
 
 <para>You <emphasis>must</emphasis> build cygwin in a separate directory from
 the source, so create something like a <literal>build/</literal> directory.
@@ -711,7 +711,7 @@ also want to install to the temporary location <literal>install</literal>:
 </para>
 <screen>
 mkdir /oss/build
-mkdir /oss/install 
+mkdir /oss/install
 cd build
 (/oss/src/configure --prefix=/oss/install -v; make) &gt;&amp; make.out
 make install &gt; install.log 2&gt;&amp;1
@@ -726,7 +726,7 @@ 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. 
+same time. Remove all but one.
 </para>
 </answer></qandaentry>
 
@@ -760,8 +760,8 @@ the instructions at <ulink url="https://cygwin.com/faq/faq.html#faq.programming.
 </para>
 
 <para>
-You can also contact the mailing list for pointers (a simple test case that 
-demonstrates the bug is always welcome).  
+You can also contact the mailing list for pointers (a simple test case that
+demonstrates the bug is always welcome).
 </para>
 </answer></qandaentry>
 
diff --git a/winsup/doc/faq-setup.xml b/winsup/doc/faq-setup.xml
index b242fbae42..1e0988491c 100644
--- a/winsup/doc/faq-setup.xml
+++ b/winsup/doc/faq-setup.xml
@@ -10,21 +10,26 @@
 <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 <command>setup-*.exe</command>.  It is flexible and easy to use.  
+<para>
+There is only one recommended way to install Cygwin, which is to use the
+Cygwin Setup program, a GUI installer named
+<command>setup-x86_64.exe</command> for 64 bit Windows, or
+<command>setup-x86.exe</command> for 32 bit Windows. 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="https://cygwin.com/cygwin-ug-net/setup-net.html"/>.
+tools.
+<ulink url="https://cygwin.com/cygwin-ug-net/setup-net.html">More information</ulink>
+is available on using the Cygwin Setup program.
 </para>
 <para>If you do it any other way, you're on your own!
 If something doesn't work right for you, and
-it's not covered here or in the latest development snapshot at
-<ulink url="https://cygwin.com/snapshots/"/>, then by all means report it to the
-mailing list.
+it's not covered here or in the
+<ulink url="https://cygwin.com/snapshots/">latest development snapshot</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="https://cygwin.com/packages/"/>.
+<para>There is a searchable
+<ulink url="https://cygwin.com/packages/">list of packages</ulink>
+that can be installed with Cygwin.
 </para>
 </answer></qandaentry>
 
@@ -34,48 +39,49 @@ see <ulink url="https://cygwin.com/packages/"/>.
 
 <para>The Cygwin Setup program is designed to be interactive, but there are
 a few different ways to automate it. If you are deploying to multiple systems,
-the best way is to run through a full installation once, saving the entire 
-downloaded package tree. Then, on target systems, run Cygwin Setup as a
-"Local Install" pointed at your downloaded package tree. You could do this 
+the best way is to run through a full installation once, saving the entire
+downloaded package tree. Then, on target systems, run the Cygwin Setup program as a
+"Local Install" pointed at your downloaded package tree. You could do this
 non-interactively with the command line options
-<literal>-q -L -l x:\cygwin-local\</literal>, where your downloaded 
-package tree is in <literal>x:\cygwin-local\</literal> (see the next FAQ for
+<literal>-q -L -l x:\cygwin-local\</literal>, where your downloaded
+package tree is in <filename>x:\cygwin-local\</filename> (see the next FAQ for
 an explanation of those options.)
 </para>
 <para>
-For other options, search the mailing lists with terms such as 
+For other options, search the mailing lists with terms such as
 <ulink url="http://www.google.com/search?q=cygwin+automated+setup">cygwin automated setup</ulink> or
 <ulink url="http://www.google.com/search?q=automated+cygwin+install">automated cygwin install</ulink>.
 </para>
 </answer></qandaentry>
 
 <qandaentry id="faq.setup.cli">
-<question><para>Does Setup accept command-line arguments?</para></question>
+<question><para>Does the Cygwin Setup program accept command-line arguments?</para></question>
 <answer>
 
-<para>Yes, run <literal>setup-x86.exe --help</literal> or
-<literal>setup-x86_64.exe --help</literal> for a list.
+<para>Yes, run the Cygwin Setup program with option
+<literal>--help</literal> for an up to date list:
 </para>
 
 <screen>
     --allow-unsupported-windows    Allow old, unsupported Windows versions
- -a --arch                         architecture to install (x86_64 or x86)
+ -a --arch                         Architecture to install (x86_64 or x86)
  -C --categories                   Specify entire categories to install
- -o --delete-orphans               remove orphaned packages
+ -o --delete-orphans               Remove orphaned packages
  -A --disable-buggy-antivirus      Disable known or suspected buggy anti virus
                                    software packages during execution.
- -D --download                     Download from internet
- -f --force-current                select the current version for all packages
- -h --help                         print help
- -I --include-source               Automatically include source download
+ -D --download                     Download packages from internet only
+ -f --force-current                Select the current version for all packages
+ -h --help                         Print help
+ -I --include-source               Automatically install source for every
+                                   package installed
  -i --ini-basename                 Use a different basename, e.g. "foo",
                                    instead of "setup"
  -U --keep-untrusted-keys          Use untrusted keys and retain all
- -L --local-install                Install from local directory
+ -L --local-install                Install packages from local directory only
  -l --local-package-dir            Local package directory
- -m --mirror-mode                  Skip availability check when installing from
-                                   local directory (requires local directory to
-                                   be clean mirror!)
+ -m --mirror-mode                  Skip package availability check when
+                                   installing from local directory (requires
+                                   local directory to be clean mirror!)
  -B --no-admin                     Do not check for and enforce running as
                                    Administrator
  -d --no-desktop                   Disable creation of desktop shortcut
@@ -85,23 +91,29 @@ For other options, search the mailing lists with terms such as
                                    shortcuts
  -N --no-startmenu                 Disable creation of start menu shortcut
  -X --no-verify                    Don't verify setup.ini signatures
- -O --only-site                    Ignore all sites except for -s
+    --no-version-check             Suppress checking if a newer version of
+                                   setup is available
+    --old-keys                     Enable old cygwin.com keys
+ -O --only-site                    Do not download mirror list.  Only use sites
+                                   specified with -s.
  -M --package-manager              Semi-attended chooser-only mode
  -P --packages                     Specify packages to install
  -p --proxy                        HTTP/FTP proxy (host:port)
- -Y --prune-install                prune the installation to only the requested
+ -Y --prune-install                Prune the installation to only the requested
                                    packages
- -K --pubkey                       URL of extra public key file (gpg format)
+ -K --pubkey                       URL or absolute path of extra public key
+                                   file (RFC4880 format)
  -q --quiet-mode                   Unattended setup mode
  -c --remove-categories            Specify categories to uninstall
  -x --remove-packages              Specify packages to uninstall
  -R --root                         Root installation directory
- -S --sexpr-pubkey                 Extra public key in s-expr format
- -s --site                         Download site
- -u --untrusted-keys               Use untrusted keys from last-extrakeys
- -g --upgrade-also                 also upgrade installed packages
+ -S --sexpr-pubkey                 Extra DSA public key in s-expr format
+ -s --site                         Download site URL
+ -u --untrusted-keys               Use untrusted saved extra keys
+ -g --upgrade-also                 Also upgrade installed packages
     --user-agent                   User agent string for HTTP requests
  -v --verbose                      Verbose output
+ -V --version                      Show version
  -W --wait                         When elevating, wait for elevated child
                                    process
 </screen>
@@ -116,15 +128,14 @@ For other options, search the mailing lists with terms such as
 this allows to set up the Cygwin environment so that all users can start
 a Cygwin shell out of the box.  However, if you don't have administrator
 rights for your machine, and the admins don't want to install it for you,
-you can install Cygwin just for yourself by downloading
-<command>setup-x86.exe</command> (for a 32 bit install) or
-<command>setup-x86_64.exe</command> (for a 64 bit install) and then start
-it from the command line or via the "Run..." dialog from the start menu
+you can install Cygwin just for yourself by downloading the Cygwin Setup
+program, and then start
+it from the command line or via the "Run..." dialog from the Start menu
 using the <literal>--no-admin</literal> option, for instance:</para>
 
 <para>
 <screen>
-  setup-x86.exe --no-admin
+  setup-x86_64.exe --no-admin
 </screen>
 </para>
 </answer></qandaentry>
@@ -134,37 +145,37 @@ using the <literal>--no-admin</literal> option, for instance:</para>
 <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
+The default is <filename>C:\cygwin</filename>, but you can change it.  You are urged not to
+choose something like <filename>C:\</filename> (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
+like <filename>etc</filename>, <filename>lib</filename> and <filename>bin</filename> could easily be corrupted by
+other (non-Cygwin) applications or packages that use <filename>\etc</filename>,
+<filename>\lib</filename> or <filename>\bin</filename>.  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
+for people who installed in <filename>C:\</filename>, 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>
+<question><para>Can I use the Cygwin Setup program 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="https://cygwin.com/packages/"/>.  There is no complete archive of
+<para>The Cygwin Setup program can be used to install any packages that are on a
+Cygwin mirror, which usually includes at least one version previous to the
+current one. The <ulink url="https://cygwin.com/packages/">complete list</ulink>
+may be searched. 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="https://cygwin.com/problems.html"/>.
+a Cygwin package, please report it to the mailing list following the
+<ulink url="https://cygwin.com/problems.html">guidelines</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
+version (for example, <filename>gcc2-2.95.3-10-src.tar.bz2</filename>), 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>
@@ -180,12 +191,12 @@ Here is how Cygwin secures the installation and update process to counter
 </para>
 
 <orderedlist>
-<listitem><para>The Cygwin website provides the setup program
-(<literal>setup-x86.exe</literal> or <literal>setup-x86_64.exe</literal>)
+<listitem><para>The Cygwin website provides the Cygwin Setup program
+(<filename>setup-x86_64.exe</filename> or <filename>setup-x86.exe</filename>)
 using HTTPS (SSL/TLS).
-This authenticates that the setup program
+This authenticates that the Cygwin Setup program
 came from the Cygwin website
-(users simply use their web browsers to download the setup program).
+(users simply use their web browsers to download the Cygwin Setup program).
 You can use tools like Qualsys' SSL Server Test,
 <ulink url="https://www.ssllabs.com/ssltest/"/>,
 to check the HTTPS configuration of Cygwin.
@@ -193,31 +204,32 @@ The cygwin.com site supports HTTP Strict Transport Security (HSTS),
 which forces the browser to keep using HTTPS once the browser has seen
 it before (this counters many downgrade attacks).
 </para></listitem>
-<listitem><para>The setup program has the
+<listitem><para>The Cygwin Setup program has the
 Cygwin public key embedded in it.
 The Cygwin public key is protected from attacker subversion
 during transmission by the previous step, and this public
 key is then used to protect all later steps.
-You can confirm that the key is in setup by looking at the setup project
+You can confirm that the key is in the Cygwin Setup program by looking at the setup project
 (<ulink url="http://sourceware.org/cygwin-apps/setup.html"/>)
-source code file <literal>cyg-pubkey.h</literal>
-(the key is automatically generated from file <literal>cygwin.pub</literal>).
+source code file <filename>cyg-pubkey.h</filename>
+(the key is automatically generated from file <filename>cygwin.pub</filename>).
 </para></listitem>
-<listitem><para>The setup program downloads
-the package list <literal>setup.ini</literal> from a mirror
+<listitem><para>The Cygwin Setup program downloads
+the package list <filename>setup.ini</filename> from a mirror
 and checks its digital signature.
-The package list is in the file
-<literal>setup.bz2</literal> (compressed) or
-<literal>setup.ini</literal> (uncompressed) on the selected mirror.
+The package list is in the files
+<filename>setup.zst</filename>, <filename>setup.xz</filename>,
+<filename>setup.bz2</filename> (compressed), or
+<filename>setup.ini</filename> (uncompressed) on the selected mirror.
 The package list includes for every official Cygwin package
 the package name, cryptographic hash, and length (in bytes).
-The setup program also gets the relevant <literal>.sig</literal>
+The Cygwin Setup program also gets the relevant <literal>.sig</literal>
 (signature) file for that package list, and checks that the package list
-is properly signed with the Cygwin public key embedded in the setup program.
+is properly signed with the Cygwin public key embedded in the Setup program.
 A mirror could corrupt the package list and/or signature, but this
-would be detected by setup program's signature detection
+would be detected by the Cygwin Setup program's signature detection
 (unless you use the <literal>-X</literal> option to disable signature checking).
-The setup program also checks the package list
+The Cygwin Setup program also checks the package list
 timestamp/version and reports to the user if the file
 goes backwards in time; that process detects downgrade attacks
 (e.g., where an attacker subverts a mirror to send a signed package list
@@ -226,11 +238,11 @@ that is older than the currently-downloaded version).
 <listitem><para>The packages to be installed
 (which may be updates) are downloaded and both their
 lengths and cryptographic hashes
-(from the signed <literal>setup.{bz2,ini}</literal> file) are checked.
+(from the signed <filename>setup.zst/.xz/.bz2/.,ini</filename> file) are checked.
 Non-matching packages are rejected, countering any attacker's
 attempt to subvert the files on a mirror.
 Cygwin currently uses the cryptographic hash function SHA-512
-for the <literal>setup.ini</literal> files.
+for the <filename>setup.ini</filename> files.
 </para></listitem>
 </orderedlist>
 
@@ -250,8 +262,8 @@ widely-used SHA-2 suite of cryptographic hashes).
 
 <para>
 To best secure your installation and update process, download
-the setup program <literal>setup-x86.exe</literal> (32-bit) or
-<literal>setup-x86_64.exe</literal> (64-bit), and then
+the Cygwin Setup program <filename>setup-x86_64.exe</filename> (64-bit) or
+<filename>setup-x86.exe</filename> (32-bit), and then
 check its signature (using a signature-checking tool you trust)
 using the Cygwin public key
 (<ulink url="https://cygwin.com/key/pubring.asc"/>).
@@ -277,22 +289,22 @@ Not everyone will go through this additional effort,
 but we make it possible for those who want that extra confidence.
 We also provide automatic mechanisms
 (such as our use of HTTPS) for those with limited time and
-do not want to perform the signature checking on the setup program itself.
-Once the correct setup program is running, it will counter other attacks
+do not want to perform the signature checking on the Cygwin Setup program itself.
+Once the correct Setup program is running, it will counter other attacks
 as described in
 <ulink url="https://cygwin.com/faq/faq.html#faq.setup.install-security"/>.
 </para>
 </answer></qandaentry>
 
 <qandaentry id="faq.setup.virus">
-<question><para>Is Cygwin Setup, or one of the packages, infected with a virus?</para></question>
+<question><para>Is the Cygwin Setup program, 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
+running the Cygwin Setup program.  Read the next entry for a fairly safe way to do
 this.
 </para>
 </answer></qandaentry>
@@ -304,17 +316,18 @@ this.
 <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
+software when running the Cygwin Setup program.  The following procedure should be
 a fairly safe way to do that:
 </para>
-<orderedlist><listitem><para>Download <literal>setup-x86.exe</literal> or
-<literal>setup-x86_64.exe</literal> and scan it explicitly.
+<orderedlist><listitem><para>Download <filename>setup-x86_64.exe</filename> or
+<filename>setup-x86.exe</filename> 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.
+<listitem><para>Run the Cygwin Setup program to download and install or upgrade
+all desired packages.
 </para>
 </listitem>
 <listitem><para>Re-activate your anti-virus software and scan everything
@@ -324,16 +337,17 @@ disk if you are paranoid.
 </listitem>
 </orderedlist>
 
-<para>This should be safe, but only if Cygwin Setup is not substituted by
+<para>This should be safe, but only if the Cygwin Setup program is not substituted by
 something malicious.
-See also
-<ulink url="https://cygwin.com/faq/faq.html#faq.setup.install-security"/>
-for a description of how the
-Cygwin project counters man-in-the-middle (MITM) attacks.
+Read the description of how the Cygwin project
+<ulink url="https://cygwin.com/faq/faq.html#faq.setup.install-security">
+counters man-in-the-middle (MITM) attacks</ulink>.
 </para>
 
-<para>See also <ulink url="https://cygwin.com/faq/faq.html#faq.using.bloda"/>
-for a list of applications that have been known, at one time or another, to
+<para>See the "<ulink url="https://cygwin.com/faq/faq.html#faq.using.bloda">
+Big List Of Dodgy Applications</ulink>"
+(<ulink url="https://cygwin.com/acronyms/#BLODA">BLODA</ulink>)
+that have been known, at one time or another, to
 interfere with the normal functioning of Cygwin.
 </para>
 </answer></qandaentry>
@@ -341,13 +355,13 @@ interfere with the normal functioning of Cygwin.
 <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
+<para>When using the Cygwin Setup program for the first time, the default is to install
 a minimal subset of all available packages.  If you want anything beyond that,
-you will have to select it explicitly.  See 
-<ulink url="https://cygwin.com/packages/"/> for a searchable list of available
-packages, or use <literal>cygcheck -p </literal> as described in the Cygwin
-User's Guide at
-<ulink url="https://cygwin.com/cygwin-ug-net/cygcheck.html"/>.
+you will have to select it explicitly.  There is a searchable
+<ulink url="https://cygwin.com/packages/">list of available packages</ulink>,
+or use
+<ulink url="https://cygwin.com/cygwin-ug-net/cygcheck.html"><command>cygcheck -p</command></ulink>
+as described in the Cygwin User's Guide.
 </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
@@ -361,53 +375,19 @@ User's Guide at
 
 <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
+core of packages. The Cygwin Setup program 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 to the
-``Pending'' 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 ``Pending'' 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>
-
+categories.
+There are now more than 10000 Cygwin packages requiring more than 150GB
+of disk space just to download and hundreds of GB more to install so you
+are strongly advised not to attempt to
+<ulink url="https://cygwin.com/install.html#everything">install everything</ulink>
+at once, unless you have a lot of free disk space, a very high speed network
+connection, and the system will not be required for any other purpose for
+many hours (or days) until installation completes.
+For a 32-bit Cygwin installation, you can not install everything, as the
+installation will fail because the 4GB memory available is insufficient to allow
+all the DLLs required to run along with the programs using them.
 </answer></qandaentry>
 
 <qandaentry id="faq.setup.disk-space">
@@ -415,20 +395,20 @@ ought to check whether you <emphasis>really</emphasis> want to install everythin
 <answer>
 
 <para>That depends, obviously, on what you've chosen to download and
-install.  A full installation today is probably larger than 1 GB
+install.  A full installation today is many hundreds of GB
 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-x86{_64}.exe</literal>.  You may conserve disk space by
+Package Directory''.  By default the location of the Cygwin Setup program.
+You may conserve disk space by
 deleting the subdirectories there.  These directories will have very weird
 looking names, being encoded with their URLs
-(named <literal>ftp%3a%2f...</literal>).
+(named  <literal>http%3a%2f...cygwin...%2f</literal>).
 </para>
 <para>Of course, you can keep them around in case you want to reinstall a
 package. If you want to clean out only the outdated packages, Michael Chase
-has written a script called <literal>clean_setup.pl</literal>, available
+has written a script called <command>clean_setup.pl</command>, available
 at <filename>unsupported/clean_setup.pl</filename> in a Cygwin mirror.
 </para>
 </answer></qandaentry>
@@ -438,42 +418,42 @@ at <filename>unsupported/clean_setup.pl</filename> in a Cygwin mirror.
 <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>.
+<filename>/var/log/setup.log.full</filename> and less verbose information about
+prior actions is in <filename>/var/log/setup.log</filename>.
 </para>
 
 </answer></qandaentry>
 
 <qandaentry id="faq.setup.setup-fails">
-<question><para>What if setup fails?</para></question>
+<question><para>What if the Cygwin Setup program fails?</para></question>
 <answer>
 
-<para>First, make sure that you are using the latest version of Cygwin Setup.
+<para>First, make sure that you are using the latest version of the Cygwin Setup program.
 The latest version is always available from the Cygwin Home Page at
 <ulink url="https://cygwin.com/"/>.
 </para>
 <para>If you are downloading from the Internet, setup will fail if it cannot
-download the list of mirrors at <ulink url="https://cygwin.com/mirrors.html"/>.
+download the list of mirrors at <ulink url="https://cygwin.com/mirrors.lst"/>.
 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
+<para>If the Cygwin Setup program 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
+<para>If the Cygwin Setup program has otherwise behaved strangely, check the files
+<filename>setup.log</filename> and <filename>setup.log.full</filename> in
+<filename>/var/log</filename> (<filename>C:\cygwin\var\log</filename> 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,
+the Cygwin Setup program, options you selected, contents of setup.log and setup.log.full,
 what happened that wasn't supposed to happen, etc.
 </para>
 </answer></qandaentry>
@@ -517,8 +497,8 @@ translated to POSIX form.
 <listitem><para>Otherwise, use the pw_home field from the passwd entry as
 returned by <command>getent passwd</command>.  If you want to learn how this
 field is set by Cygwin and how you can change it, this is explained in great
-detail in the Cygwin User's Guide at
-<ulink url="https://cygwin.com/cygwin-ug-net/ntsec.html"/>.
+detail in the
+<ulink url="https://cygwin.com/cygwin-ug-net/ntsec.html">Cygwin User's Guide</ulink>.
 </para>
 </listitem>
 </orderedlist>
@@ -527,14 +507,14 @@ detail in the Cygwin User's Guide at
 <literal>HOME</literal> is always taken from the passwd entry.
 </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 
+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 Cygwin (on local drive).
 Note that ssh only considers the account information as retrieved by
-getpwnam(3), disregarding <literal>HOME</literal>. 
+getpwnam(3), disregarding <literal>HOME</literal>.
 </para>
 </answer></qandaentry>
 
@@ -542,7 +522,7 @@ getpwnam(3), disregarding <literal>HOME</literal>.
 <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
+<para>Run the Cygwin Setup program 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''.
@@ -553,19 +533,19 @@ the action reads ``Uninstall''.  Proceed by clicking ``Next''.
 <question><para>How do I uninstall a Cygwin service?</para></question>
 <answer>
 <orderedlist>
-<listitem><para>List all services you have installed with 
-<literal>cygrunsrv -L</literal>. If you do not have 
-<literal>cygrunsrv</literal> installed, skip this FAQ.
+<listitem><para>List all services you have installed with
+<command>cygrunsrv -L</command>. If you do not have
+<command>cygrunsrv</command> installed, skip this FAQ.
 </para></listitem>
-<listitem><para>Before removing the service, you should stop it with 
-<literal>cygrunsrv --stop <replaceable>service_name</replaceable></literal>. 
-If you have <literal>inetd</literal> configured to run as a standalone
-service, it will not show up in the list, but 
-<literal>cygrunsrv --stop inetd</literal> will work to stop it as 
+<listitem><para>Before removing the service, you should stop it with
+<command>cygrunsrv --stop <replaceable>service_name</replaceable></command>.
+If you have <command>inetd</command> configured to run as a standalone
+service, it will not show up in the list, but
+<command>cygrunsrv --stop inetd</command> will work to stop it as
 well.
-</para></listitem> 
+</para></listitem>
 <listitem><para>Lastly, remove the service with
-<literal>cygrunsrv --remove <replaceable>service_name</replaceable></literal>.
+<command>cygrunsrv --remove <replaceable>service_name</replaceable></command>.
 </para></listitem>
 </orderedlist>
 </answer></qandaentry>
@@ -573,28 +553,28 @@ well.
 <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 
+<para>Setup has no automatic uninstall facility.  The recommended method to remove all
 of Cygwin is as follows:
 </para>
 <orderedlist>
-<listitem><para>If you have any Cygwin services running, remove by repeating 
+<listitem><para>If you have any Cygwin services running, remove by repeating
 the instructions in <ulink
 url="https://cygwin.com/faq/faq.html#faq.setup.uninstall-service"/> 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>, 
-<literal>postgresql</literal>, and so on.
+installed are <command>sshd</command>, <command>cron</command>,
+<command>cygserver</command>, <command>inetd</command>, <command>apache</command>,
+<command>postgresql</command>, and so on.
 </para>
 </listitem>
-<listitem><para>Stop the X11 server if it is running, and terminate any Cygwin programs 
+<listitem><para>Stop the X11 server if it is running, and terminate any Cygwin programs
 that might be running in the background.  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 
+that no Cygwin processes remain.  Note: If you want to save your mount points for a later
+reinstall, first save the output of <command>mount -m</command> as described at
 <ulink url="https://cygwin.com/cygwin-ug-net/mount.html"/>.
 </para>
 </listitem>
-<listitem><para>If you installed <literal>cyglsa.dll</literal> by running the
-shell script <literal>/usr/bin/cyglsa-config</literal> as described in
+<listitem><para>If you installed <filename>cyglsa.dll</filename> by running the
+shell script <command>/usr/bin/cyglsa-config</command> as described in
 <ulink url="https://cygwin.com/cygwin-ug-net/ntsec.html"/>, then you need to
 configure Windows to stop using the LSA authentication package.  You do so by
 editing the registry and restoring
@@ -618,30 +598,30 @@ 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 by using other tools such as
-<literal>icacls.exe</literal> or directly from Cygwin by using
-<literal>chown</literal>.  Please note that you shouldn't use the
+<command>icacls</command> or directly from Cygwin by using
+<command>chown</command>.  Please note that you shouldn't use the
 recursive form of chown on directories that have other file systems
 mounted under them (specifically you must avoid
-<literal>/proc</literal>) since you'd change ownership of the files under those
+<filename>/proc</filename>) since you'd change ownership of the files under those
 mount points as well.
 </para>
 </listitem>
 <listitem><para>Delete the Cygwin shortcuts on the Desktop and Start Menu, and
-anything left by setup-x86{_64}.exe in the download directory.  However, if you
-plan to reinstall Cygwin it's a good idea to keep your setup-x86{_64}.exe
+anything left by the Cygwin Setup program in the download directory.  However, if you
+plan to reinstall Cygwin it's a good idea to keep your
 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 
+<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\Cygwin</literal> under <literal>HKEY_LOCAL_MACHINE</literal> and/or 
-<literal>HKEY_CURRENT_USER</literal>.  However, if you followed the directions above you 
+<listitem><para>Finally, if you want to be thorough you can delete the registry tree
+<literal>Software\Cygwin</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 everything important.  Typically only the installation
 directory has been stored in the registry at all.
 </para>
@@ -659,23 +639,23 @@ have not been tested.  Use them <emphasis role='bold'>only</emphasis> if there i
 bugfix that you need to try, and you are willing to deal with any
 problems, or at the request of a Cygwin developer.
 </para>
-<para>You cannot use Cygwin Setup to install a snapshot.
+<para>You cannot use the Cygwin Setup program to install a snapshot.
 </para>
 <para>First, you will need to download the snapshot from the snapshots
 page at <ulink url="https://cygwin.com/snapshots/"/>.  Note the directory where
 you saved the snapshot tarball.
 </para>
 <para>Before installing a snapshot, you must first Close <emphasis role='bold'>all</emphasis> Cygwin
-applications, including shells and services (e.g., <literal>inetd</literal>, <literal>sshd</literal>).
-You will not be able to replace <literal>cygwin1.dll</literal> if any Cygwin process is
+applications, including shells and services (e.g., <command>inetd</command>, <command>sshd</command>).
+You will not be able to replace <filename>cygwin1.dll</filename> if any Cygwin process is
 running.  You may have to restart Windows to clear the DLL from memory
 (beware of automatic service startup).
 </para>
-<para>Most of the downloaded snapshot can be installed using <literal>tar</literal>.  Cygwin
-<literal>tar</literal> won't be able to update <literal>/usr/bin/cygwin1.dll</literal> (because it's
-used by <literal>tar</literal> itself), but it should succeed with everything else.  If
+<para>Most of the downloaded snapshot can be installed using <command>tar</command>.  Cygwin
+<command>tar</command> won't be able to update <filename>/usr/bin/cygwin1.dll</filename> (because it's
+used by <command>tar</command> itself), but it should succeed with everything else.  If
 you are only installing the DLL snapshot, skip the first tar command.  Open
-a <literal>bash</literal> shell (it should be the only running Cygwin process) and issue
+a <command>bash</command> shell (it should be the only running Cygwin process) and issue
 the following commands:
 <screen>
 	/bin/tar -C / -xvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.* --exclude=usr/bin/cygwin1.dll
@@ -683,11 +663,11 @@ the following commands:
 </screen>
 </para>
 <para>Exit the bash shell, and use Explorer or the Windows command shell to
-first rename <literal>C:\cygwin\bin\cygwin1.dll</literal> to
-<literal>C:\cygwin\bin\cygwin1-prev.dll</literal> and then move
-<literal>C:\cygwin\tmp\usr\bin\cygwin1.dll</literal>
-to <literal>C:\cygwin\bin\cygwin1.dll</literal> (assuming you installed Cygwin in
-<literal>C:\cygwin</literal>).
+first rename <filename>C:\cygwin\bin\cygwin1.dll</filename> to
+<filename>C:\cygwin\bin\cygwin1-prev.dll</filename> and then move
+<filename>C:\cygwin\tmp\usr\bin\cygwin1.dll</filename> to
+<filename>C:\cygwin\bin\cygwin1.dll</filename> (assuming you installed Cygwin in
+<filename>C:\cygwin</filename>).
 </para>
 <para>The operative word in trying the snapshots is "<emphasis>trying</emphasis>".  If you
 notice a problem with the snapshot that was not present in the release
@@ -695,25 +675,25 @@ DLL (what we call a "regression"), please report it to the Cygwin
 mailing list (see <ulink url="https://cygwin.com/problems.html"/> for problem
 reporting guidelines).  If you wish to go back to the older version of the
 DLL, again, close all Cygwin processes, delete
-<literal>C:\cygwin\bin\cygwin1.dll</literal>, and
-rename <literal>C:\cygwin\bin\cygwin1-prev.dll</literal> back to
-<literal>C:\cygwin\bin\cygwin1.dll</literal> (again assuming that your "<literal>/</literal>" is
-<literal>C:\cygwin</literal>).  To restore the rest of the snapshot
-files, reinstall the "<literal>cygwin</literal>" package using Setup.
+<filename>C:\cygwin\bin\cygwin1.dll</filename>, and
+rename <filename>C:\cygwin\bin\cygwin1-prev.dll</filename> back to
+<filename>C:\cygwin\bin\cygwin1.dll</filename> (again assuming that your "<literal>/</literal>" is
+<filename>C:\cygwin</filename>).  To restore the rest of the snapshot
+files, reinstall the "<literal>cygwin</literal>" package using the Cygwin Setup program.
 </para>
 
 </answer></qandaentry>
 
 <qandaentry id="faq.setup.mirror">
-<question><para>Can Cygwin Setup maintain a ``mirror''?</para></question>
+<question><para>Can the Cygwin Setup program maintain a ``mirror''?</para></question>
 <answer>
 
-<para>NO.  Cygwin Setup cannot do this for you.  Use a tool designed for
+<para>NO. The Cygwin Setup program cannot do this for you.  Use a tool designed for
 this purpose.  See <ulink url="http://rsync.samba.org/"/>,
 <ulink url="http://www.gnu.org/software/wget/"/> 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="https://sourceware.org/cygwin-apps/setup.html"/>.
+the <ulink url="https://sourceware.org/cygwin-apps/setup.html">Cygwin Setup program page</ulink>.
+
 </para>
 </answer></qandaentry>
 
diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml
index c24ecf6c5a..95d7abd628 100644
--- a/winsup/doc/faq-using.xml
+++ b/winsup/doc/faq-using.xml
@@ -12,10 +12,10 @@
 
 <para>Well, something has gone wrong somehow...
 </para>
-<para>To repair the damage, you must run Cygwin Setup again, and re-install the
+<para>To repair the damage, you must run the Cygwin Setup program again, and re-install the
 package which provides the missing DLL package.
 </para>
-<para>If you already installed the package at one point, Cygwin Setup won't
+<para>If you already installed the package at one point, the Cygwin Setup program won't
 show the option to install the package 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
@@ -70,7 +70,7 @@ a number of other things you can look into:</para>
     setup. This particularly affects AD clients, but there may be other
     things in your Cygwin startup that depend on getting fast answers
     back from a network server.</para>
-    
+
     <para>Keep in mind that this may affect Cygwin even when the domain
     controller is on the same machine as Cygwin, or is on a nearby
     server. A bad DNS server IP can cause long delays while the local
@@ -155,11 +155,11 @@ appears in the terminal.</para>
 <answer>
 
 <para>If suddenly <emphasis>every</emphasis> command takes a
-<emphasis>very</emphasis> long time, then something is probably attempting to 
+<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.  Using <literal>//c</literal> means
 to contact the <emphasis>network server</emphasis> <literal>c</literal>, which
-will slow things down tremendously if it does not exist.  
+will slow things down tremendously if it does not exist.
 </para>
 </answer></qandaentry>
 
@@ -170,8 +170,9 @@ will slow things down tremendously if it does not exist.
 <para>If your service is one of those which switch the user context
 (sshd, inetd, etc), then it depends on the method used to switch to
 another user.  This problem as well as its solution is described in
-detail in the Cygwin User's Guide, see
-<ulink url="https://cygwin.com/cygwin-ug-net/ntsec.html"/>.
+detail in the Cygwin User's Guide, see Chapter 3 on
+<ulink url="https://cygwin.com/cygwin-ug-net/ntsec.html">POSIX accounts,
+permissions, and security</ulink>.
 </para>
 <para>Workarounds include using public network share that does not require
 authentication (for non-critical files), providing your password to a
@@ -188,7 +189,7 @@ information).
 
 <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
+the Cygwin Setup program. The line is
 </para>
 <screen>
 	PATH="/usr/local/bin:/usr/bin:/bin:$PATH"
@@ -311,7 +312,7 @@ or
 (*.lnk files).  It sees a shortcut as a regular file and this you
 cannot "cd" into it.
 </para>
-<para>Cygwin is also capable to create POSIX symlinks as Windows shortcuts 
+<para>Cygwin is also capable to create POSIX symlinks as Windows shortcuts
 (see the CYGWIN environment variable option "winsymlinks"), but these
 shortcuts are different from shortcuts created by native Windows
 applications.  Windows applications can usually make use of Cygwin
@@ -331,7 +332,7 @@ recognize it as symlink anymore.
 <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
+aren't picking up the Windows 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
@@ -387,16 +388,18 @@ must create the whatis database.  Just run the command
 <question><para>Why doesn't <literal>chmod</literal> work?</para></question>
 <answer>
 
-<para>If you're using FAT32 instead of NTFS, <literal>chmod</literal> 
+<para>If you're using FAT32 instead of NTFS, <literal>chmod</literal>
 will fail since FAT32 does not provide any permission information.
 You should really consider converting the drive to NTFS with
 <literal>CONVERT.EXE</literal>.  FAT and FAT32 are barely good enough
 for memory cards or USB sticks to exchange pictures...
 </para>
-<para>For other cases, understand that Cygwin attempts to show UNIX 
-permissions based on the security features of Windows, so the Windows 
-ACLs are likely the source of your problem.  See the Cygwin User's 
-Guide at <ulink url="https://cygwin.com/cygwin-ug-net/ntsec.html"/>
+<para>For other cases, understand that Cygwin attempts to show UNIX
+permissions based on the security features of Windows, so the Windows
+ACLs are likely the source of your problem.  See the Cygwin User's
+Guide Chapter 3 on
+<ulink url="https://cygwin.com/cygwin-ug-net/ntsec.html">POSIX accounts,
+permission, and security</ulink>
 for more information on how Cygwin maps Windows permissions.
 </para>
 </answer></qandaentry>
@@ -410,7 +413,7 @@ for more information on how Cygwin maps Windows permissions.
 It could be missing some features you might expect in
 <command>/bin/sh</command>, if you are used to <command>/bin/sh</command>
 actually being <command>zsh</command> (MacOS X "Panther") or
-<command>ksh</command> (Tru64).  
+<command>ksh</command> (Tru64).
 </para>
 
 <para>Or, it could be a permission problem, and Cygwin doesn't understand
@@ -484,7 +487,7 @@ formfeed character to your file.
 
 <para>Internationalization is a complex issue. The short answer is that
 Cygwin relies on the setting of the setting of LANG/LC_xxx environment
-variables. The long answer can be found in the User's Guide in the
+variables. The long answer can be found in the Cygwin User's Guide in the
 section <ulink url="https://cygwin.com/cygwin-ug-net/setup-locale.html">Internationalization</ulink>
 </para>
 
@@ -537,11 +540,11 @@ if you have one a single Cygwin installation, for example, if you update the
 Cygwin package without exiting <emphasis>all</emphasis> Cygwin apps (including
 services like sshd) beforehand.</para>
 <para>The only DLL that is sanctioned by the Cygwin project is the one that
-you get by running <ulink url="https://cygwin.com/install.html">setup-x86.exe or setup-x86_64.exe</ulink>,
+you get by running the Cygwin <ulink url="https://cygwin.com/install.html">Setup program</ulink>,
 installed in a 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>.
+the Cygwin Setup program.
 </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
@@ -592,7 +595,7 @@ DLL on top of a newer DLL, my application will break?
 It depends on what you mean by "break".  If the application installs a
 version of the Cygwin DLL in another location than Cygwin's /bin
 directory then the rules in
-<xref linkend="faq.using.third-party.multiple-copies"></xref> apply. 
+<xref linkend="faq.using.third-party.multiple-copies"></xref> apply.
 If the application installs an older version of the DLL in /bin then you
 should complain loudly to the application provider.
 </para><para>
@@ -631,7 +634,7 @@ 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. 
+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
@@ -688,7 +691,7 @@ Then <literal>/cygdrive/c/Windows</literal> becomes <literal>/c/Windows</literal
 little less typing.
 </para>
 <para>Note that you have to enter the mount point into the
-<filename>/etc/fstab</filename> file to keep it indefinitely. 
+<filename>/etc/fstab</filename> file to keep it indefinitely.
 The mount command will only add the mount point for the lifetime
 of your current Cygwin session.
 </para>
@@ -711,10 +714,10 @@ and middle-mouse pastes.  It couldn't be easier!
 The options contain a toggle button, named "Quick edit mode".  It must
 be ON.  Save the properties.
 </para>
-<para>You can also bind the insert key to paste from the clipboard by adding 
-the following line to your .inputrc file: 
+<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 
+	"\e[2~": paste-from-clipboard
 </screen>
 </para>
 </answer></qandaentry>
@@ -744,7 +747,7 @@ Note that with many of these products, simply disabling the firewall
 does not remove these changes; it must be completely uninstalled.
 </para>
 <para>See also <ulink url="https://cygwin.com/faq/faq.html#faq.using.bloda"/>
-for a list of applications that have been known, at one time or another, to 
+for a list of applications that have been known, at one time or another, to
 interfere with the normal functioning of Cygwin.
 </para>
 </answer></qandaentry>
@@ -794,9 +797,10 @@ interesting.  E.g., the perl distribution has a file called
 letters 'aux' in it will hang.
 </para>
 <para>At least that's what happens when using native Windows tools.  Cygwin
-can deal with these filenames just fine.  Again, see the User's Guide at
-<ulink url="https://cygwin.com/cygwin-ug-net/using-specialnames.html"/>
-for a detailed description of what's possible with filenames and what is not.
+can deal with these filenames just fine.  Again, see the Cygwin User's Guide
+for a detailed description of
+<ulink url="https://cygwin.com/cygwin-ug-net/using-specialnames.html">
+what's possible with filenames and what is not</ulink>.
 </para>
 </answer></qandaentry>
 
@@ -882,7 +886,7 @@ this is still a problem, however.)
 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.
+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
@@ -979,9 +983,10 @@ samba configuration file:
 
 <para>Note that the 0775 can be anything as long as the 0010 bit is set.
 </para>
-<para>Alternatively, use Windows shortcuts as symlinks.  See the CYGWIN
+<para>Alternatively, use Windows shortcuts as symlinks.  See the
+<ulink url="https://cygwin.com/cygwin-ug-net/using-cygwinenv.html">CYGWIN</ulink>
 environment variable option "winsymlinks:lnk"
-<ulink url="https://cygwin.com/cygwin-ug-net/using-cygwinenv.html"/>
+
 Note that Samba does not support reparse points so some methods to
 create symlinks are just not available.
 </para>
@@ -1116,7 +1121,7 @@ look at the server's <filename>~/.ssh/authorized_keys</filename> file.</para>
 
 <para>To fix the permissions of your private key file or your
 <filename>~/.ssh/authorized_keys</filename> file, simply use the
-<command>setfacl</command> command with the <literal>-b</literal> option. 
+<command>setfacl</command> command with the <literal>-b</literal> option.
 This removes all additional ACL entries and thus fixes the permissions to
 be not too open:</para>
 
@@ -1402,10 +1407,10 @@ such as virtual memory paging and file caching.</para>
     <listitem>
       <para>
 	Force a full rebase: Run <command>rebase-trigger fullrebase</command>,
-	exit all Cygwin programs and run Cygwin setup.
+	exit all Cygwin programs and run the Cygwin Setup program.
       </para>
       <para>
-	By default, Cygwin's setup program automatically performs an incremental
+	By default, the Cygwin Setup program automatically performs an incremental
 	rebase of newly installed files.  Forcing a full rebase causes the
 	rebase map to be cleared before doing the rebase.
       </para>
@@ -1448,11 +1453,12 @@ such as virtual memory paging and file caching.</para>
 	They also may not provide any obvious way to keep the Cygwin packages
 	their application uses up to date with fixes for security issues and
 	upgrades.</para>
-    <para>The solution is simply downloading and running Cygwin Setup,
-	following the instructions in the Internet Setup section of
+    <para>The solution is simply downloading and running the Cygwin Setup program,
+	following the instructions in the
 	<ulink url="https://cygwin.com/cygwin-ug-net/setup-net.html#internet-setup">
-	    Setting Up Cygwin</ulink> in the Cygwin User's Guide.</para>
-    <para>Please exit from all applications before running Cygwin Setup.
+	Internet Setup</ulink> section of ``Setting Up Cygwin'' in the
+	Cygwin User's Guide.</para>
+    <para>Please exit from all applications before running the Cygwin Setup program.
 	When running Setup, you should not change most of the values presented,
 	just select the <literal>Next</literal> button in most cases, as you
 	already have a Cygwin release installed, and only want to upgrade your
@@ -1463,7 +1469,7 @@ such as virtual memory paging and file caching.</para>
 	faster downloads, as shown, with more details to help you choose, on the
 	<ulink url="https://cygwin.com/mirrors.html">
 	    Mirror Sites</ulink> web page.</para>
-    <para>Cygwin Setup will download and apply upgrades to all packages
+    <para>The Cygwin Setup program will download and apply upgrades to all packages
 	required for Cygwin itself and installed applications.
 	Any problems with applying updates, or the application after updates,
 	should be reported to the project or product supplier for remedial
diff --git a/winsup/doc/faq-what.xml b/winsup/doc/faq-what.xml
index ea8496ccbc..90d30d60bd 100644
--- a/winsup/doc/faq-what.xml
+++ b/winsup/doc/faq-what.xml
@@ -54,9 +54,9 @@ for download and setup, a current list of mirror sites, a User's
 Guide, an API Reference, mailing lists and archives.
 </para>
 <para>You can find documentation for the individual GNU tools typically
-as man pages or info pages as part of the Cygwin net distribution.
-Additionally you can get the latest docs at
-<ulink url="http://www.gnu.org/manual"/>.
+as man pages or info pages as part of the Cygwin distribution.
+Additionally you can get the latest documents for many tools at the
+<ulink url="http://www.gnu.org/manual">GNU manuals archive</ulink>.
 </para>
 </answer></qandaentry>
 

Re: FAQ Proposed Updates Summary and Preview Diff

[Corinna Vinschen]

Hi Brian,

On Jul 16 21:35, Brian Inglis wrote:
> Just want to get feedback on how these FAQ changes should be packaged as patches
> (separate, series, single) and whether some of the changes should not be applied
> at all.
> 
> Summary
> 
> General:
> 
> change setup references to use the Cygwin Setup program;
> change Win32 references to Windows;

Please, no.  At least not where Win32 refers to the API.  While this is
called "Windows API" these days, the word Windows alone doesn't really
cut it.  At leats use "Windows API" then, or IMHO even better, use the
informal "WinAPI" abbreviation.

> reword net release or distribution references;

Uhm... example?  I'm not sure what you mean here.

> emphasize 64-bit Cygwin and setup-x86_64 over 32-bit;
> change see <ulink/> to place links around available wording;
> change <literal> for <filename> or <command> where appropriate;
> change bash .{ext1,ext2} usage to .ext1/.ext2;

Using comma separated lists within curly braces is the offical
shell way to express alternatives:

  $ echo a.{b,c}
  a.b a.c

Please keep them as is.

> trim trailing spaces highlighted by git diff.


Thanks,
Corinna

-- 
Corinna Vinschen
Cygwin Maintainer

Re: FAQ Proposed Updates Summary and Preview Diff

[Brian Inglis]

On 2020-07-17 05:17, Corinna Vinschen wrote:
> On Jul 16 21:35, Brian Inglis wrote:
>> Just want to get feedback on how these FAQ changes should be packaged as patches
>> (separate, series, single) and whether some of the changes should not be applied
>> at all.

What about how they should be committed - by file or all in one, and submitted -
separately by file, or as a FAQ patch series?

>> Summary
>>
>> General:
>>
>> change setup references to use the Cygwin Setup program;
>> change Win32 references to Windows;
> 
> Please, no.  At least not where Win32 refers to the API.  While this is
> called "Windows API" these days, the word Windows alone doesn't really
> cut it.  At leats use "Windows API" then, or IMHO even better, use the
> informal "WinAPI" abbreviation.

Good idea - will check and change depending on context.

>> reword net release or distribution references;
> 
> Uhm... example?  I'm not sure what you mean here.

They look like original wording from when there were Cygnus/Red Hat releases and
net releases: the distinction has been moot and the phrase not used in these
lists for years.

>> emphasize 64-bit Cygwin and setup-x86_64 over 32-bit;
>> change see <ulink/> to place links around available wording;
>> change <literal> for <filename> or <command> where appropriate;
>> change bash .{ext1,ext2} usage to .ext1/.ext2;
> 
> Using comma separated lists within curly braces is the offical
> shell way to express alternatives:
> 
>   $ echo a.{b,c}
>   a.b a.c
> 
> Please keep them as is.

These usages are in descriptions, not in shell command contexts, and not used in
most (POSIX) scripts, so many users will not recognize this convention, not even
those who do some scripts but are inexperienced.
My fingers are trained in their use, but would use them in text only to other
developers. ;^>

>> trim trailing spaces highlighted by git diff.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in IEC units and prefixes, physical quantities in SI.]

Re: FAQ Proposed Updates Summary and Preview Diff

[Corinna Vinschen]

On Jul 17 06:50, Brian Inglis wrote:
> On 2020-07-17 05:17, Corinna Vinschen wrote:
> > On Jul 16 21:35, Brian Inglis wrote:
> >> Just want to get feedback on how these FAQ changes should be packaged as patches
> >> (separate, series, single) and whether some of the changes should not be applied
> >> at all.
> 
> What about how they should be committed - by file or all in one, and
> submitted - separately by file, or as a FAQ patch series?

By theme would be preferrable.  I.e, one patch Win32 -> WinAPI, one
patch ulink changes, etc.

> >> Summary
> >>
> >> General:
> >>
> >> change setup references to use the Cygwin Setup program;
> >> change Win32 references to Windows;
> > 
> > Please, no.  At least not where Win32 refers to the API.  While this is
> > called "Windows API" these days, the word Windows alone doesn't really
> > cut it.  At leats use "Windows API" then, or IMHO even better, use the
> > informal "WinAPI" abbreviation.
> 
> Good idea - will check and change depending on context.
> 
> >> reword net release or distribution references;
> > 
> > Uhm... example?  I'm not sure what you mean here.
> 
> They look like original wording from when there were Cygnus/Red Hat
> releases and net releases: the distinction has been moot and the
> phrase not used in these lists for years.

Oh, all right.  "Cygwin distro" is the new "net distro", I guess.

> >> emphasize 64-bit Cygwin and setup-x86_64 over 32-bit;
> >> change see <ulink/> to place links around available wording;
> >> change <literal> for <filename> or <command> where appropriate;
> >> change bash .{ext1,ext2} usage to .ext1/.ext2;
> > 
> > Using comma separated lists within curly braces is the offical
> > shell way to express alternatives:
> > 
> >   $ echo a.{b,c}
> >   a.b a.c
> > 
> > Please keep them as is.
> 
> These usages are in descriptions, not in shell command contexts, and
> not used in most (POSIX) scripts, so many users will not recognize
> this convention, not even those who do some scripts but are
> inexperienced.  My fingers are trained in their use, but would use
> them in text only to other developers. ;^>

Well, most of the descriptions are written for developers in the first
place.  But, be it as it is, I don't see an advantage in using
slash-separated lists here.  Whatever you use, it's a documentation
convention and there's always somebody puzzeling over them.  Usually
you fix this by adding a "conventions in this document" chapter, but at
least the curly braces have a known meaning to devs, while something
with slashes in it typically means a path.


Corinna

-- 
Corinna Vinschen
Cygwin Maintainer