Integrate MSW, OS X and iOS build instructions into doxygen

Make build instructions available in doxygen but keep the old
folder structure.

docs/doxygen/Doxyfile

@@ -292,6 +292,9 @@ WARN_LOGFILE           = doxygen.log
 INPUT                  = mainpages \
                          groups \
                          overviews \
+                         ../ios \
+                         ../msw \
+                         ../osx \
                          ../../interface
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.h *.md

docs/doxygen/mainpages/platdetails.h

@@ -62,8 +62,7 @@ distribution.
 wxOSX/Cocoa is the port of wxWidgets for the OS X platform. It requires
 OS X 10.7 or later and fully supports 64 bit builds.
 
-For further information, please see the files in @c docs/osx in the
+@subpage plat_osx_install "Build and Install Instructions"
-distribution.
 
 
 
@@ -105,7 +104,7 @@ This port can be compiled with several compilers including Microsoft Studio
 VC++ 2003 or later, Borland 5.5, MinGW32, Cygwin as well as cross-compilation
 with a Linux-hosted MinGW32 tool chain.
 
-For further information, please see the files in docs/msw in the distribution.
+@subpage plat_msw_install "Build and Install Instructions"
 
 @subsection page_port_wxmsw_resources Resources and Application Icon
 
@@ -175,7 +174,7 @@ wxiOS is a port of wxWidgets using Cocoa touch libraries for iOS. It is very
 basic in it current form, but is included for further improvements and very
 simple applications. It requires iOS 9 or later and fully supports 64 bit builds.
 
-For further information, please see the files in docs/ios in the distribution.
+@subpage plat_ios_install "Build Instructions"
 
 @section page_port_nativedocs Native Toolkit Documentation
 

docs/ios/install.md

@@ -0,0 +1,27 @@
+Building wxWidgets for iOS           {#plat_ios_install}
+----------------------------
+
+wxiOS is far from a full supported port, but can be used
+as base for simple applications and future improvements.
+
+It requires Xcode with iOS SDK 9.0 or later. Xcode is available
+for free in the OS X app store.
+
+To build wxiOS you should use Xcode to open the minimal samples
+Xcode project file located at:
+
+    samples/minimal/minimal_iphone.xcodeproj
+
+That project files includes wxiphone.xcodeproj so you just need
+to hit run in order to see the minimal sample running in the
+simulator.
+
+The library can also be build via configure/make:
+
+    mkdir build_ios
+    cd build_ios
+    ../configure --with-osx_iphone --enable-monolithic \
+        --with-macosx-version-min=8.0 --disable-shared \
+        --enable-macosx_arch=i386 \
+        --with-macosx-sdk=$(xcrun --sdk iphonesimulator --show-sdk-path)
+    make

docs/ios/readme.txt

@@ -4,35 +4,6 @@
 wxiOS is far from a full supported port, but can be used
 as base for simple applications and future improvements.
 
-It requires Xcode with iOS SDK 9.0 or later. Xcode is available
-for free in the OS X app store.
-
-More info about the wxWidgets project (including all the
-other ports and version of wxWidgets) can be found at the
-main wxWidgets homepage at:
-
-    https://www.wxwidgets.org/
-
-To build wxiOS you should use Xcode to open the minimal samples
-Xcode project file located at:
-
-    samples/minimal/minimal_iphone.xcodeproj
-
-That project files includes wxiphone.xcodeproj so you just need
-to hit run in order to see the minimal sample running in the
-simulator.
-
-The library can also be build via configure/make:
-
-    mkdir build_ios
-    cd build_ios
-    ../configure --with-osx_iphone --enable-monolithic \
-        --with-macosx-version-min=8.0 --disable-shared \
-        --enable-macosx_arch=i386 \
-        --with-macosx-sdk=$(xcrun --sdk iphonesimulator --show-sdk-path)
-    make
-
-
 Please send problems concerning installation, feature requests,
 bug reports or comments to the wxWidgets users list. These can
 be found at https://www.wxwidgets.org/support/mailing-lists/

docs/msw/gtk.md

@@ -1,4 +1,4 @@
-Building wxGTK port with Win32 GDK backend
+Building wxGTK port with Win32 GDK backend {#plat_msw_gtk}
 ------------------------------------------
 
 GTK+ widget toolkit has multiple GDK backends and one of them is Win32.
@@ -11,14 +11,15 @@ These notes don't consider building wxGTK with X11 backend under Windows.
 Building steps:
 
 1. wxGTK/Win32 build is similar to wxMSW one and you should have configured
-and be able to build wxWidgets as described in docs/msw/install.txt
+and be able to build wxWidgets as described in @ref plat_msw_install
 
 2. wxGTK/Win32 is disabled by default in wxWidgets, you need to enable it
 in bakefiles manually. Apply following patch manually or using Cygwin:
 
-    patch -p0 < docs/msw/gtkfix.patch
+        patch -p0 < docs/msw/gtkfix.patch
 
 Regenerate required make/project files:
+
     cd build\bakefiles
     bakefile_gen
 
@@ -31,6 +32,7 @@ in the C:\gtk directory.
 4. Building
 
 4.1 If you are using Visual C++ project files you need to setup GTK+ 2 include directories
+
     C:\gtk\lib\include\gtk-2.0
     C:\gtk\lib\include\glib-2.0
     C:\gtk\lib\include\cairo
@@ -44,7 +46,7 @@ and library directory
 
     C:\gtk\lib\
 
-    See http://msdn.microsoft.com/en-us/library/t9az1d21(v=vs.90).aspx
+See http://msdn.microsoft.com/en-us/library/t9az1d21(v=vs.90).aspx
 
 Open solution file in build\msw directory, select "GTK+ Debug" solution
 configuration and build the solution. To be sure that everything is as expected

docs/msw/install.md

@@ -1,37 +1,28 @@
-                   Installing wxWidgets for Windows
+Installing wxWidgets for Windows       {#plat_msw_install}
-                   --------------------------------
+--------------------------------
 
 This is wxWidgets for Microsoft Windows (XP, Vista, 7, 8, 10, etc)
 including both 32 bit and 64 bit versions.
 
+[TOC]
 
-Table of Contents:
+Installation                           {#msw_install}
- - Installation
- - Building wxWidgets
- - Configuring the Build
- - Building Applications Using wxWidgets
-
-
-Installation
 ============
 
 If you are using one of the supported compilers, you can download the
 pre-built in binaries from
 
-    https://github.com/wxWidgets/wxWidgets/releases/v3.1.1
+https://github.com/wxWidgets/wxWidgets/releases/v3.1.1
 
 In this case, just uncompress the binaries archive under any directory
-and skip to "Building Applications Using wxWidgets" part.
+and skip to [Building Applications Using wxWidgets](#msw_build_apps) part.
 
 Otherwise, or if you want to build a configuration of the library
 different from the default one, you need to build the library from
 sources before using it.
 
-If you use CMake, please see
+If you use CMake, please see @ref overview_cmake for
-
+building wxWidgets using it.
-    https://docs.wxwidgets.org/trunk/overview_cmake.html
-
-for building wxWidgets using it.
 
 The first step, which you may have already performed, unless you are
 reading this file online, is to download the source archive and
@@ -46,22 +37,22 @@ actually required, this makes using the library more convenient and
 this environment variable is used in the examples below.
 
 NB: If you checked your sources from version control repository and
-    didn't obtain them from a release file, you also need to copy
+didn't obtain them from a release file, you also need to copy
-    include/wx/msw/setup0.h to include/wx/msw/setup.h and to remember
+`include/wx/msw/setup0.h` to `include/wx/msw/setup.h` and to remember
-    to update the latter whenever the former changes, otherwise you
+to update the latter whenever the former changes, otherwise you
-    will get compilation errors if any new symbols are added to
+will get compilation errors if any new symbols are added to
-    setup0.h file in the repository.
+setup0.h file in the repository.
 
-    If you have no intention of modifying setup.h, you may avoid this
+If you have no intention of modifying setup.h, you may avoid this
-    problem by creating a symbolic link to setup0.h instead of making
+problem by creating a symbolic link to setup0.h instead of making
-    a copy of it using mklink, from an admin command prompt:
+a copy of it using mklink, from an admin command prompt:
 
-        cd %WXWIN%\include\wx\msw\
+    cd %WXWIN%\include\wx\msw\
-        mklink setup.h setup0.h
+    mklink setup.h setup0.h
 
 
 
-Building wxWidgets
+Building wxWidgets                     {#msw_build}
 ==================
 
 The following sections explain how to compile wxWidgets with each supported
@@ -70,7 +61,7 @@ building your application using wxWidgets.
 
 All makefiles and project are located in build\msw directory.
 
-Microsoft Visual C++ Compilation
+Microsoft Visual C++ Compilation       {#msw_build_msvs}
 ----------------------------------------------------------------
 
 * From command line using the provided makefiles:
@@ -79,7 +70,7 @@ Microsoft Visual C++ Compilation
    must have been installed to the "Start" menu or the "Start" screen
    by MSVS installation.
 
-1. Change directory to %WXWIN%\build\msw and type
+1. Change directory to \%WXWIN\%\build\msw and type
 
         > nmake /f makefile.vc
 
@@ -99,7 +90,7 @@ Microsoft Visual C++ Compilation
    See "Configuring the Build" for more information about the
    additional parameters that can be specified on the command line.
 
-2. To verify your build, change the directory to %WXWIN%\samples\minimal and
+2. To verify your build, change the directory to \%WXWIN\%\samples\minimal and
    run the same nmake command (with the same parameters there), this
    should create a working minimal wxWidgets sample.
 
@@ -120,7 +111,7 @@ are not always built in the correct order, and this may result in link
 errors. Simply do the build again, up to 3 times, to fix this.
 
 
-Special notes for Visual Studio 2010+:
+### Special notes for Visual Studio 2010+
 
 For Visual Studio 2010+ solutions it is possible to customize the build by
 creating a wx_local.props file in the build\msw directory which is used, if it
@@ -132,8 +123,8 @@ make the file is to copy wx_setup.props to wx_local.props and then edit local.
 For example, if you are building wxWidgets libraries using multiple versions
 of Visual Studio you could change wxCompilerPrefix to include the toolset:
 
--    <wxCompilerPrefix>vc</wxCompilerPrefix>
+    -    <wxCompilerPrefix>vc</wxCompilerPrefix>
-+    <wxCompilerPrefix>vc$(PlatformToolsetVersion)</wxCompilerPrefix>
+    +    <wxCompilerPrefix>vc$(PlatformToolsetVersion)</wxCompilerPrefix>
 
 Following that example if you are using Visual Studio 2013 and open
 wx_vc12.sln it will build using the "vc120" prefix for the build directories
@@ -147,28 +138,31 @@ updated with it. For example the version information in wx_setup.props could
 change and the information in your wx_local.props would be outdated. It is
 your responsibility to monitor for such situations.
 
-Improve debugging for Visual Studio 2012+:
+### Improve debugging for Visual Studio 2012+
 
 Debug visualizers for Visual Studio 2012+ are provided which makes inspecting
 various wxWidgets classes easier to view while debugging. To use them:
 
-1. Open the folder %WXWIN%\misc\msvc
+1. Open the folder \%WXWIN\%\misc\msvc
-2. Open the folder %USERPROFILE%\My Documents\Visual Studio 2012\Visualizers\
+2. Open the folder \%USERPROFILE\%\My Documents\Visual Studio 2012\Visualizers\
    (or the corresponding location for newer versions, e.g. ...2013\Visualizers)
 3. Copy wxWidgets.natvis and autoexp.inc
 4. For Visual Studio 2013+ additionally copy wxWidgets.2013.natvis
 
 
-Cygwin/MinGW Compilation
+Cygwin/MinGW Compilation               {#msw_build_cygwin}
 ----------------------------------------------------------------
 
 wxWidgets supports Cygwin, MinGW, MinGW-w64 and TDM-GCC tool chains under
 Windows. They can be downloaded from:
 
-    http://www.cygwin.com/
+http://www.cygwin.com/
-    http://www.mingw.org/
+
-    http://mingw-w64.sourceforge.net/
+http://www.mingw.org/
-    http://tdm-gcc.tdragon.net/
+
+http://mingw-w64.sourceforge.net/
+
+http://tdm-gcc.tdragon.net/
 
 respectively. Please retrieve and install the latest version of your preferred
 tool chain by following the instructions provided by these packages. Notice
@@ -189,7 +183,7 @@ All of these tool chains can be used either with Unix-like configure+make build
 process (preferred) or with the provided makefile.gcc makefiles without using
 configure:
 
-* Using configure
+### Using configure
 
 This method works in exactly the same way as under Unix systems,
 including OS X, and requires a Unix-like environment to work, i.e.
@@ -231,7 +225,7 @@ either MSYS or Cygwin.
    so this step can usually be omitted.
 
 
-* Using plain makefiles:
+### Using plain makefiles:
 
 NOTE: The makefile.gcc makefiles are for compilation under MinGW using
       Windows command interpreter (command.com/cmd.exe), they won't work
@@ -240,7 +234,7 @@ NOTE: The makefile.gcc makefiles are for compilation under MinGW using
 
 0. Open DOS command line window (cmd.exe, *not* Bash sh.exe).
 
-1. Change directory to %WXWIN%\build\msw and type
+1. Change directory to \%WXWIN\%\build\msw and type
 
         > mingw32-make -f makefile.gcc
 
@@ -263,7 +257,7 @@ NOTE: The makefile.gcc makefiles are for compilation under MinGW using
 
 
 
-Borland C++ Compilation
+Borland C++ Compilation                {#msw_build_borland}
 ----------------------------------------------------------------
 
 WARNING: Borland instructions are out of date, please send us your
@@ -278,7 +272,7 @@ debugger is very good. To avoid linker errors you will need to add
 -DSHARED=1 to the makefile line for the library
 
 The version 5.6 included in Borland C++ Builder 2006 works as well after the
-following small change: please remove the test for __WINDOWS__ from line 88
+following small change: please remove the test for `__WINDOWS__` from line 88
 of the file BCCDIR\include\stl\_threads.h.
 
 Compiling using the makefiles:
@@ -302,7 +296,7 @@ debug mode, edit makefile.bcc and change /aa to /Tpe in link commands.
 Using the Debugger and IDE in BDS or Turbo Explorer
 ---------------------------------------------------
 
-Doubleclick / open %WXWIN%\samples\minimal\borland.bdsproj. The current version
+Doubleclick / open \%WXWIN\%\samples\minimal\borland.bdsproj. The current version
 is to be used with a dynamic build of wxWidgets-made by running
 make -f Makefile.bcc -DBUILD=debug -DSHARED=1
 in wxWidgets\build\msw. You also need the wxWidgets\lib\bcc_dll
@@ -324,16 +318,16 @@ Compiling using the IDE files for Borland C++ 5.0 and using CBuilder IDE
 In all of your wxWidgets applications, your source code should include
 the following preprocessor directive:
 
-#ifdef __BORLANDC__
+    #ifdef __BORLANDC__
-#pragma hdrstop
+    #pragma hdrstop
-#endif
+    #endif
 
 (check the samples -- e.g., \wx2\samples\minimal\minimal.cpp -- for
 more details)
 
 
 
-Configuring the Build
+Configuring the Build                  {#msw_build_config}
 ================================================================
 
 NOTE: If you use configure to build the library with Cygwin/MinGW, the
@@ -344,7 +338,7 @@ Library configuration
 ----------------------------------------------------------------
 
 While it is never necessary to do it, you may want to change some of
-the options in the %WXWIN%\include\wx\msw\setup.h file before building
+the options in the \%WXWIN\%\\include\\wx\\msw\\setup.h file before building
 wxWidgets. This file is heavily commented, please read it and enable or disable
 the features you would like to compile wxWidgets with[out].
 
@@ -381,17 +375,20 @@ depending on the compiler used.
 
 The full list of the build settings follows:
 
-BUILD=release
+* BUILD=release
+
   Builds release version of the library. It differs from default 'debug' in
   lack of appended 'd' in name of library and uses the release CRT libraries
   instead of debug ones. Notice that even release builds do include debug
   information by default, see DEBUG_FLAG for more information about it.
 
-SHARED=1
+* SHARED=1
+
   Build shared libraries (DLLs). By default, DLLs are not built
   (SHARED=0).
 
-UNICODE=0
+* UNICODE=0
+
   To completely disable Unicode support (default is UNICODE=1). It should not
   be necessary to do this.
 
@@ -399,54 +396,62 @@ UNICODE=0
   Unicode build) and the directory where the library and setup.h are stored
   (ditto).
 
-WXUNIV=1
+* WXUNIV=1
+
   Build wxUniversal instead of native wxMSW
 
-MONOLITHIC=1
+* MONOLITHIC=1
+
   Starting with version 2.5.1, wxWidgets has the ability to be built as
   several smaller libraries instead of single big one as used to be the case
   in 2.4 and older versions. This is called "multilib build" and is the
   default behaviour of makefiles. You can still build single library
   ("monolithic build") by setting MONOLITHIC variable to 1.
 
-USE_GUI=0
+* USE_GUI=0
+
   Disable building GUI parts of the library, build only wxBase components used
   by console applications. Note that if you leave USE_GUI=1 then both wxBase
   and GUI libraries are built.
 
-USE_$(LIBRARY)=0
+* USE_$(LIBRARY)=0
+
   Do not build the corresponding library (all libraries are built by
   default). Library which can be disabled in this way are: AUI, HTML,
   MEDIA, GL (the option name is USE_OPENGL for this one), PROPGRID,
   QA, RIBBON, RICHTEXT, STC, WEBVIEW, XRC.
 
-RUNTIME_LIBS=static
+* RUNTIME_LIBS=static
+
   Links static version of C and C++ runtime libraries into the executable, so
   that the program does not depend on DLLs provided with the compiler (e.g.
   Visual C++'s msvcrt.dll or Borland's cc3250mt.dll).
   Caution: Do not use static runtime libraries when building DLL (SHARED=1)!
 
-DEBUG_FLAG=0
+* DEBUG_FLAG=0
-DEBUG_FLAG=1
+* DEBUG_FLAG=1
-DEBUG_FLAG=2
+* DEBUG_FLAG=2
+
   Specifies the level of debug support in wxWidgets. Notice that
   this is independent from both BUILD and DEBUG_INFO options. By default
   always set to 1 meaning that debug support is enabled: asserts are compiled
   into the code (they are inactive by default in release builds of the
   application but can be enabled), wxLogDebug() and wxLogTrace() are available
-  and __WXDEBUG__ is defined. Setting it to 0 completely disables all
+  and `__WXDEBUG__` is defined. Setting it to 0 completely disables all
   debugging code in wxWidgets while setting it to 2 enables even the time
   consuming assertions and checks which are deemed to be unsuitable for
   production environment.
 
-DEBUG_INFO=0
+* DEBUG_INFO=0
-DEBUG_INFO=1
+* DEBUG_INFO=1
+
   This option affects whether debugging information is generated. If
   omitted or set to 'default' its value is determined the value of
   the BUILD option.
 
-DEBUG_RUNTIME_LIBS=0
+* DEBUG_RUNTIME_LIBS=0
-DEBUG_RUNTIME_LIBS=1
+* DEBUG_RUNTIME_LIBS=1
+
   (VC++ only.) If set to 1, msvcrtd.dll is used, if to 0, msvcrt.dll
   is used. By default msvcrtd.dll is used only if the executable
   contains debug info and msvcrt.dll if it doesn't. It is sometimes
@@ -455,11 +460,13 @@ DEBUG_RUNTIME_LIBS=1
   usable .pdb files with debug information) and this setting makes it
   possible.
 
-TARGET_CPU=X64|ARM64|IA64
+* TARGET_CPU=X64|ARM64|IA64
+
   (VC++ only.) Set this variable to build for x86_64 systems. If unset, x86
   build is performed.
 
-VENDOR=<your company name>
+* VENDOR=\<your company name\>
+
   Set this to a short string identifying your company if you are planning to
   distribute wxWidgets DLLs with your application. Default value is 'custom'.
   This string is included as part of DLL name. wxWidgets DLLs contain compiler
@@ -468,72 +475,74 @@ VENDOR=<your company name>
   default settings. If you set VENDOR=mycorp, the name will change to
   wxmsw311u_core_vc_mycorp.dll.
 
-CFG=<configuration name>
+* CFG=\<configuration name\>
+
   Sets configuration name so that you can have multiple wxWidgets builds with
   different setup.h settings coexisting in same tree. The value of
   this option is appended to the build directories names. This is
   useful for building the library in some non-default configuration,
-  e.g. you could change wxUSE_STL to 1 in %WXWIN%\include\wx\msw\setup.h and
+  e.g. you could change wxUSE_STL to 1 in \%WXWIN\%\include\wx\msw\setup.h and
   then build with "CFG=-stl". Alternatively, you could build with e.g.
   "RUNTIME_LIBS=static CFG=-mt" when using MSVC.
 
-COMPILER_PREFIX=<string>
+* COMPILER_PREFIX=\<string\>
+
   If you build with multiple versions of the same compiler, you can put
   their outputs into directories like "vc6_lib", "vc8_lib" etc. instead of
   "vc_lib" by setting this variable to e.g. "vc6". This is merely a
   convenience variable, you can achieve the same effect (but different
   directory names) with the CFG option.
 
-CFLAGS
+* CFLAGS
-CXXFLAGS
+* CXXFLAGS
-CPPFLAGS
+* CPPFLAGS
-LDFLAGS
+* LDFLAGS
+
   Additional flags to be used with C compiler, C++ compiler, C
   preprocessor (used for both C and C++ compilation) and linker,
   respectively.
 
 
 
-Building Applications Using wxWidgets
+Building Applications Using wxWidgets  {#msw_build_apps}
 =====================================
 
 If you want to use CMake for building your project, please see
-
+@ref overview_cmake.
-    https://docs.wxwidgets.org/trunk/overview_cmake.html#cmake_apps
 
 Otherwise follow the instructions below for "manual" setup of your project.
 
 We suppose that wxWidgets sources are under the directory $WXWIN (notice that
 different tool chains refer to environment variables such as WXWIN in
 different ways, e.g. MSVC users should use $(WXWIN) instead of just
-$WXWIN). And we will use <wx-lib-dir> as a shortcut for the subdirectory of
+$WXWIN). And we will use \<wx-lib-dir\> as a shortcut for the subdirectory of
 $WXWIN\lib which is composed from several parts separated by underscore:
 first, a compiler-specific prefix (e.g. "vc" for MSVC, "gcc" for g++ or the
 value of COMPILER_PREFIX if you set it explicitly), then optional "x64" if
 building in 64 bits and finally either "lib" or "dll" depending on whether
 static or dynamic wx libraries are being used.
 
-For example, WXWIN could be "c:\wxWidgets\3.4.5" and <wx-lib-dir> could be
+For example, WXWIN could be "c:\wxWidgets\3.4.5" and \<wx-lib-dir\> could be
 "c:\wxWidgets\3.4.5\lib\vc_x64_lib" for 64-bit static libraries built with
 MSVC.
 
 Here is what you need to do:
 
-* Add $WXWIN\include to the
+* Add $WXWIN\\include to the
   - compiler
   - resource compiler
   include paths.
 * If using MSVC, prepend $WXWIN\include\msvc to the include paths too.
-  Otherwise, append <wx-lib-dir>\mswu[d] to the include paths, where "d" should
+  Otherwise, append \<wx-lib-dir\>\mswu[d] to the include paths, where "d" should
   be used for debug builds only.
 * Define the following symbols for the preprocessor:
-  - __WXMSW__ to ensure you use the correct wxWidgets port.
+  - `__WXMSW__` to ensure you use the correct wxWidgets port.
   - _UNICODE unless you want to use deprecated ANSI build of wxWidgets.
   - NDEBUG if you want to build in release mode, i.e. disable asserts.
   - WXUSINGDLL if you are using DLL build of wxWidgets.
 * If using MSVC 7 only (i.e. not for later versions), also define
   wxUSE_RC_MANIFEST=1 and WX_CPU_X86.
-* Add <wx-lib-dir> directory described above to the libraries path.
+* Add \<wx-lib-dir\> directory described above to the libraries path.
 
 When using MSVC, the libraries are linked automatically using "#pragma
 comment(lib)" feature of this compiler. With all the other compilers you also
@@ -554,3 +563,18 @@ using wxWidgets and always work, so in case of a problem, e.g. if the
 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 2010 or newer please see
+@subpage plat_msw_winxp "Windows XP Support" to enable visual styles in your
+application.
+
+Advanced Library Configurations        {#msw_advanced}
+===============================
+Build instructions to less common library configuartions using different UI
+backends are avaiable here.
+
+@subpage plat_msw_msys2 "Building with Win32 MSys2 backend"
+
+@subpage plat_msw_msys2_gtk "Building with Win32 MSys2 GDK backend"
+
+@subpage plat_msw_gtk "Building wxGTK port with Win32 GDK backend"

docs/msw/msys2-gtk.md

@@ -0,0 +1,124 @@
+Building wxGTK port with Win32 MSys2 GDK backend {#plat_msw_msys2_gtk}
+------------------------------------------------
+
+GTK+ widget toolkit has multiple GDK backends and one of them is Win32.
+It is a wrapper around Windows API.
+
+These notes don't consider building wxGTK with X11 backend under Windows.
+
+The MSys2 website is http://www.msys2.org/
+
+These building steps are NOT the normal way to build MSys2 MinGW packages.
+But, they are a way the wxWidgets developers can test that wxWidgets
+can build the wxGTK/Win32 libraries under MSys2 MinGW.
+
+For the MSys2 way please see
+  https://github.com/Alexpux/MINGW-packages and
+  https://github.com/msys2/msys2/wiki/Creating-packages
+
+Building steps:
+
+**Warning**: At the time these directions were written the GTK version 3
+         was NOT able to create wxGTK/Win32 libraries that were usable.
+
+1. Install the mingw32 packages needed to build wxGTK/Win32 using the
+   configure/make build method.
+   From the MSys2 prompt or MSys2 MinGW prompt:
+
+   The 32 bit Mingw packages are prefixed with "mingw-w64-i686-";
+   Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit.
+
+        pacman -S --needed --noconfirm make
+        pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo
+        pacman -S --needed --noconfirm mingw-w64-i686-libpng
+        pacman -S --needed --noconfirm mingw-w64-i686-libtiff
+        pacman -S --needed --noconfirm mingw-w64-i686-gcc
+        pacman -S --needed --noconfirm mingw-w64-i686-pkg-config
+        ## gtk2 can take a long time to update/find fonts
+        pacman -S --needed --noconfirm mingw-w64-i686-gtk2
+
+
+    Packages that are needed but are normally installed already.
+
+        pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs
+        pacman -S --needed --noconfirm mingw-w64-i686-expat
+        pacman -S --needed --noconfirm mingw-w64-i686-xz
+        pacman -S --needed --noconfirm mingw-w64-i686-zlib
+        pacman -S --needed --noconfirm mingw-w64-i686-gdk-pixbuf2
+
+
+2. Build the wxGTK/Win32 static library
+    1. Open MSys2 MinGW Prompt
+       (These steps were tested on MinGW32; but, should work under MinGW64)
+    2. Use the cd command to change directory to the wxWidgets top folder.
+
+    3. Create the "build-gtk2-static" folder to build the static libraries
+
+            mkdir -p build-gtk2-static
+
+    4. Configure wxWidgets
+       Option "--disable-precomp-headers" is NOT needed.
+       It is being used to test for compile issues.
+
+       Remove configure option "--disable-wxdib" to set wxUSE_WXDIB to 1.
+       The directions docs/msw/gtk.txt results in wxUSE_WXDIB set to 1.
+
+            cd build-gtk2-static && \
+            ../configure --with-gtk=2 \
+                --disable-wxdib \
+                --disable-shared \
+                --disable-precomp-headers \
+            && cd ..
+
+    5. clean the wxGTK static libraries
+
+            cd build-gtk2-static && make clean && cd ..
+
+    6. make the wxGTK static libraries
+
+            cd build-gtk2-static && make && cd ..
+
+
+3.  Build and run the minimal static sample
+    1. Clean the minimal sample
+
+            cd build-gtk2-static/samples/minimal && make clean && cd ../../..
+
+    2. Build the minimal sample
+
+            cd build-gtk2-static/samples/minimal && make && cd ../../..
+
+    3. Run the minimal sample
+
+            ./build-gtk2-static/samples/minimal/minimal.exe
+
+
+4. Build most of the static samples
+    1. Clean most of the static samples
+
+            cd build-gtk2-static/samples && make clean && cd ../..
+
+    2. Build most of the static samples
+
+            cd build-gtk2-static/samples && make && cd ../..
+
+
+5.  Run the drawing static sample
+
+        cd samples/drawing && ../../build-gtk2-static/samples/drawing/drawing.exe && cd ../..
+
+6.  Run the splash static sample
+
+        cd samples/splash && ../../build-gtk2-static/samples/splash/splash.exe && cd ../..
+
+7.  Run the widgets static sample
+
+        cd samples/widgets && ../../build-gtk2-static/samples/widgets/widgets.exe && cd ../..
+
+8.  Run the toolbar static sample
+
+        cd samples/toolbar && ../../build-gtk2-static/samples/toolbar/toolbar.exe && cd ../..
+
+9.  Run the image static sample
+
+        cd samples/image && ../../build-gtk2-static/samples/image/image.exe && cd ../..

docs/msw/msys2-gtk.txt

@@ -1,111 +0,0 @@
-Building wxGTK port with Win32 MSys2 GDK backend
-------------------------------------------------
-
-GTK+ widget toolkit has multiple GDK backends and one of them is Win32.
-It is a wrapper around Windows API.
-
-These notes don't consider building wxGTK with X11 backend under Windows.
-
-The MSys2 website is http://www.msys2.org/
-
-These building steps are NOT the normal way to build MSys2 MinGW packages.
-But, they are a way the wxWidgets developers can test that wxWidgets
-can build the wxGTK/Win32 libraries under MSys2 MinGW.
-
-For the MSys2 way please see 
-  https://github.com/Alexpux/MINGW-packages and
-  https://github.com/msys2/msys2/wiki/Creating-packages
-
-Building steps:
-
-#Note: The "#" is used in front of a comment to help the people who cut
-#      and paste these directions.
-#Warning: At the time these directions were written the GTK version 3
-#         was NOT able to create wxGTK/Win32 libraries that were usable.
-
-#1. Install the mingw32 packages needed to build wxGTK/Win32 using the 
-#   configure/make build method. 
-#   From the MSys2 prompt or MSys2 MinGW prompt:
-
-#   The 32 bit Mingw packages are prefixed with "mingw-w64-i686-";
-#   Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit.
-
-pacman -S --needed --noconfirm make
-pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo
-pacman -S --needed --noconfirm mingw-w64-i686-libpng
-pacman -S --needed --noconfirm mingw-w64-i686-libtiff
-pacman -S --needed --noconfirm mingw-w64-i686-gcc
-pacman -S --needed --noconfirm mingw-w64-i686-pkg-config
-## gtk2 can take a long time to update/find fonts
-pacman -S --needed --noconfirm mingw-w64-i686-gtk2
-
-
-# Packages that are needed but are normally installed already.
-pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs
-pacman -S --needed --noconfirm mingw-w64-i686-expat
-pacman -S --needed --noconfirm mingw-w64-i686-xz
-pacman -S --needed --noconfirm mingw-w64-i686-zlib
-pacman -S --needed --noconfirm mingw-w64-i686-gdk-pixbuf2
-
-
-#2. Build the wxGTK/Win32 static library
-#2a.Open MSys2 MinGW Prompt
-#   (These steps were tested on MinGW32; but, should work under MinGW64)
-#2b.Use the cd command to change directory to the wxWidgets top folder.
-
-
-#2c.Create the "build-gtk2-static" folder to build the static libraries
-mkdir -p build-gtk2-static
-
-#2d.Configure wxWidgets
-#   Option "--disable-precomp-headers" is NOT needed.
-#   It is being used to test for compile issues.
-#
-#   Remove configure option "--disable-wxdib" to set wxUSE_WXDIB to 1.
-#   The directions docs/msw/gtk.txt results in wxUSE_WXDIB set to 1.
-cd build-gtk2-static && \
-  ../configure --with-gtk=2 \
-    --disable-wxdib \
-    --disable-shared \
-    --disable-precomp-headers \
-  && cd ..
-
-#2e.clean the wxGTK static libraries
-cd build-gtk2-static && make clean && cd ..
-
-#2f.make the wxGTK static libraries
-cd build-gtk2-static && make && cd ..
-
-
-#3  Build and run the minimal static sample
-#3a.Clean the minimal sample
-cd build-gtk2-static/samples/minimal && make clean && cd ../../..
-
-#3b.Build the minimal sample
-cd build-gtk2-static/samples/minimal && make && cd ../../..
-
-#3c.Run the minimal sample
-./build-gtk2-static/samples/minimal/minimal.exe
-
-
-#4  Build most of the static samples
-#4a.Clean most of the static samples
-cd build-gtk2-static/samples && make clean && cd ../..
-#4b.Build most of the static samples
-cd build-gtk2-static/samples && make && cd ../..
-
-
-#5  Run the drawing static sample
-cd samples/drawing && ../../build-gtk2-static/samples/drawing/drawing.exe && cd ../..
-
-#6  Run the splash static sample
-cd samples/splash && ../../build-gtk2-static/samples/splash/splash.exe && cd ../..
-
-#7  Run the widgets static sample
-cd samples/widgets && ../../build-gtk2-static/samples/widgets/widgets.exe && cd ../..
-
-#8  Run the toolbar static sample
-cd samples/toolbar && ../../build-gtk2-static/samples/toolbar/toolbar.exe && cd ../..
-
-#9  Run the image static sample
-cd samples/image && ../../build-gtk2-static/samples/image/image.exe && cd ../..

docs/msw/msys2-msw.md

@@ -0,0 +1,101 @@
+Building wxMSW port with Win32 MSys2 backend {#plat_msw_msys2}
+------------------------------------------------
+
+The MSys2 website is http://www.msys2.org/
+
+These building steps are NOT the normal way to build MSys2 MinGW packages.
+But, they are a way the wxWidgets developers can test that wxWidgets
+can build the wxMSW libraries under MSys2 MinGW.
+
+For the MSys2 way please see https://github.com/Alexpux/MINGW-packages
+
+Building steps:
+
+1. Install the mingw32 packages needed to build wxMSW using the
+   configure/make build method.
+   From the MSys2 prompt or MSys2 MinGW prompt:
+
+   The 32 bit Mingw packages are prefixed with "mingw-w64-i686-";
+   Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit.
+
+        pacman -S --needed --noconfirm make
+        pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo
+        pacman -S --needed --noconfirm mingw-w64-i686-libpng
+        pacman -S --needed --noconfirm mingw-w64-i686-libtiff
+        pacman -S --needed --noconfirm mingw-w64-i686-gcc
+
+    Packages that are needed but are normally installed already.
+
+        pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs
+        pacman -S --needed --noconfirm mingw-w64-i686-expat
+        pacman -S --needed --noconfirm mingw-w64-i686-xz
+        pacman -S --needed --noconfirm mingw-w64-i686-zlib
+
+
+2. Build the wxMSW static library
+    1. Open MSys2 MinGW Prompt
+   (These steps were tested on MinGW32; but, should work under MinGW64)
+    2. Use the cd command to change directory to the wxWidgets top folder.
+
+    3. Create the "build-msw-static" folder to build the static libraries
+
+            mkdir -p build-msw-static
+
+    4. Configure wxWidgets
+
+        Option "--disable-precomp-headers" is NOT needed.
+        I am doing it to check for compile issues;
+        And, I think my old 32 bit Windows machine
+        works best with it disabled.
+
+            cd build-msw-static && \
+            ../configure --with-msw \
+                --disable-shared \
+                --disable-precomp-headers \
+            && cd ..
+
+    5. make the wxMSW static libraries
+
+            cd build-msw-static && make && cd ..
+
+3. Build and run the minimal static sample
+
+    1. Clean the minimal sample
+
+            cd build-msw-static/samples/minimal && make clean && cd ../../..
+
+    2. Build the minimal sample
+
+            cd build-msw-static/samples/minimal && make && cd ../../..
+
+    3. Run the minimal sample
+
+            ./build-msw-static/samples/minimal/minimal.exe
+
+4. Clean the static samples
+
+        cd build-msw-static/samples && make clean && cd ../..
+
+5.  Build and run the typetest static sample to verify MIME database works
+
+        cd build-msw-static/samples/typetest && make && cd ../../..
+        ./build-msw-static/samples/typetest/typetest.exe
+
+6.  Build and run the drawing static sample
+
+        cd build-msw-static/samples/drawing && make && cd ../../..
+        cd samples/drawing && ../../build-msw-static/samples/drawing/drawing.exe && cd ../..
+
+7.  Build and run the splash static sample
+
+        cd build-msw-static/samples/splash && make && cd ../../..
+        cd samples/splash && ../../build-msw-static/samples/splash/splash.exe && cd ../..
+
+8.  Build and run the widgets static sample
+
+        cd build-msw-static/samples/widgets && make && cd ../../..
+        cd samples/widgets && ../../build-msw-static/samples/widgets/widgets.exe && cd ../..
+
+9.  Build all the rest of the static samples
+
+        cd build-msw-static/samples && make && cd ../..

docs/msw/msys2-msw.txt

@@ -1,92 +0,0 @@
-Building wxMSW port with Win32 MSys2 backend
-------------------------------------------------
-
-The MSys2 website is http://www.msys2.org/
-
-These building steps are NOT the normal way to build MSys2 MinGW packages.
-But, they are a way the wxWidgets developers can test that wxWidgets
-can build the wxMSW libraries under MSys2 MinGW.
-
-For the MSys2 way please see https://github.com/Alexpux/MINGW-packages
-
-Building steps:
-
-#Note: The "#" is used in front of a comment to help the people who cut
-#      and paste these directions.
-
-#1. Install the mingw32 packages needed to build wxMSW using the 
-#   configure/make build method. 
-#   From the MSys2 prompt or MSys2 MinGW prompt:
-
-#   The 32 bit Mingw packages are prefixed with "mingw-w64-i686-";
-#   Change the prefix to "mingw-w64-x86_64-" if you wish to do 64 bit.
-
-pacman -S --needed --noconfirm make
-pacman -S --needed --noconfirm mingw-w64-i686-libjpeg-turbo
-pacman -S --needed --noconfirm mingw-w64-i686-libpng
-pacman -S --needed --noconfirm mingw-w64-i686-libtiff
-pacman -S --needed --noconfirm mingw-w64-i686-gcc
-
-# Packages that are needed but are normally installed already.
-pacman -S --needed --noconfirm mingw-w64-i686-gcc-libs
-pacman -S --needed --noconfirm mingw-w64-i686-expat
-pacman -S --needed --noconfirm mingw-w64-i686-xz
-pacman -S --needed --noconfirm mingw-w64-i686-zlib
-
-
-#2. Build the wxMSW static library
-#2a.Open MSys2 MinGW Prompt
-#   (These steps were tested on MinGW32; but, should work under MinGW64)
-#2b.Use the cd command to change directory to the wxWidgets top folder.
-
-
-#2c.Create the "build-msw-static" folder to build the static libraries
-mkdir -p build-msw-static
-
-#2d.Configure wxWidgets
-#   Option "--disable-precomp-headers" is NOT needed.
-#   I am doing it to check for compile issues;
-#   And, I think my old 32 bit Windows machine
-#   works best with it disabled.
-cd build-msw-static && \
-  ../configure --with-msw \
-    --disable-shared \
-    --disable-precomp-headers \
-  && cd ..
-
-#2e.make the wxMSW static libraries
-cd build-msw-static && make && cd ..
-
-
-#3  Build and run the minimal static sample
-#3a.Clean the minimal sample
-cd build-msw-static/samples/minimal && make clean && cd ../../..
-
-#3b.Build the minimal sample
-cd build-msw-static/samples/minimal && make && cd ../../..
-
-#3c.Run the minimal sample
-./build-msw-static/samples/minimal/minimal.exe
-
-
-#4 Clean the static samples
-cd build-msw-static/samples && make clean && cd ../..
-
-#5  Build and run the typetest static sample to verify MIME database works
-cd build-msw-static/samples/typetest && make && cd ../../..
-./build-msw-static/samples/typetest/typetest.exe
-
-#6  Build and run the drawing static sample
-cd build-msw-static/samples/drawing && make && cd ../../..
-cd samples/drawing && ../../build-msw-static/samples/drawing/drawing.exe && cd ../..
-
-#7  Build and run the splash static sample
-cd build-msw-static/samples/splash && make && cd ../../..
-cd samples/splash && ../../build-msw-static/samples/splash/splash.exe && cd ../..
-
-#8  Build and run the widgets static sample
-cd build-msw-static/samples/widgets && make && cd ../../..
-cd samples/widgets && ../../build-msw-static/samples/widgets/widgets.exe && cd ../..
-
-#9  Build all the rest of the static samples
-cd build-msw-static/samples && make && cd ../..

docs/msw/readme.txt

@@ -1,7 +1,7 @@
 This is wxWidgets for Windows (wxMSW)
 -------------------------------------
 
-For information on installing wxWidgets, please see install.txt.
+For information on installing wxWidgets, please see install.md.
 
 For further information, please see docs/html/index.htm and the
 wxWidgets reference manual.

docs/msw/winxp.md

@@ -1,4 +1,4 @@
-Microsoft Windows XP Support from wxWidgets
+Microsoft Windows XP Support from wxWidgets {#plat_msw_winxp}
 -------------------------------------------
 
 Windows XP introduces the themes (called "visual styles" in the Microsoft
@@ -30,27 +30,25 @@ for more details.
 Here is the example manifest which you can put into controls.exe.manifest
 file to test theme support using the controls sample:
 
---- cut here ---
+    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
-<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+    <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
-<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+    <assemblyIdentity
-<assemblyIdentity
+        version="0.64.1.0"
-    version="0.64.1.0"
+        processorArchitecture="x86"
-    processorArchitecture="x86"
+        name="Controls"
-    name="Controls"
+        type="win32"
-    type="win32"
+    />
-/>
+    <description>Controls: wxWidgets sample application</description>
-<description>Controls: wxWidgets sample application</description>
+    <dependency>
-<dependency>
+        <dependentAssembly>
-    <dependentAssembly>
+            <assemblyIdentity
-        <assemblyIdentity
+                type="win32"
-            type="win32"
+                name="Microsoft.Windows.Common-Controls"
-            name="Microsoft.Windows.Common-Controls"
+                version="6.0.0.0"
-            version="6.0.0.0"
+                processorArchitecture="X86"
-            processorArchitecture="X86"
+                publicKeyToken="6595b64144ccf1df"
-            publicKeyToken="6595b64144ccf1df"
+                language="*"
-            language="*"
+            />
-        />
+        </dependentAssembly>
-    </dependentAssembly>
+    </dependency>
-</dependency>
+    </assembly>
-</assembly>
---- cut here ---

docs/osx/install.md

@@ -1,6 +1,8 @@
-wxWidgets for OS X installation
+wxWidgets for OS X installation        {#plat_osx_install}
 -----------------------------------
 
+[TOC]
+
 wxWidgets can be compiled using Apple's Cocoa library.
 
 Most OS X developers should start by downloading and installing Xcode
@@ -14,45 +16,42 @@ Next use Terminal (under Applications, Utilities, Terminal) to access a command
 prompt.  Use cd to change directories to your wxWidgets directory and execute
 the following sets of commands from the wxWidgets directory.
 
----------
+    mkdir build-cocoa-debug
+    cd build-cocoa-debug
+    ../configure --enable-debug
+    make
 
-mkdir build-cocoa-debug
+Build the samples and demos
-cd build-cocoa-debug
-../configure --enable-debug
-make
-# Build the samples and demos
-cd samples; make;cd ..
-cd demos;   make;cd ..
 
----------
+    cd samples; make;cd ..
+    cd demos;   make;cd ..
 
 After the compilation completes, use Finder to run the samples and demos
-  Go to build-cocoa-debug/samples to experiment with the Cocoa samples.
+* Go to build-cocoa-debug/samples to experiment with the Cocoa samples.
-  Go to build-cocoa-debug/demos to experiment with the Cocoa demos.
+* Go to build-cocoa-debug/demos to experiment with the Cocoa demos.
-Double-click on the executables which have an icon showing three small squares.
+* Double-click on the executables which have an icon showing three small squares.
-The source code for the samples is in wxWidgets/samples
+* The source code for the samples is in wxWidgets/samples
-The source code for the demos is in wxWidgets/demos
+* The source code for the demos is in wxWidgets/demos
-
----------
 
 More information about building on OS X is available in the wxWiki.
 Here are two useful links
-  https://wiki.wxwidgets.org/Guides_%26_Tutorials
+  * https://wiki.wxwidgets.org/Guides_%26_Tutorials
-  https://wiki.wxwidgets.org/Development:_wxMac
+  * https://wiki.wxwidgets.org/Development:_wxMac
 
----------
 
-More advanced topics are covered below.
+Advanced topics                        {#osx_advanced}
+===============
 
----------
+Installing library                     {#osx_install}
+------------------
 
 If you want to install the library into the system directories you'll need
 to do this as root.  The accepted way of running commands as root is to
 use the built-in sudo mechanism.  First of all, you must be using an
 account marked as a "Computer Administrator".  Then
 
-6) sudo make install
+    sudo make install
-7) type <YOUR OWN PASSWORD>
+    type \<YOUR OWN PASSWORD\>
 
 Note that while using this method is okay for development, it is not
 recommended that you require endusers to install wxWidgets into their
@@ -61,13 +60,13 @@ is to configure wxWidgets with --disable-shared.  Another way to avoid
 it is to make a framework for wxWidgets.  Making frameworks is beyond
 the scope of this document.
 
-Note:
+**Note:**
 It is rarely desirable to install non-Apple software into system directories.
 By configuring the library with --disable-shared and using the full path
 to wx-config with the --in-place option you can avoid installing the library.
 
 
-Apple Developer Tools: Xcode
+Apple Developer Tools: Xcode           {#osx_xcode}
 ----------------------------
 
 You can use the project in build/osx/wxcocoa.xcodeproj to build the Cocoa
@@ -79,10 +78,10 @@ also wxrc tool which doesn't have its own Xcode project. If you need this tool,
 the simplest possibility is to build it from the command line after installing
 the libraries using commands like this:
 
-$ cd utils/wxrc
+    $ cd utils/wxrc
-$ g++ -o wxrc wxrc.cpp `wx-config --cxxflags --libs base,xml`
+    $ g++ -o wxrc wxrc.cpp `wx-config --cxxflags --libs base,xml`
 
-Creating universal binaries
+Creating universal binaries            {#osx_universal_bin}
 ---------------------------
 
 The Xcode projects for the wxWidgets library and minimal project are set up
@@ -108,11 +107,11 @@ binaries together. Assuming building on a PPC system:
 
 2. Then, build for Intel, in a different folder. This time use:
 
-export CFLAGS="-g -isysroot /Developer/SDKs/MacOSX10.7.sdk -arch i386"
+        export CFLAGS="-g -isysroot /Developer/SDKs/MacOSX10.7.sdk -arch i386"
-export LDFLAGS="-syslibroot,/Developer/SDKs/MacOSX10.7.sdk"
+        export LDFLAGS="-syslibroot,/Developer/SDKs/MacOSX10.7.sdk"
 
-./configure --disable-dependency-tracking --enable-static=yes --enable-shared=no \
+        ./configure --disable-dependency-tracking --enable-static=yes --enable-shared=no \
-  --target=i386-apple-darwin8 --host=powerpc-apple-darwin8 --build=i386-apple-darwin8
+        --target=i386-apple-darwin8 --host=powerpc-apple-darwin8 --build=i386-apple-darwin8
 
 You will need to reverse the powerpc and i386 parameters everywhere to build PPC on an Intel
 machine.

docs/osx/readme.txt

@@ -4,7 +4,7 @@ More Information is available from the wxWidgets project home page at
 
 https://www.wxwidgets.org
 
-For more information, please see install.txt and the manuals.
+For more information, please see install.md and the manuals.
 
 Please send problems concerning installation, feature requests,
 bug reports or comments to the wxWidgets users list. Information