296
341
Keyboard layout (and setting it as default "when you start your
344
* Use a virtual/screen keyboard or character palette, such as:
346
- `Web-based keyboards <http://keyboard.lab.co.il/>`__ (IE only
348
- Windows: `Click-N-Type <http://www.lakefolks.org/cnt/>`__.
349
- Mac OS X: the Character Palette can store a set of favorite
350
characters for easy input. Open System Preferences,
351
International, Input Menu tab, enable "Show input menu in menu
352
bar", and be sure that Character Palette is enabled in the list.
299
354
If anyone knows of other/better solutions, please `let us know`_.
302
357
Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping)
303
358
-----------------------------------------------------------------------
305
People have tossed the idea around, but little if any actual work has
306
ever been done. There's no reason why reStructuredText should not be
307
round-trippable to/from XML; any technicalities which prevent
308
round-tripping would be considered bugs. Whitespace would not be
309
identical, but paragraphs shouldn't suffer. The tricky parts would be
310
the smaller details, like links and IDs and other bookkeeping.
360
People have tossed the idea around, and some implementations of
361
reStructuredText-generating tools can be found in the `Docutils Link
364
There's no reason why reStructuredText should not be round-trippable
365
to/from XML; any technicalities which prevent round-tripping would be
366
considered bugs. Whitespace would not be identical, but paragraphs
367
shouldn't suffer. The tricky parts would be the smaller details, like
368
links and IDs and other bookkeeping.
312
370
For HTML, true round-tripping may not be possible. Even adding lots
313
371
of extra "class" attributes may not be enough. A "simple HTML" to RST
314
372
filter is possible -- for some definition of "simple HTML" -- but HTML
315
373
is used as dumb formatting so much that such a filter may not be
316
particularly useful. No general-purpose filter exists. An 80/20
317
approach should work though: build a tool that does 80% of the work
318
automatically, leaving the other 20% for manual tweaks.
374
particularly useful. An 80/20 approach should work though: build a
375
tool that does 80% of the work automatically, leaving the other 20%
378
.. _Docutils Link List: docs/user/links.html
321
381
Are there any Wikis that use reStructuredText syntax?
395
463
There is no elegant built-in way, yet. There are several ideas, but
396
464
no obvious winner. This issue requires a champion to solve the
397
465
technical and aesthetic issues and implement a generic solution.
398
Here's the `to-do list entry <spec/notes.html#math-markup>`__.
400
There are several quick & dirty ways to include equations in
403
* For HTML there is MathML but its rendering is still quite broken (or
404
absent) on most browsers. An example of raw MathML is `here
405
<http://sf.net/mailarchive/message.php?msg_id=2177102>`__.
407
* If you use LaTeX output only, a simple way is to use the "raw"
408
directive; examples are `here
409
<http://article.gmane.org/gmane.text.docutils.devel/521>`__.
411
* Images of the equations can be used, typically generated by TeX.
412
Beni Cherniavsky has written some `preprocessing scripts`__ for
413
making inline TeX (for LaTeX and other [HTML etc.] output) math much
414
easier; `instructions here`__.
466
Here's the `to-do list entry`__.
468
__ http://docutils.sourceforge.net/docs/dev/todo.html#math-markup
470
There are several quick & dirty ways to include equations in documents.
471
They all presently use LaTeX syntax or dialects of it.
473
* For LaTeX output, nothing beats raw LaTeX math. A simple way is to
474
use the `raw directive`_::
478
\[ x^3 + 3x^2a + 3xa^2 + a^3, \]
480
For inline math you could use substitutions of the raw directive but
481
the recently added `raw role`_ is more convenient. You must define a
482
custom role based on it once in your document::
484
.. role:: raw-latex(raw)
487
and then you can just use the new role in your text::
489
the binomial expansion of :raw-latex:`$(x+a)^3$` is
491
.. _raw directive: http://docutils.sourceforge.net/docs/ref/rst/
492
directives.html#raw-data-pass-through
493
.. _raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw
495
* Jens Jørgen Mortensen has implemented a "latex-math" role and
496
directive, available from `his sandbox`__.
498
__ http://docutils.sourceforge.net/sandbox/jensj/latex_math/
500
* For HTML the "Right" w3c-standard way to include math is MathML_.
501
Unfortunately its rendering is still quite broken (or absent) on many
502
browsers but it's getting better. Another bad problem is that typing
503
or reading raw MathML by humans is *really* painful, so embedding it
504
in a reST document with the raw directive would defy the goals of
505
readability and editability of reST (see an `example of raw MathML
506
<http://sf.net/mailarchive/message.php?msg_id=2177102>`__).
508
A much less painful way to generate HTML+MathML is to use itex2mml_ to
509
convert a dialect of LaTeX syntax to presentation MathML. Here is an
510
example of potential `itex math markup
511
<http://article.gmane.org/gmane.text.docutils.user/118>`__. The
512
simplest way to use it is to add ``html`` to the format lists for the
513
raw directive/role and postprocess the resulting document with
514
itex2mml. This way you can *generate LaTeX and HTML+MathML from the
515
same source*, but you must limit yourself to the intersection of LaTeX
516
and itex markups for this to work. Alan G. Isaac wrote a detailed
517
HOWTO_ for this approach.
519
.. _MathML: http://www.w3.org/Math/
520
.. _itex2mml: http://pear.math.pitt.edu/mathzilla/itex2mml.html
521
.. _HOWTO: http://www.american.edu/econ/itex2mml/mathhack.rst
523
* The other way to add math to HTML is to use images of the equations,
524
typically generated by TeX. This is inferior to MathML in the long
525
term but is perhaps more accessible nowdays.
527
Of course, doing it by hand is too much work. Beni Cherniavsky has
528
written some `preprocessing scripts`__ for converting the
529
``texmath`` role/directive into images for HTML output and raw
530
directives/subsitution for LaTeX output. This way you can *generate
531
LaTeX and HTML+images from the same source*. `Instructions here`__.
416
533
__ http://docutils.sourceforge.net/sandbox/cben/rolehack/
417
534
__ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html
419
* Here is an example of potential `itex math markup
420
<http://article.gmane.org/gmane.text.docutils.user/118>`__.
537
Is nested inline markup possible?
538
---------------------------------
540
Not currently, no. It's on the `to-do list`__ (`details here`__), and
541
hopefully will be part of the reStructuredText parser soon. At that
542
time, markup like this will become possible::
544
Here is some *emphasized text containing a `hyperlink`_ and
545
``inline literals``*.
547
__ http://docutils.sf.net/docs/dev/todo.html#nested-inline-markup
548
__ http://docutils.sf.net/docs/dev/rst/alternatives.html#nested-inline-markup
550
There are workarounds, but they are either convoluted or ugly or both.
551
They are not recommended.
553
* Inline markup can be combined with hyperlinks using `substitution
554
definitions`__ and references__ with the `"replace" directive`__.
557
Here is an |emphasized hyperlink|_.
559
.. |emphasized hyperlink| replace:: *emphasized hyperlink*
560
.. _emphasized hyperlink: http://example.org
562
It is not possible for just a portion of the replacement text to be
563
a hyperlink; it's the entire replacement text or nothing.
565
__ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-definitions
566
__ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-references
567
__ http://docutils.sf.net/docs/ref/rst/directives.html#replace
569
* The `"raw" directive`__ can be used to insert raw HTML into HTML
572
Here is some |stuff|.
574
.. |stuff| raw:: html
576
<em>emphasized text containing a
577
<a href="http://example.org">hyperlink</a> and
578
<tt>inline literals</tt></em>
580
Raw LaTeX is supported for LaTeX output, etc.
582
__ http://docutils.sf.net/docs/ref/rst/directives.html#raw
585
How to indicate a line break or a significant newline?
586
------------------------------------------------------
588
`Line blocks`__ are designed for address blocks, verse, and other
589
cases where line breaks are significant and must be preserved. Unlike
590
literal blocks, the typeface is not changed, and inline markup is
591
recognized. For example::
593
| A one, two, a one two three four
595
| Half a bee, philosophically,
596
| must, *ipso facto*, half not be.
597
| But half the bee has got to be,
598
| *vis a vis* its entity. D'you see?
600
| But can a bee be said to be
601
| or not to be an entire bee,
602
| when half the bee is not a bee,
603
| due to some ancient injury?
607
__ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#line-blocks
609
Here's a workaround for manually inserting explicit line breaks in
616
I want to break this line here: |br| this is after the break.
618
If the extra whitespace bothers you, |br|\ backslash-escape it.
621
A URL containing asterisks doesn't work. What to do?
622
-----------------------------------------------------
624
Asterisks are valid URL characters (see :RFC:`2396`), sometimes used
625
in URLs. For example::
627
http://cvs.example.org/viewcvs.py/*checkout*/module/file
629
Unfortunately, the parser thinks the asterisks are indicating
630
emphasis. The slashes serve as delineating punctuation, allowing the
631
asterisks to be recognized as markup. The example above is separated
632
by the parser into a truncated URL, an emphasized word, and some
635
http://cvs.example.org/viewcvs.py/
639
To turn off markup recognition, use a backslash to escape at least the
640
first asterisk, like this::
642
http://cvs.example.org/viewcvs.py/\*checkout*/module/file
644
Escaping the second asterisk doesn't hurt, but it isn't necessary.
647
How can I make a literal block with *some* formatting?
648
------------------------------------------------------
650
Use the `parsed-literal`_ directive.
652
.. _parsed-literal: docs/ref/rst/directives.html#parsed-literal
654
Scenario: a document contains some source code, which calls for a
655
literal block to preserve linebreaks and whitespace. But part of the
656
source code should be formatted, for example as emphasis or as a
657
hyperlink. This calls for a *parsed* literal block::
661
print "Hello world!" # *tricky* code [1]_
663
The emphasis (``*tricky*``) and footnote reference (``[1]_``) will be
667
Can reStructuredText be used for web or generic templating?
668
-----------------------------------------------------------
670
Docutils and reStructuredText can be used with or as a component of a
671
templating system, but they do not themselves include templating
672
functionality. Templating should simply be left to dedicated
673
templating systems. Users can choose a templating system to apply to
674
their reStructuredText documents as best serves their interests.
676
There are many good templating systems for Python (ht2html_, YAPTU_,
677
Quixote_'s PTL, Cheetah_, etc.; see this non-exhaustive list of `some
678
other templating systems`_), and many more for other languages, each
679
with different approaches. We invite you to try several and find one
680
you like. If you adapt it to use Docutils/reStructuredText, please
681
consider contributing the code to Docutils or `let us know`_ and we'll
684
One reST-specific web templating system is `rest2web
685
<http://www.voidspace.org.uk/python/rest2web>`_, a tool for
686
automatically building websites, or parts of websites.
688
.. _ht2html: http://ht2html.sourceforge.net/
690
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305
691
.. _Quixote: http://www.mems-exchange.org/software/quixote/
692
.. _Cheetah: http://www.cheetahtemplate.org/
693
.. _some other templating systems:
694
http://webware.sourceforge.net/Papers/Templates/
697
How can I mark up a FAQ or other list of questions & answers?
698
-------------------------------------------------------------
700
There is no specific syntax for FAQs and Q&A lists. Here are two
703
1. For a FAQ (Frequently Asked Questions, usually with answers), a
704
convenient way to mark up the questions is as section titles, with
705
the answer(s) as section content. This document is marked up in
708
The advantages of using section titles for questions are: sections
709
can be numbered automatically, and a table of contents can be
710
generated automatically. One limitation of this format is that
711
questions must fit on one line (section titles may not wrap, in the
712
source text). For very long questions, the title may be a summary
713
of the question, with the full question in the section body.
715
2. Field lists work well as Q&A lists::
717
:Q: What kind of questions can we
720
:A: Any kind we like!
722
In order to separate questions, lists can be used:
724
1. :Q: What kind of question can we
726
:A: Any kind we like!
728
2. :Q: How many answers can a question have?
731
:A3: Answers can be numbered like this.
735
If you don't want to number or otherwise mark questions, you can
736
use an empty comment between individual field lists to separate
542
884
The rendering of enumerators (the numbers or letters acting as list
543
885
markers) is completely governed by the stylesheet, so either the
544
886
browser can't find the stylesheet (try using the "--embed-stylesheet"
545
option), or the browser can't understand it (try a recent Mozilla or
887
option), or the browser can't understand it (try a recent Firefox,
888
Mozilla, Konqueror, Opera, Safari, or even MSIE).
891
There appear to be garbage characters in the HTML. What's up?
892
--------------------------------------------------------------
894
What you're seeing is most probably not garbage, but the result of a
895
mismatch between the actual encoding of the HTML output and the
896
encoding your browser is expecting. Your browser is misinterpreting
897
the HTML data, which is encoded text. A discussion of text encodings
898
is beyond the scope of this FAQ; see one or more of these documents
901
* `UTF-8 and Unicode FAQ for Unix/Linux
902
<http://www.cl.cam.ac.uk/~mgk25/unicode.html>`_
904
* Chapters 3 and 4 of `Introduction to i18n [Internationalization]
905
<http://www.debian.org/doc/manuals/intro-i18n/>`_
907
* `Python Unicode Tutorial
908
<http://www.reportlab.com/i18n/python_unicode_tutorial.html>`_
910
* `Python Unicode Objects: Some Observations on Working With Non-ASCII
911
Character Sets <http://effbot.org/zone/unicode-objects.htm>`_
913
The common case is with the default output encoding (UTF-8), when
914
either numbered sections are used (via the "sectnum_" directive) or
915
symbol-footnotes. 3 non-breaking spaces are inserted in each numbered
916
section title, between the generated number and the title text. Most
917
footnote symbols are not available in ASCII, nor are non-breaking
918
spaces. When encoded with UTF-8 and viewed with ordinary ASCII tools,
919
these characters will appear to be multi-character garbage.
921
You may have an decoding problem in your browser (or editor, etc.).
922
The encoding of the output is set to "utf-8", but your browswer isn't
923
recognizing that. You can either try to fix your browser (enable
924
"UTF-8 character set", sometimes called "Unicode"), or choose a
925
different encoding for the HTML output. You can also try
926
``--output-encoding=ascii:xmlcharrefreplace`` for HTML (not applicable
927
to non-XMLish outputs).
929
If you're generating document fragments, the "Content-Type" metadata
930
(between the HTML ``<head>`` and ``</head>`` tags) must agree with the
931
encoding of the rest of the document. For UTF-8, it should be::
933
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
935
Also, Docutils normally generates an XML declaration as the first line
936
of the output. It must also match the document encoding. For UTF-8::
938
<?xml version="1.0" encoding="utf-8" ?>
941
http://docutils.sourceforge.net/docs/ref/rst/directives.html#sectnum
944
How can I retrieve the body of the HTML document?
945
-------------------------------------------------
947
(This is usually needed when using Docutils in conjunction with a
950
You can use the `docutils.core.publish_parts()`_ function, which
951
returns a dictionary containing an 'html_body_' entry.
953
.. _docutils.core.publish_parts():
954
docs/api/publisher.html#publish-parts
956
docs/api/publisher.html#html-body
959
Why is the Docutils XHTML served as "Content-type: text/html"?
960
--------------------------------------------------------------
964
Docutils' HTML output looks like XHTML and is advertised as such::
966
<?xml version="1.0" encoding="utf-8" ?>
967
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
968
"http://www.w3.org/TR/xht ml1/DTD/xhtml1-transitional.dtd">
970
But this is followed by::
972
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
974
Shouldn't this be "application/xhtml+xml" instead of "text/html"?
976
In a perfect web, the Docutils XHTML output would be 100% strict
977
XHTML. But it's not a perfect web, and a major source of imperfection
978
is Internet Explorer. Despite it's drawbacks, IE still represents the
979
majority of web browsers, and cannot be ignored.
981
Short answer: if we didn't serve XHTML as "text/html" (which is a
982
perfectly valid thing to do), it couldn't be viewed in Internet
985
Long answer: see the `"Criticisms of Internet Explorer" Wikipedia
986
entry <http://en.wikipedia.org/wiki/Criticisms_of_Internet_Explorer#XHTML>`__.
988
However, there's also `Sending XHTML as text/html Considered
989
Harmful`__. What to do, what to do? We're damned no matter what we
990
do. So we'll continue to do the practical instead of the pure:
991
support the browsers that are actually out there, and not fight for
992
strict standards compliance.
994
__ http://hixie.ch/advocacy/xhtml
996
(Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan
549
1000
Python Source Reader
added
removed
FAQ.txt
