Doc summary is too large

[mglisse]

Issue Details

The page summary in the documentation can take a lot of space, and between the left bar and the summary, the main text is squeezed to almost nothing. See attached screenshot. In this particular case, I guess abbreviating the title to just GMP & MPFR would help, but I don't know if doxygen has an option so titles can wrap in the summary.

Environment

• Web browser: firefox
• CGAL version: current master

[sloriot]

IIRC, the TOC is something that we added and that is not part of doxygen. See the function generate_autotoc() in Documentation/doc/resources/XXXX/hacks.js. I guess we could limit the length of the text of the link to a fixed number of characters have something like "GNU Multiple Precision ...

I guess the number of character could also be made dynamic.

--- a/Documentation/doc/resources/1.8.13/hacks.js
+++ b/Documentation/doc/resources/1.8.13/hacks.js
@@ -20,15 +20,21 @@ function generate_autotoc() {
             for(var l = levelTag; l < 3; ++l){
                 indices[l] = 0;
             }
+            
+            
+            var link_text=current.text();
+            if (link_text.length > 40)
+              link_text =  link_text.substr(0,39)+"...";
+

             if(cur_id == undefined) {
                 current.attr('id', 'title' + i);
                 current.addClass('anchor');
                 toc.append("<li class='level" + levelTag + "'><a id='link" + i + "' href='#title" +
-                           i + "' title='" + current.prop("tagName") + "'>" + current.text() + "</a></li>");
+                           i + "' title='" + current.prop("tagName") + "'>" + link_text + "</a></li>");
             } else {
                 toc.append("<li class='level" + levelTag + "'><a id='" + cur_id + "' href='#title" +
-                           i + "' title='" + current.prop("tagName") + "'>" + current.text() + "</a></li>");
+                           i + "' title='" + current.prop("tagName") + "'>" + link_text + "</a></li>");
             }

Warning: substr seems deprecated...

[sloriot]

@CGAL/geometryfactory @mglisse Any opinion of the fix proposed (actually on the result)?

[mglisse]

Yes, I think it looks better. If the first 40 characters are not good enough to at least hint at what the section is about, too bad, the authors should look for a shorter heading. I think it still looks strange to have a super long, full-text title for this one while NTL only has its initials, writing "GMP & MPFR" seems good enough, but your patch ensures we don't get something ridiculous elsewhere so it seems useful even if this particular title changes.

[maxGimeno]

@CGAL/geometryfactory @mglisse Any opinion of the fix proposed (actually on the result)?

I think it's far better now

[lrineau]

I think it will not be optimal on a page like https://doc.cgal.org/5.2/Mesh_3/, because of the long lengths of sections titles.

[lrineau]

Is not there a CSS way to "unfloat" something when it takes a significant part of the width?

[sloriot]

The toc appears in the doc if we put in the code \cgalAutoToc. We could add another command like \cgalAutoTocLarge or \cgalAutoTocCentered that remove the float attribute. Here is the output example for Mesh_3 and the page @mglisse refers to in this ticket.

[sloriot]

But I agree with Marc that shortening to GMP/MPFR is a good solution for that page.