cgal
cgal copied to clipboard
CGAL
Using the tag `<details>` for cgalExamples
Enhancement / suggestion
Since version `1.9.3 doxygen supports the HTML tag <details> so that parts of the documentation can be easily collapsed. This will make parts of the documentation a bit clearer and cleaner.
The following will give a small overview of the old and the new situation for the Weights package, but it applies to all packages.
old
new
Note In general a critical (re)view should be done regarding the white space above examples is (especially) now at some places a bit a bit large, but this would be a separate PR / task.
Should I adjust all the files where cgalExample is used in respect to the note in the PR description regarding:
In general a critical (re)view should be done regarding the white space above examples is (especially) now at some places a bit a bit large, but this would be a separate PR / task.
or wait with it till this PR #6914 is integrated?
As far as I can see with removing the <br> from the cgalExamples and using the <details> tag the layout is OK.
As far as I can see with removing the
<br>from thecgalExamplesand using the<details>tag the layout is OK.
Is your previous remark ("In general a critical (re)view should be done regarding the white space above examples is (especially) now at some places a bit a bit large, but this would be a separate PR / task.") still applicable after this change or did you mean only for this specific example?
I am not sure that this makes sense for the examples. They are not in the middle of explanations, and usually they come with little text. At least the default should be that they are open, as otherwise I have to open them one after the other.
@afabri
- This could be easily accomplished by add replacing the
<details>by<details open>in the alias. - I think the flow of the chapter as shown in the example with the description (https://github.com/CGAL/cgal/pull/6914#issue-1390747777) shows an example that is in the midst of the complete chapter.
I am not sure that this makes sense for the examples. They are not in the middle of explanations, and usually they come with little text. At least the default should be that they are open, as otherwise I have to open them one after the other.
Having everything hidden would also make it harder to search (ctrl F) for a specific text, or for other uses of a particular code.
I wonder if the "pollution" of open examples could not be reduced by changing the way it is presented: make it a block that is not as wide as the rest of the page, and change its color. Both changes make it easier to skip it and get to the next "normal" text.
Quick example below:
It could be even narrower since examples are code and we are pretty much never going above 100 characters.
It could be even narrower since examples are code and we are pretty much never going above 100 characters.
Is a dangerous assumption (one never knows...). Furthermore the user can make the entire window smaller in which case a overflow might occur much earlier or the user can move the vertical split bar to the right, making the text area smaller
- Did you try in your example what would happen in these cases?
I don't see it as a dangerous assumption: examples are not external code that we have no control over. If some example has a line with 500 characters, it's easy enough to change it.
If the window gets thinner, everything becomes unreadable anyway. Actually, code blocks probably should have an horizontal scrollbar rather than use text wrapping.