Based on the problems with the line numbers in some warnings, see review of https://github.com/CGAL/cgal/pull/6688 one of the problems was the `ALIASES` for figures, here we have the code `\latexonly ^^ \endlatexonly` though the code in the `\latexonly` part should be LaTeX commands. Here the "attempted" newline is not necessary at all so the `^^` can be removed leaving an empty `\latexonly` part that can be removed as well.
There are a number of other numbering problems found in https://github.com/CGAL/cgal/pull/6688 but they are on the doxygen side as a proposed pull request https://github.com/doxygen/doxygen/pull/9465 has been submitted.
Update of documentation in respect of code fragments
- making code fragments work in footnotes
- placing some words in in code tags
- completing some words to code tags
- removing some `#` as they are not necessary
- don't show obfuscation code in email
In the BGL package we get a warning like:
```
/home/cgal-testsuite/cgal_doc_build/CGAL-5.4-Ic-33/doc/BGL/PackageDescription.txt:29: warning: ignoring \dot command because HAVE_DOT is not set
```
The BGL package uses the `\dot` and has now to use the setting `HAVE_DOT=YES` to see the dot image.
Till now this went OK as the `\dot` command didn't look at the setting of the `HAVE_DOT` setting in the Doxyfile, though by the issue https://github.com/doxygen/doxygen/issues/7273 and the pull request https://github.com/doxygen/doxygen/pull/8663 it is now required that `HAVE_DOT` is set.
The idea of setting `HAVE_DOT` for the BGL project removed the warning (and shows the figure again) though has also as side effect that the inheritance graphs are shown. Until now CGAL shows for the inheritance just the text version.
Doxygen now has for the `CLASS_GRAPH` setting the possibility `TEXT` that does exactly what is required.
Due to the general setting of `HAVE_DOT` also the not needed `graph_legend` was generated and some `INCLUDE_GRAPH`s, by setting this to `NO ` these are no suppressed as well.
```
warning: Tag 'LATEX_SOURCE_CODE' at line 1971 of file '.../doc_dxy/BaseDoxyfile' has become obsolete.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'RTF_SOURCE_CODE' at line 2061 of file '.../doc_dxy/BaseDoxyfile' has become obsolete.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
warning: Tag 'DOCBOOK_PROGRAMLISTING' at line 2166 of file '.../BaseDoxyfile' has become obsolete.
To avoid this warning please remove this line from your configuration file or upgrade it using "doxygen -u"
```
these tags have been declared obsolete (in the current master version), so they should be removed..
CGAL doesn't use the involved formats so this has no influence on the CGAL documentation processing.
In pull request #4644 a central MATHJAX_CODEFILE was introduced, but the snap rounding package was omitted, so this is corrected here.
For the MathJax V3 ( see #5707) this change is even mandatory (the current construct doesn't work).
Below the bottom blue block we see for the packages some extra white space. For the Manual page this white space is not present.
The reason is the placing of the "hack.js" code.
In the version 1.9.0 the setting `COLS_IN_ALPHA_INDEX` has been made obsolete and generates a warning during building.
As the default value is used it can also be removed (doxygen will automatically take the default value in the older versions).
For a better quality also the close image was converted to an svg image, so the png does not exists anymore. This has to be reflected in this file as well.
For a better quality also the close image was converted to an svg image, so the png does not exists anymore. This has to be reflected in this file as well.
Due to some subtle interactions between used doxygen commands and the defined `\cgalAdvancedEnd` incorrect HTML code is generated.
This was shown by `xmllint (and some options) as
```
parser error : Opening and ending tag mismatch: div line</td></tr>
```
With the `\noop` "trick" this can here be overcome.
The presented output though looked OK.
Due to the change for the doxygen fix https://github.com/doxygen/doxygen/pull/7888 the file `mag_sel.png` is replaced by `mag_sel.svg`, as a result the search glass in the search box was not present anymore.
(Note this is only valid for versions 1.8.19 and newer).
When having a bit a long citation description, the description runs, in the HTML output on the bibliography page, into 3 or more lines where the 3rd and following lines continue underneath the citation number like:
```
[1] Eric Berberich, Arno Eigenwillig, Michael Hemmer, Susan Hert, Lutz Kettner, Kurt Mehlhorn, Joachim Reichel, Susanne Schmitt, Elmar Schömer, and Nicola Wolpert. Exacus: Efficient and exact
algorithms for curves and surfaces. In Gerth S. Brodal and Stefano Leonardi, editors, 13th Annual European Symposium on Algorithms (ESA 2005), volume 3669 of Lecture Notes in Computer Science,
pages 155–166, Palma de Mallorca, Spain, October 2005. European Association for Theoretical Computer Science (EATCS), Springer.
```
The example was found in e.g. https://doc.cgal.org/latest/Algebraic_foundations/citelist.html
- corrected the "overflow"
- made the citation number right aligned
When (re)generating the documentation from the sources and not using the, internally patched CGAL, doxygen version one gets messages about:
```
warning: ignoring unsupported tag 'EXTRACT_ALL_NO_DETAILED_IF_EMPTY'
```
By introducing the option `CGAL_EXTRACT_ALL_NO_DETAILED_IF_EMPTY` this doxygen setting can be steered
- option not supplied to cmake, will use as if specified `-DCGAL_EXTRACT_ALL_NO_DETAILED_IF_EMPTY=ON`
- option supplied to cmake as `-DCGAL_EXTRACT_ALL_NO_DETAILED_IF_EMPTY=ON` will write the line `EXTRACT_ALL_NO_DETAILED_IF_EMPTY = YES` in the doxygen configuration
- option supplied to cmake as `-DCGAL_EXTRACT_ALL_NO_DETAILED_IF_EMPTY=OFF` will write the line `#EXTRACT_ALL_NO_DETAILED_IF_EMPTY = NO` in the doxygen configuration, so just using the default setting of `NO` line could be omitted but it is better to have a placeholder
Currently the needed extra definitions for MathJax usage (i.e. `\newcommand` and `\def` commaonds) are distributed over the header file and in a number of source code files.
Doxygen has the possibility for a centralize this by means of the MATHJAX_CODEFILE configuration setting, this has been implemented.
Use a generated version of deprecated.html
# Conflicts:
# Documentation/doc/resources/1.8.13/deprecated.html
# Documentation/doc/resources/1.8.14/deprecated.html
# Documentation/doc/resources/1.8.4/deprecated.html
Based on #3713 a number of problems were solved, but also some new issues introduced.
- BaseDoxyfile.h see to it that the CGALAdvancedBegin is in a detailed part, so be sure to terminate the brief part by an extra carriage return
- commands like \pre, \note read till the beginning of the next section but a \htmlonly is not seen as a section separator, so insert an extra carriage return
- some places missed an "Advanced" indicator, used the cgalAdvancedType here.
##Note
in Periodic_2_triangulation_2.h there appear to be a number of images that are a bit in thin air (Captions: "Insertion of a point on an edge." and "Insertion in a face."). Also just above these images theer are a number of functions that have documentation, but this is non-doxygen documentation and as such not seen by doxygen
Form the doxygen documentation:
Normally the contents between \htmlonly and \endhtmlonly is inserted as-is. When you want to insert a HTML
fragment that has block scope like a table or list which should appear outside <p>..</p>, this can lead to invalid
HTML. You can use \htmlonly[block] to make doxygen end the current paragraph and restart it after \endhtmlonly.