WiX: Update the README.

Migrate packaging/wix/README to AsciiDoc and update its contents. Update
a comment in Wireshark.wxs.

3 files changed, 49 insertions, 36 deletions

diff --git a/packaging/wix/README b/packaging/wix/README
deleted file mode 100644
index cfd5f187f4..0000000000
--- a/packaging/wix/README
+++ /dev/null
@@ -1,35 +0,0 @@
-WiX installer for Wireshark
-
-This is currently an experimental feature to provide Wireshark with an .msi installer.
-It is intended to replace the NSIS installer, but needs to be a little more complete
-before doing so.
-
-(Developer) Differences/notes compared to NSIS installer:
-1. You need the WiX toolset to build the installer.  See http://wixtoolset.org/releases/
-(v3.10 is recommended)
-2. SNMP, Radius, Diameter, and Qt translations files are harvested to be included in
-the installer.  Any custom/additional files just need to be written to the appropriate
-build output directory and the installer will pick them up.  NSIS required modifying
-a file (custom_mibs.txt, etc) for inclusion
-3. Plugin DLLs are not automatically harvested.  To include your DLL, modify Plugins.wxi
-4. To build the WiX installer run:
-> msbuild /m /p:Configuration=RelWithDebInfo wix_package_prep.vcxproj
-> msbuild /m /p:Configuration=RelWithDebInfo wix_package.vcxproj
-
-
-Known issues:
-1. It does not include installing Npcap or USBPcap (the NSIS installer does).  These
-currently come as NSIS installers and it seems it would make more sense to "bundle" them
-with WiX rather than include them as part of the Wireshark.msi.
-2. Needs more flexible handling of VC CRT Merge module (need build script to provide
-appropriate macros).  Something like (or modifying existing) FindMSVC_REDIST.cmake.
-Currently only VS2013 / CRT120 and VS 2015 / CRT140 are supported.
-3. Uninstalling previous versions.  NSIS installer did things more "manually" than Wix does
-by default.  Need to merge as best as possible to handle backwards compatibility. The .msi
-architecture uses an "UpgradeCode" help facilitate install/uninstall/upgrade and NSIS
-installer doesn't have that.  The NSIS installer also removed whole directories instead of
-just removing what it installed (still not sure if this is better or worse)
-
-
-Patches welcome to address any of the issues above or improvements you think can be
-made.
diff --git a/packaging/wix/README.adoc b/packaging/wix/README.adoc
new file mode 100644
index 0000000000..1d36e9d6a8
--- /dev/null
+++ b/packaging/wix/README.adoc
@@ -0,0 +1,47 @@
+= WiX (.msi) Installer For Wireshark
+
+This is an experimental feature to provide Wireshark with an .msi installer as requested in https://gitlab.com/wireshark/wireshark/-/issues/8814[issue 8814].
+It might one day replace the NSIS installer, but needs to be a little more complete before doing so.
+
+== Differences/Notes Compared To The NSIS Installer
+
+. You need the https://wixtoolset.org/[WiX toolset] to build the .msi installer.
+Version 3.10 or later is recommended.
+
+. SNMP, Radius, Diameter, and Qt translations files are harvested to be included in
+the installer.  Any custom/additional files just need to be written to the appropriate
+build output directory and the installer will pick them up.  NSIS required modifying
+a file (custom_mibs.txt, etc) for inclusion
+
+. Plugin DLLs are not automatically harvested. To include your DLL, modify Plugins.wxi.
+
+. To build the WiX installer run:
+----
+> msbuild /m /p:Configuration=RelWithDebInfo wix_package_prep.vcxproj
+> msbuild /m /p:Configuration=RelWithDebInfo wix_package.vcxproj
+----
+
+== Known Issues
+
+. The .msi installer does not include and install Npcap or USBPcap like the NSIS installer does.
+These currently come as NSIS-generated .exe installers.
+We might be able to bundle them as https://wixtoolset.org/documentation/manual/v3/xsd/wix/exepackage.html[ExePackage elements].
+
+// This appears to be fixed in the MERGE_MODULE_DIR code in CMakeLists.txt?
+// . Needs more flexible handling of VC CRT Merge module (need build script to provide appropriate macros).
+// Something like (or modifying existing) FindMSVC_REDIST.cmake.
+// Currently only VS2013 / CRT120 and VS 2015 / CRT140 are supported.
+
+. Transitioning, upgrading, downgrading, and reinstalling is more tricky.
+The NSIS-based installer handles previously-installed versions by running any existing uninstaller prior to installation, which empties the installation directory and removes registry entries.
+These are subsequently filled back in by the installer.
+The Windows Installer architecture keeps track of installed items in a https://docs.microsoft.com/en-us/windows/win32/msi/installer-database[database] and uses the https://docs.microsoft.com/en-us/windows/win32/msi/upgradecode[UpgradeCode property] to identify installed products and the https://wixtoolset.org/documentation/manual/v3/xsd/wix/majorupgrade.html[MajorUpgrade property] to control upgrade behavior.
+As a result,
+  * We can't easily upgrade from an NSIS-based installation to a .msi installation, and vice versa.
+  * We have to be careful about setting things like UpgradeCode, MajorUpgrade, and REINSTALLMODE in our WiX configuration.
+
+. The lax behavior of the NSIS-based installer lets you install more than one copy of Wireshark if you specify different installation directories.
+(The most recently installed version "wins" as far as registry entries and file associations go).
+The .msi installer doesn't allow this.
+
+Patches welcome to address any of the issues above or improvements you think can be made.
diff --git a/packaging/wix/Wireshark.wxs b/packaging/wix/Wireshark.wxs
index 98e35335d2..8421bf0d09 100644
--- a/packaging/wix/Wireshark.wxs
+++ b/packaging/wix/Wireshark.wxs
@@ -27,7 +27,8 @@
     <!-- We set AllowSameVersionUpgrade so that automated builds (which
          only differ by micro version numbers) won't get installed side
          by side. The WiX documentation seems to warn against this, so we
-         might want to find a better fix.
+         might want to find a better fix, e.g. REINSTALLMODE + AllowDowngrades:
+         https://stackoverflow.com/questions/1544990/wix-major-upgrade-doesnt-completely-install-app-on-downgrade
     -->
     <MajorUpgrade
       DowngradeErrorMessage="A newer version of $(var.WiresharkName) is already installed."