From cfa1a3bd401cea0e2cc9a5172971c28ead7dcfff Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Tue, 3 Oct 2023 09:19:36 +0200 Subject: [PATCH] Enhance info about documentation generation - update build requirements - clarify CMake options - make clear that a POSIX shell and some Unix tools are required to build the PDF documentation --- README.CMake.txt | 13 ++++-- documentation/README.txt | 99 ++++++++++++++++++++++++++++------------ 2 files changed, 78 insertions(+), 34 deletions(-) diff --git a/README.CMake.txt b/README.CMake.txt index f7bf6604c..97cf7822f 100644 --- a/README.CMake.txt +++ b/README.CMake.txt @@ -226,20 +226,25 @@ Documentation options: these options are only available if `doxygen' is OPTION_BUILD_HTML_DOCUMENTATION - default ON OPTION_BUILD_PDF_DOCUMENTATION - default ON These options can be used to switch HTML documentation generation with - doxygen on. The build targets ('html', 'pdf', or 'docs') need still to - be executed explicitly. + doxygen on. If these are ON the build targets 'html', 'pdf', and 'docs' + are generated but must be built explicitly. Technically the build targets + are generated but excluded from 'ALL'. You can safely leave these two + options ON if you want to save build time because the docs are not + built automatically. OPTION_INCLUDE_DRIVER_DOCUMENTATION - 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 - or advanced users. + and advanced users. It is only used if at least one of the documentation + options above is ON as well. OPTION_INSTALL_HTML_DOCUMENTATION - default OFF OPTION_INSTALL_PDF_DOCUMENTATION - default OFF - If these options are ON then the HTML and/or PDF docs get installed + 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 need to select above options OPTION_BUILD_*_DOCUMENTATION as well. + 2.3 Building under Linux with Unix Makefiles ----------------------------------------------- diff --git a/documentation/README.txt b/documentation/README.txt index f144bc68b..848ec66f1 100644 --- a/documentation/README.txt +++ b/documentation/README.txt @@ -1,9 +1,9 @@ README.txt (documentation) --------------------------- -FLTK 1.3 (and higher) documentation is available in HTML and PDF format. -The documentation must be generated in a separate step or downloaded -from FLTK's software download pages. The documentation can also -be accessed online. +Documentation is available in HTML and PDF format built using 'doxygen' +since FLTK 1.3. The documentation must be generated in a separate step +or downloaded from FLTK's software download pages. The documentation can +also be accessed online. To read the docs after downloading or generating them, open the files: @@ -13,16 +13,30 @@ To read the docs after downloading or generating them, open the files: with your browser or PDF viewer, respectively. -Online Documentation: ---------------------- +Online Documentation (Latest Release): +-------------------------------------- A documentation version is available online at the FLTK web site, along with the PDF version of the manual. The docs on the web site -are usually somewhat older (latest release). Use this URL to find -the current online documentation: +are usually somewhat older (latest release). The active development +version (currently 1.4.0) is updated from time to time. + +Use this URL to find the current online documentation: https://www.fltk.org/documentation.php +Online Documentation (Daily CI Build): +-------------------------------------- +The documentation of the development branch 'master' is generated +daily in the CI (Continuous Integration) build on our GitLab mirror. +This is experimental and may be discontinued at any time. + +Documentation can be found at these URL's: + + HTML: https://fltk.gitlab.io/fltk/ + PDF: https://fltk.gitlab.io/fltk/fltk.pdf + + Documentation Download: ----------------------- To download pre-generated docs, go to @@ -38,20 +52,34 @@ Extract the documentation tarballs into the same directory as you did with the source tarball. -Generation of Documentation (common part): +Generation of Documentation (Common Part): ------------------------------------------ -To generate the documentation yourself, you should have Doxygen -version 1.8 or later (recommended version is 1.8.13 or later). +To generate the documentation yourself you should have Doxygen +version 1.8 or later. Recommended version as of this writing +(October 2023) is 1.9.8 or later. Older Doxygen versions than 1.8 may or may not work. +Full documentation generation is supported only on Unix/Linux +platforms that provide a POSIX compatible shell (e.g. 'bash') and +some standard Unix tools. Doxygen alone may be enough to generate +HTML docs but PDF documentation *requires* a POSIX shell and the +mentioned Unix tools. + +On the Windows platform building HTML and particularly PDF docs +*may* work if you install and use MinGW, MSYS2, or Cygwin and all +required LaTeX tools but this is not supported and we don't +recommend it. + To generate the PDF version you also need a current version of LaTeX. -You can use the packages tetex (older) or texlive (current) if your -distribution provides them. You may need to install additional fonts -and other sub-packages for the PDF version to be generated correctly. +To install all required packages on recent Debian and Ubuntu Linux +distributions you can install the package 'doxygen-latex' which +"adds dependencies for all LaTeX packages required to build documents +using the default stylesheet" according to its description. -Note: packages known to work under Ubuntu 18.04: - - texlive texlive-extra-utils texlive-latex-extra texlive-font-utils +On other (and older) distributions you may use the packages tetex (older) +or texlive (current as of Ubuntu 18.04) if your distribution provides +them. You may need to install additional fonts and other sub-packages +for the PDF version to be generated correctly. Generation of Documentation with autoconf (configure) + make: @@ -63,34 +91,45 @@ generates both versions in one step (as would do "make clean html pdf"). To read the HTML or PDF docs, see above. -Generation of Documentation with CMake + make: ----------------------------------------------- +Generation of Documentation with CMake: +--------------------------------------- We assume that you use an out-of-source build as recommended. Documentation is not generated in a default build. You must set one or more CMake options using cmake-gui, ccmake, or cmake -DOPTION... -These options are predefined to OFF and can be switched ON: +For simplicity we use 'make' in the following description. If you +use another build system (e.g. 'ninja') please replace 'make' with +your preferred build command. - - OPTION_BUILD_HTML_DOCUMENTATION:BOOL=OFF target: html - - OPTION_BUILD_PDF_DOCUMENTATION:BOOL=OFF target: pdf +The following two options are predefined ON if you have the +required software packages (doxygen, LaTeX) installed. You can +always leave them ON because the documentation is not built +automatically (it is excluded from the default target "ALL"). + + - OPTION_BUILD_HTML_DOCUMENTATION:BOOL=ON target: html + - OPTION_BUILD_PDF_DOCUMENTATION:BOOL=ON target: pdf + +The following two options default to OFF and can be switched ON. +They are only used when installing the software ('make install') +and the corresponding build options are ON. - OPTION_INSTALL_HTML_DOCUMENTATION:BOOL=OFF - OPTION_INSTALL_PDF_DOCUMENTATION:BOOL=OFF -If you switch one or both of the first two options ON, then the +If you switch one or both of the first two options ON, then the build targets 'html' and/or 'pdf' are generated, respectively. Target 'docs' is added to generate both 'html' and 'pdf'. As said above, you need installed Doxygen and LaTeX software for this to work. -Use "make html" in the root or documentation directory of the build tree -to generate the HTML documentation, or "make pdf" to generate the PDF -version. "make docs" generates both versions in one step (as would do -"make clean html pdf"). +Use 'make html' in the root directory of the build tree to generate the +HTML documentation, or 'make pdf' to generate the PDF version. +'make docs' generates both versions in one step (as would do +'make clean html pdf'). To read the HTML or PDF docs, see above, but use the build directory. Note: if you enable one or more of the "*INSTALL*" options, then -`make install' will install the docs, but you must still build them +'make install' will install the docs, but you must still build them manually, because the generation is not included in the standard ('all') target. This may be changed in the future. @@ -106,7 +145,7 @@ Bugs and Feature Requests: -------------------------- If you find any typos, things that are unclear, or would like to contribute an example, section, or chapter to the FLTK manual, please -post a question in the fltk group fltk.general or post a bug -report or feature request. For more information see this page: +post a question in the fltk group fltk.general or post a bug report +or feature request. For more information see this page: https://www.fltk.org/bugs.php