WSDG: Stop recommending Cygwin.

Note in the quick setup and tools documentation that we no longer
require or recommend Cygwin.

Change-Id: Ie0eb92c5817ae1d786136035adf8fa3988c8b98d
Reviewed-on: https://code.wireshark.org/review/27244
Reviewed-by: Guy Harris <guy@alum.mit.edu>

2 files changed, 160 insertions, 237 deletions

diff --git a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
index c6d9961559..a27cf8bfcf 100644
--- a/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
+++ b/docbook/wsdg_src/WSDG_chapter_quick_setup.asciidoc
@@ -40,21 +40,6 @@ Known traps are:
 
 ====
 
-[[ChSetupChocolatey]]
-
-==== Recommended: Install Chocolatey
-
-https://chocolatey.org/[Chocolatey] is a native package manager for Windows.
-There are https://chocolatey.org/packages[packages] for most of the software
-listed below. Along with traditional Windows packages it supports Cygwin and
-the Python Package Index.
-
-// ...such as:
-// - Active Perl and/or StrawberryPerl
-// - Devbox-UnZip and/or 7zip and/or peazip
-// - Wget
-// - Git (a native win32 (MSYS) version)
-
 [[ChSetupMSVC]]
 
 ==== Install Microsoft C compiler and SDK
@@ -123,6 +108,36 @@ directory, e.g. _C:\Qt\5.9.1\msvc2015_64_
 The Qt maintenance tool (_C:\Qt\MaintenanceTool.exe_) can be used to
 upgrade Qt to newer versions.
 
+[[ChSetupChocolatey]]
+
+==== Recommended: Install Chocolatey
+
+https://chocolatey.org/[Chocolatey] is a native package manager for
+Windows. There are https://chocolatey.org/packages[packages] for most of
+the software listed below. Along with traditional Windows packages it
+supports the Python Package Index and Cygwin.
+
+Chocolatey tends to install packages into its own path (%ChocolateyInstall%).
+In most cases this is OK, but in some instances (Python in particular)
+this might not be what you want. You can install Chocolatey packages
+using the command `choco install`.
+
+[source,cmd]
+----
+> rem Flex and Bison are required.
+> choco install winflexbison
+> rem Git, CMake, Perl, Python, etc are also required, but can be installed
+> rem via their respective installation packages.
+> choco install git cmake
+> rem Choose one of Strawberry...
+> choco install strawberryperl
+> rem ...or ActiveState Perl
+> choco install activeperl
+> rem This will likely install Python in a non-standard location, but
+> rem should otherwise work.
+> choco install python3
+----
+
 [[ChSetupCygwin]]
 
 ==== Optional: Install Cygwin
@@ -132,8 +147,14 @@ On 32-bit Windows, http://www.cygwin.com/setup-x86.exe[download the
 http://www.cygwin.com/setup-x86_64.exe[download the 64-bit Cygwin
 installer] and start it.
 
-Over time the Wireshark development toolchain has been migrating away from Cygwin
-toward native tools and we hope to eliminate it as a requirement someday.
+[NOTE]
+.Cygwin is no longer required
+====
+In the past the Wireshark development toolchain depended on Cygwin, but
+it it no longer required. Although you can often use the Cygwin version
+of a particular tool for Wireshark development that's not always the
+case.
+====
 
 At the "Select Packages" page, you'll need to select
 some additional packages which are not installed by default.
@@ -141,19 +162,17 @@ Navigate to the required Category/Package row and, if the package
 has a "Skip" item in the "New" column, click on the "Skip" item
 so it shows a version number for:
 
-* Devel/bison (or install Win flex-bison - see Chocolatey below)
+* Devel/bison (or install Win flex-bison -- see Chocolatey above)
 
-* Devel/flex (or install Win flex-bison - see Chocolatey below)
+* Devel/flex (or install Win flex-bison -- see Chocolatey above)
 
-* Devel/git (recommended - see discussion about using Git below)
+* Devel/git (recommended, but it's also available via Chocolatey -- see the Git discussion below)
 
 * Interpreters/perl
 
 * Utils/patch (only if needed) (may be Devel/patch instead)
 
-* Web/wget (not needed if using CMake)
-
-* Text/docbook-xml45
+* Text/docbook-xml45 (only needed if you're building the documenation)
 
 // Also need: bash/sh, sed
 
@@ -184,13 +203,6 @@ You can directly download packages via `cyg-get`
 PS$>cyg-get docbook-xml45 [...]
 ----
 
-You can use Chocolatey’s Win flex-bison packages rather than the Cygwin
-Bison and Flex package:
-
-----
-PS$>choco install winflexbison
-----
-
 [[ChSetupPython]]
 
 ==== Install Python
@@ -223,7 +235,7 @@ Chocolatey installs Python in _C:\tools\python3_ and _C:\tools\python2_ by defau
 Please note that the following is not required to build Wireshark but can be
 quite helpful when working with the sources.
 
-Working with the Git source repositories is highly recommended, see
+Working with the Git source repositories is highly recommended, as described in
 <<ChSrcObtain>>. It is much easier to update a personal source tree (local repository) with Git
 rather than downloading a zip file and merging new sources into a personal
 source tree by hand. It also makes first-time setup easy and enables the
@@ -277,7 +289,7 @@ the default location.  Ensure the directory containing cmake.exe is added to you
 Alternatively you can install CMake using Chocolatey:
 
 ----
-PS$>choco install cmake.portable
+PS$>choco install cmake
 ----
 
 Chocolatey ensures cmake.exe is on your path.
@@ -287,7 +299,7 @@ Chocolatey ensures cmake.exe is on your path.
 ==== Install Asciidoctor, Xsltproc, And DocBook
 
 http://asciidoctor.org/[Asciidoctor] can be run directly as a Ruby
-script or via a Java wrapper (AsciidoctorJ). It is used in conjuntion
+script or via a Java wrapper (AsciidoctorJ). It is used in conjunction
 with Xsltproc and DocBook to generate the documenation you're reading
 and the User’s Guide.
 
diff --git a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc
index e7c269733c..b17f950ebd 100644
--- a/docbook/wsdg_src/WSDG_chapter_tools.asciidoc
+++ b/docbook/wsdg_src/WSDG_chapter_tools.asciidoc
@@ -8,23 +8,21 @@
 
 === Introduction
 
-This chapter will provide you with information about the
-various tools needed for Wireshark development.
-
-None of the tools mentioned in this chapter are needed to
-run Wireshark; they are only needed to build it.
-
-Most of these tools have their roots on UNIX like
-platforms, but Windows ports are also available. Therefore the
-tools are available in different "flavours":
-
-* UNIX (or Windows Cygwin): the tools should be commonly available on the
-  supported UNIX platforms, and for Windows platforms by using the Cygwin UNIX
-  emulation
-* Windows native: some tools are available as native Windows tools, no special
-  emulation is required.  Many of these tools can be installed (and updated)
-  using http://chocolatey.org[Chocolatey], a Windows package manager similar
-  to the Linux package managers apt-get or yum.
+This chapter will provide you with information about the various tools
+needed for Wireshark development. None of the tools mentioned in this
+chapter are needed to run Wireshark. They are only needed to build it.
+
+Most of these tools have their roots on UNIX or UNIX-like platforms such
+as Linux, but Windows ports are also available. Therefore the tools are
+available in different "flavours":
+
+* UNIX: The tools should be commonly available on the supported UNIX
+  platforms and for Windows platforms by using an emulation layer such
+  as Cygwin.
+* Windows native: Some tools are available as native Windows tools, no
+  special emulation is required.  Many of these tools can be installed
+  (and updated) using http://chocolatey.org[Chocolatey], a Windows
+  package manager similar to the Linux package managers apt-get or yum.
 
 [WARNING]
 .Follow the directions
@@ -64,106 +62,36 @@ or a Powershell prompt:
 PS:\>iex ((new-object net.webclient).DownloadString(_https://chocolatey.org/install.ps1_))
 ----
 
-Chocolatey sometimes installs packages in unexpected locations. Cygwin is a notable
-example -- recent versions of the Cygwin package are installed in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ instead of Cygwin’s default location
-(_C:\cygwin_ or _C:\cygwin64_).
+Chocolatey sometimes installs packages in unexpected locations. Python
+is a notable example. While it's typically installed in a top-level
+directory, e.g. _C:\Python27_ or in %PROGRAMFILES%, e.g. _C:\Program
+Files\Python36_, Chocolatey tends to install it under
+_C:\ProgramData\chocolatey_ or _C:\Tools_. If you want to avoid this
+behavior you'll probabaly want to install Python using the packages from
+python.org.
 
 [[ChToolsCygwin]]
 
 === Windows: Cygwin
 
-Cygwin provides a lot of UNIX based tools on the Windows platform. It uses a UNIX
-emulation layer which might be a bit slower compared to the native Windows tools,
-but at an acceptable level. The installation and update is pretty easy and done
-through a single utility, _setup-x86.exe_ for 32-bit Windows and
-_setup-x86_64.exe_ for 64-bit Windows.
-
-Over time the Wireshark development toolchain has been migrating away from Cygwin
-toward native tools and we hope to eliminate it as a requirement someday.
-
-Although Cygwin consists of several separate packages, the installation
-and update is done through a single utility, _setup-x86.exe_ or
-_setup-x86_64.exe_, which acts similarly to other web based installers.
-You can install Cygwin and its packages using Chocolatey, but this is not
-recommended due to Chocolatey’s default installation location, described
-in the previous section.
-
-==== Installing Cygwin using the Cygwin installer
-
-You will find _setup-x86.exe_, for 32-bit systems, and
-_setup-x86_64.exe_, for 64-bit systems, at
-http://www.cygwin.com/install.html[]. Click on the link for the
-appropriate setup utility to download it. After the download completes,
-run it.
-
-All tools will be installed into one base folder. The default is
-_C:\cygwin_ for the 32-bit installer and _C:\cygwin64_ for the 64-bit
-installer.
-
-The setup utility will ask you for some settings. The defaults
-should usually work well, at least initially.
-
-If, at the "Choose A Download Source" page, you use the default "Install
-from Internet" setting, you will need to choose a download site at the
-"Choose A Download Site" page. See the list of mirror sites at
-http://cygwin.com/mirrors.html[] to choose a download site appropriate
-to your location.
-
-At the "Select Packages" page, you'll need to select some additional
-packages, which are not installed by default.  Navigate to the required
-Category/Package row and click on the "Skip" item in the "New" column so
-it shows a version number for the required package.
-
-After clicking the Next button several times the setup
-will then download and install the selected packages (this may
-take a while, depending on the package size).
-
-Under menu:Start[Programs,Cygwin,Cygwin Bash Shell] you should now be able to start
-a new Cygwin bash shell, which is similar to the standard Windows Command Prompt
-(cmd.exe) but much more powerful.
-
-[[ChToolsCygwinPackages]]
-
-==== Add/Update/Remove Cygwin Packages
-
-If you want to add, update, or remove packages later you can do so by
-running the setup utility again.  At the "Select Packages" page, the
-entry in the "New" column will control what is done (or not) with the
-package.  If a new version of a package is available, the new version
-number will be displayed, so it will be automatically updated.  You can
-change the current setting by simply clicking at it, it will change
-between:
-
-* _A specific version number._ This specific package version will be installed.
-
-* _Skip._ Not installed, no changes.
+Cygwin provides a lot of UNIX based tools on the Windows platform. It
+uses a UNIX emulation layer which might be a bit slower compared to the
+native Windows tools, but at an acceptable level. The installation and
+update is pretty easy and done through a single utility, _setup-x86.exe_
+for 32-bit Windows and _setup-x86_64.exe_ for 64-bit Windows. However,
+it can also be problematic. Cygwin utilities have a non-standard view of
+the filesystem, and sometimes things don't work as expected. For
+example, many files in _/usr/bin_ are symlinks which can't be run
+directly from Windows.
 
-* _Keep._ Already installed, no changes.
-
-* _Uninstall._ Uninstall this package.
-
-* _Reinstall._ Reinstall this package.
-
-==== Installing Cygwin using Chocolatey
-
-Chocolatey supports Cygwin as an external package source.
-To install Cygwin itself run
-
-[source,cmd]
-----
-PS$>choco install cygwin
-# You might also need to install cyg-get:
-PS$>choco install cyg-get
-----
-
-Chocolatey installs Cygwin in _C:\ProgramData\chocolatey\lib\Cygwin\tools\cygwin_ by default.
-
-One or more Cygwin packages can be installed using `cyg-get`:
-
-[source,cmd]
-----
-PS$>cyg-get sed asciidoc
-----
+[NOTE]
+.Cygwin is no longer required
+====
+In the past the Wireshark development toolchain depended on Cygwin, but
+it it no longer required. Although you can often use the Cygwin version
+of a particular tool for Wireshark development that's not always the
+case.
+====
 
 [[ChToolsCMake]]
 
@@ -213,7 +141,7 @@ optional libraries have xxx_INCLUDE_DIR and xxx_LIB flags that let you
 control their discovery.
 
 
--DPYTHON_EXECUTABLE=c:/Python27/python:: Force the Python path. Useful on Windows since Cygwin’s /usrbin/python is a symlink.
+-DPYTHON_EXECUTABLE=c:/Python36/python:: Force the Python path. Useful on Windows since Cygwin’s _/usr/bin/python_ is a symlink.
 
 -DENABLE_APPLICATION_BUNDLE=OFF:: Disable building an application bundle (Wireshark.app) on macOS
 
@@ -774,14 +702,11 @@ The bash shell is needed to run several shell scripts.
 
 [[ChToolsGNUBash]]
 
-==== UNIX and Cygwin: GNU bash
+==== UNIX: GNU Bash
 
-The bash shell is available for most of the UNIX-like
-platforms and as the bash package from the
-<<ChToolsCygwin,Cygwin setup>>.
-
-If bash isn't already installed or
-available as a package for your platform, you can get it at
+Bash (the GNU Bourne-Again SHell) is available for most UNIX and
+UNIX-like platforms. If it isn't already installed or available as a
+package for your platform, you can get it at
 http://www.gnu.org/software/bash/bash.html[].
 
 After correct installation, typing at the bash command line prompt:
@@ -794,13 +719,11 @@ $ bash --version
 should result in something like:
 
 ----
-GNU bash, version 3.1.17(6)-release (i686-pc-cygwin)
-Copyright (C) 2005 Free Software Foundation, Inc.
+GNU bash, version 4.4.12(1)-release (x86_64-pc-linux-gnu)
+Copyright (C) 2016 Free Software Foundation, Inc.
 ----
 
-However, the version string may vary.
-
-[[ChToolsWindowsBash]]
+Your version string will likely vary.
 
 [[ChToolsPython]]
 
@@ -808,9 +731,8 @@ However, the version string may vary.
 
 http://python.org/[Python] is an interpreted programming language. It is
 used to generate some source files, documenation, and other tasks.
-Python 2.5 or later (including Python 3) should work fine and Python 3.5 and
-2.7 are recommended. If you're building documentation you must have Python
-2 installed since AsciiDoc doesn't support Python 3.
+Python 2.5 or later (including Python 3) should work fine and Python 3 is
+recommended. It may be required in the future.
 
 Python is either included or available as a package on most UNIX-like platforms.
 Windows packages and source are available at http://python.org/download/[].
@@ -872,15 +794,11 @@ and above should work fine.
 
 [[ChToolsUnixPerl]]
 
-==== UNIX and Cygwin: Perl
+==== UNIX: Perl
 
-Perl is available for most of the UNIX-like platforms
-and as the perl package from the
-<<ChToolsCygwin,Cygwin setup>>.
-
-If perl isn't already installed or available
-as a package for your platform, you can get it at
-http://www.perl.com/[].
+Perl is available for most UNIX and UNIX-like platforms. If perl isn't
+already installed or available as a package for your platform, you can
+get it at http://www.perl.com/[].
 
 After correct installation, typing at the
 bash command line prompt:
@@ -893,62 +811,62 @@ $ perl --version
 should result in something like:
 
 ----
-This is perl, v5.8.7 built for cygwin-thread-multi-64int
-(with 1 registered patch, see perl -V for more detail)
+This is perl 5, version 26, subversion 0 (v5.26.0) built for x86_64-linux-gnu-thread-multi
+(with 62 registered patches, see perl -V for more detail)
 
-Copyright 1987-2005, Larry Wall
+Copyright 1987-2017, Larry Wall
 
 Perl may be copied only under the terms of either the Artistic License or the
 GNU General Public License, which may be found in the Perl 5 source kit.
 
 Complete documentation for Perl, including FAQ lists, should be found on
-this system using *`man perl'* or *`perldoc perl'*.  If you have access to the
-Internet, point your browser at http://www.perl.com/, the Perl Home Page.
+this system using "man perl" or "perldoc perl".  If you have access to the
+Internet, point your browser at http://www.perl.org/, the Perl Home Page.
 ----
 
 However, the version string may vary.
 
-//[[ChToolsWindowsPerl]]
-//
-//==== Windows native: Perl
-//
-//A native Windows Perl package can be obtained from
-//http://www.ActiveState.com[Active State] or http://strawberryperl.com/[Strawberry Perl]. The installation
-//should be straightforward.
-//
-//You may also use Chocolatey to install either package:
-//
-//----
-//PS:\> choco install ActivePerl
-//----
-//
-//or
-//
-//----
-//PS:\> choco install StrawberryPerl
-//----
-//
-//After correct installation, typing at the command
-//line prompt (cmd.exe):
-//
-//----
-//> perl -v
-//----
-//
-//should result in something like:
-//
-//----
-//This is perl, v5.8.0 built for MSWin32-x86-multi-thread
-//(with 1 registered patch, see perl -V for more detail)
-//
-//Copyright 1987-2002, Larry Wall
-//
-//Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
-//Built 18:08:02 Feb  4 2003
-//...
-//----
-//
-//However, the version string may vary.
+[[ChToolsWindowsPerl]]
+
+==== Windows Native: Perl
+
+A native Windows Perl package can be obtained from
+http://www.ActiveState.com[Active State] or http://strawberryperl.com/[Strawberry Perl]. The installation
+should be straightforward.
+
+You may also use Chocolatey to install either package:
+
+----
+PS:\> choco install ActivePerl
+----
+
+or
+
+----
+PS:\> choco install StrawberryPerl
+----
+
+After correct installation, typing at the command
+line prompt (cmd.exe):
+
+----
+> perl -v
+----
+
+should result in something like:
+
+----
+This is perl, v5.8.0 built for MSWin32-x86-multi-thread
+(with 1 registered patch, see perl -V for more detail)
+
+Copyright 1987-2002, Larry Wall
+
+Binary build 805 provided by ActiveState Corp. http://www.ActiveState.com
+Built 18:08:02 Feb  4 2003
+...
+----
+
+However, the version string may vary.
 
 // Sed is no longer required.
 //[[ChToolsSed]]
@@ -961,10 +879,10 @@ Bison is a parser generator used for some of Wireshark’s file format support.
 
 [[ChToolsUnixBison]]
 
-==== UNIX or Cygwin: bison
+==== UNIX: Bison
 
-Bison is available for most UNIX-like platforms and as the bison package from
-<<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
+Bison is available for most UNIX and UNIX-like platforms. See the next
+section for native Windows options.
 
 If GNU Bison isn't already installed or available as a package for your
 platform you can get it at: http://www.gnu.org/software/bison/bison.html[].
@@ -998,8 +916,8 @@ https://chocolatey.org/[Chocolatey] package. Note that the executable is named
 _win_bison_.
 
 Native packages are available from other sources such as
-http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin]. They aren't
-officially supported but _should_ work.
+http://gnuwin32.sourceforge.net/packages/bison.htm[GnuWin] and Cygwin.
+They aren't officially supported but _should_ work.
 
 [[ChToolsFlex]]
 
@@ -1010,10 +928,10 @@ file formats, and other features.
 
 [[ChToolsUnixFlex]]
 
-==== UNIX or Cygwin: flex
+==== UNIX: flex
 
-Flex is available for most UNIX-like platforms and as the flex package from
-<<ChToolsCygwin,Cygwin>>. See the next section for native Windows options.
+Flex is available for most UNIX and UNIX-like platforms. See the next
+section for native Windows options.
 
 If GNU flex isn't already installed or available as a package for your platform
 you can get it at http://www.gnu.org/software/flex/[].
@@ -1068,14 +986,11 @@ client.
 
 [[ChToolsUnixGit]]
 
-==== UNIX or Cygwin: git
+==== UNIX: git
 
-Git is available for most of the UNIX-like platforms
-and as the Git package from the
-<<ChToolsCygwin,Cygwin setup>>
-
-If Git isn't already installed or available as a package for your platform, you
-can get it at: http://git-scm.com/[].
+Git is available for most UNIX and UNIX-like platforms. If Git isn't
+already installed or available as a package for your platform, you can
+get it at: http://git-scm.com/[].
 
 After correct installation, typing at the bash command line prompt:
 
@@ -1161,15 +1076,11 @@ tool.
 
 [[ChToolsUnixPatch]]
 
-==== UNIX and Cygwin: patch
-
-Patch is available for most of the UNIX-like platforms
-and as the patch package from the
-<<ChToolsCygwin,Cygwin setup>>.
+==== UNIX: patch
 
-If GNU patch isn't already installed or
-available as a package for your platform, you can get it at
-http://www.gnu.org/software/patch/patch.html[].
+Patch is available for most UNIX and UNIX-like platforms. If GNU patch
+isn't already installed or available as a package for your platform, you
+can get it at http://www.gnu.org/software/patch/patch.html[].
 
 After correct installation, typing at the
 bash command line prompt: