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
This commit is contained in:
Albrecht Schlosser
parent
4132590d8c
commit
cfa1a3bd40
@ -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
|
||||
-----------------------------------------------
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user