From e7297592cbf56eb40a07d7a5a83f2c667ce6614f Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sat, 7 Jan 2023 18:39:04 +0000
Subject: [PATCH] Move manifest explanation in the main wxMSW install docs

This is important enough to be described directly there, especially now
when a manifest is required.
---
 docs/index.htm      |  2 +-
 docs/msw/install.md | 36 +++++++++++++++++++++++++++++++++---
 docs/msw/winxp.md   | 25 -------------------------
 samples/sample.rc   |  2 +-
 4 files changed, 35 insertions(+), 30 deletions(-)
 delete mode 100644 docs/msw/winxp.md

diff --git a/docs/index.htm b/docs/index.htm
index 1c3f349019..6937160250 100644
--- a/docs/index.htm
+++ b/docs/index.htm
@@ -41,7 +41,7 @@
   <ul>
     <li>Readme:
       <a href="readme.txt"><b>General ReadMe</b></a>,
-      <a href="msw/readme.txt">wxMSW</a> (<a href="msw/winxp.txt">wxMSW for WinXP</a>),
+      <a href="msw/readme.txt">wxMSW</a>,
       <a href="gtk/readme.txt">wxGTK</a>,
       <a href="osx/readme.txt">wxOSX</a>,
       <a href="qt/readme.txt">wxQt</a>
diff --git a/docs/msw/install.md b/docs/msw/install.md
index 66ea59fd53..c80deae208 100644
--- a/docs/msw/install.md
+++ b/docs/msw/install.md
@@ -476,9 +476,39 @@ instructions here are out of date, you can always simply copy a makefile or
 project file from `$WXWIN\samples\minimal` or some other sample and adapt it to
 your application.
 
-If you are not using Visual Studio please see
-@subpage plat_msw_winxp "Theme Support" to enable visual styles in your
-application.
+
+Using a Manifest                       {#msw_manifest}
+----------------
+
+All Windows applications should use a "manifest", which is a special kind of
+Windows resource containing information about the application compatibility,
+required, among else, for the application UI to look correctly instead
+of looking very outdated and different from other native applications.
+MSVS projects automatically generate the manifest and embed it into the final
+executable by default, so you don't need to do anything special when using
+them, however you need to ensure that a manifest specifying the use of the v6
+of the Common Controls Library is included when using another compiler.
+
+The most straightforward way to do this is to include one of the manifests
+provided by wxWidgets in the `include\wx\msw\wx.rc` file. It is sufficient to
+simply include it from your own `.rc` file in order to use a correct manifest
+automatically.
+
+To be precise, wxWidgets offers three manifests, differing only in which
+DPI-awareness mode they use. Which of the three is used depends on the value of
+`wxUSE_DPI_AWARE_MANIFEST` define. See [MSW Platform-Specific Build Issues](@ref high_dpi_platform_msw)
+section of the High DPI overview for more information.
+
+Note that the behaviour described above is customizable and you may define
+`wxUSE_NO_MANIFEST` before including `wx/msw/wx.rc` to prevent including a
+manifest if you prefer to embed it in some other way and so don't want to use
+the wxWidgets-provided or, on the contrary, predefine `wxUSE_RC_MANIFEST=1` to
+force using wxWidgets manifest even with MSVC, where it wouldn't be used by
+default.
+
+More information about application manifests in general is available at
+https://learn.microsoft.com/en-us/windows/win32/controls/cookbook-overview#using-manifests-or-directives-to-ensure-that-visual-styles-can-be-applied-to-applications
+
 
 Advanced Library Configurations        {#msw_advanced}
 -------------------------------
diff --git a/docs/msw/winxp.md b/docs/msw/winxp.md
deleted file mode 100644
index 4deab53994..0000000000
--- a/docs/msw/winxp.md
+++ /dev/null
@@ -1,25 +0,0 @@
-Microsoft Windows Theme Support from wxWidgets {#plat_msw_winxp}
--------------------------------------------
-
-Windows XP introduced the themes (called "visual styles" in the Microsoft
-documentation) which have been used since then for Win32 controls.
-As wxWidgets uses the standard Windows controls for most of its
-classes, it can take advantage of it without (almost) any effort from your part.
-The only thing you need to do if you want your program to honour the visual style is to
-add the manifest file to your program (this is not at all specific to
-wxWidgets programs but is required for all Windows applications).
-
-wxWidgets now includes manifest resources in wx.rc, so it should be enough to
-include "wx/msw/wx.rc" in your application's resource file and you get
-proper look automatically. Notice that MSVS automatically generates the manifest
-and embeds it in the executables it produces. Therefore, wxWidgets by default doesn't
-use its own manifest when using MSVC (i.e., wxUSE_RC_MANIFEST is not defined as 1).
-If you don't want to use wxWidgets manifest with any compiler you may define wxUSE_NO_MANIFEST
-as 1 prior to including wx/msw/wx.rc.
-
-wxWidgets offers three manifests, differing only in which DPI-awareness mode they use.
-Which of the three is used depends on the value of wxUSE_DPI_AWARE_MANIFEST define.
-See more in @ref high_dpi_platform_msw "MSW Platform-Specific Build Issues" the High DPI guide.
-
-More information about application manifests is available at
-https://learn.microsoft.com/en-us/windows/win32/controls/cookbook-overview#using-manifests-or-directives-to-ensure-that-visual-styles-can-be-applied-to-applications
\ No newline at end of file
diff --git a/samples/sample.rc b/samples/sample.rc
index dfcd104b4f..fdbc1bbaf7 100644
--- a/samples/sample.rc
+++ b/samples/sample.rc
@@ -22,7 +22,7 @@ sample ICON "sample.ico"
 
 // set this to 1 if you don't want to use manifest resource provided by wxWidgets.
 // An aplication manifest is needed for the application UI to look properly and other
-// things - see docs/msw/winxp.md for more information)
+// things - see docs/msw/install.md for more information)
 #define wxUSE_NO_MANIFEST 0
 
 // to enable full High DPI suppport, we need to opt in into Per-Monitor (V2) DPI awareness,