--epub-page-direction=XXX option possible?

[kawabata]

If possible, I hope "page-progression-direction" attribute of "spine" element
of EPUB OPF file could be specified in pandoc EPUB writer.

The specification of this attribute is as follows.
http://www.idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem

I have two ideas on realizing this.

One is repeatable option --epub-spine-attribute, as
--epub-spine-attribute=page-progression-direction:ltr.

Another is --epub-page-direction=ltr. My preference is latter.

As far as I've checked, I couldn't find anyone, requesting this feature.

[elmimmo]

The feature is actually indispensable for supporting East-Asian languages such as Japanese, Chinese (whose publishing industries are nothing to sneeze at).

If you add the feature, please add a syntax for the metadata block as well, as any book requiring it will always need it, and therefore it makes sense not enforcing having to remembering the command-line option on each run.

[mpickering]

There is already support for a YAML metadata block if you are converting from Markdown. I am in favour of doing this, just need to wait for John to decide what the best way is.

[jgm]

My preference would be to use a text-direction metadata field, with allowed values ltr or rtl. The epub writer would check for this and set the dir element accordingly. @mpickering, did you want to implement this? (It should also be documented in the EPUB Metadata section of the README.)

[mpickering]

sure, will do it tomorrow

On Sun, Aug 10, 2014 at 10:13 PM, John MacFarlane [email protected]
wrote:

My preference would be to use a text-direction metadata field, with
allowed values ltr or rtl. The epub writer would check for this and set
the dir element accordingly. @mpickering https://github.com/mpickering,
did you want to implement this? (It should also be documented in the EPUB
Metadata section of the README.)

—
Reply to this email directly or view it on GitHub
#1455 (comment).

[kawabata]

Text-direction and page direction should not be confused.
Text-direction can be vertical (top-to-down), left-to-right
or right-to-left. On the other hand, page progression direction can be
left-to-right or right-to-left. Japanese vertical writing would have
page direction of rtl, while Mongolian vertical writing would have
page direction of ltr, Japanese horizontal writing would have page
direction of ltr, while Arabic one would have rtl, etc.

So the ame of --epub-page-direction or --epub-page-progression-direction
would be appropriate, I believe.

I want Pandoc command line option to be able to support this, too,
as not all the document formats support metadata section.

Regards,

On Mon, Aug 11, 2014 at 6:31 AM, mpickering [email protected]
wrote:

sure, will do it tomorrow

On Sun, Aug 10, 2014 at 10:13 PM, John MacFarlane <
[email protected]>
wrote:

My preference would be to use a text-direction metadata field, with
allowed values ltr or rtl. The epub writer would check for this and set
the dir element accordingly. @mpickering https://github.com/mpickering,

did you want to implement this? (It should also be documented in the
EPUB
Metadata section of the README.)

—
Reply to this email directly or view it on GitHub
#1455 (comment).

—
Reply to this email directly or view it on GitHub
#1455 (comment).

---

川幡 太一 (KAWABATA, Taichi) E-mail: [email protected]

[jgm]

+++ kawabata [Aug 10 14 16:53 ]:

Text-direction and page direction should not be confused.
Text-direction can be vertical (top-to-down), left-to-right
or right-to-left. On the other hand, page progression direction can be
left-to-right or right-to-left. Japanese vertical writing would have
page direction of rtl, while Mongolian vertical writing would have
page direction of ltr, Japanese horizontal writing would have page
direction of ltr, while Arabic one would have rtl, etc.

OK - I see a 'dir' element of the spine which can be rtl or ltr.
Is that text direction or page direction? And where does one
put the other in the epub spine?

So the ame of --epub-page-direction or
--epub-page-progression-direction
would be appropriate, I believe.
I want Pandoc command line option to be able to support this, too,
as not all the document formats support metadata section.

I'd rather stick with metadata. You can specify metadata from the
command line, in any format, with the -M/--metadata option.

[jgm]

Oh, I see: as you said originally, page-progression-direction in spine.

[kawabata]

In EPUB, page direction should be specified to epub spine element.
Text direction should be specified to CSS of HTML files.

In Pandoc, CSS can already be specified in --epub-stylesheet, but another
is missing currently.

On Mon, Aug 11, 2014 at 10:17 AM, John MacFarlane [email protected]
wrote:

Oh, I see: as you said originally, page-progression-direction in spine.

—
Reply to this email directly or view it on GitHub
#1455 (comment).

---

川幡 太一 (KAWABATA, Taichi) E-mail: [email protected]

[elmimmo]

Well, the options for text directionality are indeed no small deal.

I recommend reading EPUB 3 and Global Language Support to better understand the options for text directionality in EPUB, specifically the sections Vertical writing and Page Progression Direction. The EPUB Samples repository has a bunch of EPUB 3 samples featuring different text directions and writing modes (although not all combinations are necessarily supported by any reading system).

Chinese and Japanese can be written and read both horizontally and vertically. In some contexts one direction is more usual than the other, and vice versa. When horizontal, characters will most often flow from left to right, lines being ordered top-to-bottom just, like in Latin scripts; when vertical, characters will flow from top to bottom, and lines will be ordered right-to-left (think of it as if you had rotated the horizontal text 90° clockwise). Mongolian and Manchu are purportedly vertical, and their lines ordered left-to-right (note that I am not one bit familiar with these two, though).

The EPUB 3.0.1 spec details different properties that set the direction in which the content flows, each affecting it in an independent way:

1. The OPF's spine element's page-progression-direction attribute:

The global direction in which the content flows.

Allowed values are ltr (left-to-right), rtl (right-to-left) and default.

The spec is rather unspecific about what it means with "content flow" here, but taking into account the name of the attribute itself, I would assume that (and iBooks behaves this way), in practice, it determines the direction in which pagination flows (when content is paginated), but not the direction of text itself.
2. The writing-mode CSS3 property (which iBooks will only support on the html or body elements):

This property specifies whether lines of text are laid out horizontally or vertically and the direction in which blocks progress. Possible values:

horizontal-tb
: Top-to-bottom block flow direction. The writing mode is horizontal.

vertical-rl
: Right-to-left block flow direction. The writing mode is vertical.

vertical-lr
: Left-to-right block flow direction. The writing mode is vertical.

Japanese books with vertical layout will most often use page-progression-direction="rtl" on the spine, and -epub-writing-mode: vertical-rl applied to head or body elements. Horizontal books will generally lack either and therefore default to the same rules as Latin scripts.
3. The OPF's dir attribute, applicable to the package element and, independently, to some of the elements in the metadata block, which can be set to ltr or rtl.

This one does not affect the content of the EPUB, though, but rather its metadata only. For example, it could determine that the title only, but not the rest of metadata, should be displayed right-to-left.
4. HTML's dir attribute, applicable to any HTML element, which hardcodes the element's text directionality irrespective of CSS styling. The EPUB spec does not mention this attribute, but EPUB 3's dependency on HTML5 and CSS3 makes it supported.

I guess the last two, though, are really only necessary for very rare exceptions, whatever the language of the book. Unicode has its own algorithm for determining the text direction of a string depending on the characters used themselves (i.e. Arab should be displayed right-to-left by default), so I would assume (but I do not know) that, in languages that do have an intrinsic right-to-left text direction, the reading engine itself should be correctly guessing the direction of text without the need of specifying any dir attribute.

So, my take on how Pandoc should handle this:

1. It should leave the writing-mode CSS3 property as well as the HTML's dir attribute to the author. The source markdown document and associated CSS should have them if the author/content requires them.
2. It should allow setting the OPF's spine element's page-progression-direction attribute in the metadata block and with a command-line option. Considering it is an EPUB-only attribute, I do not see a reason for Pandoc's syntax to be different to EPUB's itself (in fact I find that counterproductive). I would therefore suggest:

• -epub-page-progression-direction for the command line option.
• page-progression-direction for the metadata block.

accepting values ltr, rtl and default, just like EPUB does.
3. If you want Pandoc to cater for custom text direction in metadata, you could do it in the metadata block the same way one sets the role of an author or the scheme of an identifier:

title:
- dir: rtl
  text: My right-to-left title

but, like I said, I bet that the need for such a thing will be exceptionally rare.

[elmimmo]

jgm commented:

You can specify metadata from the command line, in any format, with the -M/--metadata option.

Note that page-progression-direction in EPUB 3 is not a meta element, but an attribute of spine, therefore it is not currently supported.

[mpickering]

See the patch I just submitted.

On Mon, Aug 11, 2014 at 12:31 PM, elmimmo [email protected] wrote:

You can specify metadata from the command line, in any format, with the
-M/--metadata option.

Note that page-progression-direction in EPUB 3
http://www.idpf.org/epub/301/spec/epub-publications.html#attrdef-spine-page-progression-direction
is not a meta element, but an attribute of spine, therefore it is not
currently supported.

—
Reply to this email directly or view it on GitHub
#1455 (comment).

[kawabata]

Thank you very much!

Though text directionality issue is a bit complex, for "page progression direction",
I think this is all what I want!

[jgm]

+++ elmimmo [Aug 11 14 04:31 ]:

You can specify metadata from the command line, in any format, with
the -M/--metadata option.

Note that [1]page-progression-direction in EPUB 3 is not a meta
element, but an attribute of spine, therefore it is not currently
supported.

True, but we can consider it part of the pandoc metadata, and the
writer could put it in the spine.