Separate FLUID user documentation, screen shot automation (#936)

* CMake integration, no autotiools
* alignment panel is now correctly renamed to setting panel
* source view is now correctly renamed to code view
* Merge FLTK FLUID docs into FLUID user manual.
* Add two simple entry tutorials
* Remove FLUID chapter form FLTK docs.
* GitHub action to generate HTML and PDF docs and
  make the available as artefacts

.github/workflows/build_fluid_docs.yml

@@ -0,0 +1,84 @@
+#
+# This script builds the FLUID User Handbook as html directory and pdf
+# document on a Linux machine.
+#
+
+name: 'Build FLUID User Handbook'
+
+# This job must be called explicitly form the 'Actions' tab in GitHub
+on: [workflow_dispatch]
+
+permissions:
+  contents: read
+
+jobs:
+  build-html:
+    runs-on: ubuntu-latest
+
+## This can also run on macOS, but BasicTeX will not generate the pdf document
+#    runs-on: macos-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install prerequisites
+      run: |
+        sudo apt-get update -y
+        sudo apt-get install -y libwayland-dev wayland-protocols libdbus-1-dev libxkbcommon-dev libpango1.0-dev libgtk-3-dev
+        sudo apt-get install -y doxygen
+        sudo apt-get install -y doxygen-latex
+        sudo apt-get install -y xvfb
+        sudo apt-get install -y x11-xkb-utils xfonts-100dpi xfonts-75dpi xfonts-scalable xfonts-cyrillic x11-apps
+
+## Use the following line when 1.10.0 becomes available on Ubuntu. On 4/14/24 it's 1.9.2
+#        sudo apt-get install -y doxygen=1.10.0
+
+## xvfb creates a headless X server for us, so we can render snapshot with FLUID
+
+## We need at least Doxygen on macOS. BasicTeX is not enough though.
+#        brew install doxygen
+#        brew install --cask basictex
+#        eval "$(/usr/libexec/path_helper)"
+
+    - name: Create Build Environment
+      run: cmake -E make_directory ${{github.workspace}}/build
+
+    - name: Configure CMake
+      shell: bash
+      working-directory: ${{github.workspace}}/build
+      run: |
+        cmake $GITHUB_WORKSPACE \
+          -D CMAKE_BUILD_TYPE=Debug \
+          -D CMAKE_CXX_STANDARD=11 \
+          -D CMAKE_CXX_EXTENSIONS=OFF \
+          -D CMAKE_C_FLAGS_INIT="-Wall -Wunused" \
+          -D CMAKE_CXX_FLAGS_INIT="-Wall -Wunused -Wsuggest-override" \
+          -D FLTK_BUILD_FLTK_OPTIONS=OFF \
+          -D FLTK_BUILD_FLUID=ON \
+          -D FLTK_BUILD_GL=OFF \
+          -D FLTK_BUILD_TEST=OFF \
+          -D FLTK_BUILD_FLUID_DOCS=ON
+
+    - name: Build
+      working-directory: ${{github.workspace}}/build
+      shell: bash
+      run: |
+        Xvfb :19 -screen 0 1024x768x16 &
+        export DISPLAY=:19
+        cmake --build . --config Debug --target fluid_docs
+        cmake --build . --config Debug --target fluid_pdf
+    - name: Store html docs as an artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: fluid-html
+        path: build/fluid/documentation/html
+        retention-days: 3
+        overwrite: true
+    - name: Store pdf docs as an artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: fluid-pdf
+        path: build/fluid/documentation/fluid.pdf
+        retention-days: 3
+        overwrite: true
+

CMake/options.cmake

@@ -459,6 +459,8 @@ endif()
 if(DOXYGEN_FOUND)
   option(FLTK_BUILD_HTML_DOCS "build html docs" ON)
   option(FLTK_INSTALL_HTML_DOCS "install html docs" OFF)
+  option(FLTK_BUILD_FLUID_DOCS "build FLUID docs" OFF)
+  option(FLTK_INSTALL_FLUID_DOCS "install FLUID docs" OFF)
 
   option(FLTK_INCLUDE_DRIVER_DOCS "include driver (developer) docs" OFF)
   mark_as_advanced(FLTK_INCLUDE_DRIVER_DOCS)
@@ -473,6 +475,10 @@ if(FLTK_BUILD_HTML_DOCS OR FLTK_BUILD_PDF_DOCS)
   add_subdirectory(documentation)
 endif(FLTK_BUILD_HTML_DOCS OR FLTK_BUILD_PDF_DOCS)
 
+if(FLTK_BUILD_FLUID_DOCS)
+  add_subdirectory(fluid/documentation)
+endif(FLTK_BUILD_FLUID_DOCS)
+
 #######################################################################
 # Include optional Cairo support
 #######################################################################

README.CMake.txt

@@ -325,16 +325,23 @@ FLTK_BUILD_PDF_DOCS  - default ON
     You can safely leave these two options ON if you want to save build time
     because the docs are not built automatically.
 
+FLTK_BUILD_FLUID_DOCS - default OFF
+    If this option is ON, the FLUID user documentation will be built. If 
+    FLTK_BUILD_PDF_DOCS is ON, the FLUID documentation will be generated
+    in PDF forma. To generate the screen shots used in the handbook,
+    the CMake build mode must be set to "Debug".
+
 FLTK_INCLUDE_DRIVER_DOCS - default OFF
     This option adds driver documentation to HTML and PDF docs (if ON). This
     option is marked as "advanced" since it is only useful for FLTK developers
     and advanced users. It is only used if at least one of the documentation
     options above is ON as well.
 
 FLTK_INSTALL_HTML_DOCS - default OFF
+FLTK_INSTALL_FLUID_DOCS - default OFF
 FLTK_INSTALL_PDF_DOCS  - default OFF
-    If these options are ON then the HTML and/or PDF docs are installed
-    when the 'install' target is executed, e.g. with `make install'. You
+    If these options are ON then the HTML, FLUID, and/or PDF docs are installed
+    when the 'install' target is executed, e.g. with `make install'. You 
     need to select above options FLTK_BUILD_*_DOCS as well.
 
 

documentation/CMakeLists.txt

@@ -52,7 +52,7 @@ if(GENERATE_DOCS)
   # find git revision
 
   # FIXME: This must also work with tarballs where git is not available.
-  #        For now we just ignore errors and set GIT_REVISION = "unkown".
+  #        For now we just ignore errors and set GIT_REVISION = "unknown".
   #        In the future tarball/zip generation should create a file
   #        that contains the git revision.
 

documentation/Doxyfile.in

@@ -794,7 +794,6 @@ INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src/index.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/events.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/subclassing.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/opengl.dox \
-                         @CMAKE_CURRENT_SOURCE_DIR@/src/fluid.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/fltk-options.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/advanced.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/unicode.dox \

documentation/Makefile

@@ -36,7 +36,6 @@ HTMLFILES	= 	 \
                          $(SRC_DOCDIR)/events.dox \
                          $(SRC_DOCDIR)/subclassing.dox \
                          $(SRC_DOCDIR)/opengl.dox \
-                         $(SRC_DOCDIR)/fluid.dox \
                          $(SRC_DOCDIR)/fltk-options.dox \
                          $(SRC_DOCDIR)/advanced.dox \
                          $(SRC_DOCDIR)/unicode.dox \

documentation/src/examples.dox

@@ -252,7 +252,7 @@ and shows OpenGL text.
 \subsection examples_CubeView CubeView
 
 \par
-\c CubeView shows how to create a UI containing OpenGL with Fluid.
+\c CubeView shows how to create a UI containing OpenGL with FLUID.
 
 
 \subsection examples_cursor cursor
@@ -577,7 +577,7 @@ come in handy. They remember any kind of data between program launches.
 \subsection examples_radio radio
 
 \par
-The \c radio tool was created entirely with <i>fluid</i>. It
+The \c radio tool was created entirely with <i>FLUID</i>. It
 shows some of the available button types and tests radio
 button behavior.
 
@@ -658,7 +658,7 @@ The \c table demo shows the features of the Fl_Table widget.
 \subsection examples_tabs tabs
 
 \par
-The \c tabs tool was created with <i>fluid</i>. It tests
+The \c tabs tool was created with <i>FLUID</i>. It tests
 correct hiding and redisplaying of tabs, navigation across tabs,
 resize behavior, and no unneeded redrawing of invisible widgets.
 
@@ -733,13 +733,13 @@ font draws each of the Unicode code points ranging between U+0020 and U+FFFF.
 while the focus stays in the original window.
 
 
-\subsection examples_fluid fluid
+\subsection examples_fluid FLUID
 
 \par
-\c fluid is not only a big test program, but also a very
-useful visual UI designer. Many parts of \c fluid were
-created using \c fluid. See the \link fluid Fluid Tutorial \endlink
-for more details.
+\c FLUID is not only a big test program, but also a very
+useful visual UI designer. Many parts of \c FLUID were
+created using \c FLUID. Check out the FLUID User Manual and
+the tutorials that come with it at https://www.fltk.org/documentation.php .
 
 
 

documentation/src/fltk-options.dox

@@ -41,8 +41,8 @@ tool called fltk-options.
 `fltk-options` is a hybrid app that is part of FLTK and can be installed on
 the target system. It includes an up-to-date man page.
 
-\image html fluid-edit-global-fltk-settings.png "fltk-options Application"
-\image latex fluid-edit-global-fltk-settings.png "fltk-options Application" width=10cm
+\image html fltk-options.png "fltk-options Application"
+\image latex fltk-options.png "fltk-options Application" width=10cm
 
 When fltk-options is called without any command-line arguments, it opens in
 interactive mode and provides a user interface to view and alter all
@@ -67,9 +67,9 @@ A full list of options can be found in the manual at Fl::Fl_Option.
 <table summary="navigation bar" width="100%" border="0">
 <tr>
   <td width="45%" align="LEFT">
-    <a class="el" href="fluid.html">
+    <a class="el" href="opengl.html">
     [Prev]
-    Programming with FLUID
+    Using OpenGL
     </a>
   </td>
   <td width="10%" align="CENTER">