Patch: Improve XHTML backend's table of contents generation latency

27 views
Skip to first unread message

Hongli Lai

unread,
Apr 6, 2011, 7:39:50 AM4/6/11
to asciidoc
One of the things that annoy me in the XHTML backend is the fact that
I have to wait until the entire page is loaded (window.onload) until
the TOC is generated. This delay is very noticeable on large documents
such as the Asciidoc user guide. The following patch improves upon
this aspect by regenerating the TOC every 500 msec until either
window.onload fires or until the DOM is ready.
https://gist.github.com/905514

Hongli Lai

unread,
Apr 7, 2011, 3:55:59 AM4/7/11
to asciidoc
Is this the right place to send patches to?

Lex Trotman

unread,
Apr 7, 2011, 4:08:05 AM4/7/11
to asci...@googlegroups.com

Yes, patience the developers will get to it when they can.

Cheers
Lex

>
> --
> You received this message because you are subscribed to the Google Groups "asciidoc" group.
> To post to this group, send email to asci...@googlegroups.com.
> To unsubscribe from this group, send email to asciidoc+u...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.
>
>

Stuart Rackham

unread,
Apr 11, 2011, 5:06:57 AM4/11/11
to asci...@googlegroups.com
Hi Hongli Lai

I'm ambivalent about this optimization, it adds significant complexity to the
script and I'm not motivated by the gains.

I did some really rough measurements downloading and displaying the User Guide
with Firefox and Google Chrome without the patch and the total download and
display times ranged from between 1 and 2 seconds with the TOC display time
consuming less than a third of that time (much less on Chrome). Once the page is
cached there is a brief TOC pause on Firefox when you return to the page, it's
instantaneous with Chrome. It just doesn't annoy me enough to want to do
anything about it.


Cheers, Stuart

Lex Trotman

unread,
Apr 11, 2011, 6:03:43 AM4/11/11
to asci...@googlegroups.com

This could also be a problem with the CPU load if displaying on
lightweight platforms like Android devices. The result may even be
worse.

Hongli Lai

unread,
Apr 11, 2011, 6:50:13 AM4/11/11
to asciidoc
On Apr 11, 11:06 am, Stuart Rackham <srack...@gmail.com> wrote:
> I'm ambivalent about this optimization, it adds significant complexity to the
> script and I'm not motivated by the gains.

I basically just modified toc() and footnotes() to remove the old
entries before (re-adding) the new ones, and installed a timer which
runs until DOMloaded/window.onload.


> I did some really rough measurements downloading and displaying the User Guide
> with Firefox and Google Chrome without the patch and the total download and
> display times ranged from between 1 and 2 seconds with the TOC display time
> consuming less than a third of that time (much less on Chrome). Once the page is
> cached there is a brief TOC pause on Firefox when you return to the page, it's
> instantaneous with Chrome. It just doesn't annoy me enough to want to do
> anything about it.

It depends a little on the caching settings as well as the user's
Internet connection. If I Shift-Refresh with Chrome, the Users Guide
takes 5 seconds to load. The TOC isn't generated until everything is
done loading, including images. I have a manual written in Asciidoc
which takes a bit longer to load than that because of all the embedded
images. But even a 1-2 seconds delay annoys me enough to write a
patch. As a user it feels very strange to see the TOC suddenly appear;
I want to be able to get a birds-eye overview of what's in the manual
while it's loading.

At the very least I think you should take the part which uses the 'DOM
loaded' event instead of the 'window.onload' event. That way the TOC
can be generated before all images are done loading.

Hongli Lai

unread,
Apr 11, 2011, 6:54:26 AM4/11/11
to asciidoc
On Apr 11, 12:03 pm, Lex Trotman <ele...@gmail.com> wrote:
> This could also be a problem with the CPU load if displaying on
> lightweight platforms like Android devices.  The result may even be
> worse.

My opinion is that it makes the experience better on mobile devices,
which tend to have lower Internet speeds. That way they don't have to
wait, say, half a minute before they see the TOC. Sure it contributes
to higher CPU usage but it happens only in intervals of 500 msecs and
stops when the page is done loading. I argue that the increased CPU
usage does not contribute significantly to power consumption because:
1. While the page is loading, the user's screen is turned on, which
contributes a lot more to power consumption than the CPU does.
2. While the page is loading, the browser is already using CPU,
meaning it wasn't already in a low-power idle state. This script
therefore should not significantly contribute to the number of CPU
idle-wakes.

Hongli Lai

unread,
Apr 11, 2011, 6:56:21 AM4/11/11
to asciidoc
By the way I see that you don't have gzip enabled on the Asciidoc
website. You should; the users guide is 300 KB and if you enable gzip
that should reduce the load time by a factor of 2-3.

Stuart Rackham

unread,
Apr 17, 2011, 12:24:01 AM4/17/11
to asci...@googlegroups.com

On 11/04/11 22:50, Hongli Lai wrote:
> On Apr 11, 11:06 am, Stuart Rackham<srack...@gmail.com> wrote:
>> I'm ambivalent about this optimization, it adds significant complexity to the
>> script and I'm not motivated by the gains.
>
> I basically just modified toc() and footnotes() to remove the old
> entries before (re-adding) the new ones, and installed a timer which
> runs until DOMloaded/window.onload.
>
>
>> I did some really rough measurements downloading and displaying the User Guide
>> with Firefox and Google Chrome without the patch and the total download and
>> display times ranged from between 1 and 2 seconds with the TOC display time
>> consuming less than a third of that time (much less on Chrome). Once the page is
>> cached there is a brief TOC pause on Firefox when you return to the page, it's
>> instantaneous with Chrome. It just doesn't annoy me enough to want to do
>> anything about it.
>
> It depends a little on the caching settings as well as the user's
> Internet connection. If I Shift-Refresh with Chrome, the Users Guide
> takes 5 seconds to load. The TOC isn't generated until everything is
> done loading, including images. I have a manual written in Asciidoc
> which takes a bit longer to load than that because of all the embedded
> images. But even a 1-2 seconds delay annoys me enough to write a
> patch. As a user it feels very strange to see the TOC suddenly appear;
> I want to be able to get a birds-eye overview of what's in the manual
> while it's loading.

I generated the AsciiDoc User Guide with the patch
(http://www.methods.co.nz/tmp/asciidoc2.html) and without the patch
(http://www.methods.co.nz/tmp/asciidoc.html) but I can't see any
appreciable difference between the two in loading on my Android phone (low end
LG Optimus P500) or desktop PC.

I cleared the cache first so what am I missing here?

Anyone else out there with TOC loading issues?


>
> At the very least I think you should take the part which uses the 'DOM
> loaded' event instead of the 'window.onload' event. That way the TOC
> can be generated before all images are done loading.
>

It does make sense not to wait for linked images and frames to load but I think
there are IE compatibility issues with DOMContentLoaded, see:
http://stackoverflow.com/questions/1795089/need-help-with-jquery-to-javascript/1795167#1795167


Cheers, Stuart

Stuart Rackham

unread,
Apr 17, 2011, 2:14:06 AM4/17/11
to asci...@googlegroups.com

Thank you for the heads up, I have enabled compression.

Cheers, Stuart

Hongli Lai

unread,
Apr 21, 2011, 12:45:55 PM4/21/11
to asciidoc
On Apr 17, 6:24 am, Stuart Rackham <srack...@gmail.com> wrote:
> I generated the AsciiDoc User Guide with the patch
> (http://www.methods.co.nz/tmp/asciidoc2.html) and without the patch
> (http://www.methods.co.nz/tmp/asciidoc.html) but I can't see any
> appreciable difference between the two in loading on my Android phone (low end
> LG Optimus P500) or desktop PC.
>
> I cleared the cache first so what am I missing here?
>
> Anyone else out there with TOC loading issues?

I've discovered some issues in my previous patch. I wrongly used
setTimeout() but should have use setInterval() instead. I also didn't
take into account that the TOC element may not exist yet at the time
the TOC installation function is called. I've put up a new patch here
which solves these issues:
https://gist.github.com/934945

In order to facilitate testing I've written a mini web server in Ruby
which simulates a slow connection:
https://gist.github.com/934946

This should be saved as slowserver.rb in the Asciidoc source
directory. You can run it with:

ruby slowserver.rb

This will start it on localhost port 3000. Upon accessing /, it will
serve the file doc/asciidoc.html at a slow rate: it serves 128 bytes
at a time, sleeping 10 msec after every iteration. This behavior can
be adjusted by modifying the BLOCK_SIZE and SLEEP_TIME constants.

You can order slowserver.rb to serve a different file than doc/
asciidoc.html by passing the filename as an argument, like this:

ruby slowserver.rb asciidoc3.html


> It does make sense not to wait for linked images and frames to load but I think
> there are IE compatibility issues with DOMContentLoaded, see:http://stackoverflow.com/questions/1795089/need-help-with-jquery-to-j...

Correct. My patch falls back to window.onload if DOMContentLoaded is
not supported.

Stuart Rackham

unread,
Apr 21, 2011, 11:52:31 PM4/21/11
to asci...@googlegroups.com

That's really neat, I was trying to figure out how to simulate a slow
connection. I've used your slowserver to run the patch on Firefox 3.6, Chrome
10.0 and IE8 and it works a treat.

Have committed it to the trunk:
http://code.google.com/p/asciidoc/source/detail?r=327c1c7ff4da355f2bfd7d43a5c005be69767352


Cheers, Stuart

Stuart Rackham

unread,
Apr 22, 2011, 6:14:28 AM4/22/11
to asci...@googlegroups.com
Does the patch work for linked CSS and JavaScript files (generated with the
AsciiDoc -a linkcss option)?

The slow server does not serve linked documents so I was not able to tell.

Cheers, Stuart


On 22/04/11 04:45, Hongli Lai wrote:

Stuart Rackham

unread,
Apr 22, 2011, 6:25:02 AM4/22/11
to asci...@googlegroups.com
Forgot to add in my previous post that I had to change the order of JavaScript
loading to ensure latency patch works with linked JavaScript:
http://code.google.com/p/asciidoc/source/detail?r=ba5be0913f90ef9cf2ad4ba5070991edf94b9b22

Cheers, Stuart


On 22/04/11 04:45, Hongli Lai wrote:

Hongli Lai

unread,
Apr 23, 2011, 4:53:51 PM4/23/11
to asciidoc
On Apr 22, 12:14 pm, Stuart Rackham <srack...@gmail.com> wrote:
> Does the patch work for linked CSS and JavaScript files (generated with the
> AsciiDoc -a linkcss option)?
>
> The slow server does not serve linked documents so I was not able to tell.

Yes it does. I've updated slowserver to support css and javascript
files: https://gist.github.com/934946

Stuart Rackham

unread,
Apr 23, 2011, 5:46:45 PM4/23/11
to asci...@googlegroups.com

Tried it out and it works great!
slowserver.rb is a handy script.

Cheers, Stuart

Reply all
Reply to author
Forward
0 new messages