AH Formatter V6.0 - Ruby Extension

AH Formatter V6.0 is capable of expressing ruby. AH Formatter V5 or earlier could not express ruby directly, there was no other choice to use fo:inline-container etc. and follow an example. Therefore, there were a lot of restrictions for arranging ruby and the line break. The ruby extension removed such restrictions and the original ruby is expressible. V6.0

See also the followings for more details of ruby.

Requirements for Japanese Text Layout W3C Working Group Note 4 June 2009
JIS X 4051:2004 Formatting rules for Japanese documents
CSS3 Ruby Module W3C Working Draft 30 June 2011
Ruby Annotation W3C Recommendation 31 May 2001 (Markup errors corrected 25 June 2008)

Ruby is expressed by the following three elements.

XSL-FO	HTML	CSS	Meanings
<axf:ruby>	<ruby>	display: ruby	Shows the ruby structure.
<axf:ruby-base>	<rb>	display: ruby-base	Shows the base character of ruby.
<axf:ruby-text>	<rt>	display: ruby-text	Shows ruby.

One <axf:ruby-base> maps to one <axf:ruby-text>. A pair of one <axf:ruby-base> and <axf:ruby-text> is called the ruby container. The line can break between a ruby containter and another ruby container though the line cannot break within a ruby container.

Ruby has three types and it is classified as follows. (<ruby> <rb> <rt> are used in the following example.)

Mono-ruby
Mono-ruby is expressed as follows.

<ruby><rb>京</rb><rt>きよう</rt></ruby><ruby><rb>都</rb><rt>と</rt></ruby><ruby><rb>府</rb><rt>ふ</rt></ruby>

Mono-ruby can be considered as a group ruby whose base character consists of one character. The ruby container of mono-ruby is independent and ruby characters never overhang the base character of the adjacent ruby.
Group-ruby
Group-ruby is expressed as follows.

<ruby><rb>京都府</rb><rt>きようとふ</rt></ruby>

Group-ruby can be considered as a jyukugo (idiom) ruby whose base character consists of one character. Group-ruby is evenly arranged to the entire base characters.
Jukugo (kanji compound word)-ruby
Jukugo-ruby is expressed as follows.

<ruby><rb>京</rb><rt>きよう</rt><rb>都</rb><rt>と</rt><rb>府</rb><rt>ふ</rt></ruby>

Jyukugo-ruby consists of one or more ruby containers. The line can break between ruby containters. The method of arranging Jyukogo-ruby is complex. As a general rule, the ruby container arranges ruby as group-ruby. However when the ruby text is wider than the ruby base characeters, ruby text is allowed to partially overhang any adjacent text in addition to its own base to adjust its position.

鬼門の方角を<ruby><rb>凝</rb><rt>ぎよう</rt><rb>視</rb><rt>し</rt></ruby>する。

When ruby is wider than its own base characters, ruby will overhang the adjacent character. In the following cases, ruby cannot overhang the character.

The adjacent content is a non-text structure, such as an image or <fo:inline-container>.
The adjacent content is ruby.
The font size of the adjacent base character differs from the ruby's own base or it's a script other than Kanji or Kana or there are any improprieties.
The adjacent character is a character excluded by axf:ruby-overhang.
Ruby overhangs the adjacent character and there is no enough space between ruby and adjacet to the adjacent ruby. (Ruby might overhang partially.)

Ruby and emphasis marks can be used together. When the ruby and emphasis marks are put on the same side, emphasis marks will be put outside of ruby. When you want to align emphasis marks to the text without ruby and emphasis marks to ruby, please specify axf:text-emphasis-offset.

... text-emphasis-offset="0.5em">ルビと<ruby><rb>圏点</rb><rt>けんてん</rt></ruby>

With group-ruby, ruby can overhang both side of text or it can be nested several times. At this time, only ruby specified on the outside can overhang the adjacent character.

<ruby ruby-position="after"><rb><ruby ruby-position="before"><rb>東南</rb><rt>とうなん</rt></ruby></rb><rt>たつみ</rt></ruby>の方向

In AH Formatter V6.0, ruby has the following restrictions.

Ruby cannot overhang non-text content, like an image, etc.
Bopomofo is not supported.
Emphasis marks can be put on the base characters of ruby, but they cannot be put on ruby characters.
Within the ruby structure, it doesn't expand by justify. This is defined by JIS X 4051 and "Requirements for Japanese Text Layout".
Ruby doesn't affect the line height. The line height is decided only by the base characters.

Ruby Extended Elements

<axf:ruby>

Common Usage:

Specifies the ruby structure.

Areas:

Generates and returns the ruby area.

Constraints:

<!ELEMENT axf:ruby (axf:ruby-base, axf:ruby-text)+>
<!ATTLIST axf:ruby axf:ruby-align             CDATA   "auto">
<!ATTLIST axf:ruby axf:ruby-position          CDATA   "before">
<!ATTLIST axf:ruby axf:ruby-offset            CDATA   "0pt">
<!ATTLIST axf:ruby axf:ruby-overhang          CDATA   "auto">
<!ATTLIST axf:ruby axf:ruby-limit-overhang    CDATA   "1.0">
<!ATTLIST axf:ruby axf:ruby-limit-space       CDATA   "1.0">
<!ATTLIST axf:ruby axf:ruby-small-kana        CDATA   "auto">
<!ATTLIST axf:ruby axf:ruby-font-family       CDATA   #IMPLIED>
<!ATTLIST axf:ruby axf:ruby-font-size         CDATA   "0.5">
<!ATTLIST axf:ruby axf:ruby-minimum-font-size CDATA   #IMPLIED>
<!ATTLIST axf:ruby axf:ruby-font-style        CDATA   #IMPLIED>
<!ATTLIST axf:ruby axf:ruby-font-weight       CDATA   #IMPLIED>
<!ATTLIST axf:ruby axf:ruby-font-stretch      CDATA   #IMPLIED>
<!ATTLIST axf:ruby axf:ruby-condense          CDATA   "none">
<!ATTLIST axf:ruby axf:ruby-color             CDATA   #IMPLIED>

<axf:ruby-base>

Common Usage:

Specifies the base character of ruby.

Areas:

Generates and returns the text area.

Constraints:

<!ELEMENT axf:ruby-base (#PCDATA | axf:ruby)>

<axf:ruby-text>

Common Usage:

Specifies ruby.

Areas:

Generates and returns the text area. This text area does not impact upon the block progression dimension in the line area.

Constraints:

<!ELEMENT axf:ruby-text #PCDATA>

Within the axf:ruby extension elements, the Nth axf:ruby-text extension element addresses to the Nth axf:ruby-base extension element. The Nth axf:ruby-text extension element must be placed after the Nth axf:ruby-base extension element.

Ruby Extended Properties

axf:ruby-align

Specifies the alignment of ruby. V6.0

Value:	auto \| [[distribute-space \| distribute-letter] \|\| [center \| start \| end \| start-if-vertical]]
Initial:	auto
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

Values have the following meanings.

auto: The value specified by ruby-align in the Option Setting File is adopted.
distribute-space: Same as distribute-space center.
distribute-space center: Spaces before and after ruby are made and ruby is evenly distributed. If ruby consists of one character, then it's center aligned.
distribute-space start: Spaces before and after ruby are made and ruby is evenly distributed. If ruby consists of one character, then it is start aligned.
distribute-letter: Same as distribute-letter center.
distribute-letter center: Spaces before and after ruby are not made and ruby is evenly distributed. If ruby consists of one character, then it is center aligned.
distribute-letter start: Spaces before and after ruby are not made and ruby is evenly distributed. If ruby consists of one character, then it is start aligned.
center: Ruby is positioned at the center with solid setting.
start: Ruby is positioned on the start side with solid setting.
end: Ruby is positioned on the end side with solid setting.
start-if-vertical: Same as start if the writing-mode is vertical, same as center if the writing-mode is horizontal.

Axf:ruby-align decides the alignment of ruby. Originally, center alignment and start alignment are the concept of mono-ruby, however, the same concept is also applied for group-ruby whose base text has more than 2 characters. When ruby is longer than its base characters, ruby will be positioned with solid setting.

Center alignment of mono-ruby can be specified as follows;

Start alignment of mono-ruby can be specified as follows;

The following shows the example of giving spaces before and after group-ruby. The amount of space before and after the ruby is harf the size of a character.

The following shows the example of not giving spaces before and after group-ruby.

axf:ruby-position

Specifies on which side of base characters ruby overhangs. V6.0

Value:	before \| after
Initial:	before
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

Values have the following meanings.

before: Ruby overhangs on the before side.
after: Ruby overhangs on the after side.

axf:ruby-offset

Specifies the spacing between ruby and its base character. V6.0

Value:	<number> \| <length> \| <percentage>
Initial:	0pt
Applies to:	axf:ruby
Inherited:	yes
Percentages:	refer to the font size

Values have the following meanings.

<number>: It's a value created by crossing the font size of ruby (axf:ruby-font-size) in the axf:ruby-text element.
<length>: Specifies the length.
<percentage>: It's a value created by crossing the font size (not the font size of ruby).

axf:ruby-overhang

Specifies how ruby overhangs the adjacent base character. V6.0

Value:	none \| auto \| [start \|\| end \|\| except-kanji \|\| except-katakana \|\| except-start-open-parenthesis \|\| except-end-close-parenthesis]
Initial:	auto
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

Values have the following meanings.

none: Does not overhang the adjacent base character.
auto: Same as start end except-kanji
start: Overhangs on the start side of the adjacent base character (if available).
end: Overhangs on the end side of the adjacent base character (if available).
except-kanji: Does not overhang when the adjacent base character is kanji.
except-katakana: Does not overhang when the adjacent base character is katakana.
except-start-open-parenthesis: Does not overhang when the open parenthesis is on the start side.
except-end-close-parenthesis: Does not overhang when the close parenthesis is on the end side.

When only except-* is specified and neither start nor end are specified, it is considered as start and end are specified.

axf:ruby-limit-overhang

Specifies the limit of the amount that ruby overhangs the adjacent base character when ruby is longer than its own base character. V6.0

Value:	<number> \| <length> \| <percentage>
Initial:	1.0
Applies to:	axf:ruby
Inherited:	yes
Percentages:	refer to the font size

Values have the following meanings.

<number>: It's a value created by crossing the font size of ruby (axf:ruby-font-size) in the axf:ruby-text element. The value should be non-negative.
<length>: Specifies the length. The value should be non-negative.
<percentage>: It's a value created by crossing the font size (not the font size of ruby). The value should be non-negative.

This value shows the amount that ruby overhangs the adjacent base character (It is not a protruding amount).

axf:ruby-limit-space

Specifies the limit of the amount of the space before and after the ruby when ruby is shorter than its base characters. V6.0

Value:	<number> \| <length> \| <percentage> \| none
Initial:	1.0
Applies to:	axf:ruby
Inherited:	yes
Percentages:	refer to the font size

Values have the following meanings.

<number>: It's a value created by crossing the font size of ruby (axf:ruby-font-size) in the axf:ruby-text element. The value should be non-negative.
<length>: Specifies the length. The value should be non-negative.
<percentage>: It's a value created by crossing the font size (not the font size of ruby). The value should be non-negative.
none: Does not limit the amount of the space.

Possible to avoid generating too much spaces before and after the ruby because ruby is too shorter than its base characters when axf:ruby-align="distribute-space" is specified. The amount of the space will be limitted to the specified value.

<ruby ruby-limit-space="none"><rb>なげきの聖母像</rb><rt>ピエタ</rt></ruby>

<ruby ruby-limit-space="1.0"><rb>なげきの聖母像</rb><rt>ピエタ</rt></ruby>

axf:ruby-small-kana

Specifies whether to allow using small kana for ruby. V6.0

Value:	auto \| convert
Initial:	auto
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

Values have the following meanings.

auto: Does nothing.
convert: Small kana of only full width is converted into the general kana. Half width characters will not be converted.

It's made available not to use small kana for ruby. Even if small kana is specified to ruby in FO, it will be transformed into the original kana.

When ruby-small-kana="auto" is specified, there is nothing special. Small kana will be applied for ruby as is unless text-transform="fullsize-kana" is specified.

axf:ruby-font-family

Specifies the font family of ruby. V6.0

Value:	[[<family-name> \| <generic-family>],]* [<family-name> \| <generic-family>]
Initial:	empty string
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

If nothing is specified, it's considered the same as font-family.

axf:ruby-font-size

Specifies the font size of ruby. V6.0

Value:	<number> \| <absolute-size> \| <relative-size> \| <length> \| <percentage>
Initial:	0.5
Applies to:	axf:ruby
Inherited:	yes
Percentages:	refer to the font size

It's a value created by crossing the font size with the setting of <number>

axf:ruby-minimum-font-size

Specifies the minimum font size of ruby. V6.0

Value:	none \| <absolute-size> \| <relative-size> \| <length> \| <percentage>
Initial:	none
Applies to:	axf:ruby
Inherited:	yes
Percentages:	refer to the font size

axf:ruby-font-style

Specifies whether ruby is made Italic. V6.0

Value:	normal \| italic
Initial:	empty
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

If nothing is specified, it's considered the same as font-style.

axf:ruby-font-weight

Specifies the font weight of ruby. V6.0

Value:	normal \| bold \| bolder \| lighter \| 100 \| 200 \| 300 \| 400 \| 500 \| 600 \| 700 \| 800 \| 900
Initial:	empty
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

If nothing is specified, it's considered the same as font-weight.

axf:ruby-font-stretch

Specifies the font stretching of ruby. V6.0

Value:	normal \| wider \| narrower \| ultra-condensed \| extra-condensed \| condensed \| semi-condensed \| semi-expanded \| expanded \| extra-expanded \| ultra-expanded \| <percentage> \| <number>
Initial:	empty
Applies to:	axf:ruby
Inherited:	yes
Percentages:	refer to the ruby-font-size

If nothing is specified, it's considered the same as font-stretch.

axf:ruby-condense

Specifies the font condense when ruby is longer than its base. V6.0

Value:	none \| <percentage> \| <number>
Initial:	none
Applies to:	axf:ruby
Inherited:	yes
Percentages:	refer to the ruby-font-size

Condenses ruby by "stretch" so that length of ruby becomes the same as its base characters when ruby is longer than its base characters. The numerical value shows the limit to be shorten at that time. If none is specified, ruby is not condensed.

axf:ruby-color

Specifies the color of ruby. V6.0

Value:	<color>
Initial:	empty
Applies to:	axf:ruby
Inherited:	yes
Percentages:	N/A

If nothing is specified, it's considered the same as color.