Re: [Maxima-discuss] Syntax coloring of the manual

[Raymond T. <toy...@gm...>]

On 7/15/25 9:24 PM, Jaime Villate wrote:

> On 16/07/25 02:08, Raymond Toy wrote:
>> The nice thing about the current version is that we're less dependent 
>> on the version of texinfo used to create the docs. Presumably, 
>> developers will be the only ones to create docs, so how it's done is 
>> less important. And of course a developer will be one to update the 
>> website with the desired HTML manual.
>
> But we are dependent on the Javascript on each user's browser. Every 
> time a user opens a manual page, his browser will go through every 
> single example redoing the coloring. I prefer the method I use in my 
> books: I decide how the colors and math equations should look and they 
> are added statically to my  web pages; no javascript, no time wasted 
> redoing everything in each user's browser, and no surprises with 
> plug-ins that disappear or start misbehaving.

Yes, but doing that statically for something the size of the user manual 
is pretty painful. I doubt anyone wants to do that.

In any case, let's actually see what it costs. Before this, I had no 
idea, but was never bothered with the rendering time, and I have a 
fairly fast ISP (500 Mbps).

I used Chrome to do some measurements by emptying the cache and loading 
the entire manual as one page. Loading the page is 6.9 MB, taking 373 ms 
(locally). The JS code for highlighting is about 48.6 KB and 616 ms 
(over my ISP). All the images is way more space and time. I didn't 
calculate the sum, but it's pretty obvious since one image 
(plotting26.png) is 63 kB, taking 94 ms. Loading all 26 plots is about 
2.3 sec.

For the whole page, highlight apparently took 4 sec. Rendering Mathjax 
took 13 sec.

I assume most people don't load up the entire manual all at once. Let's 
look at Special Functions page by itself.

Mathjax took 2.5 sec, highlighting took 250 ms.

All done on my 5-6 year old laptop, that's not super fast nor super slow.

Also, this was done on the master branch, which tries to highlight every 
example block. On my other branch, I assume highlighting takes 
(somewhat?) less time because it only looks at text generated from 
|@example maxima|

I can live without highlighting but will always enable it on my local 
copy. I will never render my copy of the manual without Mathjax.

BTW, Chrome's Lighthouse feature says we could do a better job with 
accessiblity.

  *

    A lot of the (highlighted) examples lack sufficient contrast.

  *

    Links rely on color to be distinguishable.

  *

    Touch targets do not have sufficient size or spacing.

Lighthouse gives suggestions on how to improve these, though. I wonder 
if people really use a mobile device to read the user manual. I don't 
usually.

​