Menu
▾
▴
[Docutils-checkins] r4557 - trunk/docutils/FAQ.txt
|
From: <sf...@us...> - 2006-05-16 05:32:25
|
Author: sfcben Date: 2006-05-16 07:33:51 +0200 (Tue, 16 May 2006) New Revision: 4557 Modified: trunk/docutils/FAQ.txt Log: Documented implicit solution. The FAQ is accumulating HOWTO-style answers (e.g. this one, math support). Should they perhaps be extracted to separated documents? Modified: trunk/docutils/FAQ.txt =================================================================== --- trunk/docutils/FAQ.txt 2006-05-16 03:00:48 UTC (rev 4556) +++ trunk/docutils/FAQ.txt 2006-05-16 05:33:51 UTC (rev 4557) @@ -1058,6 +1058,8 @@ .. _sectnum: docs/ref/rst/directives.html#sectnum +.. _bidi: + Can I produce documents in right-to-left languages? --------------------------------------------------- @@ -1075,63 +1077,92 @@ 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). +allow reasonable use of editors limited to a single base direction for +the whole document (like Notepad, Vim and text boxes in Firefox). -The second problem is bidi markup of the output. Here is an explicit -solution for HTML: +.. _Unicode Bidi Algorithm: http://www.unicode.org/reports/tr9/ +.. _geresh: http://www.typo.co.il/~mooffie/geresh/ +.. _translate: docs/howto/i18n.html -Copy ``default.css`` to a new file and add relevant parts of the -following:: +The second problem is bidi markup of the output. There is an almost +transparent implicit solution for HTML: - /* Use these two if the main document direction is RTL */ - body { direction: rtl; } - div.sidebar { float: left !important; } +* Grab http://cben-hacks.sourceforge.net/bidi/hibidi.py and + http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py. + Put them both in the same directory and make them executable. + +* Use ``rst2html_hibidi.py`` instead of ``rst2html.py``. - /* 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; } +* It infers dir attributes in the HTML from the text. It does it + hierachically, giving much better results than usual. You can still + use LRM/RLM and LRE/RLE/PDF control codes to help it. - /* Allow manual direction override by class directive and roles */ - .rtl { direction: rtl; } - .ltr { direction: ltr; } + * If you want the gory details: See the full theory_, and note the + incomplete practice_ (this is still a partial implementation - but + sufficient for most needs). -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:: + .. _theory: http://cben-hacks.sf.net/bidi/hibidi.html + .. _practice: http://cben-hacks.sf.net/bidi/hibidi.html#practice - .. class:: rtl +There is also an explicit way to set directions through CSS and +classes in the HTML: -or:: +* Copy ``default.css`` to a new file and add relevant parts of the + following:: - .. class:: ltr + /* Use these two if the main document direction is RTL */ + body { direction: rtl; } + div.sidebar { float: left !important; } -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:: + /* 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; } - .. role:: ltr - .. role:: rtl + /* Allow manual direction override by class directive and roles */ + .rtl { direction: rtl; } + .ltr { direction: ltr; } -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. +* 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:: -.. _Unicode Bidi Algorithm: http://www.unicode.org/reports/tr9/ -.. _geresh: http://www.typo.co.il/~mooffie/geresh/ -.. _translate: docs/howto/i18n.html + .. 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 + .. _stylesheet: docs/user/config.html#stylesheet .. _class: docs/ref/rst/directives.txt#class +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. +If you have any questions/problems/bugs related to bidi with docutils, +ask `Beni Cherniavsky`__ directly or the `Docutils-users`_ mailing +list. + +__ mailto:cb...@us... + + How can I retrieve the body of the HTML document? ------------------------------------------------- |