16
This is a work in progress. Please feel free to ask questions and/or
17
provide answers; send email to the `Docutils-users`_ mailing list.
18
Project members should feel free to edit the source text file
21
This is a work in progress. If you are reading a local copy, the
22
`master copy`_ might be newer. This document uses are relative links;
23
if they don't work, please use the `master copy`_.
25
Please feel free to ask questions and/or provide answers; send email
26
to the `Docutils-users`_ mailing list. Project members should feel
27
free to edit the source text file directly.
29
.. _master copy: http://docutils.sourceforge.net/FAQ.html
22
31
.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
136
159
reference are a good place to start. The `reStructuredText Markup
137
160
Specification`_ is a detailed technical specification.
139
.. _A ReStructuredText Primer:
140
http://docutils.sourceforge.net/docs/user/rst/quickstart.html
141
.. _Quick reStructuredText:
142
http://docutils.sourceforge.net/docs/user/rst/quickref.html
162
.. _A ReStructuredText Primer: docs/user/rst/quickstart.html
163
.. _Quick reStructuredText: docs/user/rst/quickref.html
143
164
.. _reStructuredText Markup Specification:
144
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
165
docs/ref/rst/restructuredtext.html
145
166
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
146
167
.. _StructuredText:
147
168
http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
293
316
thus you need to add spaces ("``foo |---| bar``") and advise the
294
317
reStructuredText parser to trim the spaces.
296
.. _Standard Substitution Definition Sets:
297
http://docutils.sf.net/docs/ref/rst/substitutions.html
299
http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
319
.. _Standard Substitution Definition Sets: docs/ref/rst/substitutions.html
320
.. _unicode: docs/ref/rst/directives.html#unicode-character-codes
300
321
.. _are available: http://docutils.sourceforge.net/tmp/charents/
301
322
.. _tarball: http://docutils.sourceforge.net/tmp/charents.tgz
302
323
.. _description and instructions:
303
324
http://docutils.sourceforge.net/tmp/charents/README.html
304
.. _to-do list: http://docutils.sourceforge.net/docs/dev/todo.html
325
.. _to-do list: docs/dev/todo.html
307
328
How can I generate backticks using a Scandinavian keyboard?
387
408
* `Webware for Python wiki
388
409
<http://wiki.webwareforpython.org/thiswiki.html>`__
389
411
* `Ian Bicking's experimental code
390
412
<http://docutils.sf.net/sandbox/ianb/wiki/Wiki.py>`__
391
414
* `MoinMoin <http://moinmoin.wikiwikiweb.de/>`__ has some support;
392
415
`here's a sample <http://moinmoin.wikiwikiweb.de/RestSample>`__
393
417
* Zope-based `Zwiki <http://zwiki.org/>`__
394
* Zope3-based Zwiki (in the Zope 3 source tree as ``zope.products.zwiki``)
419
* Zope3-based Zwiki (in the Zope 3 source tree as
420
``zope.products.zwiki``)
395
422
* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
396
* `Trac <http://projects.edgewall.com/trac/>`__ `supports using reStructuredText
397
<http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as an
398
alternative to wiki markup. This includes support for `TracLinks
399
<http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within RST
400
text via a custom RST reference-directive or, even easier, an interpreted text
402
* `Vogontia <http://www.ososo.de/vogontia/>`__, a Wiki-like FAQ system
424
* `Trac <http://projects.edgewall.com/trac/>`__ `supports using
426
<http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as
427
an alternative to wiki markup. This includes support for `TracLinks
428
<http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within
429
RST text via a custom RST reference-directive or, even easier, an
430
interpreted text role 'trac'
404
432
Please `let us know`_ of any other reStructuredText Wikis.
417
445
* `Firedrop <http://www.voidspace.org.uk/python/firedrop2/>`__
418
446
* `Python Desktop Server <http://pyds.muensterland.org/>`__
419
* `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom/>`__
447
* `PyBloxsom <http://pyblosxom.sourceforge.net/>`__
420
448
* `Lino WebMan <http://lino.sourceforge.net/webman.html>`__
422
450
Please `let us know`_ of any other reStructuredText Blogs.
425
Can lists be indented without generating block quotes?
426
------------------------------------------------------
428
Some people like to write lists with indentation, without intending a
429
block quote context, like this::
436
There has been a lot of discussion about this, but there are some
437
issues that would need to be resolved before it could be implemented.
438
There is a summary of the issues and pointers to the discussions in
441
__ http://docutils.sourceforge.net/docs/dev/todo.html#indented-lists
453
.. _Can lists be indented without generating block quotes?:
455
How should I mark up lists?
456
---------------------------
458
Bullet_ & enumerated_ list markup is very intuitive but there are 2
459
points that must be noted:
461
.. _bullet: docs/ref/rst/restructuredtext.html#bullet-lists
462
.. _enumerated: docs/ref/rst/restructuredtext.html#enumerated-lists
464
1. Lists should **not** be indented. This is correct::
475
while this is probably incorrect::
486
The extra indentation (of the list containing items 1.1 and 1.2) is
487
recognized as a block quote. This is usually not what you mean and
488
it causes the list in the output to be indented too much.
490
2. There **must** be blank lines around list items, except between
491
items of the same level, where blank lines are optional. The
492
example above shows this.
494
Note that formatting of the *output* is independent of the input, and
495
is decided by the writer and the stylesheet. For instance, lists
496
*are* indented in HTML output by default. See `How are lists
497
formatted in HTML?`_ for details.
500
Could lists be indented without generating block quotes?
501
--------------------------------------------------------
503
Some people like to write lists with indentation but don't intend a
504
blockquote context. There has been a lot of discussion about allowing
505
this in reStructuredText, but there are some issues that would need to
506
be resolved before it could be implemented. There is a summary of the
507
issues and pointers to the discussions in `the to-do list`__.
509
__ docs/dev/todo.html#indented-lists
444
512
Could the requirement for blank lines around lists be relaxed?
817
Can I produce documents in right-to-left languages?
818
---------------------------------------------------
820
Languages written from right to left, such as Arabic and Hebrew, must
821
be reordered according to the `Unicode Bidi Algorithm`_. This
822
requires support from the editor and special markup in the output
825
The source format of reStructuredText is relatively bidi-friendly:
826
most constructs are denoted by punctuation without intrusion of
827
English and when you must write in English, it's usually on a separate
828
line. So any editor that auto-detects direction per-line (like gedit
829
or geresh_) will suffice.
831
Moreover, it's possible to translate_ all reStructuredText keywords.
832
This was not yet done for any RTL language, but when it is, it will be
833
possible to write an RTL document with vitually no English. This will
834
allow reasonable use of editors limited to a single base direction for
835
the whole document (like Notepad, Vim and text boxes in Firefox).
837
.. _Unicode Bidi Algorithm: http://www.unicode.org/reports/tr9/
838
.. _geresh: http://www.typo.co.il/~mooffie/geresh/
839
.. _translate: docs/howto/i18n.html
841
The second problem is bidi markup of the output. There is an almost
842
transparent implicit solution for HTML:
844
* Grab http://cben-hacks.sourceforge.net/bidi/hibidi.py and
845
http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py.
846
Put them both in the same directory and make them executable.
848
* Use ``rst2html_hibidi.py`` instead of ``rst2html.py``.
850
* It infers dir attributes in the HTML from the text. It does it
851
hierachically, giving much better results than usual. You can still
852
use LRM/RLM and LRE/RLE/PDF control codes to help it.
854
* If you want the gory details: See the full theory_, and note the
855
incomplete practice_ (this is still a partial implementation - but
856
sufficient for most needs).
858
.. _theory: http://cben-hacks.sf.net/bidi/hibidi.html
859
.. _practice: http://cben-hacks.sf.net/bidi/hibidi.html#practice
861
There is also an explicit way to set directions through CSS and
864
* Copy ``default.css`` to a new file and add relevant parts of the
867
/* Use these two if the main document direction is RTL */
868
body { direction: rtl; }
869
div.sidebar { float: left !important; }
871
/* The next 3 rules are very useful in documents containing pieces
872
of code in english */
873
/* Use this if you all your literal blocks (::) are LTR */
874
pre {direction: ltr; unicode-bidi: embed; }
875
/* Use this if you all your inline literals (``) are LTR */
876
tt {direction: ltr; unicode-bidi: embed; }
877
/* Use this if you all your interpretted text (`) is LTR */
878
cite {direction: ltr; unicode-bidi: embed; }
880
/* Allow manual direction override by class directive and roles */
881
.rtl { direction: rtl; }
882
.ltr { direction: ltr; }
884
* Select this new stylesheet with ``--stylesheet=<file>`` or the
887
* Now if you need to override the direction of some element (from a
888
paragraph to a whole section), write::
896
before it (see the class_ directive for details).
898
* To change the direction of some inline text fragment, you can use
899
RLE/LRE/PDF control characters, or write ``:rtl:`RTL text``` /
900
``:ltr:`RTL text```. To use the latter syntax, you must write this
901
once at the beginning of your document::
906
.. _stylesheet: docs/user/config.html#stylesheet
907
.. _class: docs/ref/rst/directives.txt#class
909
LaTeX is quite hard to implement (it doesn't support the bidi
910
algorithm, so all direction changes - even numbers in RTL text - must
911
be explicitly marked). Other formats are more-or-less easy.
913
If you have any questions/problems/bugs related to bidi with docutils,
914
ask `Beni Cherniavsky`__ directly or the `Docutils-users`_ mailing
917
__ mailto:cben@users.sf.net
920
What's the official MIME type for reStructuredText data?
921
--------------------------------------------------------
923
While there is no registered MIME type for reStructuredText, the
924
"official unofficial" standard MIME type is "text/x-rst". This was
925
invented for the build system for PEPs (Python Enhancement Proposals),
926
and it's used by the python.org web site build system.
928
(The "x-" prefix means it's an unregistered MIME type.)
930
Also see `What's the standard filename extension for a
931
reStructuredText file?`_
870
1056
to your specific document, you might end up with bad HTML (e.g. H3
874
http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform
875
.. _initial_header_level:
876
http://docutils.sourceforge.net/docs/user/config.html#initial-header-level
1059
.. _doctitle_xform: docs/user/config.html#doctitle-xform
1060
.. _initial_header_level: docs/user/config.html#initial-header-level
878
1062
(Thanks to Mark McEahern for the question and much of the answer.)
1065
How are lists formatted in HTML?
1066
--------------------------------
1068
If list formatting looks strange, first check that you understand
1071
__ `How should I mark up lists?`_
1073
* By default, HTML browsers indent lists relative to their context.
1074
This follows a long tradition in browsers (but isn't so established
1075
in print). If you don't like it, you should change the stylesheet.
1077
This is different from how lists look in reStructuredText source.
1078
Extra indentation in the source indicates a blockquote, resulting in
1079
too much indentation in the browser.
1081
* A list item can contain multiple paragraphs etc. In complex cases
1082
list items are separated by vertical space. By default this spacing
1083
is omitted in "simple" lists. A list is simple if every item
1084
contains a simple paragraph and/or a "simple" nested list. For
1096
text after a nested list
1102
In this example the nested lists are simple (and should appear
1103
compacted) but the outer list is not.
1105
If you want all lists to have equal spacing, disable the
1106
`compact_lists`_ setting (``--no-compact-lists`` option). The
1107
precise spacing can be controlled in the stylesheet.
1109
Note again that this is not exactly WYSIWYG: it partially resembles
1110
the rules about blank lines being optional between list items in
1111
reStructuredText -- but adding/removing optional blank lines does
1112
not affect spacing in the output! It's a feature, not a bug: you
1113
write it as you like but the output is styled consistently.
1115
.. _compact_lists: docs/user/config.html#compact-lists
881
1118
Why do enumerated lists only use numbers (no letters or roman numerals)?
882
1119
------------------------------------------------------------------------
884
1121
The rendering of enumerators (the numbers or letters acting as list
885
1122
markers) is completely governed by the stylesheet, so either the
886
browser can't find the stylesheet (try using the "--embed-stylesheet"
887
option), or the browser can't understand it (try a recent Firefox,
888
Mozilla, Konqueror, Opera, Safari, or even MSIE).
1123
browser can't find the stylesheet (try enabling the
1124
`embed_stylesheet`_ setting [``--embed-stylesheet`` option]), or the
1125
browser can't understand it (try a recent Firefox, Mozilla, Konqueror,
1126
Opera, Safari, or even MSIE).
1128
.. _embed_stylesheet: docs/user/config.html#embed-stylesheet
891
1131
There appear to be garbage characters in the HTML. What's up?
923
1163
recognizing that. You can either try to fix your browser (enable
924
1164
"UTF-8 character set", sometimes called "Unicode"), or choose a
925
1165
different encoding for the HTML output. You can also try
926
``--output-encoding=ascii:xmlcharrefreplace`` for HTML (not applicable
927
to non-XMLish outputs).
1166
``--output-encoding=ascii:xmlcharrefreplace`` for HTML or XML, but not
1167
applicable to non-XMLish outputs (if using runtime
1168
settings/configuration files, use ``output_encoding=ascii`` and
1169
``output_encoding_error_handler=xmlcharrefreplace``).
929
1171
If you're generating document fragments, the "Content-Type" metadata
930
1172
(between the HTML ``<head>`` and ``</head>`` tags) must agree with the
added
removed
FAQ.txt
