From cb6ee39852d2a3ddeba1a68fab3086c487b998bc Mon Sep 17 00:00:00 2001
From: Albrecht Schlosser <albrechts.fltk@online.de>
Date: Thu, 17 Oct 2024 16:01:32 +0200
Subject: [PATCH] Update documentation
- fix missing doxygen version in PDF docs created by CMake
- remove unnecessary quotes ('...') from version numbers and
Git revisions (previously added for debugging purposes)
- fix navigation links at the bottom of tutorial pages (HTML only)
- remove 'D. Gibson' from documentation headers on his request
---
documentation/CMakeLists.txt | 6 ++
documentation/generated.dox.in | 4 +-
documentation/src/development.dox | 77 +++++++++-------------
documentation/src/examples.dox | 2 +-
documentation/src/fltk-title.tex.in | 4 +-
documentation/src/glut.dox | 2 +-
documentation/src/index.dox | 2 +-
documentation/src/license.dox | 4 +-
documentation/src/migration_1_4.dox | 4 +-
documentation/src/unicode.dox | 2 +-
fluid/documentation/generated.dox.in | 4 +-
fluid/documentation/src/fluid-title.tex.in | 6 +-
fluid/documentation/src/index.dox | 2 +-
13 files changed, 54 insertions(+), 65 deletions(-)
diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt
index 150771a0d..f93d0cba5 100644
--- a/documentation/CMakeLists.txt
+++ b/documentation/CMakeLists.txt
@@ -161,6 +161,12 @@ if(FLTK_BUILD_PDF_DOCS)
# convert Doxybook to current doxygen version
+ # set DOXY_VERSION for compatibility with configure/make,
+ # to be replaced in fltk-title.tex.in
+ # FIXME: this can be simplified when configure/make is no longer supported
+
+ set(DOXY_VERSION "${DOXYGEN_VERSION_SHORT}") #
+
add_custom_command(
OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${DOXYFILE}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
diff --git a/documentation/generated.dox.in b/documentation/generated.dox.in
index 75f8dfc1e..fc6afa009 100644
--- a/documentation/generated.dox.in
+++ b/documentation/generated.dox.in
@@ -1,6 +1,6 @@
<br>
<small>
Generated on @CURRENT_DATE@
- from Git revision '@FLTK_GIT_REVISION@'
- by Doxygen version '@DOXYGEN_VERSION_SHORT@'
+ from Git revision @FLTK_GIT_REVISION@
+ by Doxygen version @DOXYGEN_VERSION_SHORT@
</small>
diff --git a/documentation/src/development.dox b/documentation/src/development.dox
index 89d67f431..4b976d183 100644
--- a/documentation/src/development.dox
+++ b/documentation/src/development.dox
@@ -117,9 +117,14 @@ These comments will not be visible in the generated document.
will be shown as:
- The following text is a developer comment.
- <!-- *** This *** is *** invisible *** -->
- This will be visible again.
+ The following text is a developer comment.
+ <!-- *** This *** is *** invisible *** -->
+ This will be visible again.
+
+\note Since an unknown Doxygen version indentation by four or more bytes
+ is automatically displayed as if it was framed by \\code and \\endcode.
+ You need to take care that "normal" text is not indented that much to
+ avoid mis-interpretation and formatting as code.
<H3>Different Headlines</H3>
@@ -131,29 +136,29 @@ there seems to be no difference in the font sizes of \<H3> and \<H4>
in the pdf output, whereas the html output uses different font sizes.
\code
- <H1>Headline in big text (H1)</H1>
- <H2>Headline in big text (H2)</H2>
- <H3>Headline in big text (H3)</H3>
- <H4>Headline in big text (H4)</H4>
+ <H1>Headline in big text (H1)</H1>
+ <H2>Headline in big text (H2)</H2>
+ <H3>Headline in big text (H3)</H3>
+ <H4>Headline in big text (H4)</H4>
\endcode
- <H1>Headline in big text (H1)</H1>
- <H2>Headline in big text (H2)</H2>
- <H3>Headline in big text (H3)</H3>
- <H4>Headline in big text (H4)</H4>
+ <H1>Headline in big text (H1)</H1>
+ <H2>Headline in big text (H2)</H2>
+ <H3>Headline in big text (H3)</H3>
+ <H4>Headline in big text (H4)</H4>
\section development_non_ascii Non-ASCII Characters
\code
- Doxygen understands many HTML quoting characters like
- ", ü, ç, Ç, but not all HTML quoting characters.
+ Doxygen understands many HTML quoting characters like
+ ", ü, ç, Ç, but not all HTML quoting characters.
\endcode
This will appear in the document:
- Doxygen understands many HTML quoting characters like
- ", ü, ç, Ç, but not all HTML quoting characters.
+ Doxygen understands many HTML quoting characters like
+ ", ü, ç, Ç, but not all HTML quoting characters.
For further informations about HTML quoting characters see
<br> \b http://www.doxygen.org/manual/htmlcmds.html
@@ -190,18 +195,18 @@ links \b from normal (e.g. class) documentation \b to documentation sections
This page has
\code
- \page development I - Developer Information
+ \page development Developer Information
\endcode
at its top.
This section is
\code
- \section development_structure Document Structure
+ \section development_structure Document Structure
\endcode
The following section is
\code
- \section development_links Creating Links
+ \section development_links Creating Links
\endcode
@@ -307,7 +312,9 @@ Each introduction (tutorial) page ends with navigation elements. These
elements must only be included in the html documentation, therefore
they must be separated with \\htmlonly and \\endhtmlonly.
-The following code gives the navigation bar at the bottom of this page:
+The following code creates the navigation bar at the bottom of the
+\ref basics HTML page as an example of all pages in the "FLTK Programming Manual"
+section. Note that \b this \b page is one of the appendices w/o navigation bar.
\verbatim
\htmlonly
@@ -315,17 +322,17 @@ The following code gives the navigation bar at the bottom of this page:
<table summary="navigation bar" width="100%" border="0">
<tr>
<td width="45%" align="LEFT">
- <a class="el" href="migration_1_4.html">
+ <a class="el" href="intro.html">
[Prev]
- Migrating Code from FLTK 1.3 to 1.4
+ Introduction to FLTK
</a>
</td>
<td width="10%" align="CENTER">
<a class="el" href="index.html">[Index]</a>
</td>
<td width="45%" align="RIGHT">
- <a class="el" href="license.html">
- Software License
+ <a class="el" href="common.html">
+ Common Widgets and Attributes
[Next]
</a>
</td>
@@ -334,28 +341,4 @@ The following code gives the navigation bar at the bottom of this page:
\endhtmlonly
\endverbatim
-
-\htmlonly
-<hr>
-<table summary="navigation bar" width="100%" border="0">
-<tr>
- <td width="45%" align="LEFT">
- <a class="el" href="migration_1_4.html">
- [Prev]
- Migrating Code from FLTK 1.3 to 1.4
- </a>
- </td>
- <td width="10%" align="CENTER">
- <a class="el" href="index.html">[Index]</a>
- </td>
- <td width="45%" align="RIGHT">
- <a class="el" href="license.html">
- Software License
- [Next]
- </a>
- </td>
-</tr>
-</table>
-\endhtmlonly
-
*/
diff --git a/documentation/src/examples.dox b/documentation/src/examples.dox
index 6c02ccc0f..0bca5dcdd 100644
--- a/documentation/src/examples.dox
+++ b/documentation/src/examples.dox
@@ -807,7 +807,7 @@ image drawing example:
<a class="el" href="index.html">[Index]</a>
</td>
<td width="45%" align="RIGHT">
- <a class="el" href="faq.html">
+ <a class="el" href="FAQ.html">
Frequently Asked Questions
[Next]
</a>
diff --git a/documentation/src/fltk-title.tex.in b/documentation/src/fltk-title.tex.in
index 8a5e2dee2..cc7f853c9 100644
--- a/documentation/src/fltk-title.tex.in
+++ b/documentation/src/fltk-title.tex.in
@@ -11,7 +11,7 @@
\end{DoxyImageNoCaption}\\
\vspace*{2cm}
{\Large
-By F. Costantini, D. Gibson, M. Melcher, \\
+By F. Costantini, M. Melcher, \\
A. Schlosser, B. Spitzak, and M. Sweet.}\\
\vspace*{1.5cm}
{\large Copyright © 1998 - @YEAR@ by Bill Spitzak and others.}\\
@@ -27,7 +27,7 @@ provided this copyright and permission notice are preserved.}\\
\vspace*{0.5cm}
\today{}\\
\vspace*{0.5cm}
-{\small Git revision '@FLTK_GIT_REVISION@'}\\
+{\small Git revision @FLTK_GIT_REVISION@}\\
\end{center}
\end{titlepage}
%
diff --git a/documentation/src/glut.dox b/documentation/src/glut.dox
index 0effbe5a4..5fad54ca1 100644
--- a/documentation/src/glut.dox
+++ b/documentation/src/glut.dox
@@ -235,7 +235,7 @@ Switches all drawing functions to the GLUT window.
<td width="45%" align="LEFT">
<a class="el" href="enumerations.html">
[Prev]
- FLTK Enumerations
+ Constants and Enumerations
</a>
</td>
<td width="10%" align="CENTER">
diff --git a/documentation/src/index.dox b/documentation/src/index.dox
index e82bccfd6..f64c85be9 100644
--- a/documentation/src/index.dox
+++ b/documentation/src/index.dox
@@ -10,7 +10,7 @@
<TD><CENTER>
<B>FLTK 1.4.0 Programming Manual</B>
- By F. Costantini, D. Gibson, M. Melcher,
+ By F. Costantini, M. Melcher,
A. Schlosser, B. Spitzak and M. Sweet.
\include{doc} copyright.dox
diff --git a/documentation/src/license.dox b/documentation/src/license.dox
index 1110280ed..ff4bc4ac1 100644
--- a/documentation/src/license.dox
+++ b/documentation/src/license.dox
@@ -497,9 +497,9 @@ DAMAGES.
<table summary="navigation bar" width="100%" border="0">
<tr>
<td width="45%" align="LEFT">
- <a class="el" href="development.html">
+ <a class="el" href="migration_1_4.html">
[Prev]
- Developer Information
+ Migrating Code from FLTK 1.3 to 1.4
</a>
</td>
<td width="10%" align="CENTER">
diff --git a/documentation/src/migration_1_4.dox b/documentation/src/migration_1_4.dox
index acbe75f93..398bf0097 100644
--- a/documentation/src/migration_1_4.dox
+++ b/documentation/src/migration_1_4.dox
@@ -317,8 +317,8 @@ OPTION_WAYLAND_ONLY | FLTK_BACKEND_X11=OFF
<a class="el" href="index.html">[Index]</a>
</td>
<td width="45%" align="RIGHT">
- <a class="el" href="development.html">
- Developer Information
+ <a class="el" href="license.html">
+ Software License
[Next]
</a>
</td>
diff --git a/documentation/src/unicode.dox b/documentation/src/unicode.dox
index 4d74f9931..31bae7756 100644
--- a/documentation/src/unicode.dox
+++ b/documentation/src/unicode.dox
@@ -525,7 +525,7 @@ converts the strings to lower case Unicode as part of the comparison.
</td>
<td width="45%" align="RIGHT">
<a class="el" href="enumerations.html">
- FLTK Enumerations
+ Constants and Enumerations
[Next]
</a>
</td>
diff --git a/fluid/documentation/generated.dox.in b/fluid/documentation/generated.dox.in
index 75f8dfc1e..fc6afa009 100644
--- a/fluid/documentation/generated.dox.in
+++ b/fluid/documentation/generated.dox.in
@@ -1,6 +1,6 @@
<br>
<small>
Generated on @CURRENT_DATE@
- from Git revision '@FLTK_GIT_REVISION@'
- by Doxygen version '@DOXYGEN_VERSION_SHORT@'
+ from Git revision @FLTK_GIT_REVISION@
+ by Doxygen version @DOXYGEN_VERSION_SHORT@
</small>
diff --git a/fluid/documentation/src/fluid-title.tex.in b/fluid/documentation/src/fluid-title.tex.in
index 294d82779..7cd13d794 100644
--- a/fluid/documentation/src/fluid-title.tex.in
+++ b/fluid/documentation/src/fluid-title.tex.in
@@ -11,7 +11,7 @@
\end{DoxyImageNoCaption}\\
\vspace*{2cm}
{\Large
-By F. Costantini, D. Gibson, M. Melcher, \\
+By F. Costantini, M. Melcher, \\
A. Schlosser, B. Spitzak, and M. Sweet.}\\
\vspace*{1.5cm}
{\large Copyright © 1998 - @YEAR@ by Bill Spitzak and others.}\\
@@ -23,11 +23,11 @@ Permission is granted to reproduce this manual or any portion for any purpose,}\
{\small
provided this copyright and permission notice are preserved.}\\
\vspace*{1.5cm}
-{\large Generated by Doxygen @DOXY_VERSION@}\\
+{\large Generated by Doxygen @DOXYGEN_VERSION_SHORT@}\\
\vspace*{0.5cm}
\today{}\\
\vspace*{0.5cm}
-{\small Git revision '@FLTK_GIT_REVISION@'}\\
+{\small Git revision @FLTK_GIT_REVISION@}\\
\end{center}
\end{titlepage}
%
diff --git a/fluid/documentation/src/index.dox b/fluid/documentation/src/index.dox
index 984981de3..9e858fcd6 100644
--- a/fluid/documentation/src/index.dox
+++ b/fluid/documentation/src/index.dox
@@ -16,7 +16,7 @@
<TD><CENTER>
<B>FLUID 1.4.0 User Manual</B>
- By F. Costantini, D. Gibson, M. Melcher,
+ By F. Costantini, M. Melcher,
A. Schlosser, B. Spitzak and M. Sweet.
Copyright © 1998 - 2024 by Bill Spitzak and others.
--
GitLab