Using the tag <details> for cgalExamples
#6914
Conversation
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.
|
Should I adjust all the files where
or wait with it till this PR #6914 is integrated? |
The `<br>` is not necessary anymore.
|
As far as I can see with removing the |
This comment was marked as off-topic.
This comment was marked as off-topic.
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? |
|
When remembering correctly the examples I inspected were now all OK. |
MaelRL
added
Ready to be tested
Not yet approved
|
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. |
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
|
|
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. |
| "cpp11=C++11" \ | ||
| "CC=C++" \ | ||
| "cgalExample{1}=<br><b>File</b> \ref \1 \include \1" \ | ||
| "cgalExample{1}=<details><summary><b>File</b> \ref \1</summary> \include \1 </details>" \ |
There was a problem hiding this comment.
| "cgalExample{1}=<details><summary><b>File</b> \ref \1</summary> \include \1 </details>" \ | |
| "cgalExample{1}=<details open=\"true\"><summary><b>File</b> \ref \1</summary> \include \1 </details>" \ |
There was a problem hiding this comment.
When trying locally with doxygen 1.9.6 I got a warning about the fact that \ref\ cannot be used in summary.
5 participants
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.