Documented explicit bidi solution for HTML.

[I will presently release and document an implicit solution.]


git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@4556 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 74 insertions, 0 deletions

diff --git a/docutils/FAQ.txt b/docutils/FAQ.txt
index 63ecb2588..d8662b36c 100644
--- a/docutils/FAQ.txt
+++ b/docutils/FAQ.txt
@@ -1058,6 +1058,80 @@ of the output.  It must also match the document encoding.  For UTF-8::
 .. _sectnum: docs/ref/rst/directives.html#sectnum
 
 
+Can I produce documents in right-to-left languages?
+---------------------------------------------------
+
+Languages written from right to left, such as Arabic and Hebrew, must
+be reordered according to the `Unicode Bidi Algorithm`_.  This
+requires support from the editor and special markup in the output
+format.
+
+The source format of reStructuredText is relatively bidi-friendly:
+most constructs are denoted by punctuation without intrusion of
+English and when you must write in English, it's usually on a separate
+line.  So any editor that auto-detects direction per-line (like gedit
+or geresh_) will suffice.
+
+Moreover, it's possible to translate_ all reStructuredText keywords.
+This was not yet done for any RTL language, but when it is, it will be
+possible to write an RTL document with vitually no English.  This will
+allow reasonable use of editors that show the whole document as either
+LTR or RTL (like Notepad, Vim and text boxes in Firefox).
+
+The second problem is bidi markup of the output.  Here is an explicit
+solution for HTML:
+
+Copy ``default.css`` to a new file and add relevant parts of the
+following::
+
+    /* Use these two if the main document direction is RTL */
+    body { direction: rtl; }
+    div.sidebar { float: left !important; }
+
+    /* The next 3 rules are very useful in documents containing pieces
+    of code in english */
+    /* Use this if you all your literal blocks (::) are LTR */
+    pre {direction: ltr; unicode-bidi: embed; }
+    /* Use this if you all your inline literals (``) are LTR */
+    tt {direction: ltr; unicode-bidi: embed; }
+    /* Use this if you all your interpretted text (`) is LTR */
+    cite {direction: ltr; unicode-bidi: embed; }
+
+    /* Allow manual direction override by class directive and roles */
+    .rtl { direction: rtl; }
+    .ltr { direction: ltr; }
+
+Select this new stylesheet with ``--stylesheet=<file>`` or the
+stylesheet_ setting.  Now if you need to override the direction of
+some element (from a paragraph to a whole section), write::
+
+    .. class:: rtl
+
+or::
+
+    .. class:: ltr
+
+before it (see the class_ directive for details).  To change the
+direction of some inline text fragment, you can use RLE/LRE/PDF
+control characters, or write ``:rtl:`RTL text``` / ``:ltr:`RTL
+text```.  To use the latter syntax, you must write this once at the
+beginning of your document::
+
+    .. role:: ltr
+    .. role:: rtl
+
+LaTeX is quite hard to implement (it doesn't support the bidi
+algorithm, so all direction changes - even numbers in RTL text - must
+be explicitly marked).  Other formats are more-or-less easy - ask on
+the `Docutils-users`_ mailing list.
+
+.. _Unicode Bidi Algorithm: http://www.unicode.org/reports/tr9/
+.. _geresh: http://www.typo.co.il/~mooffie/geresh/
+.. _translate: docs/howto/i18n.html
+.. _stylesheet: docs/user/config.html#stylesheet
+.. _class: docs/ref/rst/directives.txt#class
+
+
 How can I retrieve the body of the HTML document?
 -------------------------------------------------