docbook-apps

User experience first. Developer convenience close second.

I believe it's not hard to see the reason in these sentences. I've
borrowed (and simplified) them from Google Web Toolkit's design
principles, which can be roughly defined as a client side (i.e.
JavaScript) web application framework.

Docbook's web presentation nowadays relies on the chunked html files
with a table of contents (besides bightml), which can be arranged into a
html frameset, and main theme of its working is this: user clicks on
table of contents entry, browser gets html document from server and display.

I'm wondering about an another theme of working: user clicks on table of
contents entry, browser applies xslt stylesheet to the previously
downloaded docbook xml file, and display.

The potential of this method relies in the fact that there's no need for
browser-server communication - after the stylesheet and docbook
documents are loaded. Which is the disadvantage of the method of course:
user needs to wait for the whole document to download even if all she
needs is a part or a chapter only.

I say potential, because some other factors need to be considered to
make it work: the xslt transformation needs to be actually faster then
response from the server.

Then there's of course the question of browser compatibility of xslt
processing. In this regard, I've prepared a small proof of concept
example, using Google Web Toolkit's architecture. It's available at:

http://docbook-publishing.appspot.com/DocBookPublishing.html

The files there are simple but valid DocBook documents, the table of
contents are custom-made, so is the little xslt file which the processor
applies every time the user clicks on a table of contents item.

I've tried it in several different browsers ( recent versions of Mozilla
Firefox, Internet Explorer, Opera, Safari, Google Chrome ), and it seems
to work. An my impression is that it's really fast. (Again, I don't
count the initial load time of the document - I believe this can be made
acceptable with proper progress indication.)

Now the next step would be to apply this on arbitrary DocBook documents.
I can see some problems to solve. First, table of contents generation.
This should be very similar to that of HTMLHelp's TOC. I'm wondering
whether the "links" to different parts of the document could be xpath
path definitions instead of id-s of tags. This way those parts of the
document could be referred too, which don't hold id attribute (id
generation not being an option here: I don't think we should assign id-s
to the document's parts at this point).

Second, html formatting of selected parts. Main problem to solve here,
that I can see, is that for the sake of the xslt processors, the
stylesheet should be a single file. (Talking about developer
convenience, huh?) (Browsers' xslt processors can handle loading of
imported stylesheets, but something prevents it from loading documents
dynamically, around i18n. Maybe just the paths, I haven't investigated
thoroughly yet.) And if I concatenate all the files required to html
transformation, the size is around 1.4 megabyte.

So this is where I'm at now. Thanks for following my little train of
thoughs, I'm really interested in your opinions. (Or tell me if I've
invented the wheel or hot water or something like that, or it worths
nothing because...)

Yours,
Arpad

----
Szabó Árpád Zoltán
from Hungary

On 3/12/2010 10:51 AM, Szabó Árpád Zoltán wrote:
> User experience first. Developer convenience close second.
>
> I believe it's not hard to see the reason in these sentences. I've
> borrowed (and simplified) them from Google Web Toolkit's design
> principles, which can be roughly defined as a client side (i.e.
> JavaScript) web application framework.
>
> Docbook's web presentation nowadays relies on the chunked html files
> with a table of contents (besides bightml), which can be arranged into a
> html frameset, and main theme of its working is this: user clicks on
> table of contents entry, browser gets html document from server and display.
>
> I'm wondering about an another theme of working: user clicks on table of
> contents entry, browser applies xslt stylesheet to the previously
> downloaded docbook xml file, and display.
>
> The potential of this method relies in the fact that there's no need for
> browser-server communication - after the stylesheet and docbook
> documents are loaded. Which is the disadvantage of the method of course:
> user needs to wait for the whole document to download even if all she
> needs is a part or a chapter only.
>
> I say potential, because some other factors need to be considered to
> make it work: the xslt transformation needs to be actually faster then
> response from the server.
>
> Then there's of course the question of browser compatibility of xslt
> processing. In this regard, I've prepared a small proof of concept
> example, using Google Web Toolkit's architecture. It's available at:
>
> http://docbook-publishing.appspot.com/DocBookPublishing.html
>
> The files there are simple but valid DocBook documents, the table of
> contents are custom-made, so is the little xslt file which the processor
> applies every time the user clicks on a table of contents item.
>
> I've tried it in several different browsers ( recent versions of Mozilla
> Firefox, Internet Explorer, Opera, Safari, Google Chrome ), and it seems
> to work. An my impression is that it's really fast. (Again, I don't
> count the initial load time of the document - I believe this can be made
> acceptable with proper progress indication.)
>
> Now the next step would be to apply this on arbitrary DocBook documents.
> I can see some problems to solve. First, table of contents generation.
> This should be very similar to that of HTMLHelp's TOC. I'm wondering
> whether the "links" to different parts of the document could be xpath
> path definitions instead of id-s of tags. This way those parts of the
> document could be referred too, which don't hold id attribute (id
> generation not being an option here: I don't think we should assign id-s
> to the document's parts at this point).
>
> Second, html formatting of selected parts. Main problem to solve here,
> that I can see, is that for the sake of the xslt processors, the
> stylesheet should be a single file. (Talking about developer
> convenience, huh?) (Browsers' xslt processors can handle loading of
> imported stylesheets, but something prevents it from loading documents
> dynamically, around i18n. Maybe just the paths, I haven't investigated
> thoroughly yet.) And if I concatenate all the files required to html
> transformation, the size is around 1.4 megabyte.
>
> So this is where I'm at now. Thanks for following my little train of
> thoughs, I'm really interested in your opinions. (Or tell me if I've
> invented the wheel or hot water or something like that, or it worths
> nothing because...)
>
> Yours,
> Arpad
>
> ----
> Szabó Árpád Zoltán
> from Hungary
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>
That looks pretty slick.

That is a very interesting idea. I am wondering if there is some sort of size limit beyond which you would not want to do this, though. If you have a very large document, is the time required to download and transform the entire thing up front so long that it counterbalances the benefits of being able to browse topics quickly? Consider the user that only needs to look at one or two of the topics. For them the traditional method might be quicker.



Original Message-----
From: Szabó Árpád Zoltán [mailto:szabo.arpad.zoltan@gmail.com]
Sent: Friday, March 12, 2010 7:51 AM
To: docbook-apps@lists.oasis-open.org
Subject: DocBook transformation by browsers' xslt engine

User experience first. Developer convenience close second.

I believe it's not hard to see the reason in these sentences. I've
borrowed (and simplified) them from Google Web Toolkit's design
principles, which can be roughly defined as a client side (i.e.
JavaScript) web application framework.

Docbook's web presentation nowadays relies on the chunked html files
with a table of contents (besides bightml), which can be arranged into a
html frameset, and main theme of its working is this: user clicks on
table of contents entry, browser gets html document from server and display.

I'm wondering about an another theme of working: user clicks on table of
contents entry, browser applies xslt stylesheet to the previously
downloaded docbook xml file, and display.

The potential of this method relies in the fact that there's no need for
browser-server communication - after the stylesheet and docbook
documents are loaded. Which is the disadvantage of the method of course:
user needs to wait for the whole document to download even if all she
needs is a part or a chapter only.

I say potential, because some other factors need to be considered to
make it work: the xslt transformation needs to be actually faster then
response from the server.

Then there's of course the question of browser compatibility of xslt
processing. In this regard, I've prepared a small proof of concept
example, using Google Web Toolkit's architecture. It's available at:

http://docbook-publishing.appspot.com/DocBookPublishing.html

The files there are simple but valid DocBook documents, the table of
contents are custom-made, so is the little xslt file which the processor
applies every time the user clicks on a table of contents item.

I've tried it in several different browsers ( recent versions of Mozilla
Firefox, Internet Explorer, Opera, Safari, Google Chrome ), and it seems
to work. An my impression is that it's really fast. (Again, I don't
count the initial load time of the document - I believe this can be made
acceptable with proper progress indication.)

Now the next step would be to apply this on arbitrary DocBook documents.
I can see some problems to solve. First, table of contents generation.
This should be very similar to that of HTMLHelp's TOC. I'm wondering
whether the "links" to different parts of the document could be xpath
path definitions instead of id-s of tags. This way those parts of the
document could be referred too, which don't hold id attribute (id
generation not being an option here: I don't think we should assign id-s
to the document's parts at this point).

Second, html formatting of selected parts. Main problem to solve here,
that I can see, is that for the sake of the xslt processors, the
stylesheet should be a single file. (Talking about developer
convenience, huh?) (Browsers' xslt processors can handle loading of
imported stylesheets, but something prevents it from loading documents
dynamically, around i18n. Maybe just the paths, I haven't investigated
thoroughly yet.) And if I concatenate all the files required to html
transformation, the size is around 1.4 megabyte.

So this is where I'm at now. Thanks for following my little train of
thoughs, I'm really interested in your opinions. (Or tell me if I've
invented the wheel or hot water or something like that, or it worths
nothing because...)

Yours,
Arpad

----
Szabó Árpád Zoltán
from Hungary

Bandwidth of the server and the client, and memory of the browser. And
the time...

Well, xml files are pretty well compress, my ~300 kilobytes files goes
down to ~100 kilobytes when gzipped (which usually automatically happens
if both the browser and the webserver support it). The document can be
even cached by the browser for some prolonged time I believe, so no need
for downloading again and again.

Browsers just love to eat big chunks of memory anyway, aren't they? So
an extra couple of megabytes shouldn't be a problem. I've just did a
quick test: my Firefox eats 33 megabytes when started, 35, when I loaded
a simple html file, 40 when I loaded
http://docbook-publishing.appspot.com/DocBookPublishing.html , and
around 47, when the table of contents is loaded (the xml file is loaded
into the xslt processor at this point).

The time, I don't know. It's a long way to go for me to have those
stylesheets ready for check, we'll see hopefully.

After all, I think there might be some use-cases where it's appropriate
and a lot of other cases where it's not. And since it's just an idea, we
can't tell for sure yet. I find it useful to collect arguments against
and in favour.

Yours,
Arpad

2010.03.12. 20:24 keltezéssel, Cavicchio_Rob@emc.com írta:
> That is a very interesting idea. I am wondering if there is some sort of size limit beyond which you would not want to do this, though. If you have a very large document, is the time required to download and transform the entire thing up front so long that it counterbalances the benefits of being able to browse topics quickly? Consider the user that only needs to look at one or two of the topics. For them the traditional method might be quicker.
>
>

Hi,
I'm trying to find the answer to the question: what is the best method for
identifying nodes to be transformed when toc entry is clicked on, for the
purposes of browser-based xslt transformation?

I had an idea to use the unique xpath to the node, but I came to realize,
that an xslt processor is not able evaluate an xpath expression which comes
from a parameter. If I want to use xpath, xslt document has to be modified
for matching the proper node. Which means I have to create a new
XSLTProcessor object in Mozilla for each transformation, and I can't use the
XSLTemplate object in Explorer, which provides caching for more efficient
xslt processing (rough estimate: around 30%) for cases of repeated
transform() method calls.

If I go with the id, I have to take care of the nodes which don't have id-s.
They usually got generated values, as toc entry id-s, and
filenames accordingly. In my case there are no files, so I guess I will have
a pre-processing phase, to create the missing id attributes and fill them
with the generated values in the docbook's DOM document.

Could you tell me please, if I'm missing something obvious here?

Thanks,
Arpad