Documentation Advanced in brief description

[albert-github]

Issue Details

When running a html lint checker over the documentation we get a number of messages about "Opening and ending tag mismatch".

Looking at a place (insert_in_hole in the file "Triangulation/classTriangulationDataStructure.html") we see here:

This is an "Advanced:" block inside a brief description and this is again due to the definition of the commands in the ALIASES:

"cgalAdvancedBegin=\htmlonly[block] <div class=\"CGALAdvanced\"> <div>Advanced</div> \endhtmlonly ^^" \
"cgalAdvancedEnd=\htmlonly[block] </div> \endhtmlonly" \

It is strange to have an extensive description in a brief description. This is a similar issue as has been present for cgalConcept (#3551)

[lrineau]

I think the intent of the author of the documentation was to flag that function insert_in_hole as an advanced function. Is there a labeling that could be used in Doxygen to mark it differently?

I have seen that interesting proposal: mosra/m.css#79, but it seems to be a sort of post-processing of the XML output.

[albert-github]

I agree that the purpose is to signal that e.g. the function insert_in_hole is a function for advanced use.
I think there are some possibilities like cgalAdvancedBegin=<b>Advanced</b> or evencgalAdvancedBegin=<b class=\"advancedColor\">Advanced</b>.

As far as I know the things in the mosra repository indeed need some extra post-processing and are based on the XML output.

[sloriot]

I think what we are missing a \cgalAdvancedFunction macro before the \cgalAdvancedBegin that is responsible for adding This is an advanced function as brief. @lrineau do you agree?

[lrineau]

You are right. \cgalAdvancedFunction would add "This is an advanced functions." as the brief description.

[lrineau]

@albert-github commented on Feb 27, 2019, 2:10 PM GMT+1:

When running a html lint checker over the documentation we get a number of messages about "Opening and ending tag mismatch".

@albert-github I would like to improve our document test process. In the past you mentioned that most of the checks you did recently on the CGAL documentation were not yet ready to be widely used, because it was using experimental features of Doxygen. Is that still the case?

As for this check you did, you mention "html lint checker". Which tool was it?

[albert-github]

The html lint checker is the xml lint checker as mentioned before.
I call it like:
xmllint --path <path to doxygen development environment>/testing/dtd --noout --nonet --postvalid $*
where
$* are all the (x)html files

I use the the standard doxygen development version (master). Most problems have been solved, there are still some outstanding pull requests in CGAL and in doxygen (e.g doxygen/doxygen#6861). Further I've seen some messages about a.o. double definition of anchors, something about allowfullscreen (this is a HTML5 when I remember correctly).

[lrineau]

Thanks @albert-github. For the moment that sounds a bit to early for us to adopt those tools in CGAL. Once all the needed pull-requests in CGAL and Doxygen are merged, I hope we will install and setup that sort of checks.

[albert-github]

Just some statistics:

• runtime doc generation (i.e. make doc second run, so refs are present): approx 540 sec
• runtime xmllint: approx 80 sec

Total lines in output with warning: 249

• most warnings take 3 / 4 lines for each warning
• 45 warnings are are from 'already defined anchors'
• 3 warnings are from allowfullscreen
• other warnings are from not yet integrated pull requests

The 'already defined anchors' is something that has to be addressed in doxygen.

Also it still has to be investigated what the effect of the CGAL post processing step is, some preliminary results:

• runtime doc generation (i.e. make doc_with_postprocessing second run, so refs are present): approx 710 sec
• total lines in output with warnings: 9296
• 2088 warnings are are from 'already defined anchors'

[lrineau]

Fixed by #3734.

[albert-github]

I'm still getting a lot of warnings regarding the advanced sections.
I'll have a closer look at it and make issues / pull request for it.