Continued work on "Support right-to-left languages"

[cN3rd]

Build on top of the work done by #1489, by:

• Add a text_direction attribute to config.
• Derive the actual direction via said attribute, or by deriving it from the language.
• Expose and use it in the HTML output.
• Fix the arrows in the theme with local overrides.

AFAIK the sidebar seems to be fine even with the code.

Feedback welcome, especially on names.

[XVilka]

Probably worth to wait for https://github.com/rust-lang/mdBook/pull/1662 to be merged first, to autotest these changes.

[ivilata]

I did the same test as for #1489, and without needing to manually add dir="rtl" to HTML pages, just by adding text_direction = "rtl" under the [book] section of the TOML file, the output is properly formatted, including the prev/next arrows. Update: text_direction isn't actually needed with a proper language under [book].

@cN3rd, please note that a few changes happened to #1489 a few days ago, you may want to rebase your changes. Thanks a lot!

[jnny]

Adding my support for merging this PR, please! Thanks for your work @cN3rd :)

[cN3rd]

Hi @ivilata, finally got to rebase on the changes and even fixed a small bug. The author information got kinda fudged around in the newer commits, but I don't personally mind it.

I think the next step would be to either test this or wait upon the multi-language support. See #5 and #1306.

[ivilata]

Thanks a lot @cN3rd! I did a cursory test comparing output from 0411d62 and the newest 304a0df, and nothing seems to have broken in the process, the output looks just as correct. :+1:

I'll check #5 and #1306, but in my opinion this PR would already represent a big gain for multi-language support in mdBook. :clap:

[ywmaa]

how is it going with this pull request ? I would like to have right to left functionality even if it is not perfect.

[mgeisler]

Hey all, we're also starting to need this over in Comprehensive Rust: https://github.com/google/comprehensive-rust/issues/671. I would love to see this merged :smile: Let me add a few comments in case that helps with the review.

[jnny]

Thanks for resurfacing this PR, @mgeisler! Begging mdbook devs once again to please merge this absolutely necessary PR! As it stands we continue to use @cN3rd's branch as we have a significant Persian userbase.

[ehuss]

I pushed some changes to rebase on master and fix some issues, particularly with some recent CSS changes. I also changed it so that the arrow keys switch direction based on the text direction, since I assume pages flip in the opposite direction.

I suspect there are still a number of issues where it isn't rendering correctly, but I don't know exactly what should be changed.

Thanks everyone! I'm going to go ahead and merge. @mgeisler (or anyone) would be able to check out the latest master and test things out, particularly with different browsers and different OS's and devices?

[mgeisler]

Thanks everyone! I'm going to go ahead and merge. @mgeisler (or anyone) would be able to check out the latest master and test things out, particularly with different browsers and different OS's and devices?

Thanks @ehuss! I'll get this set up for one of our in-progress translations for a right-to-left language: https://github.com/google/comprehensive-rust/issues/1164. Then we should be able to quietly test this and hopefully find any major blockers that way.

[mgeisler]

Thanks @ehuss! I'll get this set up for one of our in-progress translations for a right-to-left language: google/comprehensive-rust#1164. Then we should be able to quietly test this and hopefully find any major blockers that way.

The message in https://github.com/google/comprehensive-rust/pull/1165 is that the RTL looks good. We'll merge this later today or tomorrow and start using it in our translations.

Thanks @cN3rd for creating this PR and thanks @Manishearth and @ehuss for helping getting it across the finishing line!

[Manishearth]

Oh, btw, ICU4X will have LocaleDirectionality APIs in 1.3 (hopefully to be released soon). It's going to be experimental until 1.4 so you need to use an = dep, but it may replace the manual locale matching.

[mgeisler]

We now publish the Persian translation of Comprehensive Rust at https://google.github.io/comprehensive-rust/fa/!

@jnny, this is a small demo of mdbook-i18n-helpers in action on a right-to-left language :slightly_smiling_face:

[moaminsharifi]

Were we supposed to say that we supported RTL? The simplest way to do it is to add dir=rtl to the <html> tag, but where is bi-directional text rendering?

Normally with adding dir=rtl all direction of html page will be right to left but what about english (or any ltr) text? for example:

Neither RTL support nor bidi were available when we started translating the book into Persian (farsi), making it difficult to read.

As mentioned earlier by @mgeisler we added dir=rtl to<html> tag is first step to supporting rtl but bidi is still a thing. I proposed a simple way to handle it with theme but not the best way: https://github.com/google/comprehensive-rust/issues/1413

It might be better to also discuss it here.

[Manishearth]

I believe bidirectional text is already supported by using more dir attributes on mixed language content. Careful sprinkling of unicode-bidi: embed on things like blockquotes and maybe code blocks is also probably good.