7 files changed, 120 insertions, 4 deletions
diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt
index 6cd1d1462..3dc9fbd1b 100644
--- a/documentation/CMakeLists.txt
+++ b/documentation/CMakeLists.txt
@@ -56,6 +56,13 @@ if(GENERATE_DOCS)
     string(REGEX REPLACE " .*$" "" DOXYGEN_VERSION_SHORT ${DOXYGEN_VERSION})
   endif(DOXYGEN_FOUND)
 
+  # configure version.dox (includes the bare FLTK version number)
+  configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/version.dox.in
+    ${CMAKE_CURRENT_BINARY_DIR}/version.dox
+    @ONLY
+  )
+
   # configure copyright.dox (includes current year)
   configure_file(
     ${CMAKE_CURRENT_SOURCE_DIR}/copyright.dox.in
diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in
index a96d1d718..f7ee0be90 100644
--- a/documentation/Doxyfile.in
+++ b/documentation/Doxyfile.in
@@ -805,6 +805,7 @@ INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src/index.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/forms.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/osissues.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/migration_1_4.dox \
+                         @CMAKE_CURRENT_SOURCE_DIR@/src/migration_1_5.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/development.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/license.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/examples.dox \
diff --git a/documentation/src/index.dox b/documentation/src/index.dox
index 6a51c1674..f75ee60d6 100644
--- a/documentation/src/index.dox
+++ b/documentation/src/index.dox
@@ -8,7 +8,7 @@
     \image latex FL200.png "" width=5cm
   </CENTER></TD>
   <TD><CENTER>
-    <B>FLTK 1.5.0 Programming Manual</B>
+    <B>FLTK \include{doc} version.dox Programming Manual</B>
 
     By F.&nbsp;Costantini, M.&nbsp;Melcher,
     A.&nbsp;Schlosser, B.&nbsp;Spitzak and M.&nbsp;Sweet.
@@ -17,6 +17,7 @@
   </CENTER></TD>
 </TR>
 </TABLE>
+
 <TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
 <TR>
   <TD style="text-align: center;">
@@ -88,6 +89,8 @@
 
         - \subpage migration_1_4
 
+        - \subpage migration_1_5
+
         - \subpage license
 
         - \subpage examples
diff --git a/documentation/src/migration_1_4.dox b/documentation/src/migration_1_4.dox
index 27962129a..0a92072c0 100644
--- a/documentation/src/migration_1_4.dox
+++ b/documentation/src/migration_1_4.dox
@@ -430,8 +430,8 @@ This code will load the old font 'Arial' on Windows:
     <a class="el" href="index.html">[Index]</a>
   </td>
   <td width="45%" align="RIGHT">
-    <a class="el" href="license.html">
-    Software License
+    <a class="el" href="migration_1_5.html">
+    Migrating Code from FLTK 1.4 to 1.5
     [Next]
     </a>
   </td>
diff --git a/documentation/src/migration_1_5.dox b/documentation/src/migration_1_5.dox
new file mode 100644
index 000000000..cbe98919b
--- /dev/null
+++ b/documentation/src/migration_1_5.dox
@@ -0,0 +1,103 @@
+/**
+
+ \page  migration_1_5   Migrating Code from FLTK 1.4 to 1.5
+
+This appendix describes the differences between FLTK
+1.4.x and FLTK 1.5.x functions and classes and potential requirements
+to change source code. We also explain how code can be made compatible
+so it can be compiled by FLTK 1.3.x, 1.4.x, and 1.5.x.
+
+If you need to migrate your code from prior FLTK versions to FLTK 1.4,
+please consult the relevant appendices in the FLTK 1.3 online documentation
+or by downloading the FLTK 1.3 documentation.
+See https://www.fltk.org/doc-1.3/migration_1_3.html and/or
+https://www.fltk.org/software.php, respectively.
+
+
+\section migration_1_5_cmake CMake is required to build FLTK
+
+Building with configure/make and included Makefile's has been discontinued.
+Since FLTK 1.5.0 CMake is required to build FLTK. Please see README.CMake.txt
+for details.
+
+
+\section migration_1_5_cxx_standard FLTK requires C++11 or higher
+
+You need a compiler or build system capable of at least C++ standard C++11.
+The compiler must be configured to run in C++11 mode or higher.
+
+FLTK sets the required compiler options automatically (via CMake) for its own
+build.
+
+If you use "Modern CMake" (basically CMake in CONFIGURE mode) to build your
+own projects the appropriate options are inherited from the properties of
+the FLTK libraries as well. Otherwise you may need to set the compiler flags
+to use at least C++11 yourself.
+
+
+\section migration_1_5_forms Default for FORMS compatibility is now OFF
+
+If you need (X)Forms compatibility you must set the CMake configure option
+
+    FLTK_BUILD_FORMS:BOOL=ON
+
+manually. In previous versions (up to 1.4.x) the default was 'ON', but since
+Forms compatibility is not a primary goal of FLTK this is now optional.
+
+
+(X)Forms support \b may be removed entirely in a future FLTK release. We
+recommend all users to rewrite their code to use "native" FLTK code anyway.
+
+
+
+\section migration_1_5_fl_override Simplified FL_OVERRIDE Macro
+
+FLTK 1.4 defined a new macro \p FL_OVERRIDE as "override" if (and only if)
+a recent C++ standard (C++11 or higher) was used to compile its code.
+
+Since FLTK 1.5 this macro is unconditionally defined as 'override' because
+FLTK requires C++11 anyway.
+
+For more details please see \ref migration_1_4_fl_override.
+
+
+\section migration_1_5_deprecated Deprecated methods and functions removed
+
+Methods, functions, and global symbols that have been deprecated in FLTK 1.3
+or earlier have been removed. If you need help with those functions because
+your old code still uses one or more of them, please consult the FLTK 1.3 or
+1.4 documentation for how to replace them with newer functions/methods.
+
+The following (very likely incomplete) list may help to identify such removed
+methods and functions:
+
+Removed symbol            | Replace with ...
+--------------------------|-------------------------
+Fl::release()             | Fl::grab(0)
+
+
+
+\htmlonly
+<hr>
+<table summary="navigation bar" width="100%" border="0">
+<tr>
+  <td width="45%" align="LEFT">
+    <a class="el" href="migration_1_4.html">
+    [Prev]
+    Migrating Code from FLTK 1.3 to 1.4
+    </a>
+  </td>
+  <td width="10%" align="CENTER">
+    <a class="el" href="index.html">[Index]</a>
+  </td>
+  <td width="45%" align="RIGHT">
+    <a class="el" href="license.html">
+    Software License
+    [Next]
+    </a>
+  </td>
+</tr>
+</table>
+\endhtmlonly
+
+*/
diff --git a/documentation/src/preface.dox b/documentation/src/preface.dox
index aca7289fd..d8c881426 100644
--- a/documentation/src/preface.dox
+++ b/documentation/src/preface.dox
@@ -2,7 +2,8 @@
 
  \page preface Preface
 
-This manual describes the Fast Light Tool Kit ("FLTK") version 1.5.0,
+This manual describes the Fast Light Tool Kit ("FLTK")
+\include{doc} version.dox,
 a C++ Graphical User Interface ("GUI") toolkit for UNIX, Microsoft Windows,
 and Apple macOS.
 
diff --git a/documentation/version.dox.in b/documentation/version.dox.in
new file mode 100644
index 000000000..569b8ea85
--- /dev/null
+++ b/documentation/version.dox.in
@@ -0,0 +1 @@
+@FLTK_VERSION@