Improve documentation index and chapter "Migrating Code ..."

- remove redundant "Revision 11" from documentation index page.
- update index (missing refs and one wrong ref)
- update page break
- document header requirements and potential FLTK 1.3 code issues

documentation/src/fltk-title.tex.in

@@ -11,7 +11,7 @@
 \end{DoxyImageNoCaption}\\
 \vspace*{2cm}
 {\Large
-Revision 11 by F. Costantini, D. Gibson, M. Melcher, \\
+By F. Costantini, D. Gibson, M. Melcher, \\
 A. Schlosser, B. Spitzak, and M. Sweet.}\\
 \vspace*{1.5cm}
 {\large Copyright 1998-@YEAR@ by Bill Spitzak and others.}\\

documentation/src/index.dox

@@ -10,10 +10,10 @@
   <TD><CENTER>
     <B>FLTK 1.4.0 Programming Manual</B>
 
-    Revision 11 by F.&nbsp;Costantini, D.&nbsp;Gibson, M.&nbsp;Melcher,
+    By F.&nbsp;Costantini, D.&nbsp;Gibson, M.&nbsp;Melcher,
     A.&nbsp;Schlosser, B.&nbsp;Spitzak and M.&nbsp;Sweet.
 
-    Copyright 1998-2020 by Bill Spitzak and others.
+    Copyright 1998-2021 by Bill Spitzak and others.
   </CENTER></TD>
 </TR>
 </TABLE>
@@ -48,11 +48,19 @@
     \subpage editor
 
     \subpage drawing
+        - \ref drawing_WhenCanYouDraw
+        - \ref drawing_DrawingUnit
+        - \ref drawing_DrawingFunctions
+        - \ref drawing_images
+        - \ref drawing_offscreen
 
     \subpage events
         - \ref events_event_xxx
         - \ref events_propagation
 
+  </TD>
+  <TD ALIGN="LEFT" VALIGN="TOP">
+
     \subpage subclassing
 
     \subpage opengl
@@ -62,9 +70,6 @@
         - \ref fluid_selecting_moving
         - \ref fluid_images
 
-  </TD>
-  <TD ALIGN="LEFT" VALIGN="TOP">
-
     \subpage advanced
 
     \subpage unicode

documentation/src/migration_1_4.dox

@@ -7,17 +7,53 @@ This appendix describes the differences between the FLTK
 
 \section migration_1_4_old_versions Migrating from FLTK 1.0 or 1.1 to 1.4
 
-If you want to migrate your code from FLTK 1.0 or 1.1 to FLTK 1.4,
+If you need to migrate your code from FLTK 1.0 or 1.1 to FLTK 1.4,
 then you should first consult the relevant appendices in FLTK 1.3
 documentation online or by downloading the FLTK 1.3 documentation.
 See https://www.fltk.org/doc-1.3/index.html
 and/or https://www.fltk.org/software.php , respectively.
 
 
-\section migration_1_4_headers Minor Changes in Header Files
+\section migration_1_4_headers Changes in Header Files
 
-(to be documented)
+We strive to include only necessary header files in the public headers
+of the FLTK library to reduce dependencies and hence compile times.
 
+We try to avoid including system header files as far as possible. Known
+exceptions are \<stdio.h> where file system structures and functions are
+visible in the public API, for instance \p FILE*, and sometimes essential
+header files like \<stdlib.h> and/or \<stddef.h>. Some required platform
+headers \b may be included in platform specific header files like
+\<FL/platform.H> or \<FL/platform_types.h>.
+
+In earlier versions (1.3.x) some of the public FLTK headers included some
+not strictly required system headers by accident.
+
+The consequence for building user programs with FLTK 1.4 is that if you
+require a system or FLTK header in your user program that you don't
+\e \#include explicitly but which has been included by FLTK 1.3.x your
+FLTK 1.3 program may issue compiler errors or warnings about missing header
+files or missing declarations when compiled with FLTK 1.4.
+
+This is not a fault of FLTK 1.4 but a fault of the source code that did
+not include all required headers.
+
+Suggested solution: include all FLTK and system header files your source
+code requires explicitly and don't rely on FLTK headers to include a
+particular header file.
+
+The same applies to FLTK headers. The rule is to \#include \<FL/Fl.H> as
+the first FLTK header as described in the documentation elsewhere an to
+include FLTK headers for all classes you are using explicitly. You don't
+need to include headers of base classes - this is done by all FLTK headers
+as required. Besides that you need to include some support headers if you
+are using FLTK functions like \p fl_choice() and others. This is described
+in the function's documentation (if a required header is missing in the
+docs this is a bug).
+
+If you follow these rules your program will be compatible with both
+FLTK 1.3.x and FLTK 1.4.x as long as you use only functions and classes
+defined in FLTK 1.3.
 
 
 \section migration_1_4_preferences Fl_Preferences