A small Ruby Annotation demo

Introductory comment

Putting Ruby on the web today is inevitably a compromise. Everyone is entitled to their own compromise, but this one is done by inserting it into HTML/4.01 Strict, serving it out as text/html with CSS stylesheets, and ignoring the validation errors. Sorry!

The nearest alternative would be to produce valid XHTML/1.1, which includes the Ruby annotation module. However, the W3C deprecates sending XHTML/1.1 as text/html, but sending it with the proper XHTML content-type would cause problems with a proportion of currently-used browsers. So that too would be a compromise, in practical terms.


The test sample, with glosses and free translation, is taken from a Usenet posting - I don't even know what the original language is called, but it's said to be rare.

Rubana-cu [[dawn-ed]] ya [[when]] umusalu. [[rained]] Masi [[then]] sumusumukulu [[enemy]] kia. [[came]] Maaru [[exist]] ucani. [[one]] Ilaku ya [[I tried]] turukuuka. [[kill]] Ku-aku [[not-I]] acalia [[know]] puritongatonga. [[throw.spear]]

The above example uses "simple ruby markup", as it's called. This has a well-defined fallback behaviour. I'd rate this as being sufficiently successful to be used in practice (and was the basis of my usenet followup to the query where the original problem was posed, and from where the above sample text comes).

The following example uses "complex ruby markup" instead. This doesn't have a useful fallback behaviour. It is intended to show the glosses above the base text, and the free translation below the base text. But browser support for this has turned out less successful, as discussed below. In this variant, the line wrapping has been done in larger units, namely the ruby elements, which have been set to span each sentence of the free translation - this (at least spanning self-contained clauses of a translation) seems inevitable in this design.

Rubana-cu ya umusalu. dawn-ed when rained When it dawned, it rained. Masi sumusumukulu kia. then enemy came Then the enemy came. Maaru ucani. Ilaku ya turukuuka. exist one I tried kill There was one that I tried to kill. Ku-aku acalia puritongatonga. not-I know throw.spear But I didn't know how to throw the spear.

Trick Stylesheet, etc.

The stylesheet ruby-style.css, designed to style the Ruby annotations for browsers which don't natively support Ruby, is taken from the suggestion found at the link below. With this particular stylesheet, which I've arranged so that it's enabled by default, in the "simple ruby" the annotations are positioned above the words to which they refer; the original questioner asked for them to be below, and a slight adjustment of the stylesheet could change that if wanted.

I've added some colouring to the annotations, but this is of course entirely optional! Also I increased the annotation's font size from the suggested 60%, to 75%.

Please try varying your browser window width to see how the line wrapping works.

This page uses alternative stylesheets: the "trick ruby stylesheet" is enabled by default, but your browser should give access to the alternatives. With Mozilla/Firefox, for example, this is done with the View> Use Style menu. With Opera (8.52 etc.) it is done with the View> Style menu, having selected the Author mode (rather than User mode) in that menu.

Thinking about the stylesheet in its originally suggested form, I realised that the rbspan attribute was taken into account by using table-caption in the CSS, but with its default positioning of caption-side: top. This would be wrong when the rbspan attribute is applied to the second annotation, which should appear below, so I added another selector for that, setting caption-side: bottom; unfortunately, I have to report that the change made no difference to the displayed result in any of the tested browsers (nevertheless, it is evidently moving in the right direction in theory, so I have left it there).

Thinking about it some more: in HTML table markup, the only correct position for a caption element is directly after the opening table tag. The trick stylesheet is trying to fake the ruby markup by making it look like components of a table. The trick stylesheet, however, is trying to assign the caption style to an element which comes in a different position in the markup. So I doubt that any browser can really be blamed for what it does.

Vertical alignment

Time for a confession: the above samples, viewed with the "trick" stylesheet, only worked well in terms of vertical alignment because all of the text in the sample was "ruby"-ed. Inserting a specimen of ruby base ruby-gloss text into a paragraph of normal running text is less satisfactory, as you may be able to see here (except on IE, which, as already noted, supports "simple ruby" by itself, and is not disturbed by the trick stylesheet). The reason is that the pseudo "table row" for holding the ruby-base text is positioned with its bottom edge on the baseline of the running text, and then the ruby-base text is positioned into this "table row", with the result that the ruby-base text is positioned higher-up than the line of running text.

(The situation is even worse for "complex ruby", for which the browser's natural vertical-alignment positions the lower row of annotation text, as you might see here (on an appropriate browser): ruby base text here first annotation 2nd annotation; rather than the row of ruby-base text, leaving the ruby-base text way above the line of text on either side of it.)

An attempt to correct the vertical positioning in Mozilla, Opera etc. by applying a negative vertical-align to the ruby element, was reasonably successful on those browsers, but the vertical shift was also honoured by IE, resulting in the ruby-base text being positioned too low on IE. As yet a satisfactory solution that worked across those various browsers has not been found (short of supplying an IE-specific stylesheet, e.g via IE's "conditional comments" mechanism).


MSIE6 supports simple Ruby annotation without the help of a stylesheet (although the default annotation font is microscopic - I proposed a larger annotation font in the stylesheet).

According to my tests, the trick stylesheet persuades the following tested browsers to display the simple ruby markup as intended (except for the vertical alignment issue already mentioned): Mozilla 1.7.12, Firefox 1.5, Opera 8.52. The version of Konqueror which I tried in Linux displayed the fallback behaviour. Lynx did that too, of course.

I made no effort to hide the trick parts of the ruby-style.css stylesheet from MSIE6 (it's known that IE6 doesn't support some of the selectors used, and the remainder didn't seem to be harmful).

TO.DO: Amaya should support ruby, but it didn't care for this document in its present form at all. Evidently one should at least start with valid XHTML/1.1 with Ruby, if one should hope for good results there.

The complex markup was less successful. On IE6, it did not seem to produce anything usable, whether the trick stylesheet was applied or not. On Opera 8.52, it sort-of worked, but the second annotation line was shown above the base text instead of below, and inappropriately aligned.

Curiously, these complex markup results on Mozilla 1.7.12 seemed at first sight to be significantly better than on Firefox 1.5. Even more curiously, the results as seen on Moz. 1.7.12 were also seen on an older version of Firefox. Indeed on Firefox (where CSS problems are reported to the javascript console) it was actually reporting that the display: inline-table used in the trick stylesheet was being ignored (it's not yet implemented in the Gecko rendering engine, apparently). "Seamonkey 1.0" behaved like FF/1.5 in this regard. I had to conclude that it must have been more by accident than design that the rendering engine was getting a result which even resembled my intentions.

Mozilla with Ruby Annotation Extension

If the cited Ruby annotation extension is installed in Mozilla, then the trick stylesheet needs to be disabled, as they clash with each other (this can be done via Mozilla's menu "View>Use Style..."). Then, the results from simple as well as complex Ruby markup are evidently as intended, although the default annotation font size is microscopic (and the use of Mozilla's minimum font size setting seems to cause indigestion to the extension's layout).

Using ruby annotation with RTL scripts?

To that question, I really don't know the answer, nor did there seem to be any resources on the web. However, that's not going to stop us from giving it a try, so let's have a "simple ruby" example such as caratقيراط or, conversely, قيراطcarat. A.Prilop has now provided some additional material of this kind - see the link in the lists below.


N.B "Ruby Annotation" has nothing to do with the "Ruby" object-oriented scripting (programming) language.

|Up| |RagBag|About the author|