Remove hardcoded version numbers (part 2) and more documentation

The goal is to change the version number for a new release only in
CMakeLists.txt. This is the second step.

This commit also adds a chapter "Migrating Code from FLTK 1.4 to 1.5".

Details:

- documentation/CMakeLists.txt: configure 'version.dox'
- fluid/documentation/CMakeLists.txt: same as above
- documentation/Doxyfile.in: add "Migrating Code from FLTK 1.4 to 1.5"
- documentation/src/index.dox: include 'version.dox' and 'migrating...'
- fluid/documentation/src/index.dox: same as above
- documentation/src/preface.dox: include 'version.dox'
- documentation/version.dox.in: input to CMake configure 'version.dox'
- fluid/documentation/version.dox.in: same as above
- documentation/src/migration_1_4.dox: update links
- documentation/src/migration_1_5.dox: new documentation chapter

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

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 \

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

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">
+    <a class="el" href="migration_1_5.html">
-    Software License
+    Migrating Code from FLTK 1.4 to 1.5
     [Next]
     </a>
   </td>

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
+
+*/

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.
 

documentation/version.dox.in

@@ -0,0 +1 @@
+@FLTK_VERSION@

fluid/documentation/CMakeLists.txt

@@ -47,6 +47,13 @@ if(FLTK_BUILD_FLUID_DOCS OR FLTK_BUILD_PDF_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

fluid/documentation/src/index.dox

@@ -2,27 +2,27 @@
 
 /**
 
- \cond FL_HTML_INDEX
+\cond FL_HTML_INDEX
 
- \mainpage FLUID User Manual
+\mainpage FLUID User Manual
 
 
- <TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
+<TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
- <TR>
+<TR>
-   <TD><CENTER>
+  <TD><CENTER>
-     \image html fluid-128.png
+    \image html fluid-128.png
-     \image latex fluid-128.png  "" width=3cm
+    \image latex fluid-128.png  "" width=3cm
-   </CENTER></TD>
+  </CENTER></TD>
-   <TD><CENTER>
+  <TD><CENTER>
-     <B>FLUID 1.5.0 User Manual</B>
+    <B>FLUID \include{doc} version.dox User Manual</B>
 
-     By F.&nbsp;Costantini, M.&nbsp;Melcher,
+    By F.&nbsp;Costantini, M.&nbsp;Melcher,
-     A.&nbsp;Schlosser, B.&nbsp;Spitzak and M.&nbsp;Sweet.
+    A.&nbsp;Schlosser, B.&nbsp;Spitzak and M.&nbsp;Sweet.
 
-     Copyright © 1998 - 2025 by Bill Spitzak and others.
+    \include{doc} copyright.dox
-   </CENTER></TD>
+  </CENTER></TD>
- </TR>
+</TR>
- </TABLE>
+</TABLE>
 
  <TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
  <TR>

fluid/documentation/version.dox.in

@@ -0,0 +1 @@
+@FLTK_VERSION@