Update documentation

documentation/src/drawing.dox

@@ -409,7 +409,7 @@ used up to FLTK 1.3.x. You can use
   fl_contrast_mode(FL_CONTRAST_LEGACY);
 
 early in your program to select the old behavior if you really need strict backwards
-compatibility but this is discouraged because the new algorithm is much better with
+compatibility. This is discouraged because the new algorithm is much better with
 regard to human contrast perception. The default mode since FLTK 1.4.0 is
 
   fl_contrast_mode(FL_CONTRAST_CIELAB);

documentation/src/examples.dox

@@ -36,86 +36,87 @@ you build FLTK, unlike those in the 'test' directory shown below.
 <td> \ref examples_checkers        </td>
 </tr>
 <tr>
+<td> \ref examples_clipboard       </td>
 <td> \ref examples_clock           </td>
 <td> \ref examples_colbrowser      </td>
 <td> \ref examples_color_chooser   </td>
 <td> \ref examples_cube            </td>
 <td> \ref examples_CubeView        </td>
-<td> \ref examples_cursor          </td>
 </tr>
 <tr>
+<td> \ref examples_cursor          </td>
 <td> \ref examples_curve           </td>
 <td> \ref examples_demo            </td>
 <td> \ref examples_device          </td>
 <td> \ref examples_doublebuffer    </td>
 <td> \ref examples_editor          </td>
-<td> \ref examples_fast_slow       </td>
 </tr>
 <tr>
+<td> \ref examples_fast_slow       </td>
 <td> \ref examples_file_chooser    </td>
 <td> \ref examples_fluid           </td>
 <td> \ref examples_fonts           </td>
 <td> \ref examples_forms           </td>
 <td> \ref examples_fractals        </td>
-<td> \ref examples_fullscreen      </td>
 </tr>
 <tr>
+<td> \ref examples_fullscreen      </td>
 <td> \ref examples_gl_overlay      </td>
 <td> \ref examples_glpuzzle        </td>
 <td> \ref examples_hello           </td>
 <td> \ref examples_help_dialog     </td>
 <td> \ref examples_icon            </td>
-<td> \ref examples_iconize         </td>
 </tr>
 <tr>
+<td> \ref examples_iconize         </td>
 <td> \ref examples_image           </td>
 <td> \ref examples_inactive        </td>
 <td> \ref examples_input           </td>
 <td> \ref examples_input_choice    </td>
 <td> \ref examples_keyboard        </td>
-<td> \ref examples_label           </td>
 </tr>
 <tr>
+<td> \ref examples_label           </td>
 <td> \ref examples_line_style      </td>
 <td> \ref examples_list_visuals    </td>
 <td> \ref examples_mandelbrot      </td>
 <td> \ref examples_menubar         </td>
 <td> \ref examples_message         </td>
-<td> \ref examples_minimum         </td>
 </tr>
 <tr>
+<td> \ref examples_minimum         </td>
 <td> \ref examples_native-filechooser </td>
 <td> \ref examples_navigation      </td>
 <td> \ref examples_offscreen       </td>
 <td> \ref examples_output          </td>
 <td> \ref examples_overlay         </td>
-<td> \ref examples_pack            </td>
 </tr>
 <tr>
+<td> \ref examples_pack            </td>
 <td> \ref examples_pixmap          </td>
 <td> \ref examples_pixmap_browser  </td>
 <td> \ref examples_preferences     </td>
 <td> \ref examples_radio           </td>
 <td> \ref examples_resize          </td>
-<td> \ref examples_resizebox       </td>
 </tr>
 <tr>
+<td> \ref examples_resizebox       </td>
 <td> \ref examples_rotated_text    </td>
 <td> \ref examples_scroll          </td>
 <td> \ref examples_shape           </td>
 <td> \ref examples_subwindow       </td>
 <td> \ref examples_sudoku          </td>
-<td> \ref examples_symbols         </td>
 </tr>
 <tr>
+<td> \ref examples_symbols         </td>
 <td> \ref examples_table           </td>
 <td> \ref examples_tabs            </td>
 <td> \ref examples_threads         </td>
 <td> \ref examples_tile            </td>
 <td> \ref examples_tiled_image     </td>
-<td> \ref examples_tree            </td>
 </tr>
 <tr>
+<td> \ref examples_tree            </td>
 <td> \ref examples_twowin          </td>
 <td> \ref examples_unittests       </td>
 <td> \ref examples_utf8            </td>
@@ -204,7 +205,8 @@ The \c button test is a simple demo of push-buttons and callbacks.
 
 \par
 \c cairo_test shows a sample of drawing with Cairo in an Fl_Cairo_Window.
-This program can only be built if FLTK was configured with Cairo support.
+This program can only be built completely if FLTK was configured with Cairo
+support. It displays a message box if Cairo support was not included.
 
 
 \subsection examples_checkers checkers
@@ -217,6 +219,16 @@ pieces, and how the pieces are drawn by layering. Then tell me
 how to beat the computer at Checkers.
 
 
+\subsection examples_clipboard clipboard
+
+\par
+The \c clipboard demo can be used to view the contents of the
+system clipboard, either text or image contents. Currently an
+image is preferred if the clipboard contains both formats.
+Images can be stored as PNG files so screenshots can be
+stored on disk with this little FLTK demo program.
+
+
 \subsection examples_clock clock
 
 \par
@@ -273,9 +285,8 @@ on few systems (some version of Irix for example).
 \subsection examples_demo demo
 
 \par
-This tool allows quick access to all programs in the \c test directory.
-\c demo is based on the visuals of the IrixGL demo program. The menu
-tree can be changed by editing <tt>test/demo.menu</tt>.
+This tool allows quick access to most programs in the \c test directory.
+The menu tree can be changed by editing <tt>test/demo.menu</tt>.
 
 
 \subsection examples_device device
@@ -283,9 +294,9 @@ tree can be changed by editing <tt>test/demo.menu</tt>.
 \par
 Exercises the Fl_Image_Surface, Fl_Copy_Surface, and Fl_Printer classes to draw to an
 Fl_Image object, copy graphical data to the clipboard, and for print support.
-\note The clipboard.cxx program of the 'examples' directory is a clipboard watching
+\note The clipboard.cxx program of the 'test' directory is a clipboard watching
 application that continuously displays the textual or graphical content of the system
-clipboard (a.k.a pasteboard on Mac OS X) exercising Fl::paste().
+clipboard (a.k.a pasteboard on macOS) exercising Fl::paste().
 
 
 \subsection examples_doublebuffer doublebuffer
@@ -307,6 +318,7 @@ and derived classes are rather light weight, however
 Fl_Text_Editor is a complete port of <i>nedit</i> (with permission).
 The \c editor test is almost a full application, showing custom
 syntax highlighting and dialog creation.
+See chapter \ref editor for a tutorial about creating this program.
 
 
 \subsection examples_fast_slow fast_slow

documentation/src/forms.dox

@@ -5,16 +5,25 @@
 
 This appendix describes the Forms compatibility included with FLTK.
 
-<center>
-<table border="1" width="90%" bgcolor="#cccccc">
-<tr>
-<th align="center">
-Warning: The Forms compatibility is deprecated and no longer maintained
-since FLTK 1.3.0 and is likely to be removed completely in FLTK 1.4 or 1.5
-</th>
-</tr>
-</table>
-</center>
+\note The Forms compatibility library is deprecated, no longer actively
+  maintained since FLTK 1.3.0, and likely to be removed completely
+  in FLTK 1.5.
+
+Since FLTK 1.4 building the Forms compatibility library \c fltk_forms
+(configure/Makefiles) or \c fltk::forms (CMake) can be disabled with
+one of these commands:
+  \code
+    - ./configure --disable-forms ...
+    - cmake -D FLTK_BUILD_FORMS:BOOL=OFF ...
+    - cmake-gui ...
+  \endcode
+
+Fluid can still import Forms and XForms designer (.fd) files but w/o
+any guarantees for working results. Manual fixes may be necessary.
+
+In the next minor or major release (1.5 or higher) the Forms compatibility
+library will not be built by default or will be removed entirely.
+
 
 \section forms_importing Importing Forms Layout Files