diff options
Diffstat (limited to 'docutils')
459 files changed, 0 insertions, 78381 deletions
diff --git a/docutils/BUGS.txt b/docutils/BUGS.txt deleted file mode 100644 index 8bb781508..000000000 --- a/docutils/BUGS.txt +++ /dev/null @@ -1,280 +0,0 @@ -================ - Docutils_ Bugs -================ - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - - -Bugs in Docutils?!? Yes, we do have a few. Some are old-timers that -tend to stay in the shadows and don't bother anybody. Once in a while -new bugs are born. From time to time some bugs (new and old) crawl -out into the light and must be dealt with. Icky. - -This document describes how to report a bug, and lists known bugs. - -.. contents:: - - -How To Report A Bug -=================== - -If you think you've discovered a bug, please read through these -guidelines before reporting it. - -First, make sure it's a new bug: - -* Please check the list of `known bugs`_ below and the `SourceForge - Bug Tracker`_ to see if it has already been reported. - -* Are you using the very latest version of Docutils? The bug may have - already been fixed. Please get the latest version of Docutils from - the repository_ or from the current snapshot_ and check again. Even - if your bug has not been fixed, others probably have, and you're - better off with the most up-to-date code. - - If you don't have time to check the latest snapshot, please report - the bug anyway. We'd rather tell you that it's already fixed than - miss reports of unfixed bugs. - -* If Docutils does not behave the way you expect, look in the - documentation_ (don't forget the FAQ_!) and `mailing list archives`_ - for evidence that it should behave the way you expect. - -If you're not sure, please ask on the Docutils-users_ mailing list -first. - -If it's a new bug, the most important thing you can do is to write a -simple description and a recipe that reproduces the bug. Try to -create a minimal document that demonstrates the bug. The easier you -make it to understand and track down the bug, the more likely a fix -will be. - -Now you're ready to write the bug report. Please include: - -* A clear description of the bug. Describe how you expected Docutils - to behave, and contrast that with how it actually behaved. While - the bug may seem obvious to you, it may not be so obvious to someone - else, so it's best to avoid a guessing game. - -* A complete description of the environment in which you reproduced - the bug: - - - Your operating system & version. - - The version of Python (``python -V``). - - The version of Docutils (use the "-V" option to most Docutils - front-end tools). - - Any private modifications you made to Docutils. - - Anything else that could possibly be relevant. Err on the side - of too much information, rather than too little. - -* A literal transcript of the *exact* command you ran, and the *exact* - output. Use the "--traceback" option to get a complete picture. - -* The exact input and output files. Better to attach complete files - to your bug report than to include just a summary or excerpt. - -* If you also want to include speculation as to the cause, and even a - patch to fix the bug, that would be great! - -The best place to send your bug report is to the `SourceForge Bug -Tracker`_. That way, it won't be misplaced or forgotten. In fact, an -open bug report on SourceForge is a constant irritant that begs to be -squashed. - -Thank you! - -(This section was inspired by the `Subversion project's`__ BUGS__ -file.) - -__ http://subversion.tigris.org/ -__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup - -.. _CVS: http://sourceforge.net/cvs/?group_id=38414 -.. _repository: docs/dev/repository.html -.. _snapshot: http://docutils.sourceforge.net/#download -.. _documentation: docs/ -.. _FAQ: FAQ.html -.. _mailing list archives: http://docutils.sf.net/#mailing-lists -.. _Docutils-users: docs/user/mailing-lists.html#docutils-users -.. _SourceForge Bug Tracker: - http://sourceforge.net/tracker/?group_id=38414&atid=422030 - - -Known Bugs -========== - -Also see the `SourceForge Bug Tracker`_. - -* The "stylesheet" setting (a URL, to be used verbatim) should be - allowed to be combined with "embed_stylesheet". The stylesheet data - should be read in using urllib. There was an assumption that a - stylesheet to be embedded should exist as a file on the local - system, and only the "stylesheet_path" setting should be used. - -* ``utils.relative_path()`` sometimes returns absolute _`paths on - Windows` (like ``C:/test/foo.css``) where it could have chosen a - relative path. - - Furthermore, absolute pathnames are inserted verbatim, like - ``href="C:/test/foo.css"`` instead of - ``href="file:///C:/test/foo.css"``. - - For details, see `this posting by Alan G. Isaac - <http://article.gmane.org/gmane.text.docutils.user/1569>`_. - -* _`Line numbers` in system messages are inconsistent in the parser. - - - In text inserted by the "include" directive, errors are often not - reported with the correct "source" or "line" numbers. Perhaps all - Reporter calls need "source" and "line" keyword arguments. - Elements' .line assignments should be checked. (Assign to .source - too? Add a set_info method? To what?) There's a test in - test/test_parsers/test_rst/test_directives/test_include.py. - - - Some line numbers in elements are not being set properly - (explicitly), just implicitly/automatically. See rev. 1.74 of - docutils/parsers/rst/states.py for an example of how to set. - -* .. _none source: - - Quite a few nodes are getting a "None" source attribute as well. In - particular, see the bodies of definition lists. - -* Footnote label "5" should be "4" when processing the following - input:: - - ref [#abc]_ [#]_ [1]_ [#4]_ - - .. [#abc] footnote - .. [#] two - .. [1] one - .. [#4] four - - Output:: - - <document source="<stdin>"> - <paragraph> - ref - <footnote_reference auto="1" ids="id1" refid="abc"> - 2 - - <footnote_reference auto="1" ids="id2" refid="id5"> - 3 - - <footnote_reference ids="id3" refid="id6"> - 1 - - <footnote_reference auto="1" ids="id4" refid="id7"> - 5 - <footnote auto="1" backrefs="id1" ids="abc" names="abc"> - <label> - 2 - <paragraph> - footnote - <footnote auto="1" backrefs="id2" ids="id5" names="3"> - <label> - 3 - <paragraph> - two - <footnote backrefs="id3" ids="id6" names="1"> - <label> - 1 - <paragraph> - one - <footnote auto="1" backrefs="id4" ids="id7" names="4"> - <label> - 5 - <paragraph> - four - -* IDs are based on names. Explicit hyperlink targets have priority - over implicit targets. But if an explicit target comes after an - implicit target with the same name, the ID of the first (implicit) - target remains based on the implicit name. Since HTML fragment - identifiers based on the IDs, the first target keeps the name. For - example:: - - .. contents:: - - Section - ======= - - .. _contents: - - Subsection - ---------- - - text with a reference to contents_ and section_ - - .. _section: - - This paragraph is explicitly targeted with the name "section". - - When processed to HTML, the 2 internal hyperlinks (to "contents" & - "section") will work fine, but hyperlinks from outside the document - using ``href="...#contents"`` and ``href="...#section"`` won't work. - Such external links will connect to the implicit targets (table of - contents and "Section" title) instead of the explicit targets - ("Subsection" title and last paragraph). - - Hyperlink targets with duplicate names should be assigned new IDs - unrelated to the target names (i.e., "id"-prefix serial IDs). - -* The "contents" ID of the local table of contents in - ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in - the HTML output at - ``test/functional/expected/standalone_rst_html4css1.html``. - -* _`Blank first columns` in simple tables with explicit row separators - silently swallow their input. They should at least produce system - error messages. But, with explicit row separators, the meaning is - unambiguous and ought to be supported:: - - ============== ========== - Table with row separators - ============== ========== - and blank - -------------- ---------- - entries - -------------- ---------- - in first - -------------- ---------- - columns. - ============== ========== - - Added a commented-out test case to - test/test_parsers/test_rst/test_SimpleTableParser.py. - -* _`Footnote references with hyperlink targets` cause a possibly - invalid node tree and make the HTML writer crash:: - - $ rst2pseudoxml.py - [1]_ - - .. _1: URI - <document source="<stdin>"> - <paragraph> - <footnote_reference ids="id1" refuri="URI"> - 1 - <target ids="id2" names="1" refuri="URI"> - -* Anonymous references have "name" attributes. Should they? Are they - used? See ``test/test_parsers/test_rst/test_inline_markup.py``. - -* <reference> elements have a "name" attribute, not "names". The - attribute should be "names"; this is an inconsistency. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/COPYING.txt b/docutils/COPYING.txt deleted file mode 100644 index 4994ef1fa..000000000 --- a/docutils/COPYING.txt +++ /dev/null @@ -1,129 +0,0 @@ -================== - Copying Docutils -================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Date: $Date$ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -Most of the files included in this project have been placed in the -public domain, and therefore have no license requirements and no -restrictions on copying or usage; see the `Public Domain Dedication`_ -below. There are a few exceptions_, listed below. - -One goal of the Docutils project is to be included in the Python -standard library distribution, at which time it is expected that -copyright will be asserted by the `Python Software Foundation -<http://www.python.org/psf/>`_. - - -Public Domain Dedication -======================== - -The persons who have associated their work with this project (the -"Dedicator": David Goodger and the many contributors to the Docutils -project) hereby dedicate the entire copyright, less the exceptions_ -listed below, in the work of authorship known as "Docutils" identified -below (the "Work") to the public domain. - -The primary repository for the Work is the Internet World Wide Web -site <http://docutils.sourceforge.net/>. The Work consists of the -files within the "docutils" module of the Docutils project Subversion -repository (Internet host svn.berlios.de, filesystem path -/svnroot/repos/docutils), whose Internet web interface is located at -<http://svn.berlios.de/viewcvs/docutils/>. Files dedicated to the -public domain may be identified by the inclusion, near the beginning -of each file, of a declaration of the form:: - - Copyright: This document/module/DTD/stylesheet/file/etc. has been - placed in the public domain. - -Dedicator makes this dedication for the benefit of the public at large -and to the detriment of Dedicator's heirs and successors. Dedicator -intends this dedication to be an overt act of relinquishment in -perpetuity of all present and future rights under copyright law, -whether vested or contingent, in the Work. Dedicator understands that -such relinquishment of all rights includes the relinquishment of all -rights to enforce (by lawsuit or otherwise) those copyrights in the -Work. - -Dedicator recognizes that, once placed in the public domain, the Work -may be freely reproduced, distributed, transmitted, used, modified, -built upon, or otherwise exploited by anyone for any purpose, -commercial or non-commercial, and in any way, including by methods -that have not yet been invented or conceived. - -(This dedication is derived from the text of the `Creative Commons -Public Domain Dedication -<http://creativecommons.org/licenses/publicdomain>`_.) - - -Exceptions -========== - -The exceptions to the `Public Domain Dedication`_ above are: - -* docutils/writers/s5_html/themes/default/iepngfix.htc: - - IE5.5+ PNG Alpha Fix v1.0 by Angus Turnbull - <http://www.twinhelix.com>. Free usage permitted as long as - this notice remains intact. - -* extras/optparse.py, copyright by Gregory P. Ward, released under a - BSD-style license (which can be found in the module's source code). - -* extras/textwrap.py, copyright by Gregory P. Ward and the Python - Software Foundation, released under the `Python 2.3 license`_ - (`local copy`__). - - __ licenses/python-2-3.txt - -* extras/roman.py, copyright by Mark Pilgrim, released under the - `Python 2.1.1 license`_ (`local copy`__). - - __ licenses/python-2-1-1.txt - -* test/docutils_difflib.py, copyright by the Python Software - Foundation, released under the `Python 2.2 license`_ (`local - copy`__). This file is included for compatibility with Python - versions less than 2.2. (It's only used to report test failures - anyhow; it isn't installed anywhere. The included file is a - pre-generator version of the difflib.py module included in Python - 2.2.) - - __ licenses/python-2-2.txt - -* tools/pep2html.py, copyright by the Python Software Foundation, - released under the `Python 2.2 license`_ (`local copy`__). - - __ licenses/python-2-2.txt - -* tools/editors/emacs/rst-html.el, copyright by Martin Blais, released - under the `GNU General Public License`_ (`local copy`__). - - __ licenses/gpl.txt - -* tools/editors/emacs/rst-mode.el, copyright by Stefan Merten, - released under the `GNU General Public License`_ (`local copy`__). - - __ licenses/gpl.txt - -(Disclaimer: I am not a lawyer.) The BSD license and the Python -licenses are OSI-approved_ and GPL-compatible_. Although complicated -by multiple owners and lots of legalese, the Python license basically -lets you copy, use, modify, and redistribute files as long as you keep -the copyright attribution intact, note any changes you make, and don't -use the owner's name in vain. The BSD license is similar. - -Plaintext versions of all the linked-to licenses are provided in the -licenses_ directory. - -.. _licenses: licenses/ -.. _Python 2.1.1 license: http://www.python.org/2.1.1/license.html -.. _Python 2.2 license: http://www.python.org/2.2/license.html -.. _Python 2.3 license: http://www.python.org/2.3/license.html -.. _GNU General Public License: http://www.gnu.org/copyleft/gpl.html -.. _OSI-approved: http://opensource.org/licenses/ -.. _GPL-compatible: http://www.gnu.org/philosophy/license-list.html diff --git a/docutils/FAQ.txt b/docutils/FAQ.txt deleted file mode 100644 index e8b7692e4..000000000 --- a/docutils/FAQ.txt +++ /dev/null @@ -1,1049 +0,0 @@ -.. -*- coding: utf-8 -*- - -=========================================== - Docutils FAQ (Frequently Asked Questions) -=========================================== - -:Date: $Date$ -:Revision: $Revision$ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. contents:: -.. sectnum:: - - -This is a work in progress. Please feel free to ask questions and/or -provide answers; send email to the `Docutils-users`_ mailing list. -Project members should feel free to edit the source text file -directly. - -.. _let us know: -.. _Docutils-users: docs/user/mailing-lists.html#docutils-users - - -Docutils -======== - -What is Docutils? ------------------ - -Docutils_ is a system for processing plaintext documentation into -useful formats, such as HTML, XML, and LaTeX. It supports multiple -types of input, such as standalone files (implemented), inline -documentation from Python modules and packages (under development), -`PEPs (Python Enhancement Proposals)`_ (implemented), and others as -discovered. - -For an overview of the Docutils project implementation, see `PEP -258`_, "Docutils Design Specification". - -Docutils is implemented in Python_. - -.. _Docutils: http://docutils.sourceforge.net/ -.. _PEPs (Python Enhancement Proposals): - http://www.python.org/peps/pep-0012.html -.. _PEP 258: http://www.python.org/peps/pep-0258.html -.. _Python: http://www.python.org/ - - -Why is it called "Docutils"? ----------------------------- - -Docutils is short for "Python Documentation Utilities". The name -"Docutils" was inspired by "Distutils", the Python Distribution -Utilities architected by Greg Ward, a component of Python's standard -library. - -The earliest known use of the term "docutils" in a Python context was -a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in -the Python Doc-SIG mailing list. It was suggested `as a project -name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to -a question from Tony "Tibs" Ibbs: "What do we want to *call* this -thing?". This was shortly after David Goodger first `announced -reStructuredText`__ on Doc-SIG. - -Tibs used the name "Docutils" for `his effort`__ "to document what the -Python docutils package should support, with a particular emphasis on -documentation strings". Tibs joined the current project (and its -predecessors) and graciously donated the name. - -For more history of reStructuredText and the Docutils project, see `An -Introduction to reStructuredText`_. - -Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils" -or any other variation. - -.. _An Introduction to reStructuredText: - http://docutils.sourceforge.net/docs/ref/rst/introduction.html -__ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html -__ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html - - -Is there a GUI authoring environment for Docutils? --------------------------------------------------- - -DocFactory_ is under development. It uses wxPython and looks very -promising. - -.. _DocFactory: - http://docutils.sf.net/sandbox/gschwant/docfactory/doc/ - - -What is the status of the Docutils project? -------------------------------------------- - -Although useful and relatively stable, Docutils is experimental code, -with APIs and architecture subject to change. - -Our highest priority is to fix bugs as they are reported. So the -latest code from the repository_ (or the snapshots_) is almost always -the most stable (bug-free) as well as the most featureful. - - -What is the Docutils project release policy? --------------------------------------------- - -It's "release early & often". We also have automatically-generated -snapshots_ which always contain the latest code from the repository_. -As the project matures, we may formalize on a -stable/development-branch scheme, but we're not using anything like -that yet. - -.. _repository: docs/dev/repository.html -.. _snapshots: http://docutils.sourceforge.net/#download - - -reStructuredText -================ - -What is reStructuredText? -------------------------- - -reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get -plaintext markup syntax and parser system. The reStructuredText -parser is a component of Docutils_. reStructuredText is a revision -and reinterpretation of the StructuredText_ and Setext_ lightweight -markup systems. - -If you are reading this on the web, you can see for yourself. `The -source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open -it in another window and compare them side by side. - -`A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user -reference are a good place to start. The `reStructuredText Markup -Specification`_ is a detailed technical specification. - -.. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/user/rst/quickstart.html -.. _Quick reStructuredText: - http://docutils.sourceforge.net/docs/user/rst/quickref.html -.. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/ -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html - - -Why is it called "reStructuredText"? ------------------------------------- - -The name came from a combination of "StructuredText", one of -reStructuredText's predecessors, with "re": "revised", "reworked", and -"reinterpreted", and as in the ``re.py`` regular expression module. -For a detailed history of reStructuredText and the Docutils project, -see `An Introduction to reStructuredText`_. - - -What's the standard abbreviation for "reStructuredText"? --------------------------------------------------------- - -"RST" and "ReST" (or "reST") are both acceptable. Care should be -taken with capitalization, to avoid confusion with "REST__", an -acronym for "Representational State Transfer". - -The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used; -they overemphasize reStructuredText's precedessor, Zope's -StructuredText. - -__ http://en.wikipedia.org/wiki/Representational_State_Transfer - - -What's the standard filename extension for a reStructuredText file? -------------------------------------------------------------------- - -It's ".txt". Some people would like to use ".rest" or ".rst" or -".restx", but why bother? ReStructuredText source files are meant to -be readable as plaintext, and most operating systems already associate -".txt" with text files. Using a specialized filename extension would -require that users alter their OS settings, which is something that -many users will not be willing or able to do. - - -Are there any reStructuredText editor extensions? -------------------------------------------------- - -See `Editor Support for reStructuredText`__. - -__ http://docutils.sf.net/tools/editors/README.html - - -How can I indicate the document title? Subtitle? -------------------------------------------------- - -A uniquely-adorned section title at the beginning of a document is -treated specially, as the document title. Similarly, a -uniquely-adorned section title immediately after the document title -becomes the document subtitle. For example:: - - This is the Document Title - ========================== - - This is the Document Subtitle - ----------------------------- - - Here's an ordinary paragraph. - -Counterexample:: - - Here's an ordinary paragraph. - - This is *not* a Document Title - ============================== - - The "ordinary paragraph" above the section title - prevents it from becoming the document title. - -Another counterexample:: - - This is not the Document Title, because... - =========================================== - - Here's an ordinary paragraph. - - ... the title adornment is not unique - ===================================== - - Another ordinary paragraph. - - -How can I represent esoteric characters (e.g. character entities) in a document? --------------------------------------------------------------------------------- - -For example, say you want an em-dash (XML character entity —, -Unicode character U+2014) in your document: use a real em-dash. -Insert concrete characters (e.g. type a *real* em-dash) into your -input file, using whatever encoding suits your application, and tell -Docutils the input encoding. Docutils uses Unicode internally, so the -em-dash character is a real em-dash internally. - -Emacs users should refer to the `Emacs Support for reStructuredText`__ -document. Tips for other editors are welcome. - -__ http://docutils.sourceforge.net/tools/editors/emacs/README.html - -ReStructuredText has no character entity subsystem; it doesn't know -anything about XML charents. To Docutils, "—" in input text is -7 discrete characters; no interpretation happens. When writing HTML, -the "&" is converted to "&", so in the raw output you'd see -"&mdash;". There's no difference in interpretation for text -inside or outside inline literals or literal blocks -- there's no -character entity interpretation in either case. - -If you can't use a Unicode-compatible encoding and must rely on 7-bit -ASCII, there is a workaround. New in Docutils 0.3.10 is a set of -`Standard Substitution Definition Sets`_, which provide equivalents of -XML & HTML character entity sets as substitution definitions. For -example, the Japanese yen currency symbol can be used as follows:: - - .. include:: <xhtml1-lat1.txt> - - |yen| 600 for a complete meal? That's cheap! - -For earlier versions of Docutils, equivalent files containing -character entity set substitution definitions using the "unicode_" -directive `are available`_. Please read the `description and -instructions`_ for use. Thanks to David Priest for the original idea. - -If you insist on using XML-style charents, you'll have to implement a -pre-processing system to convert to UTF-8 or something. That -introduces complications though; you can no longer *write* about -charents naturally; instead of writing "—" you'd have to write -"&mdash;". - -For the common case of long dashes, you might also want to insert the -following substitution definitons into your document (both of them are -using the "unicode_" directive):: - - .. |--| unicode:: U+2013 .. en dash - .. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace - :trim: - -.. |--| unicode:: U+2013 .. en dash -.. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace - :trim: - -Now you can write dashes using pure ASCII: "``foo |--| bar; foo |---| -bar``", rendered as "foo |--| bar; foo |---| bar". (Note that Mozilla -and Firefox may render this incorrectly.) The ``:trim:`` option for -the em dash is necessary because you cannot write "``foo|---|bar``"; -thus you need to add spaces ("``foo |---| bar``") and advise the -reStructuredText parser to trim the spaces. - -.. _Standard Substitution Definition Sets: - http://docutils.sf.net/docs/ref/rst/substitutions.html -.. _unicode: - http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes -.. _are available: http://docutils.sourceforge.net/tmp/charents/ -.. _tarball: http://docutils.sourceforge.net/tmp/charents.tgz -.. _description and instructions: - http://docutils.sourceforge.net/tmp/charents/README.html -.. _to-do list: http://docutils.sourceforge.net/docs/dev/todo.html - - -How can I generate backticks using a Scandinavian keyboard? ------------------------------------------------------------ - -The use of backticks in reStructuredText is a bit awkward with -Scandinavian keyboards, where the backtick is a "dead" key. To get -one ` character one must press SHIFT-` + SPACE. - -Unfortunately, with all the variations out there, there's no way to -please everyone. For Scandinavian programmers and technical writers, -this is not limited to reStructuredText but affects many languages and -environments. - -Possible solutions include - -* If you have to input a lot of backticks, simply type one in the - normal/awkward way, select it, copy and then paste the rest (CTRL-V - is a lot faster than SHIFT-` + SPACE). - -* Use keyboard macros. - -* Remap the keyboard. The Scandinavian keyboard layout is awkward for - other programming/technical characters too; for example, []{} - etc. are a bit awkward compared to US keyboards. - - According to Axel Kollmorgen, - - Under Windows, you can use the `Microsoft Keyboard Layout Creator - <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily - map the backtick key to a real backtick (no dead key). took me - five minutes to load my default (german) keyboard layout, untick - "Dead Key?" from the backtick key properties ("in all shift - states"), "build dll and setup package", install the generated - .msi, and add my custom keyboard layout via Control Panel > - Regional and Language Options > Languages > Details > Add - Keyboard layout (and setting it as default "when you start your - computer"). - -* Use a virtual/screen keyboard or character palette, such as: - - - `Web-based keyboards <http://keyboard.lab.co.il/>`__ (IE only - unfortunately). - - Windows: `Click-N-Type <http://www.lakefolks.org/cnt/>`__. - - Mac OS X: the Character Palette can store a set of favorite - characters for easy input. Open System Preferences, - International, Input Menu tab, enable "Show input menu in menu - bar", and be sure that Character Palette is enabled in the list. - -If anyone knows of other/better solutions, please `let us know`_. - - -Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping) ------------------------------------------------------------------------ - -People have tossed the idea around, and some implementations of -reStructuredText-generating tools can be found in the `Docutils Link -List`_. - -There's no reason why reStructuredText should not be round-trippable -to/from XML; any technicalities which prevent round-tripping would be -considered bugs. Whitespace would not be identical, but paragraphs -shouldn't suffer. The tricky parts would be the smaller details, like -links and IDs and other bookkeeping. - -For HTML, true round-tripping may not be possible. Even adding lots -of extra "class" attributes may not be enough. A "simple HTML" to RST -filter is possible -- for some definition of "simple HTML" -- but HTML -is used as dumb formatting so much that such a filter may not be -particularly useful. An 80/20 approach should work though: build a -tool that does 80% of the work automatically, leaving the other 20% -for manual tweaks. - -.. _Docutils Link List: docs/user/links.html - - -Are there any Wikis that use reStructuredText syntax? ------------------------------------------------------ - -There are several, with various degrees of completeness. With no -implied endorsement or recommendation, and in no particular order: - -* `Webware for Python wiki - <http://wiki.webwareforpython.org/thiswiki.html>`__ -* `Ian Bicking's experimental code - <http://docutils.sf.net/sandbox/ianb/wiki/Wiki.py>`__ -* `MoinMoin <http://moinmoin.wikiwikiweb.de/>`__ has some support; - `here's a sample <http://moinmoin.wikiwikiweb.de/RestSample>`__ -* Zope-based `Zwiki <http://zwiki.org/>`__ -* Zope3-based Zwiki (in the Zope 3 source tree as ``zope.products.zwiki``) -* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__ -* `Trac <http://projects.edgewall.com/trac/>`__ `supports using reStructuredText - <http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as an - alternative to wiki markup. This includes support for `TracLinks - <http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within RST - text via a custom RST reference-directive or, even easier, an interpreted text - role 'trac' -* `Vogontia <http://www.ososo.de/vogontia/>`__, a Wiki-like FAQ system - -Please `let us know`_ of any other reStructuredText Wikis. - -The example application for the `Web Framework Shootout -<http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using -reStructuredText. - - -Are there any Weblog (Blog) projects that use reStructuredText syntax? ----------------------------------------------------------------------- - -With no implied endorsement or recommendation, and in no particular -order: - -* `Firedrop <http://www.voidspace.org.uk/python/firedrop2/>`__ -* `Python Desktop Server <http://pyds.muensterland.org/>`__ -* `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom/>`__ -* `Lino WebMan <http://lino.sourceforge.net/webman.html>`__ - -Please `let us know`_ of any other reStructuredText Blogs. - - -Can lists be indented without generating block quotes? ------------------------------------------------------- - -Some people like to write lists with indentation, without intending a -block quote context, like this:: - - paragraph - - * list item 1 - * list item 2 - -There has been a lot of discussion about this, but there are some -issues that would need to be resolved before it could be implemented. -There is a summary of the issues and pointers to the discussions in -`the to-do list`__. - -__ http://docutils.sourceforge.net/docs/dev/todo.html#indented-lists - - -Could the requirement for blank lines around lists be relaxed? --------------------------------------------------------------- - -Short answer: no. - -In reStructuredText, it would be impossible to unambigously mark up -and parse lists without blank lines before and after. Deeply nested -lists may look ugly with so many blank lines, but it's a price we pay -for unambiguous markup. Some other plaintext markup systems do not -require blank lines in nested lists, but they have to compromise -somehow, either accepting ambiguity or requiring extra complexity. -For example, `Epytext <http://epydoc.sf.net/epytext.html#list>`__ does -not require blank lines around lists, but it does require that lists -be indented and that ambiguous cases be escaped. - - -How can I include mathematical equations in documents? ------------------------------------------------------- - -There is no elegant built-in way, yet. There are several ideas, but -no obvious winner. This issue requires a champion to solve the -technical and aesthetic issues and implement a generic solution. -Here's the `to-do list entry`__. - -__ http://docutils.sourceforge.net/docs/dev/todo.html#math-markup - -There are several quick & dirty ways to include equations in documents. -They all presently use LaTeX syntax or dialects of it. - -* For LaTeX output, nothing beats raw LaTeX math. A simple way is to - use the `raw directive`_:: - - .. raw:: latex - - \[ x^3 + 3x^2a + 3xa^2 + a^3, \] - - For inline math you could use substitutions of the raw directive but - the recently added `raw role`_ is more convenient. You must define a - custom role based on it once in your document:: - - .. role:: raw-latex(raw) - :format: latex - - and then you can just use the new role in your text:: - - the binomial expansion of :raw-latex:`$(x+a)^3$` is - - .. _raw directive: http://docutils.sourceforge.net/docs/ref/rst/ - directives.html#raw-data-pass-through - .. _raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw - -* Jens Jørgen Mortensen has implemented a "latex-math" role and - directive, available from `his sandbox`__. - - __ http://docutils.sourceforge.net/sandbox/jensj/latex_math/ - -* For HTML the "Right" w3c-standard way to include math is MathML_. - Unfortunately its rendering is still quite broken (or absent) on many - browsers but it's getting better. Another bad problem is that typing - or reading raw MathML by humans is *really* painful, so embedding it - in a reST document with the raw directive would defy the goals of - readability and editability of reST (see an `example of raw MathML - <http://sf.net/mailarchive/message.php?msg_id=2177102>`__). - - A much less painful way to generate HTML+MathML is to use itex2mml_ to - convert a dialect of LaTeX syntax to presentation MathML. Here is an - example of potential `itex math markup - <http://article.gmane.org/gmane.text.docutils.user/118>`__. The - simplest way to use it is to add ``html`` to the format lists for the - raw directive/role and postprocess the resulting document with - itex2mml. This way you can *generate LaTeX and HTML+MathML from the - same source*, but you must limit yourself to the intersection of LaTeX - and itex markups for this to work. Alan G. Isaac wrote a detailed - HOWTO_ for this approach. - - .. _MathML: http://www.w3.org/Math/ - .. _itex2mml: http://pear.math.pitt.edu/mathzilla/itex2mml.html - .. _HOWTO: http://www.american.edu/econ/itex2mml/mathhack.rst - -* The other way to add math to HTML is to use images of the equations, - typically generated by TeX. This is inferior to MathML in the long - term but is perhaps more accessible nowdays. - - Of course, doing it by hand is too much work. Beni Cherniavsky has - written some `preprocessing scripts`__ for converting the - ``texmath`` role/directive into images for HTML output and raw - directives/subsitution for LaTeX output. This way you can *generate - LaTeX and HTML+images from the same source*. `Instructions here`__. - - __ http://docutils.sourceforge.net/sandbox/cben/rolehack/ - __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html - - -Is nested inline markup possible? ---------------------------------- - -Not currently, no. It's on the `to-do list`__ (`details here`__), and -hopefully will be part of the reStructuredText parser soon. At that -time, markup like this will become possible:: - - Here is some *emphasized text containing a `hyperlink`_ and - ``inline literals``*. - -__ http://docutils.sf.net/docs/dev/todo.html#nested-inline-markup -__ http://docutils.sf.net/docs/dev/rst/alternatives.html#nested-inline-markup - -There are workarounds, but they are either convoluted or ugly or both. -They are not recommended. - -* Inline markup can be combined with hyperlinks using `substitution - definitions`__ and references__ with the `"replace" directive`__. - For example:: - - Here is an |emphasized hyperlink|_. - - .. |emphasized hyperlink| replace:: *emphasized hyperlink* - .. _emphasized hyperlink: http://example.org - - It is not possible for just a portion of the replacement text to be - a hyperlink; it's the entire replacement text or nothing. - - __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-definitions - __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-references - __ http://docutils.sf.net/docs/ref/rst/directives.html#replace - -* The `"raw" directive`__ can be used to insert raw HTML into HTML - output:: - - Here is some |stuff|. - - .. |stuff| raw:: html - - <em>emphasized text containing a - <a href="http://example.org">hyperlink</a> and - <tt>inline literals</tt></em> - - Raw LaTeX is supported for LaTeX output, etc. - - __ http://docutils.sf.net/docs/ref/rst/directives.html#raw - - -How to indicate a line break or a significant newline? ------------------------------------------------------- - -`Line blocks`__ are designed for address blocks, verse, and other -cases where line breaks are significant and must be preserved. Unlike -literal blocks, the typeface is not changed, and inline markup is -recognized. For example:: - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -__ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#line-blocks - -Here's a workaround for manually inserting explicit line breaks in -HTML output:: - - .. |br| raw:: html - - <br /> - - I want to break this line here: |br| this is after the break. - - If the extra whitespace bothers you, |br|\ backslash-escape it. - - -A URL containing asterisks doesn't work. What to do? ------------------------------------------------------ - -Asterisks are valid URL characters (see :RFC:`2396`), sometimes used -in URLs. For example:: - - http://cvs.example.org/viewcvs.py/*checkout*/module/file - -Unfortunately, the parser thinks the asterisks are indicating -emphasis. The slashes serve as delineating punctuation, allowing the -asterisks to be recognized as markup. The example above is separated -by the parser into a truncated URL, an emphasized word, and some -regular text:: - - http://cvs.example.org/viewcvs.py/ - *checkout* - /module/file - -To turn off markup recognition, use a backslash to escape at least the -first asterisk, like this:: - - http://cvs.example.org/viewcvs.py/\*checkout*/module/file - -Escaping the second asterisk doesn't hurt, but it isn't necessary. - - -How can I make a literal block with *some* formatting? ------------------------------------------------------- - -Use the `parsed-literal`_ directive. - -.. _parsed-literal: docs/ref/rst/directives.html#parsed-literal - -Scenario: a document contains some source code, which calls for a -literal block to preserve linebreaks and whitespace. But part of the -source code should be formatted, for example as emphasis or as a -hyperlink. This calls for a *parsed* literal block:: - - .. parsed-literal:: - - print "Hello world!" # *tricky* code [1]_ - -The emphasis (``*tricky*``) and footnote reference (``[1]_``) will be -parsed. - - -Can reStructuredText be used for web or generic templating? ------------------------------------------------------------ - -Docutils and reStructuredText can be used with or as a component of a -templating system, but they do not themselves include templating -functionality. Templating should simply be left to dedicated -templating systems. Users can choose a templating system to apply to -their reStructuredText documents as best serves their interests. - -There are many good templating systems for Python (ht2html_, YAPTU_, -Quixote_'s PTL, Cheetah_, etc.; see this non-exhaustive list of `some -other templating systems`_), and many more for other languages, each -with different approaches. We invite you to try several and find one -you like. If you adapt it to use Docutils/reStructuredText, please -consider contributing the code to Docutils or `let us know`_ and we'll -keep a list here. - -One reST-specific web templating system is `rest2web -<http://www.voidspace.org.uk/python/rest2web>`_, a tool for -automatically building websites, or parts of websites. - -.. _ht2html: http://ht2html.sourceforge.net/ -.. _YAPTU: - http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305 -.. _Quixote: http://www.mems-exchange.org/software/quixote/ -.. _Cheetah: http://www.cheetahtemplate.org/ -.. _some other templating systems: - http://webware.sourceforge.net/Papers/Templates/ - - -How can I mark up a FAQ or other list of questions & answers? -------------------------------------------------------------- - -There is no specific syntax for FAQs and Q&A lists. Here are two -options: - -1. For a FAQ (Frequently Asked Questions, usually with answers), a - convenient way to mark up the questions is as section titles, with - the answer(s) as section content. This document is marked up in - this way. - - The advantages of using section titles for questions are: sections - can be numbered automatically, and a table of contents can be - generated automatically. One limitation of this format is that - questions must fit on one line (section titles may not wrap, in the - source text). For very long questions, the title may be a summary - of the question, with the full question in the section body. - -2. Field lists work well as Q&A lists:: - - :Q: What kind of questions can we - put here? - - :A: Any kind we like! - - In order to separate questions, lists can be used: - - 1. :Q: What kind of question can we - put here? - :A: Any kind we like! - - 2. :Q: How many answers can a question have? - :A: It can have one, - :A: or more. - :A3: Answers can be numbered like this. - :A: 1. Or like this. - 2. We're flexible! - - If you don't want to number or otherwise mark questions, you can - use an empty comment between individual field lists to separate - them:: - - :Q: First question? - :A: Answer. - - .. - - :Q: Second question? - :A: Answer. - - -HTML Writer -=========== - -What is the status of the HTML Writer? --------------------------------------- - -The HTML Writer module, ``docutils/writers/html4css1.py``, is a -proof-of-concept reference implementation. While it is a complete -implementation, some aspects of the HTML it produces may be -incompatible with older browsers or specialized applications (such as -web templating). Alternate implementations are welcome. - - -What kind of HTML does it produce? ----------------------------------- - -It produces XHTML compatible with the `XHTML 1.0`_ specification. A -cascading stylesheet is required for proper viewing with a modern -graphical browser. Correct rendering of the HTML produced depends on -the CSS support of the browser. A general-purpose stylesheet, -``html4css1.css`` is provided with the code, and is embedded by -default. It is installed in the "writers/html4css1/" subdirectory -within the Docutils package. Use the ``--help`` command-line option -to see the specific location on your machine. - -.. _XHTML 1.0: http://www.w3.org/TR/xhtml1/ - - -What browsers are supported? ----------------------------- - -No specific browser is targeted; all modern graphical browsers should -work. Some older browsers, text-only browsers, and browsers without -full CSS support are known to produce inferior results. Firefox, -Safari, Mozilla (version 1.0 and up), and MS Internet Explorer -(version 5.0 and up) are known to give good results. Reports of -experiences with other browsers are welcome. - - -Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why? --------------------------------------------------------------------------- - -Here's the question in full: - - I have this text:: - - Heading 1 - ========= - - All my life, I wanted to be H1. - - Heading 1.1 - ----------- - - But along came H1, and so shouldn't I be H2? - No! I'm H1! - - Heading 1.1.1 - ************* - - Yeah, imagine me, I'm stuck at H3! No?!? - - When I run it through tools/rst2html.py, I get unexpected results - (below). I was expecting H1, H2, then H3; instead, I get H1, H1, - H2:: - - ... - <html lang="en"> - <head> - ... - <title>Heading 1</title> - </head> - <body> - <div class="document" id="heading-1"> - <h1 class="title">Heading 1</h1> <-- first H1 - <p>All my life, I wanted to be H1.</p> - <div class="section" id="heading-1-1"> - <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1 - <p>But along came H1, and so now I must be H2.</p> - <div class="section" id="heading-1-1-1"> - <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2> - <p>Yeah, imagine me, I'm stuck at H3!</p> - ... - - What gives? - -Check the "class" attribute on the H1 tags, and you will see a -difference. The first H1 is actually ``<h1 class="title">``; this is -the document title, and the default stylesheet renders it centered. -There can also be an ``<h2 class="subtitle">`` for the document -subtitle. - -If there's only one highest-level section title at the beginning of a -document, it is treated specially, as the document title. (Similarly, a -lone second-highest-level section title may become the document -subtitle.) See `How can I indicate the document title? Subtitle?`_ for -details. Rather than use a plain H1 for the document title, we use ``<h1 -class="title">`` so that we can use H1 again within the document. Why -do we do this? HTML only has H1-H6, so by making H1 do double duty, we -effectively reserve these tags to provide 6 levels of heading beyond the -single document title. - -HTML is being used for dumb formatting for nothing but final display. -A stylesheet *is required*, and one is provided; see `What kind of -HTML does it produce?`_ above. Of course, you're welcome to roll your -own. The default stylesheet provides rules to format ``<h1 -class="title">`` and ``<h2 class="subtitle">`` differently from -ordinary ``<h1>`` and ``<h2>``:: - - h1.title { - text-align: center } - - h2.subtitle { - text-align: center } - -If you don't want the top section heading to be interpreted as a -title at all, disable the `doctitle_xform`_ setting -(``--no-doc-title`` option). This will interpret your document -differently from the standard settings, which might not be a good -idea. If you don't like the reuse of the H1 in the HTML output, you -can tweak the `initial_header_level`_ setting -(``--initial-header-level`` option) -- but unless you match its value -to your specific document, you might end up with bad HTML (e.g. H3 -without H2). - -.. _doctitle_xform: - http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform -.. _initial_header_level: - http://docutils.sourceforge.net/docs/user/config.html#initial-header-level - -(Thanks to Mark McEahern for the question and much of the answer.) - - -Why do enumerated lists only use numbers (no letters or roman numerals)? ------------------------------------------------------------------------- - -The rendering of enumerators (the numbers or letters acting as list -markers) is completely governed by the stylesheet, so either the -browser can't find the stylesheet (try using the "--embed-stylesheet" -option), or the browser can't understand it (try a recent Firefox, -Mozilla, Konqueror, Opera, Safari, or even MSIE). - - -There appear to be garbage characters in the HTML. What's up? --------------------------------------------------------------- - -What you're seeing is most probably not garbage, but the result of a -mismatch between the actual encoding of the HTML output and the -encoding your browser is expecting. Your browser is misinterpreting -the HTML data, which is encoded text. A discussion of text encodings -is beyond the scope of this FAQ; see one or more of these documents -for more info: - -* `UTF-8 and Unicode FAQ for Unix/Linux - <http://www.cl.cam.ac.uk/~mgk25/unicode.html>`_ - -* Chapters 3 and 4 of `Introduction to i18n [Internationalization] - <http://www.debian.org/doc/manuals/intro-i18n/>`_ - -* `Python Unicode Tutorial - <http://www.reportlab.com/i18n/python_unicode_tutorial.html>`_ - -* `Python Unicode Objects: Some Observations on Working With Non-ASCII - Character Sets <http://effbot.org/zone/unicode-objects.htm>`_ - -The common case is with the default output encoding (UTF-8), when -either numbered sections are used (via the "sectnum_" directive) or -symbol-footnotes. 3 non-breaking spaces are inserted in each numbered -section title, between the generated number and the title text. Most -footnote symbols are not available in ASCII, nor are non-breaking -spaces. When encoded with UTF-8 and viewed with ordinary ASCII tools, -these characters will appear to be multi-character garbage. - -You may have an decoding problem in your browser (or editor, etc.). -The encoding of the output is set to "utf-8", but your browswer isn't -recognizing that. You can either try to fix your browser (enable -"UTF-8 character set", sometimes called "Unicode"), or choose a -different encoding for the HTML output. You can also try -``--output-encoding=ascii:xmlcharrefreplace`` for HTML (not applicable -to non-XMLish outputs). - -If you're generating document fragments, the "Content-Type" metadata -(between the HTML ``<head>`` and ``</head>`` tags) must agree with the -encoding of the rest of the document. For UTF-8, it should be:: - - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - -Also, Docutils normally generates an XML declaration as the first line -of the output. It must also match the document encoding. For UTF-8:: - - <?xml version="1.0" encoding="utf-8" ?> - -.. _sectnum: - http://docutils.sourceforge.net/docs/ref/rst/directives.html#sectnum - - -How can I retrieve the body of the HTML document? -------------------------------------------------- - -(This is usually needed when using Docutils in conjunction with a -templating system.) - -You can use the `docutils.core.publish_parts()`_ function, which -returns a dictionary containing an 'html_body_' entry. - -.. _docutils.core.publish_parts(): - docs/api/publisher.html#publish-parts -.. _html_body: - docs/api/publisher.html#html-body - - -Why is the Docutils XHTML served as "Content-type: text/html"? --------------------------------------------------------------- - -Full question: - - Docutils' HTML output looks like XHTML and is advertised as such:: - - <?xml version="1.0" encoding="utf-8" ?> - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xht ml1/DTD/xhtml1-transitional.dtd"> - - But this is followed by:: - - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - - Shouldn't this be "application/xhtml+xml" instead of "text/html"? - -In a perfect web, the Docutils XHTML output would be 100% strict -XHTML. But it's not a perfect web, and a major source of imperfection -is Internet Explorer. Despite it's drawbacks, IE still represents the -majority of web browsers, and cannot be ignored. - -Short answer: if we didn't serve XHTML as "text/html" (which is a -perfectly valid thing to do), it couldn't be viewed in Internet -Explorer. - -Long answer: see the `"Criticisms of Internet Explorer" Wikipedia -entry <http://en.wikipedia.org/wiki/Criticisms_of_Internet_Explorer#XHTML>`__. - -However, there's also `Sending XHTML as text/html Considered -Harmful`__. What to do, what to do? We're damned no matter what we -do. So we'll continue to do the practical instead of the pure: -support the browsers that are actually out there, and not fight for -strict standards compliance. - -__ http://hixie.ch/advocacy/xhtml - -(Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan -G. Isaac.) - - -Python Source Reader -==================== - -Can I use Docutils for Python auto-documentation? -------------------------------------------------- - -Yes, in conjunction with other projects. - -Docstring extraction functionality from within Docutils is still under -development. There is most of a source code parsing module in -docutils/readers/python/moduleparser.py. We do plan to finish it -eventually. Ian Bicking wrote an initial front end for the -moduleparser.py module, in sandbox/ianb/extractor/extractor.py. Ian -also did some work on the Python Source Reader -(docutils.readers.python) component at PyCon DC 2004. - -Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_ -supports reStructuredText-format docstrings for HTML output. Docutils -0.3 or newer is required. Development of a Docutils-specific -auto-documentation tool will continue. Epydoc works by importing -Python modules to be documented, whereas the Docutils-specific tool, -described above, will parse modules without importing them (as with -`HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support -reStructuredText). - -The advantages of parsing over importing are security and flexibility; -the disadvantage is complexity/difficulty. - -* Security: untrusted code that shouldn't be executed can be parsed; - importing a module executes its top-level code. -* Flexibility: comments and unofficial docstrings (those not supported - by Python syntax) can only be processed by parsing. -* Complexity/difficulty: it's a lot harder to parse and analyze a - module than it is to ``import`` and analyze one. - -For more details, please see "Docstring Extraction Rules" in `PEP -258`_, item 3 ("How"). - - -Miscellaneous -============= - -Is the Docutils document model based on any existing XML models? ----------------------------------------------------------------- - -Not directly, no. It borrows bits from DocBook, HTML, and others. I -(David Goodger) have designed several document models over the years, -and have my own biases. The Docutils document model is designed for -simplicity and extensibility, and has been influenced by the needs of -the reStructuredText markup. diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt deleted file mode 100644 index bd5caa54f..000000000 --- a/docutils/HISTORY.txt +++ /dev/null @@ -1,2183 +0,0 @@ -================== - Docutils History -================== - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Release 0.4 (2006-01-09) -======================== - -* General: - - - Updated the project policies for trunk/branch development & - version numbering. - -* docutils/__init__.py: - - - Added ``__version_details__`` attribute to describe code source - (repository/snapshot/release). - - Replaced ``default_transforms`` attribute of TransformSpec with - ``get_transforms()`` method. - -* docutils/core.py: - - - Added ``publish_doctree`` and ``publish_from_doctree`` convenience - functions, for document tree extraction and reprocessing. - -* docutils/io.py: - - - Added ``DocTreeInput`` class, for reprocessing existing documents. - - Added support for non-Unicode (e.g. binary) writer output. - -* docutils/nodes.py: - - - Re-introduced ``Targetable.indirect_reference_name``, for - MoinMoin/reST compatibility (removed in r3124/r3129). - - Added ``serial_escape`` function; escapes string values that are - elements of a list, for serialization. Modified Docutils-XML - writing (``Element._dom_node``) and pseudo-XML writing - (``Element.starttag``) to use ``serial_escape``. - - Added ``Node.deepcopy()`` method. - - Removed the internal lists ``document.substitution_refs``, - ``document.anonymous_refs``, and ``document.anonymous_targets``. - - Added a "container" element. - - Fixed bug where values of list-valued attributes of elements - originating from custom interpreted text roles (i.e., with custom - classes) were being shared between element instances. Reported by - Shmuel Zeigerman. - -* docutils/statemachine.py: - - - Added trailing whitespace stripping to ``string2lines()``. - - Added ``StringList.pad_double_width()`` & ``.replace()`` for East - Asian double-width character support. - -* docutils/utils.py: - - - Added ``east_asian_column_width()`` for double-width character - support. - -* docutils/languages/ja.py: Added to project: Japanese mappings by - Hisashi Morita. - -* docutils/languages/zh_cn.py: Added to project: Simplified Chinese - mappings by Panjunyong. - -* docutils/parsers/null.py: Added to project; a do-nothing parser. - -* docutils/parsers/rst/__init__.py: - - - Added validator to tab_width setting, with test. Closes SF bug - #1212515, report from Wu Wei. - -* docutils/parsers/rst/states.py: - - - Fixed bug with escaped colons indicating a literal block. - - Fixed bug with enumerated lists (SF#1254145). - - Backslash-escaped colons inside of field names are now allowed. - - Targets (implicit and explicit), anonymous hyperlink references - and auto-numbered footnote references inside of substitution - definitions are now disallowed. - - Fixed bug: list items with blank first lines. - - Fixed bug: block quote attributions with indented second lines. - - Added East Asian double-width character support (Python 2.4 only). - -* docutils/parsers/rst/tableparser.py: - - - Added East Asian double-width character support (Python 2.4 only). - -* docutils/parsers/rst/directives/body.py: - - - Added the "container" directive. - -* docutils/parsers/rst/directives/misc.py: - - - Added the "default-role", "title", and "date" directives. - - Added standard data file syntax to the "include" directive. - - Added support for "class" directive content. - -* docutils/parsers/rst/directives/images.py: - - - Added ``indirect_reference_name`` support for images with a target - option. - - Added support for image width and height units. - - Fixed bug with image "target" options. - -* docutils/parsers/rst/directives/references.py: - - - Added "class" attribute to "target-notes" directive, for - footnote_reference classes. - -* docutils/parsers/rst/include/: Directory added to project; contains - standard data files for the "include" directive. Initial contents: - character entity substitution definition sets, and a set of - definitions for S5/HTML presentations. - -* docutils/parsers/rst/languages/ja.py: Added to project: Japanese - mappings by David Goodger. - -* docutils/parsers/rst/languages/zh_cn.py: Added to project: - Simplified Chinese mappings by Panjunyong. - -* docutils/readers/__init__.py: - - - Added universal.Decorations and universal.ExposeInternals - transforms as default transforms for all readers. - - Added ``ReReader`` base class for readers that reread an existing - document tree. - -* docutils/readers/doctree.py: Added to project; a reader for existing - document trees. - -* docutils/transforms/frontmatter.py: - - - Fixed the DocInfo transform to handle SVN-style expansion of the - "Date" keyword. - - In ``DocInfo.extract_authors``, treat the contents of "authors" - fields uniformly. - -* docutils/transforms/misc.py: - - - Added misc.Transitions transform, extracted from - universal.FinalChecks. - -* docutils/transforms/references.py: - - - Added references.DanglingReferences transform, extracted from - universal.FinalChecks. - - Fixed bug with doubly-indirect substitutions. - - Added footnote_reference classes attribute to "TargetNotes". - - Fixed bug with circular substitution definitions that put Docutils - into an infinite loop. - -* docutils/transforms/universal.py: - - - Added universal.ExposeInternals transform, extracted from - universal.FinalChecks. - - Removed universal.FinalChecks transform (logic has been moved to - several new transforms). - - Fixed bug with the "expose_internals" setting and Text nodes - (exposed by the "rawsource" internal attribute). - - Added the universal.StripComments transform, implementation of the - "strip_comments" setting. - -* docutils/transforms/writer_aux.py: Added to project; auxiliary - transforms for writers. - - - Added ``Compound`` transform, which flattens compound paragraphs. - -* docutils/writers/: Several writer modules (html4css1.py) were - converted into packages. Support modules and data files have been - moved into the packages. The stylesheets for the HTML writers are - now installed along with the code, the code knows where to find - them, and the default is to use them (actually, to embed them). - Some adjustments to configuration files may be necessary. The - easiest way to obtain the new default behavior is to remove all - settings whose name includes "stylesheet". - -* docutils/writers/__init__.py: - - - Added universal.Messages and universal.FilterMessages transforms - as default transforms for all writers. - - Added ``UnfilteredWriter`` base class for writers that pass the - document tree on unchanged. - -* docutils/writers/docutils_xml.py: - - - Made ``xmlcharrefreplace`` the default output encoding error - handler. - -* docutils/writers/html4css1/: - - - Added support for image width and height units. - - Made ``xmlcharrefreplace`` the default output encoding error - handler. - - Made ``--embed-stylesheet`` the default rather than - ``--link-stylesheet``. - - Moved "id" attribute from container (section etc.) to title's <a> - tag, to be on the same tag as "name". - (!!! To be reverted in Docutils 0.5.) - - Added vertical space between fields of field lists. - - Added ``--compact-field-lists`` option to remove vertical space in - simple field lists. - - Made cloaking of email addresses with ``--cloak-email-addresses`` - less obtrusive. - - Fixed support for centered images. - - Added support for class="compact" & class="open" lists. - -* docutils/writers/latex2e/: - - - Underscores in citekeys are no longer escaped. - -* docutils/writers/newlatex2e/unicode_map.py: Added to project; - mapping of Unicode characters to LaTeX equivalents. - -* docutils/writers/s5_html/: Package added to project; writer for - S5/HTML slide shows. - -* docs/dev/distributing.txt: Added to project; guide for distributors - (package maintainers). - -* docs/dev/hacking.txt: Added to project; guide for developers. - -* docs/ref/doctree.txt: - - - Updated for plural attributes "classes", "ids", "names", - "dupnames". - - Added the "container" element. - -* docs/ref/docutils.dtd: - - - Updated for plural attributes "classes", "ids", "names", - "dupnames". - -* docs/user/emacs.txt: Added to project; a document about Emacs - support for reStructuredText and Docutils. - -* docs/user/links.txt: Added to project; lists of Docutils-related - links. - -* docs/user/mailing-lists.txt: Added to project; information about - Docutils-related mailing lists and how to access them. - -* docs/user/slide-shows.txt: Added to project; example of and docs for - the S5/HTML writer (``rst2s5.py`` front end). - -* docs/ref/rst/definitions.txt: "reStructuredText Standard Definition - Files", added to project. - -* test/coverage.sh: Added to project; test coverage script. - -* test/DocutilsTestSupport.py: - - - Added support for specifying runtime settings at the suite level. - -* test/test_functional.py: - - - Added the ``clear_output_directory`` function. - - Added support for ``_test_more`` functions in functional test - config files. - -* tools/rst2s5.py: Added to project; front end for the S5/HTML writer. - -* tools/rstpep2html.py: Renamed from pep.py. - -* tools/dev/create_unimap.py: Added to project; script to create the - docutils/writers/unimap_latex.py mapping file. - -* tools/dev/profile_docutils.py: Added to project; profiler script. - -* tools/dev/unicode2rstsubs.py: Moved from tools/unicode2rstsubs.py. - -* tools/editors/emacs/restructuredtext.el, - tools/editors/emacs/rst-html.el, tools/editors/emacs/rst-mode.el: - Removed from project; the functionality is now contained in rst.el. - -* tools/editors/emacs/rst.el: Added to project. Added many features - and fixed many bugs. See docs/user/emacs.txt for details. - -* tools/stylesheets: Removed from project. Stylesheets have been - renamed and moved into writer packages. - - -Release 0.3.9 (2005-05-26) -========================== - -* General: - - - Eliminated and replaced all uses of the old string attributes - ``id``, ``name``, ``dupname`` and ``class`` with references to the - new list attributes ``ids``, ``names``, ``dupnames`` and - ``classes`` throughout the whole source tree. - -* docutils/core.py: - - - Enabled ``--dump-*`` options when ``--traceback`` specified, - allowing for easier debugging. - - In ``Publisher.publish()``, expanded the generic top-level - exception catching. - -* docutils/examples.py: - - - Added ``internals`` function for exploration. - -* docutils/io.py: - - - Fixed ``Input.decode`` method to apply heuristics only if no - encoding is explicitly given, and to provide better reporting of - decoding errors. - - The ``Input.decode`` method now removes byte order marks (BOMs) - from input streams. - -* docutils/nodes.py: - - - ``image`` element class changed to subclass of Element, not - TextElement (it's an empty element, and cannot contain text). - - Added ``attr_defaults`` dictionary for default attribute values. - - Added empty list as default value for the following attributes: - ``ids``, ``names``, ``dupnames``, ``classes``, and ``backrefs``. - - Added ``document.decoration`` attribute, - ``document.get_decoration`` method, and ``decoration.get_header`` - & ``.get_footer`` methods. - - Added ``Element.update_basic_atts()`` and ``Element.substitute()`` - methods. - -* docutils/utils.py: - - - Removed ``docutils.utils.Reporter.categories``, - ``docutils.utils.ConditionSet``, and all references to them, to - simplify error reporting. - -* docutils/languages/nl.py: Added to project; Dutch mappings by - Martijn Pieters. - -* docutils/parsers/rst/__init__.py: - - - Added settings: ``file_insertion_enabled`` & ``raw_enabled``. - -* docutils/parsers/rst/states.py: - - - Added check for escaped at-mark to prevent email address recognition. - - Fixed option lists to allow spaces inside ``<angle-bracketed option - arguments>``. - - Allowed whitespace in paths and URLs. - - Added auto-enumerated list items. - - Fixed bug that assumed ``.. _`` and ``.. |`` were invariably - followed by text. - - Added support for table stub columns. - -* docutils/parsers/rst/directives/__init__.py: - - - Allowed whitespace in paths (``path`` function). - - Added ``uri`` directive option conversion function. - -* docutils/parsers/rst/directives/body.py: - - - Fixed illegal context bug with "topic" directive (allowed within - sidebars; not within body elements). - -* docutils/parsers/rst/directives/images.py: - - - Allowed whitespace (stripped) in "image" & "figure" directive URLs. - - Added support for the ``file_insertion_enabled`` setting in the - "figure" directive (disables "figwidth" option). - - "image" directive: added checks for valid values of "align" option, - depending on context. "figure" directive: added specialized - "align" option and attribute on "figure" element. - - Made ":figwidth: image" option of "figure" directive work again. - - Fixed bug with reference names containing uppercase letters - (e.g. ``Name_``) in "target" option of "image" directive. - -* docutils/parsers/rst/directives/misc.py: - - - Fixed "include" and "raw" directives to catch text decoding - errors. - - Allowed whitespace in "include" & "raw" directive paths. - - Added support for ``file_insertion_enabled`` & ``raw_enabled`` - settings in "include" & "raw" directives. - -* docutils/parsers/rst/directives/parts.py: - - - Added "header" & "footer" directives. - - Fixed illegal context bug with "contents" directive (topics - allowed within sidebars; not within body elements). - -* docutils/parsers/rst/directives/tables.py: - - - Added "list-table" directive. - - Caught empty CSV table bug. - - Added support for the ``file_insertion_enabled`` setting in the - "csv-table" directive. - - Added ``stub-columns`` option to "csv-table" and "list-table" - directives. - -* docutils/parsers/rst/languages/nl.py: Added to project; Dutch - mappings by Martijn Pieters. - -* docutils/readers/standalone.py: - - - Added ``--section-subtitles`` and ``--no-section-subtitles`` - options to activate or deactivate the SectSubTitle transform. - -* docutils/transforms/frontmatter.py: - - - Added SectSubTitle transform to promote titles of lone - subsections to subtitles. - -* docutils/transforms/references.py: - - - Fixed mislocated internal targets bug, by propagating internal - targets to the next node, making use of the newly added support - for multiple names and IDs. - - Fixed duplicate footnote label bug. - - Replaced ``ChainedTargets`` with more generic ``PropagateTargets`` - transform. - -* docutils/writers/html4css1.py: - - - Fixed unencoded stylesheet reference bug (characters like "&" in - stylesheet references). - - ``target`` nodes now appear as ``span`` tags (instead of ``a`` - tags). - - Added support for multiple IDs per node by creating empty ``span`` - tags. - - Added the ``field_name_limit`` & ``option_limit`` settings & - support. - - Added support for table stub columns. - - Added support for the ``align`` attribute on ``figure`` elements. - - Added the ``cloak_email_addresses`` setting & support. - - Added ``html_prolog``, ``html_head``, ``html_body``, - ``html_title``, & ``html_subtitle`` to parts dictionary exposed by - ``docutils.core.publish_parts``. - - Added support for section subtitles. - -* docutils/writers/latex2e.py: - - - Fixed tables starting with more than one multirow cell. - - Improved --use-latex-docinfo so that organization/contact/address - fields are lumped with the last author field and appear on the - titlepage. - - Made sure the titlepage is always shown with --use-latex-docinfo, - even if the document has no title. - - Made sure that latex doesn't fill in today's date if no date field - was given. - - Added support for section subtitles. - -* docutils/writers/newlatex2e.py: Added to project; a new LaTeX writer - (under development). - -* docutils/writers/null.py: Added to project; a do-nothing Writer. - -* docs/api/publisher.txt: - - - Added "``publish_parts`` Details" section. - -* docutils/dev/repository.txt: Added to project; information about the - Docutils Subversion repository. - -* docs/ref/docutils.dtd: - - - Added a ``stub`` attribute to the ``colspec`` element via the - ``tbl.colspec.att`` parameter entity. - - Allowed topic elements within sidebars - - Added an ``align`` attribute to the ``figure`` element. - -* tools/rst2newlatex.py: Added to project; front end for the new LaTeX - writer. - - -Release 0.3.7 (2004-12-24) -========================== - -* docutils/frontend.py: - - - Added options: --input-encoding-error-handler, - --record-dependencies, --leave-footnote-reference-space, - --strict-visitor. - - Added command-line and config file support for "overrides" setting - parameter. - -* docutils/io.py: - - - Added support for input encoding error handler. - -* docutils/nodes.py: - - - Added dispatch_visit and dispatch_departure methods to - NodeVisitor; useful as a hook for Visitors. - - Changed structure of ``line_block``; added ``line``. - - Added ``compound`` node class. - - Added a mechanism for Visitors to transitionally ignore new node - classes. - -* docutils/utils.py: - - - Moved ``escape2null`` and ``unescape`` functions from - docutils/parsers/rst/states.py. - -* docutils/parsers/rst/roles.py: - - - Added "raw" role. - - Changed role function API: the "text" parameter now takes - null-escaped interpreted text content. - -* docutils/parsers/rst/states.py: - - - Fixed bug where a "role" directive in a nested parse would crash - the parser; the state machine's "language" attribute was not being - copied over. - - Added support for line block syntax. - - Fixed directive parsing bug: argument-less directives didn't - notice that arguments were present. - - Removed error checking for transitions. - - Added support for multiple classifiers in definition list items. - - Moved ``escape2null`` and ``unescape`` functions to docutils/utils.py. - - Changed role function API: the "text" parameter now takes - null-escaped interpreted text content. - - Empty sections and documents are allowed now. - -* docutils/parsers/rst/directives/__init__.py: - - - Added ``encoding`` directive option conversion function. - - Allow multiple class names in class_option conversion function. - -* docutils/parsers/rst/directives/body.py: - - - Converted the line-block directive to use the new structure. - - Extracted the old line-block functionality to the ``block`` - function (still used). - - Added ``compound`` directive (thanks to Felix Wiemann). - -* docutils/parsers/rst/directives/misc.py: - - - Added "encoding" option to "include" and "raw" directives. - - Added "trim", "ltrim", and "rtrim" options to "unicode" directive. - - Allow multiple class names in the "class" directive. - -* docutils/parsers/rst/directives/parts.py: - - - Directive "sectnum" now accepts "prefix", "suffix", and "start" - options. Thanks to Lele Gaifax. - -* docutils/parsers/rst/directives/tables.py: - - - Added "encoding" directive to "csv-table" directive. - - Added workaround for lack of Unicode support in csv.py, for - non-ASCII CSV input. - -* docutils/transforms/misc.py: - - - Fixed bug when multiple "class" directives are applied to a single - element. - - Enabled multiple format names for "raw" directive. - -* docutils/transforms/references.py: - - - Added support for trimming whitespace from beside substitution - references. - -* docutils/transforms/universal.py: - - - FinalChecks now checks for illegal transitions and moves - transitions between sections. - -* docutils/writers/html4css1.py: - - - HTMLTranslator.encode now converts U+00A0 to " ". - - "stylesheet" and "stylesheet_path" settings are now mutually - exclusive. - - Added support for the new line_block/line structure. - - --footnote-references now overrides - --trim-footnote-reference-space, if applicable. - - Added support for ``compound`` elements. - - Enabled multiple format names for "raw" directive. - - ``<p>`` tags of a paragraph which is the only visible child of the - document node are no longer stripped. - - Moved paragraph-compacting logic (for stripping ``<p>`` tags) to - new method ``should_be_compact_paragraph()``. - - Added class="docutils" to ``dl``, ``hr``, ``table`` and ``tt`` - elements. - - "raw" elements are now surrounded by ``span`` or ``div`` tags in - the output if they have their ``class`` attribute set. - - The whole document is now surrounded by a ``<div - class="document">`` element. - - Body-level images are now wrapped by their own ``<div>`` elements, - with image classes copied to the wrapper, and for images which - have the ``:align:`` option set, the surrounding ``<div>`` now - receives a class attribute (like ``class="align-left"``). - -* docutils/writers/latex2e.py: - - - no newline after depart_term. - - Added translations for some Unicode quotes. - - Added option "font-encoding", made package AE the default. - - "stylesheet" and "stylesheet_path" settings are now mutually - exclusive. - - --footnote-references now overrides - --trim-footnote-reference-space, if applicable. - - The footnote label style now matches the footnote reference style - ("brackets" or "superscript"). - - Added support for ``compound`` elements. - - Enabled multiple format names for "raw" directive. - -* docs/ref/docutils.dtd: - - - Changed structure of the ``line_block`` element; added ``line``. - - Added ``compound`` element. - - Added "ltrim" and "rtrim" attributes to - ``substitution_definition`` element. - - Enabled multiple format names for ``raw`` element. - - Enabled multiple classifiers in ``definition_list_item`` elements. - -* docs/ref/rst/directives.txt - - - Marked "line-block" as deprecated. - - "Class" directive now allows multiple class names. - - Added "Rationale for Class Attribute Value Conversion". - - Added warning about "raw" overuse/abuse. - -* docs/ref/rst/restructuredtext.txt: - - - Added syntax for line blocks. - - Definition list items may have multiple classifiers. - -* docs/ref/rst/roles.txt: - - - Added "raw" role. - -* tools/stylesheets/default.css: - - - Added support for the new line_block structure. - - Added "docutils" class to ``dl``, ``hr``, ``table`` and ``tt``. - - -Release 0.3.5 (2004-07-29) -========================== - -General: - -* _`Documentation cleanup/reorganization`. - - - Created new subdirectories of docs/: - - * ``docs/user/``: introductory/tutorial material for end-users - * ``docs/dev/``: for core-developers (development notes, plans, etc.) - * ``docs/api/``: API reference material for client-developers - * ``docs/ref/``: reference material for all groups - * ``docs/howto/``: for component-developers and core-developers - * ``docs/peps/``: Python Enhancement Proposals - - - Moved ``docs/*`` to ``docs/user/``. - - Moved ``pysource.dtd``, ``pysource.txt``, ``semantics.txt`` from - ``spec/`` to ``docs/dev``. - - Moved ``doctree.txt``, ``docutils.dtd``, ``soextblx.dtd``, - ``transforms.txt`` from ``spec/`` to ``docs/ref/``. - - Moved ``alternatives.txt``, and ``problems.txt`` from - ``spec/rst/`` to ``docs/dev/rst/``. - - Moved ``reStructuredText.txt``, ``directives.txt``, - ``interpreted.txt``, and ``introduction.txt`` from ``spec/rst/`` - to ``docs/ref/rst/``. Renamed ``interpreted.txt`` to - ``roles.txt``, ``reStructuredText.txt`` to - ``restructuredtext.txt``. - - Moved ``spec/howto/`` to ``docs/howto``. - - In order to keep the CVS history of moved files, we supplied - SourceForge with a `script for modifying the Docutils CVS - repository`__. - - __ http://cvs.sourceforge.net/viewcvs.py/*checkout*/docutils/sandbox/davidg/infrastructure/cvs-reorg.sh?content-type=text/plain&rev=1.5 - - After running the cleanup script: - - - Added ``docs/index.txt``. - - Added a ``.htaccess`` file to the ``web`` module, containing - redirects for all old paths to new paths. They'll preserve - fragments (the "#name" part of a URL), and won't clutter up the - file system, and will correct the URL in the user's browser. - - Added ``BUGS.txt``, ``docs/dev/policies.txt``, - ``docs/dev/website.txt``, ``docs/dev/release.txt`` from all but - the "To Do" list itself in ``docs/dev/todo.txt``. - - Moved "Future Plans" from ``HISTORY.txt`` to new "Priorities" - section of ``docs/dev/todo.txt``. - - Added ``THANKS.txt`` from "Acknowledgements" in ``HISTORY.txt``. - - Added "How To Report Bugs" to ``BUGS.txt``. - - Went through all the sources and docs (including under web/) and - updated links. Mostly done by Felix Wiemann; thanks Felix! - (Still need to update links in the sandboxes.) - -Specific: - -* BUGS.txt: Added to project. - -* THANKS.txt: Added to project. - -* docutils/__init__.py: - - - 0.3.4: Post-release. - -* docutils/core.py: - - - Added special error handling & advice for UnicodeEncodeError. - - Refactored Publisher.publish (simplified exception handling & - extracted debug dumps). - - Renamed "enable_exit" parameter of convenience functions to - "enable_exit_status". - - Enabled traceback (exception propagation) by default in - programmatic convenience functions. - - Now publish_file and publish_cmdline convenience functions return - the encoded string results in addition to their regular I/O. - - Extracted common code from publish_file, publish_string, and - publish_parts, into new publish_programmatically. Extracted - settings code to ``Publisher.process_programmatic_settings``. - - In Publisher.publish, disabled ``settings_overrides`` when - ``settings`` is supplied; redundant. - -* docutils/frontend.py: - - - Added help text for "--output-encoding-error-handler" and - "--error-encoding-error-handler". - - Renamed "--exit" to "--exit-status". - - Simplified default-setting code. - -* docutils/parsers/rst/__init__.py: - - - Added "--pep-base-url" and "--rfc-base-url" options. - -* docutils/parsers/rst/states.py: - - - Made URI recognition more aggressive and intelligent. - -* docutils/parsers/rst/directives/__init__.py: - - - Added several directive option conversion functions. - -* docutils/parsers/rst/directives/body.py: - - - Moved "table" directive to tables.py. - -* docutils/parsers/rst/directives/tables.py: Table-related directives, - added to project. - -* docutils/writers/latex2e.py: - - - Added "--table-style=(standard|booktabs|nolines)" - - figures get "here" option (LaTeX per default puts them at bottom), - and figure content is centered. - - Rowspan support for tables. - - Fix: admonition titles before first section. - - Replace ``--`` in literal by ``-{}-`` because fontencoding T1 has endash. - - Replave ``_`` in literal by an underlined blank, because it has the correct - width. - - Fix: encode pdfbookmark titles, ``#`` broke pdflatex. - - A few unicode replacements, if output_encoding != utf - - Add "--graphicx-option". - - Indent literal-blocks. - - Fix: omit ``\maketitle`` when there is no document title. - -* docs/index.txt: "Docutils Project Documentation Overview", added to - project. - -* docs/api/cmdline-tool.txt: "Inside A Docutils Command-Line Front-End - Tool", added to project. - -* docs/api/publisher.txt: "The Docutils Publisher", added to project. - -* docs/api/runtime-settings.txt: "Docutils Runtime Settings", added to project. - -* docs/dev/policies.txt: Added to project (extracted from - ``docs/dev/todo.txt``, formerly ``spec/notes.txt``). - -* docs/dev/release.txt: Added to project (extracted from - ``docs/dev/todo.txt``, formerly ``spec/notes.txt``). - -* docs/dev/testing.txt: Added to project. - -* docs/dev/website.txt: Added to project (extracted from - ``docs/dev/todo.txt``, formerly ``spec/notes.txt``). - -* docs/ref/rst/directives.txt: - - - Added directives: "table", "csv-table". - -* docs/user/rst/cheatsheet.txt: "The reStructuredText Cheat Sheet" - added to project. 1 page for syntax, and a 1 page reference for - directives and roles. Source text to be used as-is; not meant to be - converted to HTML. - -* docs/user/rst/demo.txt: Added to project; moved from tools/test.txt - with a change of title. - -* test/functional/, contents, and test/test_functional.py: Added to - project. - -* tools/buildhtml.py: Fixed bug with config file handling. - -* tools/html.py: Removed from project (duplicate of rst2html.py). - -* tools/pep2html.py: Removed from project (duplicate of Python's - nondist/peps/pep2html.py; Docutils' tools/pep.py can be used for - Docutils-related PEPs in docs/peps/). - -* tools/rst2pseudoxml.py: Renamed from publish.py. - -* tools/rst2xml.py: Renamed from docutils-xml.py. - -* tools/test.txt: Removed from project; moved to - docs/user/rst/demo.txt. - -* setup.py: Now also installs ``rst2latex.py``. - - -Release 0.3.3 (2004-05-09) -========================== - -* docutils/__init__.py: - - - 0.3.1: Reorganized config file format (multiple sections); see - docs/config.txt. - - Added unknown_reference_resolvers attribute to TransformSpec. - - 0.3.2: Interpreted text reorganization. - - 0.3.3: Released. - -* docutils/core.py: - - - Catch system messages to stop tracebacks from parsing errors. - - Catch exceptions during processing report & exit without - tracebacks, except when "--traceback" used. - - Reordered components for OptionParser; application comes last. - - Added "config_section" parameter to several methods and functions, - allowing front ends to easily specify their config file sections. - - Added publish_parts convenience function to allow access to individual - parts of a document. - -* docutils/examples.py: Added to project; practical examples of - Docutils client code, to be used as-is or as models for variations. - -* docutils/frontend.py: - - - Added "--traceback" & "--no-traceback" options ("traceback" - setting). - - Implemented support for config file reorganization: - ``standard_config_files`` moved from ``ConfigParser`` to - ``OptionParser``; added - ``OptionParser.get_config_file_settings()`` and - ``.get_standard_config_settings()``; support for old "[options]" - section (with deprecation warning) and mapping from old to new - settings. - - Reimplemented setting validation. - - Enabled flexible boolean values: yes/no, true/false, on/off. - - Added ``Values``, a subclass of ``optparse.Values``, with support - for list setting attributes. - - Added support for new ``DOCUTILSCONFIG`` environment variable; - thanks to Beni Cherniavsky. - - Added "--no-section-numbering" option. - -* docutils/io.py: - - - Catch IOErrors when opening source & destination files, report & - exit without tracebacks. Added ``handle_io_errors`` parameter to - ``FileInput`` & ``FileOutput`` to enable caller error handling. - -* docutils/nodes.py: - - - Changed ``SparseNodeVisitor`` and ``GenericNodeVisitor`` dynamic - method definitions (via ``exec``) to dynamic assignments (via - ``setattr``); thanks to Roman Suzi. - - Encapsulated visitor dynamic assignments in a function; thanks to - Ian Bicking. - - Added indirect_reference_name attribute to the Targetable - class. This attribute holds the whitespace_normalized_name - (contains mixed case) of a target. - -* docutils/statemachine.py: - - - Renamed ``StringList.strip_indent`` to ``.trim_left``. - - Added ``StringList.get_2D_block``. - -* docutils/utils.py: - - - Added "level" attribute to SystemMessage exceptions. - -* docutils/languages/af.py: Added to project; Afrikaans mappings by - Jannie Hofmeyr. - -* docutils/languages/cs.py: Added to project; Czech mappings by Marek - Blaha. - -* docutils/languages/eo.py: Added to project; Esperanto mappings by - Marcelo Huerta San Martin. - -* docutils/languages/pt_br.py: Added to project; Brazilian Portuguese - mappings by Lalo Martins. - -* docutils/languages/ru.py: Added to project; Russian mappings by - Roman Suzi. - -* docutils/parsers/rst/roles.py: Added to project. Contains - interpreted text role functions, a registry for interpreted text - roles, and an API for adding to and retrieving from the registry. - Contributed by Edward Loper. - -* docutils/parsers/rst/states.py: - - - Updated ``RSTState.nested_parse`` for "include" in table cells. - - Allowed true em-dash character and "---" as block quote - attribution marker. - - Added support for <angle-bracketed> complex option arguments - (option lists). - - Fixed handling of backslashes in substitution definitions. - - Fixed off-by-1 error with extra whitespace after substitution - definition directive. - - Added inline markup parsing to field lists' field names. - - Added support for quoted (and unindented) literal blocks. - Driven in part by a bribe from Frank Siebenlist (thanks!). - - Parser now handles escapes in URIs correctly. - - Made embedded-URIs' reference text omittable. Idea from Beni - Cherniavsky. - - Refactored explicit target processing code. - - Added name attribute to references containing the reference name only - through whitespace_normalize_name (no case changes). - - parse_target no longer returns the refname after going through - normalize_name. This is now handled in make_target. - - Fixed bug relating to role-less interpreted text in non-English - contexts. - - Reorganized interpreted text processing; moved code into the new - roles.py module. Contributed by Edward Loper. - - Refactored ``Body.parse_directive`` into ``run_directive`` and - ``parse_directive_block``. - -* docutils/parsers/rst/tableparser.py: - - - Reworked for ``StringList``, to support "include" directives in - table cells. - -* docutils/parsers/rst/directives/__init__.py: - - - Renamed ``unchanged()`` directive option conversion function to - ``unchanged_required``, and added a new ``unchanged``. - - Catch unicode value too high error; fixes bug 781766. - - Beefed up directive error reporting. - -* docutils/parsers/rst/directives/body.py: - - - Added basic "table" directive. - -* docutils/parsers/rst/directives/images.py: - - - Added "target" option to "image" directive. - - Added name attribute to references containing the reference name only - through whitespace_normalize_name (no case changes). - -* docutils/parsers/rst/directives/misc.py: - - - Isolated the import of the ``urllib2`` module; was causing - problems on SourceForge (``libssl.so.2`` unavailable?). - - Added the "role" directive for declaring custom interpreted text - roles. - -* docutils/parsers/rst/directives/parts.py: - - - The "contents" directive does more work up-front, creating the - "topic" and "title", and leaving the "pending" node for the - transform. Allows earlier reference resolution; fixes subtle bug. - -* docutils/parsers/rst/languages/af.py: Added to project; Afrikaans - mappings by Jannie Hofmeyr. - -* docutils/parsers/rst/languages/cs.py: Added to project; Czech - mappings by Marek Blaha. - -* docutils/parsers/rst/languages/eo.py: Added to project; Esperanto - mappings by Marcelo Huerta San Martin. - -* docutils/parsers/rst/languages/pt_br.py: Added to project; Brazilian - Portuguese mappings by Lalo Martins. - -* docutils/parsers/rst/languages/ru.py: Added to project; Russian - mappings by Roman Suzi. - -* docutils/transforms/parts.py: - - - The "contents" directive does more work up-front, creating the - "topic" and "title", and leaving the "pending" node for the - transform. Allows earlier reference resolution; fixes subtle bug. - - Added support for disabling of section numbering. - -* docutils/transforms/references.py: - - - Verifying that external targets are truly targets and not indirect - references. This is because we are now adding a "name" attribute to - references in addition to targets. Note sure if this is correct! - - Added code to hook into the unknown_reference_resolvers list for a - transformer in resolve_indirect_target. This allows the - unknown_reference_resolvers to keep around indirect targets which - docutils doesn't know about. - - Added specific error message for duplicate targets. - -* docutils/transforms/universal.py: - - - Added FilterMessages transform (removes system messages below the - verbosity threshold). - - Added hook (via docutils.TransformSpec.unknown_reference_resolvers) - to FinalCheckVisitor for application-specific handling of - unresolvable references. - - Added specific error message for duplicate targets. - -* docutils/writers/__init__.py: - - - Added assemble_parts method to the Writer class to allow for - access to a documents individual parts. - - Documented & set default for ``Writer.output`` attribute. - -* docutils/writers/html4css1.py: - - - Fixed unicode handling of attribute values (bug 760673). - - Prevent duplication of "class" attribute values (bug report from - Kirill Lapshin). - - Improved table grid/border handling (prompted by report from Bob - Marshall). - - Added support for table titles. - - Added "<title />" for untitled docs, for XHTML conformance; thanks - to Darek Suchojad. - - Added functionality to keep track of individual parts of a document - and store them in a dictionary as the "parts" attribute of the writer. - Contributed by Reggie Dugard at the Docutils sprint at PyCon DC 2004. - - Added proper support for the "scale" attribute of the "image" - element. Contributed by Brent Cook. - - Added ``--initial-header-level`` option. - - Fixed bug: the body_pre_docinfo segment depended on there being a - docinfo; if no docinfo, the document title was incorporated into - the body segment. Adversely affected the publish_parts interface. - -* docutils/writers/latex2e.py: - - - Changed default stylesheet to "no stylesheet" to avoid latex complaining - about a missing file. - - Added options and support: ``--compound-enumerators``, - ``--section-prefix-for-enumerators``, and - ``--section-enumerator-separator``. By John F Meinel Jr (SF patch - 934322). - - Added option ``--use-verbatim-when-possible``, to avoid - problematic characters (eg, '~' in italian) in literal blocks. - - It's now possible to use four section levels in the `book` and - `report` LaTeX classes. The default `article` class still has - three levels limit. - -* docs/config.txt: "Docutils Configuration Files", added to project. - Moved config file entry descriptions from tools.txt. - -* docs/tools.txt: - - - Moved config file entry descriptions to config.txt. - -* spec/notes.txt: Continual updates. Added "Setting Up For Docutils - Development". - -* spec/howto/rst-roles.txt: "Creating reStructuredText Interpreted - Text Roles", added to project. - -* spec/rst/reStructuredText.txt: - - - Added description of support for <angle-bracketed> complex option - arguments to option lists. - - Added subsections for indented and quoted literal blocks. - -* test: Continually adding & updating tests. - - - Added test/test_settings.py & test/data/config_*.txt support - files. - - Added test/test_writers/test_htmlfragment.py. - -* test/DocutilsTestSupport.py: - - - Refactored LaTeX publisher test suite/case class names to make - testing other writers easier. - - Added HtmlWriterPublishTestCase and HtmlFragmentTestSuite classes - to test the processing of HTML fragments which use the new - publish_parts convenience function. - -* tools/buildhtml.py: - - - Added support for the "--prune" option. - - Removed dependency on pep2html.py; plaintext PEPs no longer - supported. - -* tools/docutils.conf: - - - Updated for configuration file reorganization. - -* tools/rst2html.py: - - - copied from tools/html.py - -* setup.py: - - - added a 'scripts' section to configuration - - added 'tools/rst2html.py' to the scripts section - - -Release 0.3 (2003-06-24) -======================== - -General: - -* Renamed "attribute" to "option" for directives/extensions. - -* Renamed transform method "transform" to "apply". - -* Renamed "options" to "settings" for runtime settings (as set by - command-line options). Sometimes "option" (singular) became - "settings" (plural). Some variations below: - - - document.options -> document.settings (stored in other objects as - well) - - option_spec -> settings_spec (not directives though) - - OptionSpec -> SettingsSpec - - cmdline_options -> settings_spec - - relative_path_options -> relative_path_settings - - option_default_overrides -> settings_default_overrides - - Publisher.set_options -> Publisher.get_settings - -Specific: - -* COPYING.txt: Added "Public Domain Dedication". - -* FAQ.txt: Frequently asked questions, added to project. - -* setup.py: - - - Updated with PyPI Trove classifiers. - - Conditional installation of third-party modules. - -* docutils/__init__.py: - - - Bumped version to 0.2.1 to reflect changes to I/O classes. - - Bumped version to 0.2.2 to reflect changes to stylesheet options. - - Factored ``SettingsSpec`` out of ``Component``; separately useful. - - Bumped version to 0.2.3 because of the new "--embed-stylesheet" - option and its effect on the PEP template & writer. - - Bumped version to 0.2.4 due to changes to the PEP template & - stylesheet. - - Bumped version to 0.2.5 to reflect changes to Reporter output. - - Added ``TransformSpec`` class for new transform system. - - Bumped version to 0.2.6 for API changes (renaming). - - Bumped version to 0.2.7 for new ``docutils.core.publish_*`` - convenience functions. - - Added ``Component.component_type`` attribute. - - Bumped version to 0.2.8 because of the internal parser switch from - plain lists to the docutils.statemachine.StringList objects. - - Bumped version to 0.2.9 because of the frontend.py API changes. - - Bumped version to 0.2.10 due to changes to the project layout - (third-party modules removed from the "docutils" package), and - signature changes in ``io.Input``/``io.Output``. - - Changed version to 0.3.0 for release. - -* docutils/core.py: - - - Made ``publish()`` a bit more convenient. - - Generalized ``Publisher.set_io``. - - Renamed ``publish()`` to ``publish_cmdline()``; rearranged its - parameters; improved its docstring. - - Added ``publish_file()`` and ``publish_string()``. - - Factored ``Publisher.set_source()`` and ``.set_destination()`` - out of ``.set_io``. - - Added support for "--dump-pseudo-xml", "--dump-settings", and - "--dump-transforms" hidden options. - - Added ``Publisher.apply_transforms()`` method. - - Added ``Publisher.set_components()`` method; support for - ``publish_*()`` conveninece functions. - - Moved config file processing to docutils/frontend.py. - - Added support for exit status ("exit_level" setting & - ``enable_exit`` parameter for Publisher.publish() and convenience - functions). - -* docutils/frontend.py: - - - Check for & exit on identical source & destination paths. - - Fixed bug with absolute paths & "--config". - - Set non-command-line defaults in ``OptionParser.__init__()``: - ``_source`` & ``_destination``. - - Distributed ``relative_path_settings`` to components; updated - ``OptionParser.populate_from_components()`` to combine it all. - - Require list of keys in ``make_paths_absolute`` (was implicit in - global ``relative_path_settings``). - - Added "--expose-internal-attribute", "--dump-pseudo-xml", - "--dump-settings", and "--dump-transforms" hidden options. - - Removed nasty internals-fiddling ``ConfigParser.get_section`` - code, replaced with correct code. - - Added validation functionality for config files. - - Added "--error-encoding" option/setting, "_disable_config" - internal setting. - - Added encoding validation; updated "--input-encoding" and - "--output-encoding"; added "--error-encoding-error-handler" and - "--output-encoding-error-handler". - - Moved config file processing from docutils/core.py. - - Updated ``OptionParser.populate_from_components`` to handle new - ``SettingsSpec.settings_defaults`` dict. - - Added support for "-" => stdin/stdout. - - Added "exit_level" setting ("--exit" option). - -* docutils/io.py: - - - Split ``IO`` classes into subclasses of ``Input`` and ``Output``. - - Added automatic closing to ``FileInput`` and ``FileOutput``. - - Delayed opening of ``FileOutput`` file until ``write()`` called. - - ``FileOutput.write()`` now returns the encoded output string. - - Try to get path/stream name automatically in ``FileInput`` & - ``FileOutput``. - - Added defaults for source & destination paths. - - Allow for Unicode I/O with an explicit "unicode" encoding. - - Added ``Output.encode()``. - - Removed dependency on runtime settings; pass encoding directly. - - Recognize Unicode strings in ``Input.decode()``. - - Added support for output encoding error handlers. - -* docutils/nodes.py: - - - Added "Invisible" element category class. - - Changed ``Node.walk()`` & ``.walkabout()`` to permit more tree - modification during a traversal. - - Added element classes: ``line_block``, ``generated``, ``address``, - ``sidebar``, ``rubric``, ``attribution``, ``admonition``, - ``superscript``, ``subscript``, ``inline`` - - Added support for lists of nodes to ``Element.insert()``. - - Fixed parent linking in ``Element.replace()``. - - Added new abstract superclass ``FixedTextElement``; adds - "xml:space" attribute. - - Added support for "line" attribute of ``system_message`` nodes. - - Added support for the observer pattern from ``utils.Reporter``. - Added ``parse_messages`` and ``transform_messages`` attributes to - ``document``, removed ``messages``. Added ``note_parse_message`` - and ``note_transform_message`` methods. - - Added support for improved diagnostics: - - - Added "document", "source", and "line" internal attributes to - ``Node``, set by ``Node.setup_child()``. - - Converted variations on ``node.parent = self`` to - ``self.setup_child(node)``. - - Added ``document.current_source`` & ``.current_line`` - attributes, and ``.note_source`` observer method. - - Changed "system_message" output to GNU-Tools format. - - - Added a "rawsource" attribute to the ``Text`` class, for text - before backslash-escape resolution. - - Support for new transform system. - - Reworked ``pending`` element. - - Fixed XML DOM bug (SF #660611). - - Removed the ``interpeted`` element class and added - ``title_reference``, ``abbreviation``, ``acronym``. - - Made substitutions case-sensitive-but-forgiving; moved some code - from the parser. - - Fixed Unicode bug on element attributes (report: William Dode). - -* docutils/optik.py: Removed from project; replaced with - extras/optparse.py and extras/textwrap.py. These will be installed - only if they're not already present in the Python installation. - -* docutils/roman.py: Moved to extras/roman.py; this will be installed - only if it's not already present in the Python installation. - -* docutils/statemachine.py: - - - Factored out ``State.add_initial_transitions()`` so it can be - extended. - - Converted whitespace-specific "blank" and "indent" transitions - from special-case code to ordinary transitions: removed - ``StateMachineWS.check_line()`` & ``.check_whitespace()``, added - ``StateWS.add_initial_transitions()`` method, ``ws_patterns`` & - ``ws_initial_transitions`` attributes. - - Removed ``State.match_transition()`` after merging it into - ``.check_line()``. - - Added ``StateCorrection`` exception. - - Added support for ``StateCorrection`` in ``StateMachine.run()`` - (moved ``TransitionCorrection`` support there too.) - - Changed ``StateMachine.next_line()`` and ``.goto_line()`` to raise - ``EOFError`` instead of ``IndexError``. - - Added ``State.no_match`` method. - - Added support for the Observer pattern, triggered by input line - changes. - - Added ``strip_top`` parameter to - ``StateMachineWS.get_first_known_indented``. - - Made ``context`` a parameter to ``StateMachine.run()``. - - Added ``ViewList`` & ``StringList`` classes; - ``extract_indented()`` becomes ``StringList.get_indented()``. - - Added ``StateMachine.insert_input()``. - - Fixed ViewList slice handling for Python 2.3. Patch from (and - thanks to) Fred Drake. - -* docutils/utils.py: - - - Added a ``source`` attribute to Reporter instances and - ``system_message`` elements. - - Added an observer pattern to ``utils.Reporter`` to keep track of - system messages. - - Fixed bugs in ``relative_path()``. - - Added support for improved diagnostics. - - Moved ``normalize_name()`` to nodes.py (``fully_normalize_name``). - - Added support for encoding Reporter stderr output, and encoding - error handlers. - - Reporter keeps track of the highest level system message yet - generated. - -* docutils/languages: Fixed bibliographic field language lookups. - -* docutils/languages/es.py: Added to project; Spanish mappings by - Marcelo Huerta San Martin. - -* docutils/languages/fr.py: Added to project; French mappings by - Stefane Fermigier. - -* docutils/languages/it.py: Added to project; Italian mappings by - Nicola Larosa. - -* docutils/languages/sk.py: Added to project; Slovak mappings by - Miroslav Vasko. - -* docutils/parser/__init__.py: - - - Added ``Parser.finish_parse()`` method. - -* docutils/parser/rst/__init__.py: - - - Added options: "--pep-references", "--rfc-references", - "--tab-width", "--trim-footnote-reference-space". - -* docutils/parsers/rst/states.py: - - - Changed "title under/overline too short" system messages from INFO - to WARNING, and fixed its insertion location. - - Fixed enumerated list item parsing to allow paragraphs & section - titles to begin with enumerators. - - Converted system messages to use the new "line" attribute. - - Fixed a substitution reference edge case. - - Added support for "--pep-references" and "--rfc-references" - options; reworked ``Inliner`` code to make customization easier. - - Removed field argument parsing. - - Added support for short section title over/underlines. - - Fixed "simple reference name" regexp to ignore text like - "object.__method__"; not an anonymous reference. - - Added support for improved diagnostics. - - Reworked directive API, based on Dethe Elza's contribution. Added - ``Body.parse_directive()``, ``.parse_directive_options()``, - ``.parse_directive_arguments()`` methods. - - Added ``ExtensionOptions`` class, to parse directive options - without parsing field bodies. Factored - ``Body.parse_field_body()`` out of ``Body.field()``, overridden in - ``ExtensionOptions``. - - Improved definition list term/classifier parsing. - - Added warnings for unknown directives. - - Renamed ``Stuff`` to ``Struct``. - - Now flagged as errors: transitions at the beginning or end of - sections, empty sections (except title), and empty documents. - - Updated for ``statemachine.StringList``. - - Enabled recognition of schemeless email addresses in targets. - - Added support for embedded URIs in hyperlink references. - - Added backslash-escapes to inline markup end-string suffix. - - Added support for correct interpreted text processing. - - Fixed nested title parsing (topic, sidebar directives). - - Added special processing of backslash-escaped whitespace (idea - from David Abrahams). - - Made substitutions case-sensitive-but-forgiving; moved some code - to ``docutils.nodes``. - - Added support for block quote attributions. - - Added a kludge to work-around a conflict between the bubble-up - parser strategy and short titles (<= 3 char-long over- & - underlines). Fixes SF bug #738803 "infinite loop with multiple - titles" submitted by Jason Diamond. - - Added explicit interpreted text roles for standard inline markup: - "emphasis", "strong", "literal". - - Implemented "superscript" and "subscript" interpreted text roles. - - Added initial support for "abbreviation" and "acronym" roles; - incomplete. - - Added support for "--trim-footnote-reference-space" option. - - Optional space before colons in directives & hyperlink targets. - -* docutils/parsers/rst/tableparser.py: - - - Fixed a bug that was producing unwanted empty rows in "simple" - tables. - - Detect bad column spans in "simple" tables. - -* docutils/parsers/rst/directives: Updated all directive functions to - new API. - -* docutils/parsers/rst/directives/__init__.py: - - - Added ``flag()``, ``unchanged()``, ``path()``, - ``nonnegative_int()``, ``choice()``, and ``class_option()`` - directive option helper functions. - - Added warnings for unknown directives. - - Return ``None`` for missing directives. - - Added ``register_directive()``, thanks to William Dode and Paul - Moore. - -* docutils/parsers/rst/directives/admonitions.py: - - - Added "admonition" directive. - -* docutils/parsers/rst/directives/body.py: Added to project. Contains - the "topic", "sidebar" (from Patrick O'Brien), "line-block", - "parsed-literal", "rubric", "epigraph", "highlights" and - "pull-quote" directives. - -* docutils/parsers/rst/directives/images.py: - - - Added an "align" attribute to the "image" & "figure" directives - (by Adam Chodorowski). - - Added "class" option to "image", and "figclass" to "figure". - -* docutils/parsers/rst/directives/misc.py: - - - Added "include", "raw", and "replace" directives, courtesy of - Dethe Elza. - - Added "unicode" and "class" directives. - -* docutils/parsers/rst/directives/parts.py: - - - Added the "sectnum" directive; by Dmitry Jemerov. - - Added "class" option to "contents" directive. - -* docutils/parsers/rst/directives/references.py: Added to project. - Contains the "target-notes" directive. - -* docutils/parsers/rst/languages/__init__.py: - - - Return ``None`` from get_language() for missing language modules. - -* docutils/parsers/rst/languages/de.py: Added to project; German - mappings by Engelbert Gruber. - -* docutils/parsers/rst/languages/en.py: - - - Added interpreted text roles mapping. - -* docutils/parsers/rst/languages/es.py: Added to project; Spanish - mappings by Marcelo Huerta San Martin. - -* docutils/parsers/rst/languages/fr.py: Added to project; French - mappings by William Dode. - -* docutils/parsers/rst/languages/it.py: Added to project; Italian - mappings by Nicola Larosa. - -* docutils/parsers/rst/languages/sk.py: Added to project; Slovak - mappings by Miroslav Vasko. - -* docutils/readers/__init__.py: - - - Added support for the observer pattern from ``utils.Reporter``, in - ``Reader.parse`` and ``Reader.transform``. - - Removed ``Reader.transform()`` method. - - Added default parameter values to ``Reader.__init__()`` to make - instantiation easier. - - Removed bogus aliases: "restructuredtext" is *not* a Reader. - -* docutils/readers/pep.py: - - - Added the ``peps.TargetNotes`` transform to the Reader. - - Removed PEP & RFC reference detection code; moved to - parsers/rst/states.py as options (enabled here by default). - - Added support for pre-acceptance PEPs (no PEP number yet). - - Moved ``Inliner`` & made it a class attribute of ``Reader`` for - easy subclassing. - -* docutils/readers/python: Python Source Reader subpackage added to - project, including preliminary versions of: - - - __init__.py - - moduleparser.py: Parser for Python modules. - -* docutils/transforms/__init__.py: - - - Added ``Transformer`` class and completed transform reform. - - Added unknown_reference_resolvers list for each transformer. This list holds - the list of functions provided by each component of the transformer that - help resolve references. - -* docutils/transforms/frontmatter.py: - - - Improved support for generic fields. - - Fixed bibliographic field language lookups. - -* docutils/transforms/misc.py: Added to project. Miscellaneous - transforms. - -* docutils/transforms/parts.py: - - - Moved the "id" attribute from TOC list items to the references - (``Contents.build_contents()``). - - Added the ``SectNum`` transform; by Dmitry Jemerov. - - Added "class" attribute support to ``Contents``. - -* docutils/transforms/peps.py: - - - Added ``mask_email()`` function, updating to pep2html.py's - functionality. - - Linked "Content-Type: text/x-rst" to PEP 12. - - Added the ``TargetNotes`` PEP-specific transform. - - Added ``TargetNotes.cleanup_callback``. - - Added title check to ``Headers``. - -* docutils/transforms/references.py: - - - Added the ``TargetNotes`` generic transform. - - Split ``Hyperlinks`` into multiple transforms. - - Fixed bug with multiply-indirect references (report: Bruce Smith). - - Added check for circular indirect references. - - Made substitutions case-sensitive-but-forgiving. - -* docutils/transforms/universal.py: - - - Added support for the "--expose-internal-attributes" option. - - Removed ``Pending`` transform classes & data. - -* docutils/writers/__init__.py: - - - Removed ``Writer.transform()`` method. - -* docutils/writers/docutils-xml.py: - - - Added XML and doctype declarations. - - Added "--no-doctype" and "--no-xml-declaration" options. - -* docutils/writers/html4css1.py: - - - "name" attributes only on these tags: a, applet, form, frame, - iframe, img, map. - - Added "name" attribute to <a> in section titles for Netscape 4 - support (bug report: Pearu Peterson). - - Fixed targets (names) on footnote, citation, topic title, - problematic, and system_message nodes (for Netscape 4). - - Changed field names from "<td>" to "<th>". - - Added "@" to "@" encoding to thwart address harvesters. - - Improved the vertical whitespace optimization; ignore "invisible" - nodes (targets, comments, etc.). - - Improved inline literals with ``<span class="pre">`` around chunks - of text and `` `` for runs of spaces. - - Improved modularity of output; added ``self.body_pre_docinfo`` and - ``self.docinfo`` segments. - - Added support for "line_block", "address" elements. - - Improved backlinks (footnotes & system_messages). - - Improved system_message output. - - Redefined "--stylesheet" as containing an invariant URL, used - verbatim. Added "--stylesheet-path", interpreted w.r.t. the - working directory. - - Added "--footnote-references" option (superscript or brackets). - - Added "--compact-lists" and "--no-compact-lists" options. - - Added "--embed-stylesheet" and "--link-stylesheet" options; - factored out ``HTMLTranslator.get_stylesheet_reference()``. - - Improved field list rendering. - - Added Docutils version to "generator" meta tag. - - Fixed a bug with images; they must be inline, so wrapped in <p>. - - Improved layout of <pre> HTML source. - - Fixed attribute typo on <colspec>. - - Refined XML prologue. - - Support for no stylesheet. - - Removed "interpreted" element support. - - Added support for "title_reference", "sidebar", "attribution", - "rubric", and generic "admonition" elements. - - Added "--attribution" option. - - Added support for "inline", "subscript", "superscript" elements. - - Added initial support for "abbreviation" and "acronym"; - incomplete. - -* docutils/writers/latex2e.py: LaTeX Writer, added by Engelbert Gruber - (from the sandbox). - - - Added french. - - Double quotes in literal blocks (special treatment for de/ngerman). - - Added '--hyperlink-color' option ('0' turns off coloring of links). - - Added "--attribution" option. - - Right align attributions. - -* docutils/writers/pep_html.py: - - - Parameterized output encoding in PEP template. - - Reworked substitutions from ``locals()`` into ``subs`` dict. - - Redefined "--pep-stylesheet" as containing an invariant URL, used - verbatim. Added "--pep-stylesheet-path", interpreted w.r.t. the - working directory. - - Added an override on the "--footnote-references" option. - - Factored out ``HTMLTranslator.get_stylesheet_reference()``. - - Added Docutils version to "generator" meta tag. - - Added a "DO NOT EDIT THIS FILE" comment to generated HTML. - -* docs/tools.txt: - - - Added a "silent" setting for ``buildhtml.py``. - - Added a "Getting Help" section. - - Rearranged the structure. - - Kept up to date, with new settings, command-line options etc. - - Added section for ``rst2latex.py`` (Engelbert Gruber). - - Converted settings table into a definition list. - -* docs/rst/quickstart.txt: - - - Added a table of contents. - - Added feedback information. - - Added mention of minimum section title underline lengths. - - Removed the 4-character minimum for section title underlines. - -* docs/rst/quickref.html: - - - Added a "Getting Help" section. - - Added a style to make section title backlinks more subtle. - - Added mention of minimum section title underline lengths. - - Removed the 4-character minimum for section title underlines. - -* extras: Directory added to project; contains third-party modules - that Docutils depends on (optparse, textwrap, roman). These are - only installed if they're not already present. - -* licenses: Directory added to project; contains copies of license - files for non-public-domain files. - -* spec/doctree.txt: - - - Changed the focus. It's about DTD elements: structural - relationships, semantics, and external (public) attributes. Not - about the element class library. - - Moved some implementation-specific stuff into ``docutils.nodes`` - docstrings. - - Wrote descriptions of all common attributes and parameter - entities. Filled in introductory material. - - Working through the element descriptions: 55 down, 37 to go. - - Removed "Representation of Horizontal Rules" to - spec/rst/alternatives.txt. - -* spec/docutils.dtd: - - - Added "generated" inline element. - - Added "line_block" body element. - - Added "auto" attribute to "title". - - Changed content models of "literal_block" and "doctest_block" to - ``%text.model``. - - Added ``%number;`` attribute type parameter entity. - - Changed ``%structural.elements;`` to ``%section.elements``. - - Updated attribute types; made more specific. - - Added "address" bibliographic element. - - Added "line" attribute to ``system_message`` element. - - Removed "field_argument" element; "field_name" may contain - multiple words and whitespace. - - Changed public identifier to docutils.sf.net. - - Removed "interpreted" element; added "title_reference", - "abbreviation", "acronym". - - Removed "refuri" attribute from "footnote_reference" and - "citation_reference". - - Added "sidebar", "rubric", "attribution", "admonition", - "superscript", "subscript", and "inline" elements. - -* spec/pep-0256.txt: Converted to reStructuredText & updated. - -* spec/pep-0257.txt: Converted to reStructuredText & updated. - -* spec/pep-0258.txt: Converted to reStructuredText & updated. - -* spec/semantics.txt: Updated with text from a Doc-SIG response to - Dallas Mahrt. - -* spec/transforms.txt: Added to project. - -* spec/howto: Added subdirectory, for developer how-to docs. - -* spec/howto/rst-directives.txt: Added to project. Original by Dethe - Elza, edited & extended by David Goodger. - -* spec/howto/i18n.txt: Docutils Internationalization. Added to - project. - -* spec/rst/alternatives.txt: - - - Added "Doctree Representation of Transitions" from - spec/doctree.txt. - - Updated "Inline External Targets" & closed the debate. - - Added ideas for interpreted text syntax extensions. - - Added "Nested Inline Markup" section. - -* spec/rst/directives.txt: - - - Added directives: "topic", "sectnum", "target-notes", - "line-block", "parsed-literal", "include", "replace", "sidebar", - "admonition", "rubric", "epigraph", "highlights", "unicode" and - "class". - - Formalized descriptions of directive details. - - Added an "align" attribute to the "image" & "figure" directives - (by Adam Chodorowski). - - Added "class" options to "topic", "sidebar", "line-block", - "parsed-literal", "contents", and "image"; and "figclass" to - "figure". - -* spec/rst/interpreted.txt: Added to project. Descriptions of - interpreted text roles. - -* spec/rst/introduction.txt: - - - Added pointers to material for new users. - -* spec/rst/reStructuredText.txt: - - - Disambiguated comments (just add a newline after the "::"). - - Updated enumerated list description; added a discussion of the - second-line validity checking. - - Updated directive description. - - Added a note redirecting newbies to the user docs. - - Expanded description of inline markup start-strings in non-markup - contexts. - - Removed field arguments and made field lists a generic construct. - - Removed the 4-character minimum for section title underlines. - - Clarified term/classifier delimiter & inline markup ambiguity - (definition lists). - - Added "Embedded URIs". - - Updated "Interpreted Text" section. - - Added "Character-Level Inline Markup" section. - -* test: Continually adding & updating tests. - - - Moved test/test_rst/ to test/test_parsers/test_rst/. - - Moved test/test_pep/ to test/test_readers/test_pep/. - - Added test/test_readers/test_python/. - - Added test/test_writers/ (Engelbert Gruber). - -* tools: - - - Made the ``locale.setlocale()`` calls in front ends - fault-tolerant. - -* tools/buildhtml.py: - - - Added "--silent" option. - - Fixed bug with absolute paths & "--config". - - Updated for new I/O classes. - - Added some exception handling. - - Separated publishers' setting defaults; prevents interference. - - Updated for new ``publish_file()`` convenience function. - -* tools/pep-html-template: - - - Allow for "--embed-stylesheet". - - Added Docutils version to "generator" meta tag. - - Added a "DO NOT EDIT THIS FILE" comment to generated HTML. - - Conform to XHTML spec. - -* tools/pep2html.py: - - - Made ``argv`` a parameter to ``main()``. - - Added support for "Content-Type:" header & arbitrary PEP formats. - - Linked "Content-Type: text/plain" to PEP 9. - - Files skipped (due to an error) are not pushed onto the server. - - Updated for new I/O classes. - - Added ``check_requirements()`` & ``pep_type_error()``. - - Added some exception handling. - - Updated for new ``publish_string()`` convenience function. - - Added a "DO NOT EDIT THIS FILE" comment to generated HTML. - -* tools/quicktest.py: - - - Added "-V"/"--version" option. - -* tools/rst2latex.py: LaTeX front end, added by Engelbert Gruber. - -* tools/unicode2rstsubs.py: Added to project. Produces character - entity files (reSructuredText substitutions) from the MathML master - unicode.xml file. - -* tools/editors: Support code for editors, added to project. Contains - ``emacs/restructuredtext.el``. - -* tools/stylesheets/default.css: Moved into the stylesheets directory. - - - Added style for chunks of inline literals. - - Removed margin for first child of table cells. - - Right-aligned field list names. - - Support for auto-numbered section titles in TOCs. - - Increased the size of inline literals (<tt>) in titles. - - Restored the light gray background for inline literals. - - Added support for "line_block" elements. - - Added style for "address" elements. - - Removed "a.footnote-reference" style; doing it with ``<sup>`` now. - - Improved field list rendering. - - Vertical whitespace improvements. - - Removed "a.target" style. - -* tools/stylesheets/pep.css: - - - Fixed nested section margins. - - Other changes parallel those of ``../default.css``. - - -Release 0.2 (2002-07-31) -======================== - -General: - -- The word "component" was being used ambiguously. From now on, - "component" will be used to mean "Docutils component", as in Reader, - Writer, Parser, or Transform. Portions of documents (Table of - Contents, sections, etc.) will be called "document parts". -- Did a grand renaming: a lot of ``verylongnames`` became - ``very_long_names``. -- Cleaned up imports: no more relative package imports or - comma-separated lists of top-level modules. -- Added support for an option values object which carries default - settings and overrides (from command-line options and library use). -- Added internal Unicode support, and support for both input and - output encodings. -- Added support for the ``docutils.io.IO`` class & subclasses. - -Specific: - -* docutils/__init__.py: - - - Added ``ApplicationError`` and ``DataError``, for use throughout - the package. - - Added ``Component`` base class for Docutils components; implements - the ``supports`` method. - - Added ``__version__`` (thus, ``docutils.__version__``). - -* docutils/core.py: - - - Removed many keyword parameters to ``Publisher.__init__()`` and - ``publish()``; bundled into an option values object. Added - "argv", "usage", "description", and "option_spec" parameters for - command-line support. - - Added ``Publisher.process_command_line()`` and ``.set_options()`` - methods. - - Reworked I/O model for ``docutils.io`` wrappers. - - Updated ``Publisher.set_options()``; now returns option values - object. - - Added support for configuration files (/etc/docutils.conf, - ./docutils.conf, ~/.docutils). - - Added ``Publisher.setup_option_parser()``. - - Added default usage message and description. - -* docutils/frontend.py: Added to project; support for front-end - (command-line) scripts. Option specifications may be augmented by - components. Requires Optik (http://optik.sf.net/) for option - processing (installed locally as docutils/optik.py). - -* docutils/io.py: Added to project; uniform API for a variety of input - output mechanisms. - -* docutils/nodes.py: - - - Added ``TreeCopyVisitor`` class. - - Added a ``copy`` method to ``Node`` and subclasses. - - Added a ``SkipDeparture`` exception for visitors. - - Renamed ``TreePruningException`` from ``VisitorException``. - - Added docstrings to ``TreePruningException``, subclasses, and - ``Nodes.walk()``. - - Improved docstrings. - - Added ``SparseNodeVisitor``, refined ``NodeVisitor``. - - Moved ``utils.id()`` to ``nodes.make_id()`` to avoid circular - imports. - - Added ``decoration``, ``header``, and ``footer`` node classes, and - ``PreDecorative`` mixin. - - Reworked the name/id bookkeeping; to ``document``, removed - ``explicit_targets`` and ``implicit_targets`` attributes, added - ``nametypes`` attribute and ``set_name_id_map`` method. - - Added ``NodeFound`` exception, for use with ``NodeVisitor`` - traversals. - - Added ``document.has_name()`` method. - - Fixed DOM generation for list-attributes. - - Added category class ``Labeled`` (used by footnotes & citations). - - Added ``Element.set_class()`` method (sets "class" attribute). - -* docutils/optik.py: Added to project. Combined from the Optik - package, with added option groups and other modifications. The use - of this module is probably only temporary. - -* docutils/statemachine.py: - - - Added ``runtime_init`` method to ``StateMachine`` and ``State``. - - Added underscores to improve many awkward names. - - In ``string2lines()``, changed whitespace normalizing translation - table to regexp; restores Python 2.0 compatibility with Unicode. - -* docutils/urischemes.py: - - - Filled in some descriptions. - - Added "shttp" scheme. - -* docutils/utils.py: - - - Added ``clean_rcs_keywords`` function (moved from - docutils/transforms/frontmatter.py - ``DocInfo.filter_rcs_keywords``). - - Added underscores to improve many awkward names. - - Changed names of Reporter's thresholds: - warning_level -> report_level; error_level -> halt_level. - - Moved ``utils.id()`` to ``nodes.make_id()``. - - Added ``relative_path(source, target)``. - -* docutils/languages/de.py: German mappings; added to project. Thanks - to Gunnar Schwant for the translations. - -* docutils/languages/en.py: Added "Dedication" bibliographic field - mappings. - -* docutils/languages/sv.py: Swedish mappings; added to project by Adam - Chodorowski. - -* docutils/parsers/rst/states.py: - - - Added underscores to improve many awkward names. - - Added RFC-2822 header support. - - Extracted the inline parsing code from ``RSTState`` to a separate - class, ``Inliner``, which will allow easy subclassing. - - Made local bindings for ``memo`` container & often-used contents - (reduces code complexity a lot). See ``RSTState.runtime_init()``. - - ``RSTState.parent`` replaces ``RSTState.statemachine.node``. - - Added ``MarkupMismatch`` exception; for late corrections. - - Added ``-/:`` characters to inline markup's start string prefix, - ``/`` to end string suffix. - - Fixed a footnote bug. - - Fixed a bug with literal blocks. - - Applied patch from Simon Budig: simplified regexps with symbolic - names, removed ``Inliner.groups`` and ``Body.explicit.groups``. - - Converted regexps from ``'%s' % var`` to ``'%(var)s' % locals()``. - - Fixed a bug in ``Inliner.interpreted_or_phrase_ref()``. - - Allowed non-ASCII in "simple names" (directive names, field names, - references, etc.). - - Converted ``Inliner.patterns.initial`` to be dynamically built - from parts with ``build_regexp()`` function. - - Changed ``Inliner.inline_target`` to ``.inline_internal_target``. - - Updated docstrings. - - Changed "table" to "grid_table"; added "simple_table" support. - -* docutils/parsers/rst/tableparser.py: - - - Changed ``TableParser`` to ``GridTableParser``. - - Added ``SimpleTableParser``. - - Refactored naming. - -* docutils/parsers/rst/directives/__init__.py: Added "en" (English) as - a fallback language for directive names. - -* docutils/parsers/rst/directives/html.py: Changed the ``meta`` - directive to use a ``pending`` element, used only by HTML writers. - -* docutils/parsers/rst/directives/parts.py: Renamed from - components.py. - - - Added "backlinks" attribute to "contents" directive. - -* docutils/parsers/rst/languages/sv.py: Swedish mappings; added to - project by Adam Chodorowski. - -* docutils/readers/__init__.py: Gave Readers more control over - choosing and instantiating Parsers. - -* docutils/readers/pep.py: Added to project; for PEP processing. - -* docutils/transforms/__init__.py: ``Transform.__init__()`` now - requires a ``component`` parameter. - -* docutils/transforms/components.py: Added to project; transforms - related to Docutils components. - -* docutils/transforms/frontmatter.py: - - - In ``DocInfo.extract_authors``, check for a single "author" in an - "authors" group, and convert it to a single "author" element. - - Added support for "Dedication" and generic bibliographic fields. - -* docutils/transforms/peps.py: Added to project; PEP-specific. - -* docutils/transforms/parts.py: Renamed from old components.py. - - - Added filter for `Contents`, to use alt-text for inline images, - and to remove inline markup that doesn't make sense in the ToC. - - Added "name" attribute to TOC topic depending on its title. - - Added support for optional TOC backlinks. - -* docutils/transforms/references.py: Fixed indirect target resolution - in ``Hyperlinks`` transform. - -* docutils/transforms/universal.py: - - - Changed ``Messages`` transform to properly filter out system - messages below the warning threshold. - - Added ``Decorations`` transform (support for ``--generator``, - ``--date``, ``--time``, ``--source-link`` options). - -* docutils/writers/__init__.py: Added "pdf" alias in anticipation of - Engelbert Gruber's PDF writer. - -* docutils/writers/html4css1.py: - - - Made XHTML-compatible (switched to lowercase element & attribute - names; empty tag format). - - Escape double-dashes in comment text. - - Improved boilerplate & modularity of output. - - Exposed modular output in Writer class. - - Added a "generator" meta tag to <head>. - - Added support for the ``--stylesheet`` option. - - Added support for ``decoration``, ``header``, and ``footer`` - elements. - - In ``HTMLTranslator.attval()``, changed whitespace normalizing - translation table to regexp; restores Python 2.0 compatibility - with Unicode. - - Added the translator class as instance variable to the Writer, to - make it easily subclassable. - - Improved option list spacing (thanks to Richard Jones). - - Modified field list output. - - Added backlinks to footnotes & citations. - - Added percentage widths to "<col>" tags (from colspec). - - Option lists: "<code>" changed to "<kbd>", ``option_argument`` - "<span>" changed to "<var>". - - Inline literals: "<code>" changed to "<tt>". - - Many changes to optimize vertical space: compact simple lists etc. - - Add a command-line options & directive attributes to control TOC - and footnote/citation backlinks. - - Added support for optional footnote/citation backlinks. - - Added support for generic bibliographic fields. - - Identify backrefs. - - Relative URLs for stylesheet links. - -* docutils/writers/pep_html.py: Added to project; HTML Writer for - PEPs (subclass of ``html4css1.Writer``). - -* docutils/writers/pseudoxml.py: Renamed from pprint.py. - -* docutils/writers/docutils_xml.py: Added to project; trivial writer - of the Docutils internal doctree in XML. - -* docs/tools.txt: "Docutils Front-End Tools", added to project. - -* spec/doctree.txt: - - - Changed the title to "The Docutils Document Tree". - - Added "Hyperlink Bookkeeping" section. - -* spec/docutils.dtd: - - - Added ``decoration``, ``header``, and ``footer`` elements. - - Brought ``interpreted`` element in line with the parser: changed - attribute "type" to "role", added "position". - - Added support for generic bibliographic fields. - -* spec/notes.txt: Continual updates. Added "Project Policies". - -* spec/pep-0256.txt: Updated. Added "Roadmap to the Doctring PEPs" - section. - -* spec/pep-0257.txt: Clarified prohibition of signature repetition. - -* spec/pep-0258.txt: Updated. Added text from pysource.txt and - mailing list discussions. - -* spec/pep-0287.txt: - - - Renamed to "reStructuredText Docstring Format". - - Minor edits. - - Reworked Q&A as an enumerated list. - - Converted to reStructuredText format. - -* spec/pysource.dtd: - - - Reworked structural elements, incorporating ideas from Tony Ibbs. - -* spec/pysource.txt: Removed from project. Moved much of its contents - to pep-0258.txt. - -* spec/rst/alternatives.txt: - - - Expanded auto-enumerated list idea; thanks to Fred Bremmer. - - Added "Inline External Targets" section. - -* spec/rst/directives.txt: - - - Added "backlinks" attribute to "contents" directive. - -* spec/rst/problems.txt: - - - Updated the Enumerated List Markup discussion. - - Added new alternative table markup syntaxes. - -* spec/rst/reStructuredText.txt: - - - Clarified field list usage. - - Updated enumerated list description. - - Clarified purpose of directives. - - Added ``-/:`` characters to inline markup's start string prefix, - ``/`` to end string suffix. - - Updated "Authors" bibliographic field behavior. - - Changed "inline hyperlink targets" to "inline internal targets". - - Added "simple table" syntax to supplement the existing but - newly-renamed "grid tables". - - Added cautions for anonymous hyperlink use. - - Added "Dedication" and generic bibliographic fields. - -* test: Made test modules standalone (subdirectories became packages). - -* test/DocutilsTestSupport.py: - - - Added support for PEP extensions to reStructuredText. - - Added support for simple tables. - - Refactored naming. - -* test/package_unittest.py: Renamed from UnitTestFolder.py. - - - Now supports true packages containing test modules - (``__init__.py`` files required); fixes duplicate module name bug. - -* test/test_pep/: Subpackage added to project; PEP testing. - -* test/test_rst/test_SimpleTableParser.py: Added to project. - -* tools: - - - Updated html.py and publish.py front-end tools to use the new - command-line processing facilities of ``docutils.frontend`` - (exposed in ``docutils.core.Publisher``), reducing each to just a - few lines of code. - - Added ``locale.setlocale()`` calls to front-end tools. - -* tools/buildhtml.py: Added to project; batch-generates .html from all - the .txt files in directories and subdirectories. - -* tools/default.css: - - - Added support for ``header`` and ``footer`` elements. - - Added styles for "Dedication" topics (biblio fields). - -* tools/docutils.conf: A configuration file; added to project. - -* tools/docutils-xml.py: Added to project. - -* tools/pep.py: Added to project; PEP to HTML front-end tool. - -* tools/pep-html-template: Added to project. - -* tools/pep2html.py: Added to project from Python (nondist/peps). - Added support for Docutils (reStructuredText PEPs). - -* tools/quicktest.py: - - - Added the ``--attributes`` option, hacked a bit. - - Added a second command-line argument (output file); cleaned up. - -* tools/stylesheets/: Subdirectory added to project. - -* tools/stylesheets/pep.css: Added to project; stylesheet for PEPs. - - -Release 0.1 (2002-04-20) -======================== - -This is the first release of Docutils, merged from the now inactive -reStructuredText__ and `Docstring Processing System`__ projects. For -the pre-Docutils history, see the `reStructuredText HISTORY`__ and the -`DPS HISTORY`__ files. - -__ http://structuredtext.sourceforge.net/ -__ http://docstring.sourceforge.net/ -__ http://structuredtext.sourceforge.net/HISTORY.html -__ http://docstring.sourceforge.net/HISTORY.html - -General changes: renamed 'dps' package to 'docutils'; renamed -'restructuredtext' subpackage to 'rst'; merged the codebases; merged -the test suites (reStructuredText's test/test_states renamed to -test/test_rst); and all modifications required to make it all work. - -* docutils/parsers/rst/states.py: - - - Improved diagnostic system messages for missing blank lines. - - Fixed substitution_reference bug. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/MANIFEST.in b/docutils/MANIFEST.in deleted file mode 100644 index 9b9c4968d..000000000 --- a/docutils/MANIFEST.in +++ /dev/null @@ -1,9 +0,0 @@ -include *.txt -include *.py -recursive-include docutils * -recursive-include docs * -recursive-include extras * -recursive-include licenses * -recursive-include test * -recursive-include tools * -recursive-exclude * .cvsignore *.pyc *~ .DS_Store diff --git a/docutils/README.txt b/docutils/README.txt deleted file mode 100644 index c2005ffaf..000000000 --- a/docutils/README.txt +++ /dev/null @@ -1,334 +0,0 @@ -================== - README: Docutils -================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Date: $Date$ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Quick-Start -=========== - -This is for those who want to get up & running quickly. Read on for -complete details. - -1. Get and install the latest release of Python, available from - - http://www.python.org/ - - Python 2.2 or later [1]_ is required; Python 2.2.2 or later is - recommended. - -2. Use the latest Docutils code. Get the code from Subversion or from - the snapshot: - - http://docutils.sf.net/docutils-snapshot.tgz - - See `Releases & Snapshots`_ below for details. - -3. Unpack the tarball in a temporary directory (**not** directly in - Python's ``site-packages``) and run ``install.py`` with admin - rights. On Windows systems it may be sufficient to double-click - ``install.py``. On Unix or Mac OS X, type:: - - su - (enter admin password) - ./install.py - - See Installation_ below for details. - -4. Use a front-end tool from the "tools" subdirectory of the same - directory as in step 3. For example:: - - cd tools - ./rst2html.py ../FAQ.txt ../FAQ.html (Unix) - python rst2html.py ..\FAQ.txt ..\FAQ.html (Windows) - - See Usage_ below for details. - - -Purpose -======= - -The purpose of the Docutils project is to create a set of tools for -processing plaintext documentation into useful formats, such as HTML, -XML, and LaTeX. Support for the following sources has been -implemented: - -* Standalone files. - -* `PEPs (Python Enhancement Proposals)`_. - -Support for the following sources is planned: - -* Inline documentation from Python modules and packages, extracted - with namespace context. - -* Email (RFC-822 headers, quoted excerpts, signatures, MIME parts). - -* Wikis, with global reference lookups of "wiki links". - -* Compound documents, such as multiple chapter files merged into a - book. - -* And others as discovered. - -.. _PEPs (Python Enhancement Proposals): - http://www.python.org/peps/pep-0012.html - - -Releases & Snapshots -==================== - -While we are trying to follow a "release early & often" policy, -features are added very frequently. Since the code in the Subversion -repository is usually in a bug-free state, we recommend that you use -the current snapshot (which is usually updated within an hour of -changes being committed to the repository): - -* Snapshot of Docutils code, documentation, front-end tools, and - tests: http://docutils.sf.net/docutils-snapshot.tgz - -* Snapshot of the Sandbox (experimental, contributed code): - http://docutils.sf.net/docutils-sandbox-snapshot.tgz - -To keep up to date on the latest developments, download fresh copies -of the snapshots regularly. New functionality is being added weekly, -sometimes daily. (There's also the `Subversion repository`_.) - -.. _Subversion repository: docs/dev/repository.html - - -Requirements -============ - -To run the code, Python 2.2 or later [1]_ must already be installed. -The latest release is recommended. Python is available from -http://www.python.org/. - -The `Python Imaging Library`, or PIL, is used for some image -manipulation operations if it is installed. - -.. [1] Python 2.1 may be used providing the compiler package is - installed. The compiler package can be found in the Tools/ - directory of Python 2.1's source distribution. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ -.. _Optik: http://optik.sourceforge.net/ - - -Project Files & Directories -=========================== - -* README.txt: You're reading it. - -* COPYING.txt: Public Domain Dedication and copyright details for - non-public-domain files (most are PD). - -* FAQ.txt: Frequently Asked Questions (with answers!). - -* RELEASE-NOTES.txt: Summary of the major changes in recent releases. - -* HISTORY.txt: A detailed change log, for the current and all previous - project releases. - -* BUGS.txt: Known bugs, and how to report a bug. - -* THANKS.txt: List of contributors. - -* setup.py: Installation script. See "Installation" below. - -* install.py: Quick & dirty installation script. Just run it. For - any kind of customization or help though, setup.py must be used. - -* docutils: The project source directory, installed as a Python - package. - -* extras: Directory for third-party modules that Docutils depends on. - These are only installed if they're not already present. - -* docs: The project documentation directory. Read ``docs/index.txt`` - for an overview. - -* docs/user: The project user documentation directory. Contains the - following documents, among others: - - - docs/user/tools.txt: Docutils Front-End Tools - - docs/user/latex.txt: Docutils LaTeX Writer - - docs/user/rst/quickstart.txt: A ReStructuredText Primer - - docs/user/rst/quickref.html: Quick reStructuredText (HTML only) - -* docs/ref: The project reference directory. - ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText - reference. - -* licenses: Directory containing copies of license files for - non-public-domain files. - -* tools: Directory for Docutils front-end tools. See - ``docs/user/tools.txt`` for documentation. - -* test: Unit tests. Not required to use the software, but very useful - if you're planning to modify it. See `Running the Test Suite`_ - below. - - -Installation -============ - -The first step is to expand the ``.tgz`` archive in a temporary -directory (**not** directly in Python's ``site-packages``). It -contains a distutils setup file "setup.py". OS-specific installation -instructions follow. - - -GNU/Linux, BSDs, Unix, Mac OS X, etc. -------------------------------------- - -1. Open a shell. - -2. Go to the directory created by expanding the archive:: - - cd <archive_directory_path> - -3. Install the package:: - - python setup.py install - - If the python executable isn't on your path, you'll have to specify - the complete path, such as /usr/local/bin/python. You may need - root permissions to complete this step. - - You can also just run install.py; it does the same thing. - - -Windows -------- - -Just double-click ``install.py``. If this doesn't work, try the -following: - -1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're - calling it these days). - -2. Go to the directory created by expanding the archive:: - - cd <archive_directory_path> - -3. Install the package:: - - <path_to_python.exe>\python setup.py install - - -Usage -===== - -After unpacking and installing the Docutils package, the following -shell commands will generate HTML for all included documentation:: - - cd <archive_directory_path>/tools - ./buildhtml.py ../ - -On Windows systems, type:: - - cd <archive_directory_path>\tools - python buildhtml.py .. - -The final directory name of the ``<archive_directory_path>`` is -"docutils" for snapshots. For official releases, the directory may be -called "docutils-X.Y.Z", where "X.Y.Z" is the release version. -Alternatively:: - - cd <archive_directory_path> - tools/buildhtml.py --config=tools/docutils.conf (Unix) - python tools\buildhtml.py --config=tools\docutils.conf (Windows) - -Some files may generate system messages (warnings and errors). The -``docs/user/rst/demo.txt`` file (under the archive directory) contains -5 intentional errors. (They test the error reporting mechanism!) - -There are many front-end tools in the unpacked "tools" subdirectory. -You may want to begin with the "rst2html.py" front-end tool. Most -tools take up to two arguments, the source path and destination path, -with STDIN and STDOUT being the defaults. Use the "--help" option to -the front-end tools for details on options and arguments. See -Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation. - -The package modules are continually growing and evolving. The -``docutils.statemachine`` module is usable independently. It contains -extensive inline documentation (in reStructuredText format of course). - -Contributions are welcome! - - -Running the Test Suite -====================== - -To run the entire test suite, after installation_ open a shell and use -the following commands:: - - cd <archive_directory_path>/test - ./alltests.py - -Under Windows, type:: - - cd <archive_directory_path>\test - python alltests.py - -You should see a long line of periods, one for each test, and then a -summary like this:: - - Ran 518 tests in 24.653s - - OK - Elapsed time: 26.189 seconds - -The number of tests will grow over time, and the times reported will -depend on the computer running the tests. The difference between the -two times represents the time required to set up the tests (import -modules, create data structures, etc.). - -If any of the tests fail, please `open a bug report`_, `send email`_, -or post a message via the `web interface`_. Please include all -relevant output, information about your operating system, Python -version, and Docutils version. To see the Docutils version, use these -commands in the shell:: - - cd ../tools - ./quicktest.py --version - -Windows users type these commands:: - - cd ..\tools - python quicktest.py --version - -.. _open a bug report: - http://sourceforge.net/tracker/?group_id=38414&atid=422030 -.. _send email: mailto:docutils-users@lists.sourceforge.net - ?subject=Test%20suite%20failure -.. _web interface: http://post.gmane.org/post.php - ?group=gmane.text.docutils.user&subject=Test+suite+failure - - -Getting Help -============ - -If you have questions or need assistance with Docutils or -reStructuredText, please post a message to the Docutils-users_ mailing -list. - -.. _Docutils-users: docs/user/mailing-lists.html#docutils-users - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt deleted file mode 100644 index 31a1e3dee..000000000 --- a/docutils/RELEASE-NOTES.txt +++ /dev/null @@ -1,173 +0,0 @@ -======================== - Docutils Release Notes -======================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Date: $Date$ -:Revision: $Revision$ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - - -This document summarizes the major changes in recent releases. For a -more detailed list of changes, please see the `Docutils History`_. - -.. _Docutils History: HISTORY.html - -.. contents:: - - -Release 0.4 (2006-01-09) -======================== - -.. Note:: - - Docutils 0.4.x is the last version that will support Python 2.1. - Docutils 0.5 will *not* be compatible with Python 2.1; Python 2.2 - or later will be required. - - Docutils 0.4.x is the last version that will make compromises in - its HTML output for Netscape Navigator 4. Docutils 0.5 will - require more up-to-date browsers (the exact definition is to be - determined). - -Components: - -* Added an `S5/HTML writer`__ and the rst2s5.py__ front end: - multi-platform, multi-browser HTML slide shows. - - __ docs/user/slide-shows.html - __ docs/user/tools.html#rst2s5-py - -* The newlatex2e writer is nearing completion. - -* Added a DocTree reader, ``publish_doctree`` and - ``publish_from_doctree`` convenience functions, for document tree - extraction and reprocessing. - -reStructuredText: - -* Added directives: "container__" (generic block-level container), - "default-role__" (role used for \`backtick\` syntax), "title__" - (document title metadata), and "date__" (generate the current local - date, for substitution definitions). - - __ docs/ref/rst/directives.html#container - __ docs/ref/rst/directives.html#default-role - __ docs/ref/rst/directives.html#title - __ docs/ref/rst/directives.html#date - -* Length units are now supported for image__ sizes. - - __ docs/ref/rst/directives.html#image - -* Added `standard definition files`__ for special characters etc. - - __ docs/ref/rst/definitions.html - -Internationalization: - -* Added Japanese and Simplified Chinese language mappings, and support - for double-width CJK-characters in tables and section titles. - -Documentation: - -* Added a `guide for distributors`__ (package maintainers) and a - `guide for developers`__. - - __ docs/dev/distributing.html - __ docs/dev/hacking.html - -General: - -* Added significant `Emacs support for reST`__. - - __ docs/user/emacs.html - -* Added a `--strip-comments`__ option. - - __ docs/user/config.html#strip-comments - -* `--embed-stylesheet`__ is now the default for the HTML writer - (rather than --link-stylesheet). - - __ docs/user/config.html#embed-stylesheet - - -Release 0.3.9 (2005-05-26) -========================== - -* Added "file_insertion_enabled__" and "raw_enabled__" settings. - - __ docs/user/config.html#file-insertion-enabled - __ docs/user/config.html#raw-enabled - -* Added `auto-enumerated lists`__. - - __ docs/ref/rst/restructuredtext.html#enumerated-lists - -* Added `"header" and "footer"`__ directives. - - __ docs/ref/rst/directives.html#document-header-footer - -* Added "list-table__" directive. - - __ docs/ref/rst/directives.html#list-table - -* Added support for `section subtitles`__. - - __ docs/user/config.html#sectsubtitle-xform - -* Added "field_name_limit__" and "option_limit__" settings to HTML writer. - - __ docs/user/config.html#field-name-limit - __ docs/user/config.html#option-limit - -* Added "cloak_email_addresses__" setting to HTML writer. - - __ docs/user/config.html#cloak-email-addresses - -* UTF-8 BOMs are now removed from the input stream. - - -Release 0.3.7 (2004-12-24) -========================== - -* A special "`line block`__" syntax has been added. (Also see the - `quick reference`__.) - - __ docs/ref/rst/restructuredtext.html#line-blocks - __ docs/user/rst/quickref.html#line-blocks - -* Empty sections are now allowed. - -* A "raw__" role has been added. - - __ docs/ref/rst/roles.html#raw - -* The LaTeX writer now escapes consecutive dashes (like "--" or "---") - so that they are no longer transformed by LaTeX to en or em dashes. - (Please see the FAQ__ for how to represent such dashes.) - - __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document - -* A `dependency recorder`__ has been added. - - __ docs/user/config.html#record-dependencies - -* A directive has been added for `compound paragraphs`__. - - __ docs/ref/rst/directives.html#compound-paragraph - - -Release 0.3.5 (2004-07-29) -========================== - -* Improved, extended and reorganized the documentation__. - - __ docs/index.html - -* Added "csv-table__" directive. - - __ docs/ref/rst/directives.html#csv-table diff --git a/docutils/THANKS.txt b/docutils/THANKS.txt deleted file mode 100644 index 36cbc3019..000000000 --- a/docutils/THANKS.txt +++ /dev/null @@ -1,161 +0,0 @@ -.. -*- coding: utf-8 -*- - -Acknowledgements -================ - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -I would like to acknowledge the people who have made a direct impact -on the Docutils project, knowingly or not, in terms of encouragement, -suggestions, criticism, bug reports, code contributions, cash -donations, tasty treats, and related projects: - -* Aahz -* David Abrahams -* David Ascher -* Ned Batchelder -* Heiko Baumann -* Anthony Baxter -* Eric Bellot -* Frank Bennett -* Ian Bicking -* Marek Blaha -* Martin Blais -* Stephen Boulet -* Fred Bremmer -* Simon Budig -* Bill Bumgarner -* Brett Cannon -* Greg Chapman -* Nicolas Chauveau -* Beni Cherniavsky -* Adam Chodorowski -* Brent Cook -* Laura Creighton -* Artur de Sousa Rocha -* Stephan Deibel & `Wing IDE <http://wingide.com/>`__ -* Jason Diamond -* William Dode -* Fred Drake -* Reggie Dugard -* Dethe Elza -* Marcus Ertl -* Benja Fallenstein -* fantasai -* Stefane Fermigier -* Michael Foord -* Jim Fulton -* Peter Funk -* Lele Gaifax -* Dinu C. Gherman -* Matt Gilbert -* Jorge Gonzalez -* Engelbert Gruber -* Jacob Hallen -* Simon Hefti -* Doug Hellmann -* Marc Herbert -* Juergen Hermann -* Jannie Hofmeyr -* Steve Holden -* Michael Hudson -* Marcelo Huerta San Martin -* Ludger Humbert -* Jeremy Hylton -* Tony Ibbs -* Alan G. Isaac -* Alan Jaffray -* Joe YS Jaw -* Dmitry Jemerov -* Richard Jones -* Andreas Jung -* Robert Kern -* Garth Kidd -* Philipp Knüsel -* Axel Kollmorgen -* Jeff Kowalczyk -* Martin F. Krafft -* Dave Kuhlman -* Lloyd Kvam -* Kirill Lapshin -* Nicola Larosa -* Daniel Larsson -* Marc-Andre Lemburg -* Julien Letessier -* Chris Liechti -* Wolfgang Lipp -* Edward Loper -* Dallas Mahrt -* Mikolaj Machowski -* Ken Manheimer -* Bob Marshall -* Mark McEahern -* Vincent McIntyre -* John F Meinel Jr -* Eric Meyer -* Günter Milde -* Skip Montanaro -* Paul Moore -* Nigel W. Moriarty -* Hisashi Morita -* Mark Nodine -* Omidyar Network (Pierre Omidyar & Doug Solomon) -* Panjunyong -* Patrick K. O'Brien -* Michel Pelletier -* Sam Penrose -* Tim Peters -* Pearu Peterson -* Martijn Pieters -* Mark Pilgrim -* Brett g Porter -* David Priest -* Jens Quade -* Edward K. Ream -* Andy Robinson -* Tavis Rudd -* Tracy Ruggles -* Oliver Rutherfurd -* Luc Saffre -* Kenichi Sato -* Ueli Schlaepfer -* Gunnar Schwant -* Bill Sconce -* Frank Siebenlist -* Bruce Smith -* Nir Soffer -* Asko Soukka -* Darek Suchojad -* Roman Suzi -* Janet Swisher -* tav -* Kent Tenney -* Bob Tolbert -* Paul Tremblay -* Laurence Tratt -* Adrian van den Dries -* Guido van Rossum -* Miroslav Vasko -* Paul Viren -* Martin von Loewis -* Greg Ward -* Barry Warsaw -* Wu Wei -* Edward Welbourne -* Felix Wiemann -* Anthony Williams -* Ka-Ping Yee -* Moshe Zadka -* Shmuel Zeigerman - -Thank you! - -Special thanks to `SourceForge <http://sourceforge.net>`__ and the -`Python Software Foundation <http://www.python.org/psf/>`__. - -Hopefully I haven't forgotten anyone or misspelled any names; -apologies (and please let me know!) if I have. diff --git a/docutils/docutils/__init__.py b/docutils/__init__.py index a390a9f2b..a390a9f2b 100644 --- a/docutils/docutils/__init__.py +++ b/docutils/__init__.py diff --git a/docutils/docutils/core.py b/docutils/core.py index 598ec8e68..598ec8e68 100644 --- a/docutils/docutils/core.py +++ b/docutils/core.py diff --git a/docutils/docs/api/cmdline-tool.txt b/docutils/docs/api/cmdline-tool.txt deleted file mode 100644 index 3d3d4a635..000000000 --- a/docutils/docs/api/cmdline-tool.txt +++ /dev/null @@ -1,68 +0,0 @@ -=============================================== - Inside A Docutils Command-Line Front-End Tool -=============================================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -`The Docutils Publisher`_ class was set up to make building -command-line tools easy. All that's required is to choose components -and supply settings for variations. Let's take a look at a typical -command-line front-end tool, ``tools/rst2html.py``, from top to -bottom. - -On Unixish systems, it's best to make the file executable (``chmod +x -file``), and supply an interpreter on the first line, the "shebang" or -"hash-bang" line:: - - #!/usr/bin/env python - -Windows systems can be set up to associate the Python interpreter with -the ``.py`` extension. - -Next are some comments providing metadata:: - - # Author: David Goodger - # Contact: goodger@python.org - # Revision: $Revision: ... - # Date: $Date: ... - # Copyright: This module has been placed in the public domain. - -The module docstring describes the purpose of the tool:: - - """ - A minimal front end to the Docutils Publisher, producing HTML. - """ - -This next block attempts to invoke locale support for -internationalization services, specifically text encoding. It's not -supported on all platforms though, so it's forgiving:: - - try: - import locale - locale.setlocale(locale.LC_ALL, '') - except: - pass - -The real work will be done by the code that's imported here:: - - from docutils.core import publish_cmdline, default_description - -We construct a description of the tool, for command-line help:: - - description = ('Generates (X)HTML documents from standalone ' - 'reStructuredText sources. ' + default_description) - -Now we call the Publisher convenience function, which takes over. -Most of it's defaults are used ("standalone" Reader, -"reStructuredText" Parser, etc.). The HTML Writer is chosen by name, -and a description for command-line help is passed in:: - - publish_cmdline(writer_name='html', description=description) - -That's it! `The Docutils Publisher`_ takes care of the rest. - -.. _The Docutils Publisher: ./publisher.html diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt deleted file mode 100644 index 73cfc0ef2..000000000 --- a/docutils/docs/api/publisher.txt +++ /dev/null @@ -1,176 +0,0 @@ -======================== - The Docutils Publisher -======================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Publisher Convenience Functions -=============================== - -Each of these functions set up a ``docutils.core.Publisher`` object, -then call its ``publish`` method. ``docutils.core.Publisher.publish`` -handles everything else. There are five convenience functions in the -``docutils.core`` module: - -:_`publish_cmdline`: for command-line front-end tools, like - ``rst2html.py``. There are several examples in the ``tools/`` - directory. A detailed analysis of one such tool is in `Inside A - Docutils Command-Line Front-End Tool`_ - -:_`publish_file`: for programmatic use with file-like I/O. In - addition to writing the encoded output to a file, also returns the - encoded output as a string. - -:_`publish_string`: for programmatic use with string I/O. Returns - the encoded output as a string. - -:_`publish_parts`: for programmatic use with string input; returns a - dictionary of document parts. Dictionary keys are the names of - parts, and values are Unicode strings; encoding is up to the client. - Useful when only portions of the processed document are desired. - See `publish_parts Details`_ below. - - There are usage examples in the `docutils/examples.py`_ module. - -:_`publish_programmatically`: for custom programmatic use. This - function implements common code and is used by ``publish_file``, - ``publish_string``, and ``publish_parts``. It returns a 2-tuple: - the encoded string output and the Publisher object. - -.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html -.. _docutils/examples.py: ../../docutils/examples.py - - -Configuration -------------- - -To pass application-specific setting defaults to the Publisher -convenience functions, use the ``settings_overrides`` parameter. Pass -a dictionary of setting names & values, like this:: - - overrides = {'input_encoding': 'ascii', - 'output_encoding': 'latin-1'} - output = publish_string(..., settings_overrides=overrides) - -Settings from command-line options override configuration file -settings, and they override application defaults. For details, see -`Docutils Runtime Settings`_. See `Docutils Configuration Files`_ for -details about individual settings. - -.. _Docutils Runtime Settings: ./runtime-settings.html -.. _Docutils Configuration Files: ../user/tools.html - - -Encodings ---------- - -The default output encoding of Docutils is UTF-8. If you have any -non-ASCII in your input text, you may have to do a bit more setup. -Docutils may introduce some non-ASCII text if you use -`auto-symbol footnotes`_ or the `"contents" directive`_. - -.. _auto-symbol footnotes: - ../ref/rst/restructuredtext.html#auto-symbol-footnotes -.. _"contents" directive: - ../ref/rst/directives.html#table-of-contents - - -``publish_parts`` Details -========================= - -The ``docutils.core.publish_parts`` convenience function returns a -dictionary of document parts. Dictionary keys are the names of parts, -and values are Unicode strings. - -Each Writer component may publish a different set of document parts, -described below. Currently only the HTML Writer implements more than -the "whole" part. - - -Parts Provided By All Writers ------------------------------ - -_`whole` - ``parts['whole']`` contains the entire formatted document. - - -Parts Provided By the HTML Writer ---------------------------------- - -_`body` - ``parts['body']`` is equivalent to parts['fragment_']. It is - *not* equivalent to parts['html_body_']. - -_`docinfo` - ``parts['docinfo']`` contains the document bibliographic data. - -_`footer` - ``parts['footer']`` contains the document footer content, meant to - appear at the bottom of a web page, or repeated at the bottom of - every printed page. - -_`fragment` - ``parts['fragment']`` contains the document body (*not* the HTML - ``<body>``). In other words, it contains the entire document, - less the document title, subtitle, docinfo, header, and footer. - -_`header` - ``parts['header']`` contains the document header content, meant to - appear at the top of a web page, or repeated at the top of every - printed page. - -_`html_body` - ``parts['html_body']`` contains the HTML ``<body>`` content, less - the ``<body>`` and ``</body>`` tags themselves. - -_`html_head` - ``parts['html_head']`` contains the HTML ``<head>`` content, less - the stylesheet link and the ``<head>`` and ``</head>`` tags - themselves. Since ``publish_parts`` returns Unicode strings and - does not know about the output encoding, the "Content-Type" meta - tag's "charset" value is left unresolved, as "%s":: - - <meta http-equiv="Content-Type" content="text/html; charset=%s" /> - - The interpolation should be done by client code. - -_`html_prolog` - ``parts['html_prolog]`` contains the XML declaration and the - doctype declaration. The XML declaration's "encoding" attribute's - value is left unresolved, as "%s":: - - <?xml version="1.0" encoding="%s" ?> - - The interpolation should be done by client code. - -_`html_subtitle` - ``parts['html_subtitle']`` contains the document subtitle, - including the enclosing ``<h2 class="subtitle">`` & ``</h2>`` - tags. - -_`html_title` - ``parts['html_title']`` contains the document title, including the - enclosing ``<h1 class="title">`` & ``</h1>`` tags. - -_`meta` - ``parts['meta']`` contains all ``<meta ... />`` tags. - -_`stylesheet` - ``parts['stylesheet']`` contains the document stylesheet link. - -_`subtitle` - ``parts['subtitle']`` contains the document subtitle text and any - inline markup. It does not include the enclosing ``<h2>`` & - ``</h2>`` tags. - -_`title` - ``parts['title']`` contains the document title text and any inline - markup. It does not include the enclosing ``<h1>`` & ``</h1>`` - tags. diff --git a/docutils/docs/api/runtime-settings.txt b/docutils/docs/api/runtime-settings.txt deleted file mode 100644 index 2d60aa3e1..000000000 --- a/docutils/docs/api/runtime-settings.txt +++ /dev/null @@ -1,192 +0,0 @@ -=========================== - Docutils Runtime Settings -=========================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Introduction -============ - -Docutils runtime settings are assembled from several sources: -component settings specifications, application settings -specifications, configuration files, and command-line options. -Docutils overlays default and explicitly specified values from these -sources such that settings behave the way we want and expect them to -behave. - -To understand how Docutils deals with runtime settings, the attributes -and parameters involved must first be understood. Begin with the the -docstrings of the attributes of the ``docutils.SettingsSpec`` base -class (in the ``docutils/__init__.py`` module): - -* ``settings_spec`` -* ``settings_defaults`` -* ``settings_default_overrides`` -* ``relative_path_settings`` -* ``config_section`` -* ``config_section_dependencies`` - -Next, several _`convenience function parameters` are also significant -(described in the ``docutils.core.publish_programmatically`` function -docstring): - -* The ``settings`` parameter is a runtime settings - (``docutils.frontend.Values``) object which, if present, is assumed - to be complete (it must include all runtime settings). Also, if the - ``settings`` parameter is present, no further runtime settings - processing is done. In other words, the other parameters, described - below, will have no effect. - -* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is - treated like a fourth component (after the Parser, Reader, and - Writer). In other words, it's the settings specification for the - "Application" itself. - -* ``settings_overrides`` is a dictionary which will override the - defaults of the components (from their settings specs). - -* ``config_section`` specifies the name of an application-specific - configuration file section. - - -.. _command-line tools: - -Runtime Settings Processing for Command-Line Tools -================================================== - -Following along with the actual code is recommended. The -``docutils/__init__.py``, ``docutils/core.py``, and -``docutils.frontend.py`` modules are described. - -1. A command-line front-end tool imports and calls - ``docutils.core.publish_cmdline``. The relevant `convenience - function parameters`_ are described above. - -2. ``docutils.core.publish_cmdline`` initializes a - ``docutils.core.Publisher`` object, then calls its ``publish`` - method. - -3. The ``docutils.core.Publisher`` object's ``publish`` method checks - its ``settings`` attribute to see if it's defined. If it is, no - further runtime settings processing is done. - - If ``settings`` is not defined, ``self.process_command_line`` is - called with the following relevant arguments: - - * ``settings_spec`` - * ``config_section`` - * ``settings_overrides`` (in the form of excess keyword - arguments, collected in the ``defaults`` parameter) - -4. ``self.process_command_line`` calls ``self.setup_option_parser``, - passing ``settings_spec``, ``config_section``, and ``defaults``. - -5. ``self.setup_option_parser`` checks its ``config_section`` - parameter; if defined, it adds that config file section to - ``settings_spec`` (or to a new, empty ``docutils.SettingsSpec`` - object), replacing anything defined earlier. (See `Docutils - Configuration Files`_ for details.) Then it instantiates a new - ``docutils.frontend.OptionParser`` object, passing the following - relevant arguments: - - * ``components``: A tuple of ``docutils.SettingsSpec`` objects, - ``(self.parser, self.reader, self.writer, settings_spec)`` - * ``defaults`` (originally from ``settings_overrides``) - -6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method - calls ``self.populate_from_components`` with ``self.components``, - which consists of ``self`` prepended to the ``components`` tuple it - received. ``self`` (``docutils.frontend.OptionParser``) defines - general Docutils settings. - -7. In ``self.populate_from_components``, for each component passed, - ``component.settings_spec`` is processed and - ``component.settings_defaults`` is applied. Then, for each - component, ``component.settings_default_overrides`` is applied. - This two-loop process ensures that - ``component.settings_default_overrides`` can override the default - settings of any other component. - -8. Back in ``docutils.frontend.OptionParser.__init__``, the - ``defaults`` parameter (derived from the ``settings_overrides`` - parameter of ``docutils.core.Publisher.publish``) is overlaid over - ``self.defaults``. So ``settings_overrides`` has priority over all - ``SettingsSpec`` data. - -9. Next, ``docutils.frontend.OptionParser.__init__`` checks if - configuration files are enabled (its ``read_config_files`` - parameter is true, and ``self.defaults['_disable_config']`` is - false). If they are enabled (and normally, they are), - ``self.get_standard_config_settings`` is called. This reads the - `docutils configuration files`_, and returns a dictionary of - settings. This is then overlaid on ``self.defaults``. So - configuration file settings have priority over all software-defined - defaults. - -10. Back in the ``docutils.core.Publisher`` object, - ``self.setup_option_parser`` returns the ``option_parser`` object - to its caller, ``self.process_command_line``. - -11. ``self.process_command_line`` calls ``option_parser.parse_args``, - which parses all command line options and returns a - ``docutils.frontend.Values`` object. This is assigned to the - ``docutils.core.Publisher`` object's ``self.settings``. So - command-line options have priority over configuration file - settings. - - When ``option_parser.parse_args`` is called, the source and - destination command-line arguments are also parsed, and assigned - to the ``_source`` and ``_destination`` attributes of what becomes - the ``docutils.core.Publisher`` object's ``self.settings``. - -12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is - called with no arguments. If either ``self.source`` or - ``self.destination`` are not set, the corresponding - ``self.set_source`` and ``self.set_destination`` are called, - effectively with no arguments. - -13. ``self.set_source`` checks for a ``source_path`` parameter, and if - there is none (which is the case for command-line use), it is - taken from ``self.settings._source``. ``self.source`` is set by - instantiating a ``self.source_class`` object. For command-line - front-end tools, the default ``self.source_class`` is used, - ``docutils.io.FileInput``. - -14. ``self.set_destination`` does the same job for the destination - that ``self.set_source`` does for the source (the default - ``self.destination_class`` is ``docutils.io.FileOutput``). - -.. _Docutils Configuration Files: ../user/config.html - - -Runtime Settings Processing From Applications -============================================= - -Applications process runtime settings in a different way than -`command-line tools`_ do. Instead of calling ``publish_cmdline``, the -application calls one of ``publish_file``, ``publish_string``, or -``publish_parts``. These in turn call ``publish_programmatically``, -which implements a generic programmatic interface. Although an -application may also call ``publish_programmatically`` directly, it is -not recommended (if it does seem to be necessary, please write to the -Docutils-develop_ mailing list). - -``publish_programmatically`` accepts the same `convenience function -parameters`_ as ``publish_cmdline``. Where things differ is that -programmatic use does no command-line processing. Instead of calling -``docutils.Publisher.process_command_line`` (as ``publish_cmdline`` -does, via ``docutils.Publisher.publish``), -``docutils.Publisher.process_programmatic_settings`` is called to set -up the runtime settings. - -.. copy & modify the list from command-line tools? - - -.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop diff --git a/docutils/docs/dev/distributing.txt b/docutils/docs/dev/distributing.txt deleted file mode 100644 index c81807279..000000000 --- a/docutils/docs/dev/distributing.txt +++ /dev/null @@ -1,146 +0,0 @@ -=============================== - Docutils_ Distributor's Guide -=============================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - -This document describes how to create packages of Docutils (e.g. for -shipping with a Linux distribution). If you have any questions, -please direct them to the Docutils-develop_ mailing list. - -First, please download the most current `release tarball`_ and unpack -it. - -.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop -.. _release tarball: http://docutils.sourceforge.net/#download - - -Dependencies -============ - -Docutils has the following dependencies: - -* Python 2.1 or later is required. While the compiler package from - the Tools/ directory of Python's source distribution must be - installed for the test suite to pass with Python 2.1, the - functionality available to end users should be available without the - compiler package as well. So just use ">= Python 2.1" in the - dependencies. - -* Docutils may optionally make use of the PIL (`Python Imaging - Library`_). If PIL is present, it is automatically detected by - Docutils. - -* There are three files in the ``extras/`` directory of the Docutils - distribution, ``optparse.py``, ``textwrap.py``, and ``roman.py``. - For Python 2.1/2.2, all of them must be installed (into the - ``site-packages/`` directory). Python 2.3 and later versions have - ``textwrap`` and ``optparse`` included in the standard library, so - only ``roman.py`` is required here; installing the other files won't - hurt, though. - - These files are automatically installed by the setup script (when - calling "python setup.py install"). - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - - -Python Files -============ - -The Docutils Python files must be installed into the -``site-packages/`` directory of Python. Running ``python setup.py -install`` should do the trick, but if you want to place the files -yourself, you can just install the ``docutils/`` directory of the -Docutils tarball to ``/usr/lib/python/site-packages/docutils/``. In -this case you should also compile the Python files to ``.pyc`` and/or -``.pyo`` files so that Docutils doesn't need to be recompiled every -time it's executed. - - -Executables -=========== - -The executable front-end tools are located in the ``tools/`` directory -of the Docutils tarball. - -The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for -end-users. You should install them to ``/usr/bin/``. You do not need -to change the names (e.g. to ``docutils-rst2html.py``) because the -``rst2`` prefix is unique. - - -Documentation -============= - -The documentation should be generated using ``buildhtml.py``. To -generate HTML for all documentation files, go to the ``tools/`` -directory and run:: - - # Place html4css1.css in base directory. - cp ../docutils/writers/html4css1/html4css1.css .. - ./buildhtml.py --stylesheet-path=../html4css1.css .. - -Then install the following files to ``/usr/share/doc/docutils/`` (or -wherever you install documentation): - -* All ``.html`` and ``.txt`` files in the base directory. - -* The ``docs/`` directory. - - Do not install the contents of the ``docs/`` directory directly to - ``/usr/share/doc/docutils/``; it's incomplete and would contain - invalid references! - -* The ``licenses/`` directory. - -* ``html4css1.css`` in the base directory. - - -Removing the ``.txt`` Files ---------------------------- - -If you are tight with disk space, you can remove all ``.txt`` files in -the tree except for: - -* those in the ``licenses/`` directory because they have not been - processed to HTML and - -* ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should - be readable in source form. - -Before you remove the ``.txt`` files you should rerun ``buildhtml.py`` -with the ``--no-source-link`` switch to avoid broken references to the -source files. - - -Other Files -=========== - -You may want to install the Emacs-Lisp files -``tools/editors/emacs/*.el`` into the appropriate directory. - - -Configuration File -================== - -It is possible to have a system-wide configuration file at -``/etc/docutils.conf``. However, this is usually not necessary. You -should *not* install ``tools/docutils.conf`` into ``/etc/``. - - -Tests -===== - -While you probably do not need to ship the tests with your -distribution, you can test your package by installing it and then -running ``alltests.py`` from the ``tests/`` directory of the Docutils -tarball. diff --git a/docutils/docs/dev/enthought-plan.txt b/docutils/docs/dev/enthought-plan.txt deleted file mode 100644 index 0ab0d3c83..000000000 --- a/docutils/docs/dev/enthought-plan.txt +++ /dev/null @@ -1,480 +0,0 @@ -=========================================== - Plan for Enthought API Documentation Tool -=========================================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: 2004 by `Enthought, Inc. <http://www.enthought.com>`_ -:License: `Enthought License`_ (BSD-style) - -.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt - -This document should be read in conjunction with the `Enthought API -Documentation Tool RFP`__ prepared by Janet Swisher. - -__ enthought-rfp.html - -.. contents:: -.. sectnum:: - - -Introduction -============ - -In March 2004 at I met Eric Jones, president and CTO of `Enthought, -Inc.`_, at `PyCon 2004`_ in Washington DC. He told me that Enthought -was using reStructuredText_ for source code documentation, but they -had some issues. He asked if I'd be interested in doing some work on -a customized API documentation tool. Shortly after PyCon, Janet -Swisher, Enthought's senior technical writer, contacted me to work out -details. Some email, a trip to Austin in May, and plenty of Texas -hospitality later, we had a project. This document will record the -details, milestones, and evolution of the project. - -In a nutshell, Enthought is sponsoring the implementation of an open -source API documentation tool that meets their needs. Fortuitously, -their needs coincide well with the "Python Source Reader" description -in `PEP 258`_. In other words, Enthought is funding some significant -improvements to Docutils, improvements that were planned but never -implemented due to time and other constraints. The implementation -will take place gradually over several months, on a part-time basis. - -This is an ideal example of cooperation between a corporation and an -open-source project. The corporation, the project, I personally, and -the community all benefit. Enthought, whose commitment to open source -is also evidenced by their sponsorship of SciPy_, benefits by -obtaining a useful piece of software, much more quickly than would -have been possible without their support. Docutils benefits directly -from the implementation of one of its core subsystems. I benefit from -the funding, which allows me to justify the long hours to my wife and -family. All the corporations, projects, and individuals that make up -the community will benefit from the end result, which will be great. - -All that's left now is to actually do the work! - -.. _PyCon 2004: http://pycon.org/dc2004/ -.. _reStructuredText: http://docutils.sf.net/rst.html -.. _SciPy: http://www.scipy.org/ - - -Development Plan -================ - -1. Analyze prior art, most notably Epydoc_ and HappyDoc_, to see how - they do what they do. I have no desire to reinvent wheels - unnecessarily. I want to take the best ideas from each tool, - combined with the outline in `PEP 258`_ (which will evolve), and - build at least the foundation of the definitive Python - auto-documentation tool. - - .. _Epydoc: http://epydoc.sourceforge.net/ - .. _HappyDoc: http://happydoc.sourceforge.net/ - .. _PEP 258: - http://docutils.sf.net/docs/peps/pep-0258.html#python-source-reader - -2. Decide on a base platform. The best way to achieve Enthought's - goals in a reasonable time frame may be to extend Epydoc or - HappyDoc. Or it may be necessary to start fresh. - -3. Extend the reStructuredText parser. See `Proposed Changes to - reStructuredText`_ below. - -4. Depending on the base platform chosen, build or extend the - docstring & doc comment extraction tool. This may be the biggest - part of the project, but I won't be able to break it down into - details until more is known. - - -Repository -========== - -If possible, all software and documentation files will be stored in -the Subversion repository of Docutils and/or the base project, which -are all publicly-available via anonymous pserver access. - -The Docutils project is very open about granting Subversion write -access; so far, everyone who asked has been given access. Any -Enthought staff member who would like Subversion write access will get -it. - -If either Epydoc or HappyDoc is chosen as the base platform, I will -ask the project's administrator for CVS access for myself and any -Enthought staff member who wants it. If sufficient access is not -granted -- although I doubt that there would be any problem -- we may -have to begin a fork, which could be hosted on SourceForge, on -Enthought's Subversion server, or anywhere else deemed appropriate. - - -Copyright & License -=================== - -Most existing Docutils files have been placed in the public domain, as -follows:: - - :Copyright: This document has been placed in the public domain. - -This is in conjunction with the "Public Domain Dedication" section of -COPYING.txt__. - -__ http://docutils.sourceforge.net/COPYING.html - -The code and documentation originating from Enthought funding will -have Enthought's copyright and license declaration. While I will try -to keep Enthought-specific code and documentation separate from the -existing files, there will inevitably be cases where it makes the most -sense to extend existing files. - -I propose the following: - -1. New files related to this Enthought-funded work will be identified - with the following field-list headers:: - - :Copyright: 2004 by Enthought, Inc. - :License: Enthought License (BSD Style) - - The license field text will be linked to the license file itself. - -2. For significant or major changes to an existing file (more than 10% - change), the headers shall change as follows (for example):: - - :Copyright: 2001-2004 by David Goodger - :Copyright: 2004 by Enthought, Inc. - :License: BSD-style - - If the Enthought-funded portion becomes greater than the previously - existing portion, Enthought's copyright line will be shown first. - -3. In cases of insignificant or minor changes to an existing file - (less than 10% change), the public domain status shall remain - unchanged. - -A section describing all of this will be added to the Docutils -`COPYING`__ instructions file. - -If another project is chosen as the base project, similar changes -would be made to their files, subject to negotiation. - -__ http://docutils.sf.net/COPYING.html - - -Proposed Changes to reStructuredText -==================================== - -Doc Comment Syntax ------------------- - -The "traits" construct is implemented as dictionaries, where -standalone strings would be Python syntax errors. Therefore traits -require documentation in comments. We also need a way to -differentiate between ordinary "internal" comments and documentation -comments (doc comments). - -Javadoc uses the following syntax for doc comments:: - - /** - * The first line of a multi-line doc comment begins with a slash - * and *two* asterisks. The doc comment ends normally. - */ - -Python doesn't have multi-line comments; only single-line. A similar -convention in Python might look like this:: - - ## - # The first line of a doc comment begins with *two* hash marks. - # The doc comment ends with the first non-comment line. - 'data' : AnyValue, - - ## The double-hash-marks could occur on the first line of text, - # saving a line in the source. - 'data' : AnyValue, - -How to indicate the end of the doc comment? :: - - ## - # The first line of a doc comment begins with *two* hash marks. - # The doc comment ends with the first non-comment line, or another - # double-hash-mark. - ## - # This is an ordinary, internal, non-doc comment. - 'data' : AnyValue, - - ## First line of a doc comment, terse syntax. - # Second (and last) line. Ends here: ## - # This is an ordinary, internal, non-doc comment. - 'data' : AnyValue, - -Or do we even need to worry about this case? A simple blank line -could be used:: - - ## First line of a doc comment, terse syntax. - # Second (and last) line. Ends with a blank line. - - # This is an ordinary, internal, non-doc comment. - 'data' : AnyValue, - -Other possibilities:: - - #" Instead of double-hash-marks, we could use a hash mark and a - # quotation mark to begin the doc comment. - 'data' : AnyValue, - - ## We could require double-hash-marks on every line. This has the - ## added benefit of delimiting the *end* of the doc comment, as - ## well as working well with line wrapping in Emacs - ## ("fill-paragraph" command). - # Ordinary non-doc comment. - 'data' : AnyValue, - - #" A hash mark and a quotation mark on each line looks funny, and - #" it doesn't work well with line wrapping in Emacs. - 'data' : AnyValue, - -These styles (repeated on each line) work well with line wrapping in -Emacs:: - - ## #> #| #- #% #! #* - -These styles do *not* work well with line wrapping in Emacs:: - - #" #' #: #) #. #/ #@ #$ #^ #= #+ #_ #~ - -The style of doc comment indicator used could be a runtime, global -and/or per-module setting. That may add more complexity than it's -worth though. - - -Recommendation -`````````````` - -I recommend adopting "#*" on every line:: - - # This is an ordinary non-doc comment. - - #* This is a documentation comment, with an asterisk after the - #* hash marks on every line. - 'data' : AnyValue, - -I initially recommended adopting double-hash-marks:: - - # This is an ordinary non-doc comment. - - ## This is a documentation comment, with double-hash-marks on - ## every line. - 'data' : AnyValue, - -But Janet Swisher rightly pointed out that this could collide with -ordinary comments that are then block-commented. This applies to -double-hash-marks on the first line only as well. So they're out. - -On the other hand, the JavaDoc-comment style ("##" on the first line -only, "#" after that) is used in Fredrik Lundh's PythonDoc_. It may -be worthwhile to conform to this syntax, reinforcing it as a standard. -PythonDoc does not support terse doc comments (text after "##" on the -first line). - -.. _PythonDoc: http://effbot.org/zone/pythondoc.htm - - -Update -`````` - -Enthought's Traits system has switched to a metaclass base, and traits -are now defined via ordinary attributes. Therefore doc comments are -no longer absolutely necessary; attribute docstrings will suffice. -Doc comments may still be desirable though, since they allow -documentation to precede the thing being documented. - - -Docstring Density & Whitespace Minimization -------------------------------------------- - -One problem with extensively documented classes & functions, is that -there is a lot of screen space wasted on whitespace. Here's some -current Enthought code (from lib/cp/fluids/gassmann.py):: - - def max_gas(temperature, pressure, api, specific_gravity=.56): - """ - Computes the maximum dissolved gas in oil using Batzle and - Wang (1992). - - Parameters - ---------- - temperature : sequence - Temperature in degrees Celsius - pressure : sequence - Pressure in MPa - api : sequence - Stock tank oil API - specific_gravity : sequence - Specific gravity of gas at STP, default is .56 - - Returns - ------- - max_gor : sequence - Maximum dissolved gas in liters/liter - - Description - ----------- - This estimate is based on equations given by Mavko, Mukerji, - and Dvorkin, (1998, pp. 218-219, or 2003, p. 236) obtained - originally from Batzle and Wang (1992). - """ - code... - -The docstring is 24 lines long. - -Rather than using subsections, field lists (which exist now) can save -6 lines:: - - def max_gas(temperature, pressure, api, specific_gravity=.56): - """ - Computes the maximum dissolved gas in oil using Batzle and - Wang (1992). - - :Parameters: - temperature : sequence - Temperature in degrees Celsius - pressure : sequence - Pressure in MPa - api : sequence - Stock tank oil API - specific_gravity : sequence - Specific gravity of gas at STP, default is .56 - :Returns: - max_gor : sequence - Maximum dissolved gas in liters/liter - :Description: This estimate is based on equations given by - Mavko, Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, - p. 236) obtained originally from Batzle and Wang (1992). - """ - code... - -As with the "Description" field above, field bodies may begin on the -same line as the field name, which also saves space. - -The output for field lists is typically a table structure. For -example: - - :Parameters: - temperature : sequence - Temperature in degrees Celsius - pressure : sequence - Pressure in MPa - api : sequence - Stock tank oil API - specific_gravity : sequence - Specific gravity of gas at STP, default is .56 - :Returns: - max_gor : sequence - Maximum dissolved gas in liters/liter - :Description: - This estimate is based on equations given by Mavko, - Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236) - obtained originally from Batzle and Wang (1992). - -But the definition lists describing the parameters and return values -are still wasteful of space. There are a lot of half-filled lines. - -Definition lists are currently defined as:: - - term : classifier - definition - -Where the classifier part is optional. Ideas for improvements: - -1. We could allow multiple classifiers:: - - term : classifier one : two : three ... - definition - -2. We could allow the definition on the same line as the term, using - some embedded/inline markup: - - * "--" could be used, but only in limited and well-known contexts:: - - term -- definition - - This is the syntax used by StructuredText (one of - reStructuredText's predecessors). It was not adopted for - reStructuredText because it is ambiguous -- people often use "--" - in their text, as I just did. But given a constrained context, - the ambiguity would be acceptable (or would it?). That context - would be: in docstrings, within a field list, perhaps only with - certain well-defined field names (parameters, returns). - - * The "constrained context" above isn't really enough to make the - ambiguity acceptable. Instead, a slightly more verbose but far - less ambiguous syntax is possible:: - - term === definition - - This syntax has advantages. Equals signs lend themselves to the - connotation of "definition". And whereas one or two equals signs - are commonly used in program code, three equals signs in a row - have no conflicting meanings that I know of. (Update: there - *are* uses out there.) - - The problem with this approach is that using inline markup for - structure is inherently ambiguous in reStructuredText. For - example, writing *about* definition lists would be difficult:: - - ``term === definition`` is an example of a compact definition list item - - The parser checks for structural markup before it does inline - markup processing. But the "===" should be protected by its inline - literal context. - -3. We could allow the definition on the same line as the term, using - structural markup. A variation on bullet lists would work well:: - - : term :: definition - : another term :: and a definition that - wraps across lines - - Some ambiguity remains:: - - : term ``containing :: double colons`` :: definition - - But the likelihood of such cases is negligible, and they can be - covered in the documentation. - - Other possibilities for the definition delimiter include:: - - : term : classifier -- definition - : term : classifier --- definition - : term : classifier : : definition - : term : classifier === definition - -The third idea currently has the best chance of being adopted and -implemented. - - -Recommendation -`````````````` - -Combining these ideas, the function definition becomes:: - - def max_gas(temperature, pressure, api, specific_gravity=.56): - """ - Computes the maximum dissolved gas in oil using Batzle and - Wang (1992). - - :Parameters: - : temperature : sequence :: Temperature in degrees Celsius - : pressure : sequence :: Pressure in MPa - : api : sequence :: Stock tank oil API - : specific_gravity : sequence :: Specific gravity of gas at - STP, default is .56 - :Returns: - : max_gor : sequence :: Maximum dissolved gas in liters/liter - :Description: This estimate is based on equations given by - Mavko, Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, - p. 236) obtained originally from Batzle and Wang (1992). - """ - code... - -The docstring is reduced to 14 lines, from the original 24. For -longer docstrings with many parameters and return values, the -difference would be more significant. diff --git a/docutils/docs/dev/enthought-rfp.txt b/docutils/docs/dev/enthought-rfp.txt deleted file mode 100644 index 986f5604f..000000000 --- a/docutils/docs/dev/enthought-rfp.txt +++ /dev/null @@ -1,146 +0,0 @@ -================================== - Enthought API Documentation Tool -================================== ------------------------ - Request for Proposals ------------------------ - -:Author: Janet Swisher, Senior Technical Writer -:Organization: `Enthought, Inc. <http://www.enthought.com>`_ -:Copyright: 2004 by Enthought, Inc. -:License: `Enthought License`_ (BSD Style) - -.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt - -The following is excerpted from the full RFP, and is published here -with permission from `Enthought, Inc.`_ See the `Plan for Enthought -API Documentation Tool`__. - -__ enthought-plan.html - -.. contents:: -.. sectnum:: - - -Requirements -============ - -The documentation tool will address the following high-level goals: - - -Documentation Extraction ------------------------- - -1. Documentation will be generated directly from Python source code, - drawing from the code structure, docstrings, and possibly other - comments. - -2. The tool will extract logical constructs as appropriate, minimizing - the need for comments that are redundant with the code structure. - The output should reflect both documented and undocumented - elements. - - -Source Format -------------- - -1. The docstrings will be formatted in as terse syntax as possible. - Required tags, syntax, and white space should be minimized. - -2. The tool must support the use of Traits. Special comment syntax - for Traits may be necessary. Information about the Traits package - is available at http://code.enthought.com/traits/. In the - following example, each trait definition is prefaced by a plain - comment:: - - __traits__ = { - - # The current selection within the frame. - 'selection' : Trait([], TraitInstance(list)), - - # The frame has been activated or deactivated. - 'activated' : TraitEvent(), - - 'closing' : TraitEvent(), - - # The frame is closed. - 'closed' : TraitEvent(), - } - -3. Support for ReStructuredText (ReST) format is desirable, because - much of the existing docstrings uses ReST. However, the complete - ReST specification need not be supported, if a subset can achieve - the project goals. If the tool does not support ReST, the - contractor should also provide a tool or path to convert existing - docstrings. - - -Output Format -------------- - -1. Documentation will be output as a navigable suite of HTML - files. - -2. The style of the HTML files will be customizable by a cascading - style sheet and/or a customizable template. - -3. Page elements such as headers and footer should be customizable, to - support differing requirements from one documentation project to - the next. - - -Output Structure and Navigation -------------------------------- - -1. The navigation scheme for the HTML files should not rely on frames, - and should harmonize with conversion to Microsoft HTML Help (.chm) - format. - -2. The output should be structured to make navigable the architecture - of the Python code. Packages, modules, classes, traits, and - functions should be presented in clear, logical hierarchies. - Diagrams or trees for inheritance, collaboration, sub-packaging, - etc. are desirable but not required. - -3. The output must include indexes that provide a comprehensive view - of all packages, modules, and classes. These indexes will provide - readers with a clear and exhaustive view of the code base. These - indexes should be presented in a way that is easily accessible and - allows easy navigation. - -4. Cross-references to other documented elements will be used - throughout the documentation, to enable the reader to move quickly - relevant information. For example, where type information for an - element is available, the type definition should be - cross-referenced. - -5. The HTML suite should provide consistent navigation back to the - home page, which will include the following information: - - * Bibliographic information - - - Author - - Copyright - - Release date - - Version number - - * Abstract - - * References - - - Links to related internal docs (i.e., other docs for the same - product) - - - Links to related external docs (e.g., supporting development - docs, Python support docs, docs for included packages) - - It should be possible to specify similar information at the top - level of each package, so that packages can be included as - appropriate for a given application. - - -License -======= - -Enthought intends to release the software under an open-source -("BSD-style") license. diff --git a/docutils/docs/dev/hacking.txt b/docutils/docs/dev/hacking.txt deleted file mode 100644 index d0ec9a3fb..000000000 --- a/docutils/docs/dev/hacking.txt +++ /dev/null @@ -1,264 +0,0 @@ -========================== - Docutils_ Hacker's Guide -========================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -:Abstract: This is the introduction to Docutils for all persons who - want to extend Docutils in some way. -:Prerequisites: You have used reStructuredText_ and played around with - the `Docutils front-end tools`_ before. Some (basic) Python - knowledge is certainly helpful (though not necessary, strictly - speaking). - -.. _Docutils: http://docutils.sourceforge.net/ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Docutils front-end tools: ../user/tools.html - -.. contents:: - - -Overview of the Docutils Architecture -===================================== - -To give you an understanding of the Docutils architecture, we'll dive -right into the internals using a practical example. - -Consider the following reStructuredText file:: - - My *favorite* language is Python_. - - .. _Python: http://www.python.org/ - -Using the ``rst2html.py`` front-end tool, you would get an HTML output -which looks like this:: - - [uninteresting HTML code removed] - <body> - <div class="document"> - <p>My <em>favorite</em> language is <a class="reference" href="http://www.python.org/">Python</a>.</p> - </div> - </body> - </html> - -While this looks very simple, it's enough to illustrate all internal -processing stages of Docutils. Let's see how this document is -processed from the reStructuredText source to the final HTML output: - - -Reading the Document --------------------- - -The **Reader** reads the document from the source file and passes it -to the parser (see below). The default reader is the standalone -reader (``docutils/readers/standalone.py``) which just reads the input -data from a single text file. Unless you want to do really fancy -things, there is no need to change that. - -Since you probably won't need to touch readers, we will just move on -to the next stage: - - -Parsing the Document --------------------- - -The **Parser** analyzes the the input document and creates a **node -tree** representation. In this case we are using the -**reStructuredText parser** (``docutils/parsers/rst/__init__.py``). -To see what that node tree looks like, we call ``quicktest.py`` (which -can be found in the ``tools/`` directory of the Docutils distribution) -with our example file (``test.txt``) as first parameter (Windows users -might need to type ``python quicktest.py test.txt``):: - - $ quicktest.py test.txt - <document source="test.txt"> - <paragraph> - My - <emphasis> - favorite - language is - <reference name="Python" refname="python"> - Python - . - <target ids="python" names="python" refuri="http://www.python.org/"> - -Let us now examine the node tree: - -The top-level node is ``document``. It has a ``source`` attribute -whose value is ``text.txt``. There are two children: A ``paragraph`` -node and a ``target`` node. The ``paragraph`` in turn has children: A -text node ("My "), an ``emphasis`` node, a text node (" language is "), -a ``reference`` node, and again a ``Text`` node ("."). - -These node types (``document``, ``paragraph``, ``emphasis``, etc.) are -all defined in ``docutils/nodes.py``. The node types are internally -arranged as a class hierarchy (for example, both ``emphasis`` and -``reference`` have the common superclass ``Inline``). To get an -overview of the node class hierarchy, use epydoc (type ``epydoc -nodes.py``) and look at the class hierarchy tree. - - -Transforming the Document -------------------------- - -In the node tree above, the ``reference`` node does not contain the -target URI (``http://www.python.org/``) yet. - -Assigning the target URI (from the ``target`` node) to the -``reference`` node is *not* done by the parser (the parser only -translates the input document into a node tree). - -Instead, it's done by a **Transform**. In this case (resolving a -reference), it's done by the ``ExternalTargets`` transform in -``docutils/transforms/references.py``. - -In fact, there are quite a lot of Transforms, which do various useful -things like creating the table of contents, applying substitution -references or resolving auto-numbered footnotes. - -The Transforms are applied after parsing. To see how the node tree -has changed after applying the Transforms, we use the -``rst2pseudoxml.py`` tool: - -.. parsed-literal:: - - $ rst2pseudoxml.py test.txt - <document source="test.txt"> - <paragraph> - My - <emphasis> - favorite - language is - <reference name="Python" **refuri="http://www.python.org/"**> - Python - . - <target ids="python" names="python" ``refuri="http://www.python.org/"``> - -For our small test document, the only change is that the ``refname`` -attribute of the reference has been replaced by a ``refuri`` -attribute |---| the reference has been resolved. - -While this does not look very exciting, transforms are a powerful tool -to apply any kind of transformation on the node tree. - -By the way, you can also get a "real" XML representation of the node -tree by using ``rst2xml.py`` instead of ``rst2pseudoxml.py``. - - -Writing the Document --------------------- - -To get an HTML document out of the node tree, we use a **Writer**, the -HTML writer in this case (``docutils/writers/html4css1.py``). - -The writer receives the node tree and returns the output document. -For HTML output, we can test this using the ``rst2html.py`` tool:: - - $ rst2html.py --link-stylesheet test.txt - <?xml version="1.0" encoding="utf-8" ?> - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - <meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" /> - <title></title> - <link rel="stylesheet" href="../docutils/writers/html4css1/html4css1.css" type="text/css" /> - </head> - <body> - <div class="document"> - <p>My <em>favorite</em> language is <a class="reference" href="http://www.python.org/">Python</a>.</p> - </div> - </body> - </html> - -So here we finally have our HTML output. The actual document contents -are in the fourth-last line. Note, by the way, that the HTML writer -did not render the (invisible) ``target`` node |---| only the -``paragraph`` node and its children appear in the HTML output. - - -Extending Docutils -================== - -Now you'll ask, "how do I actually extend Docutils?" - -First of all, once you are clear about *what* you want to achieve, you -have to decide *where* to implement it |---| in the Parser (e.g. by -adding a directive or role to the reStructuredText parser), as a -Transform, or in the Writer. There is often one obvious choice among -those three (Parser, Transform, Writer). If you are unsure, ask on -the Docutils-develop_ mailing list. - -In order to find out how to start, it is often helpful to look at -similar features which are already implemented. For example, if you -want to add a new directive to the reStructuredText parser, look at -the implementation of a similar directive in -``docutils/parsers/rst/directives/``. - - -Modifying the Document Tree Before It Is Written ------------------------------------------------- - -You can modify the document tree right before the writer is called. -One possibility is to use the publish_doctree_ and -publish_from_doctree_ functions. - -To retrieve the document tree, call:: - - document = docutils.core.publish_doctree(...) - -Please see the docstring of publish_doctree for a list of parameters. - -.. XXX Need to write a well-readable list of (commonly used) options - of the publish_* functions. Probably in api/publisher.txt. - -``document`` is the root node of the document tree. You can now -change the document by accessing the ``document`` node and its -children |---| see `The Node Interface`_ below. - -When you're done with modifying the document tree, you can write it -out by calling:: - - output = docutils.core.publish_from_doctree(document, ...) - -.. _publish_doctree: ../api/publisher.html#publish_doctree -.. _publish_from_doctree: ../api/publisher.html#publish_from_doctree - - -The Node Interface ------------------- - -As described in the overview above, Docutils' internal representation -of a document is a tree of nodes. We'll now have a look at the -interface of these nodes. - -(To be completed.) - - -What Now? -========= - -This document is not complete. Many topics could (and should) be -covered here. To find out with which topics we should write about -first, we are awaiting *your* feedback. So please ask your questions -on the Docutils-develop_ mailing list. - - -.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop - - -.. |---| unicode:: 8212 .. em-dash - :trim: - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt deleted file mode 100644 index 25fb4f2e9..000000000 --- a/docutils/docs/dev/policies.txt +++ /dev/null @@ -1,549 +0,0 @@ -=========================== - Docutils Project Policies -=========================== - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -The Docutils project group is a meritocracy based on code contribution -and lots of discussion [#bcs]_. A few quotes sum up the policies of -the Docutils project. The IETF's classic credo (by MIT professor Dave -Clark) is an ideal we can aspire to: - - We reject: kings, presidents, and voting. We believe in: rough - consensus and running code. - -As architect, chief cook and bottle-washer, David Goodger currently -functions as BDFN (Benevolent Dictator For Now). (But he would -happily abdicate the throne given a suitable candidate. Any takers?) - -Eric S. Raymond, anthropologist of the hacker subculture, writes in -his essay `The Magic Cauldron`_: - - The number of contributors [to] projects is strongly and inversely - correlated with the number of hoops each project makes a user go - through to contribute. - -We will endeavour to keep the barrier to entry as low as possible. -The policies below should not be thought of as barriers, but merely as -a codification of experience to date. These are "best practices"; -guidelines, not absolutes. Exceptions are expected, tolerated, and -used as a source of improvement. Feedback and criticism is welcome. - -As for control issues, Emmett Plant (CEO of the Xiph.org Foundation, -originators of Ogg Vorbis) put it well when he said: - - Open source dictates that you lose a certain amount of control - over your codebase, and that's okay with us. - -.. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion - project <http://www.red-bean.com/sussman/svn-anti-fud.html>`__. - -.. _The Magic Cauldron: - http://www.catb.org/~esr/writings/magic-cauldron/ - - -Python Coding Conventions -========================= - -Contributed code will not be refused merely because it does not -strictly adhere to these conditions; as long as it's internally -consistent, clean, and correct, it probably will be accepted. But -don't be surprised if the "offending" code gets fiddled over time to -conform to these conventions. - -The Docutils project shall follow the generic coding conventions as -specified in the `Style Guide for Python Code`_ and `Docstring -Conventions`_ PEPs, summarized, clarified, and extended as follows: - -* 4 spaces per indentation level. No hard tabs. - -* Use only 7-bit ASCII, no 8-bit strings. See `Docutils - Internationalization`_. - -* No one-liner compound statements (i.e., no ``if x: return``: use two - lines & indentation), except for degenerate class or method - definitions (i.e., ``class X: pass`` is OK.). - -* Lines should be no more than 78 characters long. - -* Use "StudlyCaps" for class names (except for element classes in - docutils.nodes). - -* Use "lowercase" or "lowercase_with_underscores" for function, - method, and variable names. For short names, maximum two words, - joined lowercase may be used (e.g. "tagname"). For long names with - three or more words, or where it's hard to parse the split between - two words, use lowercase_with_underscores (e.g., - "note_explicit_target", "explicit_target"). If in doubt, use - underscores. - -* Avoid lambda expressions, which are inherently difficult to - understand. Named functions are preferable and superior: they're - faster (no run-time compilation), and well-chosen names serve to - document and aid understanding. - -* Avoid functional constructs (filter, map, etc.). Use list - comprehensions instead. - -* Avoid ``from __future__ import`` constructs. They are inappropriate - for production code. - -* Use 'single quotes' for string literals, and """triple double - quotes""" for docstrings. - -.. _Style Guide for Python Code: - http://www.python.org/peps/pep-0008.html -.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html -.. _Docutils Internationalization: ../howto/i18n.html#python-code - - -Documentation Conventions -========================= - -* Docutils documentation is written using reStructuredText, of course. - -* Use 7-bit ASCII if at all possible, and Unicode substitutions when - necessary. - -* Use the following section title adornment styles:: - - ================ - Document Title - ================ - - -------------------------------------------- - Document Subtitle, or Major Division Title - -------------------------------------------- - - Section - ======= - - Subsection - ---------- - - Sub-Subsection - `````````````` - - Sub-Sub-Subsection - .................. - -* Use two blank lines before each section/subsection/etc. title. One - blank line is sufficient between immediately adjacent titles. - -* Add a bibliographic field list immediately after the document - title/subtitle. See the beginning of this document for an example. - -* Add an Emacs "local variables" block in a comment at the end of the - document. See the end of this document for an example. - - -Copyrights and Licensing -======================== - -The majority of the Docutils project code and documentation has been -placed in the public domain. Unless clearly and explicitly indicated -otherwise, any patches (modifications to existing files) submitted to -the project for inclusion (via Subversion, SourceForge trackers, -mailing lists, or private email) are assumed to be in the public -domain as well. - -Any new files contributed to the project should clearly state their -intentions regarding copyright, in one of the following ways: - -* Public domain (preferred): include the statement "This - module/document has been placed in the public domain." - -* Copyright & open source license: include a copyright notice, along - with either an embedded license statement, a reference to an - accompanying license file, or a license URL. - -One of the goals of the Docutils project, once complete, is to be -incorporated into the Python standard library. At that time copyright -of the Docutils code will be assumed by or transferred to the Python -Software Foundation (PSF), and will be released under Python's -license. If the copyright/license option is chosen for new files, the -license should be compatible with Python's current license, and the -author(s) of the files should be willing to assign copyright to the -PSF. The PSF accepts the `Academic Free License v. 2.1 -<http://opensource.org/licenses/afl-2.1.php>`_ and the `Apache -License, Version 2.0 <http://opensource.org/licenses/apache2.0.php>`_. - - -Subversion Repository -===================== - -Please see the `repository documentation`_ for details on how to -access Docutils' Subversion repository. Anyone can access the -repository anonymously. Only project developers can make changes. -(If you would like to become a project developer, just ask!) Also see -`Setting Up For Docutils Development`_ below for some useful info. - -Unless you really *really* know what you're doing, please do *not* use -``svn import``. It's quite easy to mess up the repository with an -import. - -.. _repository documentation: repository.html - - -Branches --------- - -(These branch policies go into effect with Docutils 0.4.) - -The "docutils" directory of the **trunk** (a.k.a. the **Docutils -core**) is used for active -- but stable, fully tested, and reviewed --- development. - -There will be at least one active **maintenance branch** at a time, -based on at least the latest feature release. For example, when -Docutils 0.5 is released, its maintenance branch will take over, and -the 0.4.x maintenance branch may be retired. Maintenance branches -will receive bug fixes only; no new features will be allowed here. - -Obvious and uncontroversial bug fixes *with tests* can be checked in -directly to the core and to the maintenance branches. Don't forget to -add test cases! Many (but not all) bug fixes will be applicable both -to the core and to the maintenance branches; these should be applied -to both. No patches or dedicated branches are required for bug fixes, -but they may be used. It is up to the discretion of project -developers to decide which mechanism to use for each case. - -Feature additions and API changes will be done in **feature -branches**. Feature branches will not be managed in any way. -Frequent small checkins are encouraged here. Feature branches must be -discussed on the docutils-develop mailing list and reviewed before -being merged into the core. - - -Review Criteria -``````````````` - -Before a new feature, an API change, or a complex, disruptive, or -controversial bug fix can be checked in to the core or into a -maintenance branch, it must undergo review. These are the criteria: - -* The branch must be complete, and include full documentation and - tests. - -* There should ideally be one branch merge commit per feature or - change. In other words, each branch merge should represent a - coherent change set. - -* The code must be stable and uncontroversial. Moving targets and - features under debate are not ready to be merged. - -* The code must work. The test suite must complete with no failures. - See `Docutils Testing`_. - -The review process will ensure that at least one other set of eyeballs -& brains sees the code before it enters the core. In addition to the -above, the general `Check-ins`_ policy (below) also applies. - -.. _Docutils Testing: testing.html - - -Check-ins ---------- - -Changes or additions to the Docutils core and maintenance branches -carry a commitment to the Docutils user community. Developers must be -prepared to fix and maintain any code they have committed. - -The Docutils core (``trunk/docutils`` directory) and maintenance -branches should always be kept in a stable state (usable and as -problem-free as possible). All changes to the Docutils core or -maintenance branches must be in `good shape`_, usable_, documented_, -tested_, and `reasonably complete`_. - -* _`Good shape` means that the code is clean, readable, and free of - junk code (unused legacy code; by analogy to "junk DNA"). - -* _`Usable` means that the code does what it claims to do. An "XYZ - Writer" should produce reasonable XYZ output. - -* _`Documented`: The more complete the documentation the better. - Modules & files must be at least minimally documented internally. - `Docutils Front-End Tools`_ should have a new section for any - front-end tool that is added. `Docutils Configuration Files`_ - should be modified with any settings/options defined. For any - non-trivial change, the HISTORY.txt_ file should be updated. - -* _`Tested` means that unit and/or functional tests, that catch all - bugs fixed and/or cover all new functionality, have been added to - the test suite. These tests must be checked by running the test - suite under all supported Python versions, and the entire test suite - must pass. See `Docutils Testing`_. - -* _`Reasonably complete` means that the code must handle all input. - Here "handle" means that no input can cause the code to fail (cause - an exception, or silently and incorrectly produce nothing). - "Reasonably complete" does not mean "finished" (no work left to be - done). For example, a writer must handle every standard element - from the Docutils document model; for unimplemented elements, it - must *at the very least* warn that "Output for element X is not yet - implemented in writer Y". - -If you really want to check code directly into the Docutils core, -you can, but you must ensure that it fulfills the above criteria -first. People will start to use it and they will expect it to work! -If there are any issues with your code, or if you only have time for -gradual development, you should put it on a branch or in the sandbox -first. It's easy to move code over to the Docutils core once it's -complete. - -It is the responsibility and obligation of all developers to keep the -Docutils core and maintenance branches stable. If a commit is made to -the core or maintenance branch which breaks any test, the solution is -simply to revert the change. This is not vindictive; it's practical. -We revert first, and discuss later. - -Docutils will pursue an open and trusting policy for as long as -possible, and deal with any aberrations if (and hopefully not when) -they happen. We'd rather see a torrent of loose contributions than -just a trickle of perfect-as-they-stand changes. The occasional -mistake is easy to fix. That's what Subversion is for! - -.. _Docutils Front-End Tools: ../user/tools.html -.. _Docutils Configuration Files: ../user/config.html -.. _HISTORY.txt: ../../HISTORY.txt - - -Version Numbering -================= - -Docutils version numbering uses a ``major.minor.micro`` scheme (x.y.z; -for example, 0.4.1). - -**Major releases** (x.0, e.g. 1.0) will be rare, and will represent -major changes in API, functionality, or commitment. For example, as -long as the major version of Docutils is 0, it is to be considered -*experimental code*. When Docutils reaches version 1.0, the major -APIs will be considered frozen and backward compatibility will become -of paramount importance. - -Releases that change the minor number (x.y, e.g. 0.5) will be -**feature releases**; new features from the `Docutils core`_ will be -included. - -Releases that change the micro number (x.y.z, e.g. 0.4.1) will be -**bug-fix releases**. No new features will be introduced in these -releases; only bug fixes off of `maintenance branches`_ will be -included. - -This policy was adopted in October 2005, and will take effect with -Docutils version 0.4. Prior to version 0.4, Docutils didn't have an -official version numbering policy, and micro releases contained both -bug fixes and new features. - -.. _Docutils core: - http://svn.berlios.de/viewcvs/docutils/trunk/docutils/ -.. _maintenance branches: - http://svn.berlios.de/viewcvs/docutils/branches/ - - -Snapshots -========= - -Snapshot tarballs will be generated regularly from - -* the Docutils core, representing the current cutting-edge state of - development; - -* each active maintenance branch, for bug fixes; - -* each development branch, representing the unstable - seat-of-your-pants bleeding edge. - -The ``sandbox/infrastructure/docutils-update`` shell script, run as an -hourly cron job on the BerliOS server, is responsible for -automatically generating the snapshots and updating the web site. See -the `web site docs <website.html>`__. - - -Setting Up For Docutils Development -=================================== - -When making changes to the code, testing is a must. The code should -be run to verify that it produces the expected results, and the entire -test suite should be run too. The modified Docutils code has to be -accessible to Python for the tests to have any meaning. There are two -ways to keep the Docutils code accessible during development: - -1. Update your ``PYTHONPATH`` environment variable so that Python - picks up your local working copy of the code. This is the - recommended method. - - We'll assume that the Docutils trunk is checked out under your - ~/projects/ directory as follows:: - - svn co svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils/trunk \ - docutils - - For the bash shell, add this to your ``~/.profile``:: - - PYTHONPATH=$HOME/projects/docutils/docutils - PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras - export PYTHONPATH - - The first line points to the directory containing the ``docutils`` - package. The second line adds the directory containing the - third-party modules Docutils depends on. The third line exports - this environment variable. You may also wish to add the ``tools`` - directory to your ``PATH``:: - - PATH=$PATH:$HOME/projects/docutils/docutils/tools - export PATH - -2. Before you run anything, every time you make a change, reinstall - Docutils:: - - python setup.py install - - .. CAUTION:: - - This method is **not** recommended for day-to-day development; - it's too easy to forget. Confusion inevitably ensues. - - If you install Docutils this way, Python will always pick up the - last-installed copy of the code. If you ever forget to - reinstall the "docutils" package, Python won't see your latest - changes. - -A useful addition to the ``docutils`` top-level directory in branches -and alternate copies of the code is a ``set-PATHS`` file -containing the following lines:: - - # source this file - export PYTHONPATH=$PWD:$PWD/extras - export PATH=$PWD/tools:$PATH - -Open a shell for this branch, ``cd`` to the ``docutils`` top-level -directory, and "source" this file. For example, using the bash -shell:: - - $ cd some-branch/docutils - $ . set-PATHS - - -Mailing Lists -============= - -Developers are recommended to subscribe to all `Docutils mailing -lists`_. - -.. _Docutils mailing lists: ../user/mailing-lists.html - - -The Wiki -======== - -There is a development wiki at http://docutils.python-hosting.com/ as -a scratchpad for transient notes. Please use the repository for -permament document storage. - - -The Sandbox -=========== - -The `sandbox directory`_ is a place to play around, to try out and -share ideas. It's a part of the Subversion repository but it isn't -distributed as part of Docutils releases. Feel free to check in code -to the sandbox; that way people can try it out but you won't have to -worry about it working 100% error-free, as is the goal of the Docutils -core. Each developer who wants to play in the sandbox should create -either a project-specific subdirectory or personal subdirectory -(suggested name: SourceForge ID, nickname, or given name + family -initial). It's OK to make a mess in your personal space! But please, -play nice. - -Please update the `sandbox README`_ file with links and a brief -description of your work. - -In order to minimize the work necessary for others to install and try -out new, experimental components, the following sandbox directory -structure is recommended:: - - sandbox/ - project_name/ # For a collaborative project. - # Structure as in userid/component_name below. - userid/ # For personal space. - component_name/ # A verbose name is best. - README.txt # Please explain the requirements, - # purpose/goals, and usage. - docs/ - ... - component.py # The component is a single module. - # *OR* (but *not* both) - component/ # The component is a package. - __init__.py # Contains the Reader/Writer class. - other1.py # Other modules and data files used - data.txt # by this component. - ... - test/ # Test suite. - ... - tools/ # For front ends etc. - ... - setup.py # Use Distutils to install the component - # code and tools/ files into the right - # places in Docutils. - -Some sandbox projects are destined to become Docutils components once -completed. Others, such as add-ons to Docutils or applications of -Docutils, graduate to become `parallel projects`_. - -.. _sandbox README: http://docutils.sf.net/sandbox/README.html -.. _sandbox directory: - http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/ - - -.. _parallel project: - -Parallel Projects -================= - -Parallel projects contain useful code that is not central to the -functioning of Docutils. Examples are specialized add-ons or -plug-ins, and applications of Docutils. They use Docutils, but -Docutils does not require their presence to function. - -An official parallel project will have its own directory beside (or -parallel to) the main ``docutils`` directory in the Subversion -repository. It can have its own web page in the -docutils.sourceforge.net domain, its own file releases and -downloadable snapshots, and even a mailing list if that proves useful. -However, an official parallel project has implications: it is expected -to be maintained and continue to work with changes to the core -Docutils. - -A parallel project requires a project leader, who must commit to -coordinate and maintain the implementation: - -* Answer questions from users and developers. -* Review suggestions, bug reports, and patches. -* Monitor changes and ensure the quality of the code and - documentation. -* Coordinate with Docutils to ensure interoperability. -* Put together official project releases. - -Of course, related projects may be created independently of Docutils. -The advantage of a parallel project is that the SourceForge -environment and the developer and user communities are already -established. Core Docutils developers are available for consultation -and may contribute to the parallel project. It's easier to keep the -projects in sync when there are changes made to the core Docutils -code. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/pysource.dtd b/docutils/docs/dev/pysource.dtd deleted file mode 100644 index fb8af4091..000000000 --- a/docutils/docs/dev/pysource.dtd +++ /dev/null @@ -1,259 +0,0 @@ -<!-- -====================================================================== - Docutils Python Source DTD -====================================================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This DTD has been placed in the public domain. -:Filename: pysource.dtd - -This DTD (document type definition) extends the Generic DTD (see -below). - -More information about this DTD and the Docutils project can be found -at http://docutils.sourceforge.net/. The latest version of this DTD -is available from -http://docutils.sourceforge.net/docs/dev/pysource.dtd. - -The formal public identifier for this DTD is:: - - +//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML ---> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Parameter Entity Overrides -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ENTITY % additional.section.elements - " | package_section | module_section | class_section - | method_section | function_section - | module_attribute_section | function_attribute_section - | class_attribute_section | instance_attribute_section "> - -<!ENTITY % additional.inline.elements - " | package | module | class | method | function - | variable | parameter | type | attribute - | module_attribute | class_attribute | instance_attribute - | exception_class | warning_class "> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Generic DTD -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This DTD extends the Docutils Generic DTD, available from -http://docutils.sourceforge.net/docs/ref/docutils.dtd. ---> - -<!ENTITY % docutils PUBLIC - "+//IDN python.org//DTD Docutils Generic//EN//XML" - "docutils.dtd"> -%docutils; - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Additional Section Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT package_section - (package, fullname?, import_list?, %structure.model;)> -<!ATTLIST package_section %basic.atts;> - -<!ELEMENT module_section - (module, fullname?, import_list?, %structure.model;)> -<!ATTLIST module_section %basic.atts;> - -<!ELEMENT class_section - (class, inheritance_list?, fullname?, subclasses?, - %structure.model;)> -<!ATTLIST class_section %basic.atts;> - -<!ELEMENT method_section - (method, parameter_list?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST method_section %basic.atts;> - -<!ELEMENT function_section - (function, parameter_list?, fullname?, %structure.model;)> -<!ATTLIST function_section %basic.atts;> - -<!ELEMENT module_attribute_section - (attribute, initial_value?, fullname?, %structure.model;)> -<!ATTLIST module_attribute_section %basic.atts;> - -<!ELEMENT function_attribute_section - (attribute, initial_value?, fullname?, %structure.model;)> -<!ATTLIST function_attribute_section %basic.atts;> - -<!ELEMENT class_attribute_section - (attribute, initial_value?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST class_attribute_section %basic.atts;> - -<!ELEMENT instance_attribute_section - (attribute, initial_value?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST instance_attribute_section %basic.atts;> - -<!-- - Section Subelements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT fullname - (package | module | class | method | function | attribute)+> -<!ATTLIST fullname %basic.atts;> - -<!ELEMENT import_list (import_item+)> -<!ATTLIST import_list %basic.atts;> - -<!-- -Support ``import module``, ``import module as alias``, ``from module -import identifier``, and ``from module import identifier as alias``. ---> -<!ELEMENT import_item (fullname, identifier?, alias?)> -<!ATTLIST import_item %basic.atts;> - -<!ELEMENT inheritance_list (class+)> -<!ATTLIST inheritance_list %basic.atts;> - -<!ELEMENT subclasses (class+)> -<!ATTLIST subclasses %basic.atts;> - -<!ELEMENT parameter_list - ((parameter_item+, optional_parameters*) | optional_parameters+)> -<!ATTLIST parameter_list %basic.atts;> - -<!ELEMENT parameter_item - ((parameter | parameter_tuple), parameter_default?)> -<!ATTLIST parameter_item %basic.atts;> - -<!ELEMENT optional_parameters (parameter_item+, optional_parameters*)> -<!ATTLIST optional_parameters %basic.atts;> - -<!ELEMENT parameter_tuple (parameter | parameter_tuple)+> -<!ATTLIST parameter_tuple %basic.atts;> - -<!ELEMENT parameter_default (#PCDATA)> -<!ATTLIST parameter_default %basic.atts;> - -<!ELEMENT overrides (fullname+)> -<!ATTLIST overrides %basic.atts;> - -<!ELEMENT initial_value (#PCDATA)> -<!ATTLIST initial_value %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Additional Inline Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!-- Also used as the `package_section` identifier/title. --> -<!ELEMENT package (#PCDATA)> -<!ATTLIST package - %basic.atts; - %reference.atts;> - -<!-- Also used as the `module_section` identifier/title. --> -<!ELEMENT module (#PCDATA)> -<!ATTLIST module - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `class_section` identifier/title, and in the -`inheritance` element. ---> -<!ELEMENT class (#PCDATA)> -<!ATTLIST class - %basic.atts; - %reference.atts;> - -<!-- Also used as the `method_section` identifier/title. --> -<!ELEMENT method (#PCDATA)> -<!ATTLIST method - %basic.atts; - %reference.atts;> - -<!-- Also used as the `function_section` identifier/title. --> -<!ELEMENT function (#PCDATA)> -<!ATTLIST function - %basic.atts; - %reference.atts;> - -<!-- -??? Use this instead of the ``*_attribute`` elements below? Add a -"type" attribute to differentiate? - -Also used as the identifier/title for `module_attribute_section`, -`class_attribute_section`, and `instance_attribute_section`. ---> -<!ELEMENT attribute (#PCDATA)> -<!ATTLIST attribute - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `module_attribute_section` identifier/title. A module -attribute is an exported module-level global variable. ---> -<!ELEMENT module_attribute (#PCDATA)> -<!ATTLIST module_attribute - %basic.atts; - %reference.atts;> - -<!-- Also used as the `class_attribute_section` identifier/title. --> -<!ELEMENT class_attribute (#PCDATA)> -<!ATTLIST class_attribute - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `instance_attribute_section` identifier/title. ---> -<!ELEMENT instance_attribute (#PCDATA)> -<!ATTLIST instance_attribute - %basic.atts; - %reference.atts;> - -<!ELEMENT variable (#PCDATA)> -<!ATTLIST variable - %basic.atts; - %reference.atts;> - -<!-- Also used in `parameter_list`. --> -<!ELEMENT parameter (#PCDATA)> -<!ATTLIST parameter - %basic.atts; - %reference.atts; - excess_positional %yesorno; #IMPLIED - excess_keyword %yesorno; #IMPLIED> - -<!ELEMENT type (#PCDATA)> -<!ATTLIST type - %basic.atts; - %reference.atts;> - -<!ELEMENT exception_class (#PCDATA)> -<!ATTLIST exception_class - %basic.atts; - %reference.atts;> - -<!ELEMENT warning_class (#PCDATA)> -<!ATTLIST warning_class - %basic.atts; - %reference.atts;> - -<!-- -Local Variables: -mode: sgml -indent-tabs-mode: nil -fill-column: 70 -End: ---> diff --git a/docutils/docs/dev/pysource.txt b/docutils/docs/dev/pysource.txt deleted file mode 100644 index 6f173a709..000000000 --- a/docutils/docs/dev/pysource.txt +++ /dev/null @@ -1,130 +0,0 @@ -====================== - Python Source Reader -====================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -This document explores issues around extracting and processing -docstrings from Python modules. - -For definitive element hierarchy details, see the "Python Plaintext -Document Interface DTD" XML document type definition, pysource.dtd_ -(which modifies the generic docutils.dtd_). Descriptions below list -'DTD elements' (XML 'generic identifiers' or tag names) corresponding -to syntax constructs. - - -.. contents:: - - -Model -===== - -The Python Source Reader ("PySource") model that's evolving in my mind -goes something like this: - -1. Extract the docstring/namespace [#]_ tree from the module(s) and/or - package(s). - - .. [#] See `Docstring Extractor`_ below. - -2. Run the parser on each docstring in turn, producing a forest of - doctrees (per nodes.py). - -3. Join the docstring trees together into a single tree, running - transforms: - - - merge hyperlinks - - merge namespaces - - create various sections like "Module Attributes", "Functions", - "Classes", "Class Attributes", etc.; see pysource.dtd_ - - convert the above special sections to ordinary doctree nodes - -4. Run transforms on the combined doctree. Examples: resolving - cross-references/hyperlinks (including interpreted text on Python - identifiers); footnote auto-numbering; first field list -> - bibliographic elements. - - (Or should step 4's transforms come before step 3?) - -5. Pass the resulting unified tree to the writer/builder. - -I've had trouble reconciling the roles of input parser and output -writer with the idea of modes ("readers" or "directors"). Does the -mode govern the tranformation of the input, the output, or both? -Perhaps the mode should be split into two. - -For example, say the source of our input is a Python module. Our -"input mode" should be the "Python Source Reader". It discovers (from -``__docformat__``) that the input parser is "reStructuredText". If we -want HTML, we'll specify the "HTML" output formatter. But there's a -piece missing. What *kind* or *style* of HTML output do we want? -PyDoc-style, LibRefMan style, etc. (many people will want to specify -and control their own style). Is the output style specific to a -particular output format (XML, HTML, etc.)? Is the style specific to -the input mode? Or can/should they be independent? - -I envision interaction between the input parser, an "input mode" , and -the output formatter. The same intermediate data format would be used -between each of these, being transformed as it progresses. - - -Docstring Extractor -=================== - -We need code that scans a parsed Python module, and returns an ordered -tree containing the names, docstrings (including attribute and -additional docstrings), and additional info (in parentheses below) of -all of the following objects: - -- packages -- modules -- module attributes (+ values) -- classes (+ inheritance) -- class attributes (+ values) -- instance attributes (+ values) -- methods (+ formal parameters & defaults) -- functions (+ formal parameters & defaults) - -(Extract comments too? For example, comments at the start of a module -would be a good place for bibliographic field lists.) - -In order to evaluate interpreted text cross-references, namespaces for -each of the above will also be required. - -See python-dev/docstring-develop thread "AST mining", started on -2001-08-14. - - -Interpreted Text -================ - -DTD elements: package, module, class, method, function, -module_attribute, class_attribute, instance_attribute, variable, -parameter, type, exception_class, warning_class. - -To classify identifiers explicitly, the role is given along with the -identifier in either prefix or suffix form:: - - Use :method:`Keeper.storedata` to store the object's data in - `Keeper.data`:instance_attribute:. - -The role may be one of 'package', 'module', 'class', 'method', -'function', 'module_attribute', 'class_attribute', -'instance_attribute', 'variable', 'parameter', 'type', -'exception_class', 'exception', 'warning_class', or 'warning'. Other -roles may be defined. - -.. _pysource.dtd: pysource.dtd -.. _docutils.dtd: ../ref/docutils.dtd - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - fill-column: 70 - End: diff --git a/docutils/docs/dev/release.txt b/docutils/docs/dev/release.txt deleted file mode 100644 index fa58bc46f..000000000 --- a/docutils/docs/dev/release.txt +++ /dev/null @@ -1,168 +0,0 @@ -============================= - Docutils_ Release Procedure -============================= -:Author: David Goodger; Felix Wiemann; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - - -(Steps in boldface text are *not* covered by the release script at -sandbox/fwiemann/release.sh. "Not covered" means that you aren't even -reminded of them. Note: The release.sh script needs to be updated to -reflect the recent move to Subversion!) - -* **Announce a check-in freeze on Docutils-develop. Post a list of - major changes since the last release and ask for additions.** - - .. _CHANGES.txt: - - **You may want to save this list of changes in a file - (e.g. CHANGES.txt) to have it at hand when you need it for posting - announcements or pasting it into forms.** - -* Change ``__version_details__`` in docutils/docutils/__init__.py to - "release" (from "repository"). - -* Bump the _`version number` in the following files: - - + docutils/setup.py - + docutils/docutils/__init__.py - + docutils/test/functional/expected/* ("Generator: Docutils X.Y.Z") - -* Close the "Changes Since ..." section in docutils/HISTORY.txt. - -* Clear/unset the PYTHONPATH environment variable. - -* Create the release tarball: - - (a) Create a new empty directory and ``cd`` into it. - - (b) Get a clean snapshot of the main tree:: - - svn export svn://svn.berlios.de/docutils/trunk/docutils - - (c) Use Distutils to create the release tarball:: - - cd docutils - python setup.py sdist - -* Expand and _`install` the release tarball in isolation: - - (a) Expand the tarball in a new location, not over any existing - files. - - (b) Remove the old installation from site-packages (including - roman.py, and optparse.py, textwrap.py). - - Install from expanded directory:: - - cd docutils-X.Y.Z - python setup.py install - - The "install" command may require root permissions. - - (c) Repeat step b) for all supported Python versions. - -* Run the _`test suite` from the expanded archive directory with all - supported Python versions: ``cd test ; python -u alltests.py``. - -* Add a directory X.Y.Z (where X.Y.Z is the current version number - of Docutils) in the webroot (i.e. the ``htdocs/`` directory). - Put all documentation files into it:: - - cd docutils-X.Y.Z - rm -rf build - cd tools/ - ./buildhtml.py .. - cd .. - find -name test -type d -prune -o -name \*.css -print0 \ - -o -name \*.html -print0 -o -name \*.txt -print0 \ - | tar -cjvf docutils-docs.tar.bz2 -T - --null - scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net: - - Now log in to shell.sourceforge.net and:: - - cd /home/groups/d/do/docutils/htdocs/ - mkdir -m g+rwxs X.Y.Z - cd X.Y.Z - tar -xjvf ~/docutils-docs.tar.bz2 - rm ~/docutils-docs.tar.bz2 - -* Upload the release tarball:: - - $ ftp upload.sourceforge.net - Connected to osdn.dl.sourceforge.net. - ... - Name (upload.sourceforge.net:david): anonymous - 331 Anonymous login ok, send your complete e-mail address as password. - Password: - ... - 230 Anonymous access granted, restrictions apply. - ftp> bin - 200 Type set to I. - ftp> cd /incoming - 250 CWD command successful. - ftp> put docutils-X.Y.Z.tar.gz - -* Access the _`file release system` on SourceForge (Admin - interface). Fill in the fields: - - :Package ID: docutils - :Release Name: <use release number only, e.g. 0.3> - :Release Date: <today's date> - :Status: Active - :File Name: <select the file just uploaded> - :File Type: Source .gz - :Processor Type: Platform-Independent - :Release Notes: <insert README.txt file here> - :Change Log: <insert summary from CHANGES.txt_> - - Also check the "Preserve my pre-formatted text" box. - -* For verifying the integrity of the release, download the release - tarball (you may need to wait up to 30 minutes), install_ it, and - re-run the `test suite`_. - -* Register with PyPI (``python setup.py register``). - -* Restore ``__version_details__`` in docutils/docutils/__init__.py to - "repository" (from "release"). - -* Bump the `version number`_ again. - -* Add a new empty section "Changes Since ..." in HISTORY.txt. - -* Update the web page (web/index.txt). - -* Run docutils-update on the server. - -* **Send announcement email to:** - - * docutils-develop@lists.sourceforge.net (also announcing the end - of the check-in freeze) - * docutils-users@lists.sourceforge.net - * doc-sig@python.org - * python-announce@python.org - -* **Add a SourceForge News item, with title "Docutils X.Y.Z released" - and containing the release tarball's download URL.** - -* **Register with FreshMeat.** (Add a `new release`__ for the - `Docutils project`__). - - __ http://freshmeat.net/add-release/48702/ - __ http://freshmeat.net/projects/docutils/ - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/repository.txt b/docutils/docs/dev/repository.txt deleted file mode 100644 index 2c613b10e..000000000 --- a/docutils/docs/dev/repository.txt +++ /dev/null @@ -1,217 +0,0 @@ -===================================== - The Docutils_ Subversion Repository -===================================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - -Docutils uses a Subversion_ repository located at ``svn.berlios.de``. -Subversion is exhaustively documented in the `Subversion Book`_ -(svnbook). - -.. _Subversion: http://subversion.tigris.org/ -.. _Subversion Book: http://svnbook.red-bean.com/ - -.. Note:: - - While the repository resides at BerliOS, all other project data - (web site, snapshots, releases, mailing lists, trackers) is hosted - at SourceForge. - -For the project policy on repository use (check-in requirements, -branching, etc.), please see the `Docutils Project Policies`__. - -__ policies.html#subversion-repository - - -Accessing the Repository -======================== - -Web Access ----------- - -The repository can be browsed and examined via the web at -http://svn.berlios.de/viewcvs/docutils/. - - -Anonymous Access ----------------- - -Anonymous (read-only) access is available at ``svn://svn.berlios.de/docutils/``. - -To check out the current main source tree of Docutils, type :: - - svn checkout svn://svn.berlios.de/docutils/trunk/docutils - -To check out everything (main tree, sandboxes, and web site), type :: - - svn checkout svn://svn.berlios.de/docutils/trunk docutils - -This will create a working copy of the whole trunk in a new directory -called ``docutils``. - -If you cannot use the ``svn`` port, you can also use the HTTP access -method by substituting "http://svn.berlios.de/svnroot/repos" for -"svn://svn.berlios.de". - -Note that you should *not* check out ``svn://svn.berlios.de/docutils`` -(without "trunk"), because then you'd end up fetching the whole -Docutils tree for every branch and tag over and over again, wasting -your and BerliOS's bandwidth. - -To update your working copy later on, cd into the working copy and -type :: - - svn update - - -Developer Access ----------------- - -(Developers who had write-access for Docutils' CVS repository on -SourceForge.net should `register at BerliOS`__ and send a message with -their BerliOS user name to `Felix Wiemann <Felix.Wiemann@ososo.de>`_.) - -__ https://developer.berlios.de/account/register.php - -If you are a developer, you get read-write access via -``svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils/``, where -``<user>`` is your BerliOS user account name. So to retrieve a -working copy, type :: - - svn checkout svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils/trunk \ - docutils - -If you previously had an anonymous working copy and gained developer -access, you can switch the URL associated with your working copy by -typing :: - - svn switch --relocate svn://svn.berlios.de/docutils/trunk/docutils \ - svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils - -(Again, ``<user>`` is your BerliOS user account name.) - -If you cannot use the ``ssh`` port, you can also use the HTTPS access -method by substituting "https://svn.berlios.de" for -"svn+ssh://svn.berlios.de". - - -Setting Up Your Subversion Client For Development -````````````````````````````````````````````````` - -Before commiting changes to the repository, please ensure that the -following lines are contained (and uncommented) in your -~/.subversion/config file, so that new files are added with the -correct properties set:: - - [miscellany] - # For your convenience: - global-ignores = ... *.pyc ... - # For correct properties: - enable-auto-props = yes - - [auto-props] - *.py = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.txt = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.html = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.xml = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.tex = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.css = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.patch = svn:eol-style=native - *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision - *.png = svn:mime-type=image/png - *.jpg = svn:mime-type=image/jpeg - *.gif = svn:mime-type=image/gif - - -Setting Up SSH Access -````````````````````` - -With a public & private key pair, you can access the shell and -Subversion servers without having to enter your password. There are -two places to add your SSH public key on BerliOS: your web account and -your shell account. - -* Adding your SSH key to your BerliOS web account: - - 1. Log in on the web at https://developer.berlios.de/. Create your - account first if necessary. You should be taken to your "My - Personal Page" (https://developer.berlios.de/my/). - - 2. Choose "Account Options" from the menu below the top banner. - - 3. At the bottom of the "Account Maintenance" page - (https://developer.berlios.de/account/) you'll find a "Shell - Account Information" section; click on "[Edit Keys]". - - 4. Copy and paste your SSH public key into the edit box on this page - (https://developer.berlios.de/account/editsshkeys.php). Further - instructions are available on this page. - -* Adding your SSH key to your BerliOS shell account: - - 1. Log in to the BerliOS shell server:: - - ssh <user>@shell.berlios.de - - You'll be asked for your password, which you set when you created - your account. - - 2. Create a .ssh directory in your home directory, and remove - permissions for group & other:: - - mkdir .ssh - chmod og-rwx .ssh - - Exit the SSH session. - - 3. Copy your public key to the .ssh directory on BerliOS:: - - scp .ssh/id_dsa.pub <user>@shell.berlios.de:.ssh/authorized_keys - - Now you should be able to start an SSH session without needing your - password. - - -Repository Layout -================= - -The following tree shows the repository layout:: - - docutils/ - |-- branches/ - | |-- branch1/ - | | |-- docutils/ - | | |-- sandbox/ - | | `-- web/ - | `-- branch2/ - | |-- docutils/ - | |-- sandbox/ - | `-- web/ - |-- tags/ - | |-- tag1/ - | | |-- docutils/ - | | |-- sandbox/ - | | `-- web/ - | `-- tag2/ - | |-- docutils/ - | |-- sandbox/ - | `-- web/ - `-- trunk/ - |-- docutils/ - |-- sandbox/ - `-- web/ - -``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies -of the whole trunk. - -The main source tree lives at ``docutils/trunk/docutils/``, next to -the sandboxes (``docutils/trunk/sandbox/``) and the web site files -(``docutils/trunk/web/``). diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt deleted file mode 100644 index 12874c5fb..000000000 --- a/docutils/docs/dev/rst/alternatives.txt +++ /dev/null @@ -1,3129 +0,0 @@ -================================================== - A Record of reStructuredText Syntax Alternatives -================================================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -The following are ideas, alternatives, and justifications that were -considered for reStructuredText syntax, which did not originate with -Setext_ or StructuredText_. For an analysis of constructs which *did* -originate with StructuredText or Setext, please see `Problems With -StructuredText`_. See the `reStructuredText Markup Specification`_ -for full details of the established syntax. - -The ideas are divided into sections: - -* Implemented_: already done. The issues and alternatives are - recorded here for posterity. - -* `Not Implemented`_: these ideas won't be implemented. - -* Tabled_: these ideas should be revisited in the future. - -* `To Do`_: these ideas should be implemented. They're just waiting - for a champion to resolve issues and get them done. - -* `... Or Not To Do?`_: possible but questionable. These probably - won't be implemented, but you never know. - -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage -.. _Problems with StructuredText: problems.html -.. _reStructuredText Markup Specification: - ../../ref/rst/restructuredtext.html - - -.. contents:: - -------------- - Implemented -------------- - -Field Lists -=========== - -Prior to the syntax for field lists being finalized, several -alternatives were proposed. - -1. Unadorned RFC822_ everywhere:: - - Author: Me - Version: 1 - - Advantages: clean, precedent (RFC822-compliant). Disadvantage: - ambiguous (these paragraphs are a prime example). - - Conclusion: rejected. - -2. Special case: use unadorned RFC822_ for the very first or very last - text block of a document:: - - """ - Author: Me - Version: 1 - - The rest of the document... - """ - - Advantages: clean, precedent (RFC822-compliant). Disadvantages: - special case, flat (unnested) field lists only, still ambiguous:: - - """ - Usage: cmdname [options] arg1 arg2 ... - - We obviously *don't* want the like above to be interpreted as a - field list item. Or do we? - """ - - Conclusion: rejected for the general case, accepted for specific - contexts (PEPs, email). - -3. Use a directive:: - - .. fields:: - - Author: Me - Version: 1 - - Advantages: explicit and unambiguous, RFC822-compliant. - Disadvantage: cumbersome. - - Conclusion: rejected for the general case (but such a directive - could certainly be written). - -4. Use Javadoc-style:: - - @Author: Me - @Version: 1 - @param a: integer - - Advantages: unambiguous, precedent, flexible. Disadvantages: - non-intuitive, ugly, not RFC822-compliant. - - Conclusion: rejected. - -5. Use leading colons:: - - :Author: Me - :Version: 1 - - Advantages: unambiguous, obvious (*almost* RFC822-compliant), - flexible, perhaps even elegant. Disadvantages: no precedent, not - quite RFC822-compliant. - - Conclusion: accepted! - -6. Use double colons:: - - Author:: Me - Version:: 1 - - Advantages: unambiguous, obvious? (*almost* RFC822-compliant), - flexible, similar to syntax already used for literal blocks and - directives. Disadvantages: no precedent, not quite - RFC822-compliant, similar to syntax already used for literal blocks - and directives. - - Conclusion: rejected because of the syntax similarity & conflicts. - -Why is RFC822 compliance important? It's a universal Internet -standard, and super obvious. Also, I'd like to support the PEP format -(ulterior motive: get PEPs to use reStructuredText as their standard). -But it *would* be easy to get used to an alternative (easy even to -convert PEPs; probably harder to convert python-deviants ;-). - -Unfortunately, without well-defined context (such as in email headers: -RFC822 only applies before any blank lines), the RFC822 format is -ambiguous. It is very common in ordinary text. To implement field -lists unambiguously, we need explicit syntax. - -The following question was posed in a footnote: - - Should "bibliographic field lists" be defined at the parser level, - or at the DPS transformation level? In other words, are they - reStructuredText-specific, or would they also be applicable to - another (many/every other?) syntax? - -The answer is that bibliographic fields are a -reStructuredText-specific markup convention. Other syntaxes may -implement the bibliographic elements explicitly. For example, there -would be no need for such a transformation for an XML-based markup -syntax. - -.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt - - -Interpreted Text "Roles" -======================== - -The original purpose of interpreted text was as a mechanism for -descriptive markup, to describe the nature or role of a word or -phrase. For example, in XML we could say "<function>len</function>" -to mark up "len" as a function. It is envisaged that within Python -docstrings (inline documentation in Python module source files, the -primary market for reStructuredText) the role of a piece of -interpreted text can be inferred implicitly from the context of the -docstring within the program source. For other applications, however, -the role may have to be indicated explicitly. - -Interpreted text is enclosed in single backquotes (`). - -1. Initially, it was proposed that an explicit role could be indicated - as a word or phrase within the enclosing backquotes: - - - As a prefix, separated by a colon and whitespace:: - - `role: interpreted text` - - - As a suffix, separated by whitespace and a colon:: - - `interpreted text :role` - - There are problems with the initial approach: - - - There could be ambiguity with interpreted text containing colons. - For example, an index entry of "Mission: Impossible" would - require a backslash-escaped colon. - - - The explicit role is descriptive markup, not content, and will - not be visible in the processed output. Putting it inside the - backquotes doesn't feel right; the *role* isn't being quoted. - -2. Tony Ibbs suggested that the role be placed outside the - backquotes:: - - role:`prefix` or `suffix`:role - - This removes the embedded-colons ambiguity, but limits the role - identifier to be a single word (whitespace would be illegal). - Since roles are not meant to be visible after processing, the lack - of whitespace support is not important. - - The suggested syntax remains ambiguous with respect to ratios and - some writing styles. For example, suppose there is a "signal" - identifier, and we write:: - - ...calculate the `signal`:noise ratio. - - "noise" looks like a role. - -3. As an improvement on #2, we can bracket the role with colons:: - - :role:`prefix` or `suffix`:role: - - This syntax is similar to that of field lists, which is fine since - both are doing similar things: describing. - - This is the syntax chosen for reStructuredText. - -4. Another alternative is two colons instead of one:: - - role::`prefix` or `suffix`::role - - But this is used for analogies ("A:B::C:D": "A is to B as C is to - D"). - - Both alternative #2 and #4 lack delimiters on both sides of the - role, making it difficult to parse (by the reader). - -5. Some kind of bracketing could be used: - - - Parentheses:: - - (role)`prefix` or `suffix`(role) - - - Braces:: - - {role}`prefix` or `suffix`{role} - - - Square brackets:: - - [role]`prefix` or `suffix`[role] - - - Angle brackets:: - - <role>`prefix` or `suffix`<role> - - (The overlap of \*ML tags with angle brackets would be too - confusing and precludes their use.) - -Syntax #3 was chosen for reStructuredText. - - -Comments -======== - -A problem with comments (actually, with all indented constructs) is -that they cannot be followed by an indented block -- a block quote -- -without swallowing it up. - -I thought that perhaps comments should be one-liners only. But would -this mean that footnotes, hyperlink targets, and directives must then -also be one-liners? Not a good solution. - -Tony Ibbs suggested a "comment" directive. I added that we could -limit a comment to a single text block, and that a "multi-block -comment" could use "comment-start" and "comment-end" directives. This -would remove the indentation incompatibility. A "comment" directive -automatically suggests "footnote" and (hyperlink) "target" directives -as well. This could go on forever! Bad choice. - -Garth Kidd suggested that an "empty comment", a ".." explicit markup -start with nothing on the first line (except possibly whitespace) and -a blank line immediately following, could serve as an "unindent". An -empty comment does **not** swallow up indented blocks following it, -so block quotes are safe. "A tiny but practical wart." Accepted. - - -Anonymous Hyperlinks -==================== - -Alan Jaffray came up with this idea, along with the following syntax:: - - Search the `Python DOC-SIG mailing list archives`{}_. - - .. _: http://mail.python.org/pipermail/doc-sig/ - -The idea is sound and useful. I suggested a "double underscore" -syntax:: - - Search the `Python DOC-SIG mailing list archives`__. - - .. __: http://mail.python.org/pipermail/doc-sig/ - -But perhaps single underscores are okay? The syntax looks better, but -the hyperlink itself doesn't explicitly say "anonymous":: - - Search the `Python DOC-SIG mailing list archives`_. - - .. _: http://mail.python.org/pipermail/doc-sig/ - -Mixing anonymous and named hyperlinks becomes confusing. The order of -targets is not significant for named hyperlinks, but it is for -anonymous hyperlinks:: - - Hyperlinks: anonymous_, named_, and another anonymous_. - - .. _named: named - .. _: anonymous1 - .. _: anonymous2 - -Without the extra syntax of double underscores, determining which -hyperlink references are anonymous may be difficult. We'd have to -check which references don't have corresponding targets, and match -those up with anonymous targets. Keeping to a simple consistent -ordering (as with auto-numbered footnotes) seems simplest. - -reStructuredText will use the explicit double-underscore syntax for -anonymous hyperlinks. An alternative (see `Reworking Explicit Markup -(Round 1)`_ below) for the somewhat awkward ".. __:" syntax is "__":: - - An anonymous__ reference. - - __ http://anonymous - - -Reworking Explicit Markup (Round 1) -=================================== - -Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added -to reStructuredText. Subsequently it was asserted that hyperlinks -(especially anonymous hyperlinks) would play an increasingly important -role in reStructuredText documents, and therefore they require a -simpler and more concise syntax. This prompted a review of the -current and proposed explicit markup syntaxes with regards to -improving usability. - -1. Original syntax:: - - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - .. Note:: - - The comment text was intentionally made to look like a hyperlink - target. - - Origins: - - * Except for the colon (a delimiter necessary to allow for - phrase-links), hyperlink target ``.. _blah:`` comes from Setext. - * Comment syntax from Setext. - * Footnote syntax from StructuredText ("named links"). - * Directives and anonymous hyperlinks original to reStructuredText. - - Advantages: - - + Consistent explicit markup indicator: "..". - + Consistent hyperlink syntax: ".. _" & ":". - - Disadvantages: - - - Anonymous target markup is awkward: ".. __:". - - The explicit markup indicator ("..") is excessively overloaded? - - Comment text is limited (can't look like a footnote, hyperlink, - or directive). But this is probably not important. - -2. Alan Jaffray's proposed syntax #1:: - - __ _blah internal hyperlink target - __ blah: http://somewhere external hyperlink target - __ blah: blahblah_ indirect hyperlink target - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target - __ [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - The hyperlink-connoted underscores have become first-level syntax. - - Advantages: - - + Anonymous targets are simpler. - + All hyperlink targets are one character shorter. - - Disadvantages: - - - Inconsistent internal hyperlink targets. Unlike all other named - hyperlink targets, there's no colon. There's an extra leading - underscore, but we can't drop it because without it, "blah" looks - like a relative URI. Unless we restore the colon:: - - __ blah: internal hyperlink target - - - Obtrusive markup? - -3. Alan Jaffray's proposed syntax #2:: - - .. _blah internal hyperlink target - .. blah: http://somewhere external hyperlink target - .. blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - !! blah: http://somewhere directive - ## blah: http://somewhere comment - - Leading underscores have been (almost) replaced by "..", while - comments and directives have gained their own syntax. - - Advantages: - - + Anonymous hyperlinks are simpler. - + Unique syntax for comments. Connotation of "comment" from - some programming languages (including our favorite). - + Unique syntax for directives. Connotation of "action!". - - Disadvantages: - - - Inconsistent internal hyperlink targets. Again, unlike all other - named hyperlink targets, there's no colon. There's a leading - underscore, matching the trailing underscores of references, - which no other hyperlink targets have. We can't drop that one - leading underscore though: without it, "blah" looks like a - relative URI. Again, unless we restore the colon:: - - .. blah: internal hyperlink target - - - All (except for internal) hyperlink targets lack their leading - underscores, losing the "hyperlink" connotation. - - - Obtrusive syntax for comments. Alternatives:: - - ;; blah: http://somewhere - (also comment syntax in Lisp & others) - ,, blah: http://somewhere - ("comma comma": sounds like "comment"!) - - - Iffy syntax for directives. Alternatives? - -4. Tony Ibbs' proposed syntax:: - - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - This is the same as the current syntax, except for anonymous - targets which drop their "__: ". - - Advantage: - - + Anonymous targets are simpler. - - Disadvantages: - - - Anonymous targets lack their leading underscores, losing the - "hyperlink" connotation. - - Anonymous targets are almost indistinguishable from comments. - (Better to know "up front".) - -5. David Goodger's proposed syntax: Perhaps going back to one of - Alan's earlier suggestions might be the best solution. How about - simply adding "__ " as a synonym for ".. __: " in the original - syntax? These would become equivalent:: - - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target - - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target - -Alternative 5 has been adopted. - - -Backquotes in Phrase-Links -========================== - -[From a 2001-06-05 Doc-SIG post in reply to questions from Doug -Hellmann.] - -The first draft of the spec, posted to the Doc-SIG in November 2000, -used square brackets for phrase-links. I changed my mind because: - -1. In the first draft, I had already decided on single-backquotes for - inline literal text. - -2. However, I wanted to minimize the necessity for backslash escapes, - for example when quoting Python repr-equivalent syntax that uses - backquotes. - -3. The processing of identifiers (function/method/attribute/module - etc. names) into hyperlinks is a useful feature. PyDoc recognizes - identifiers heuristically, but it doesn't take much imagination to - come up with counter-examples where PyDoc's heuristics would result - in embarassing failure. I wanted to do it deterministically, and - that called for syntax. I called this construct "interpreted - text". - -4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the - idea of using double-backquotes as syntax. - -5. I worked out some rules for inline markup recognition. - -6. In combination with #5, double backquotes lent themselves to inline - literals, neatly satisfying #2, minimizing backslash escapes. In - fact, the spec says that no interpretation of any kind is done - within double-backquote inline literal text; backslashes do *no* - escaping within literal text. - -7. Single backquotes are then freed up for interpreted text. - -8. I already had square brackets required for footnote references. - -9. Since interpreted text will typically turn into hyperlinks, it was - a natural fit to use backquotes as the phrase-quoting syntax for - trailing-underscore hyperlinks. - -The original inspiration for the trailing underscore hyperlink syntax -was Setext. But for phrases Setext used a very cumbersome -``underscores_between_words_like_this_`` syntax. - -The underscores can be viewed as if they were right-pointing arrows: -``-->``. So ``hyperlink_`` points away from the reference, and -``.. _hyperlink:`` points toward the target. - - -Substitution Mechanism -====================== - -Substitutions arose out of a Doc-SIG thread begun on 2001-10-28 by -Alan Jaffray, "reStructuredText inline markup". It reminded me of a -missing piece of the reStructuredText puzzle, first referred to in my -contribution to "Documentation markup & processing / PEPs" (Doc-SIG -2001-06-21). - -Substitutions allow the power and flexibility of directives to be -shared by inline text. They are a way to allow arbitrarily complex -inline objects, while keeping the details out of the flow of text. -They are the equivalent of SGML/XML's named entities. For example, an -inline image (using reference syntax alternative 4d (vertical bars) -and definition alternative 3, the alternatives chosen for inclusion in -the spec):: - - The |biohazard| symbol must be used on containers used to dispose - of medical waste. - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -The ``|biohazard|`` substitution reference will be replaced in-line by -whatever the ``.. |biohazard|`` substitution definition generates (in -this case, an image). A substitution definition contains the -substitution text bracketed with vertical bars, followed by a an -embedded inline-compatible directive, such as "image". A transform is -required to complete the substitution. - -Syntax alternatives for the reference: - -1. Use the existing interpreted text syntax, with a predefined role - such as "sub":: - - The `biohazard`:sub: symbol... - - Advantages: existing syntax, explicit. Disadvantages: verbose, - obtrusive. - -2. Use a variant of the interpreted text syntax, with a new suffix - akin to the underscore in phrase-link references:: - - (a) `name`@ - (b) `name`# - (c) `name`& - (d) `name`/ - (e) `name`< - (f) `name`:: - (g) `name`: - - - Due to incompatibility with other constructs and ordinary text - usage, (f) and (g) are not possible. - -3. Use interpreted text syntax with a fixed internal format:: - - (a) `:name:` - (b) `name:` - (c) `name::` - (d) `::name::` - (e) `%name%` - (f) `#name#` - (g) `/name/` - (h) `&name&` - (i) `|name|` - (j) `[name]` - (k) `<name>` - (l) `&name;` - (m) `'name'` - - To avoid ML confusion (k) and (l) are definitely out. Square - brackets (j) won't work in the target (the substitution definition - would be indistinguishable from a footnote). - - The ```/name/``` syntax (g) is reminiscent of "s/find/sub" - substitution syntax in ed-like languages. However, it may have a - misleading association with regexps, and looks like an absolute - POSIX path. (i) is visually equivalent and lacking the - connotations. - - A disadvantage of all of these is that they limit interpreted text, - albeit only slightly. - -4. Use specialized syntax, something new:: - - (a) #name# - (b) @name@ - (c) /name/ - (d) |name| - (e) <<name>> - (f) //name// - (g) ||name|| - (h) ^name^ - (i) [[name]] - (j) ~name~ - (k) !name! - (l) =name= - (m) ?name? - (n) >name< - - "#" (a) and "@" (b) are obtrusive. "/" (c) without backquotes - looks just like a POSIX path; it is likely for such usage to appear - in text. - - "|" (d) and "^" (h) are feasible. - -5. Redefine the trailing underscore syntax. See definition syntax - alternative 4, below. - -Syntax alternatives for the definition: - -1. Use the existing directive syntax, with a predefined directive such - as "sub". It contains a further embedded directive resolving to an - inline-compatible object:: - - .. sub:: biohazard - .. image:: biohazard.png - [height=20 width=20] - - .. sub:: parrot - That bird wouldn't *voom* if you put 10,000,000 volts - through it! - - The advantages and disadvantages are the same as in inline - alternative 1. - -2. Use syntax as in #1, but with an embedded directivecompressed:: - - .. sub:: biohazard image:: biohazard.png - [height=20 width=20] - - This is a bit better than alternative 1, but still too much. - -3. Use a variant of directive syntax, incorporating the substitution - text, obviating the need for a special "sub" directive name. If we - assume reference alternative 4d (vertical bars), the matching - definition would look like this:: - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -4. (Suggested by Alan Jaffray on Doc-SIG from 2001-11-06.) - - Instead of adding new syntax, redefine the trailing underscore - syntax to mean "substitution reference" instead of "hyperlink - reference". Alan's example:: - - I had lunch with Jonathan_ today. We talked about Zope_. - - .. _Jonathan: lj [user=jhl] - .. _Zope: http://www.zope.org/ - - A problem with the proposed syntax is that URIs which look like - simple reference names (alphanum plus ".", "-", "_") would be - indistinguishable from substitution directive names. A more - consistent syntax would be:: - - I had lunch with Jonathan_ today. We talked about Zope_. - - .. _Jonathan: lj:: user=jhl - .. _Zope: http://www.zope.org/ - - (``::`` after ``.. _Jonathan: lj``.) - - The "Zope" target is a simple external hyperlink, but the - "Jonathan" target contains a directive. Alan proposed is that the - reference text be replaced by whatever the referenced directive - (the "directive target") produces. A directive reference becomes a - hyperlink reference if the contents of the directive target resolve - to a hyperlink. If the directive target resolves to an icon, the - reference is replaced by an inline icon. If the directive target - resolves to a hyperlink, the directive reference becomes a - hyperlink reference. - - This seems too indirect and complicated for easy comprehension. - - The reference in the text will sometimes become a link, sometimes - not. Sometimes the reference text will remain, sometimes not. We - don't know *at the reference*:: - - This is a `hyperlink reference`_; its text will remain. - This is an `inline icon`_; its text will disappear. - - That's a problem. - -The syntax that has been incorporated into the spec and parser is -reference alternative 4d with definition alternative 3:: - - The |biohazard| symbol... - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -We can also combine substitution references with hyperlink references, -by appending a "_" (named hyperlink reference) or "__" (anonymous -hyperlink reference) suffix to the substitution reference. This -allows us to click on an image-link:: - - The |biohazard|_ symbol... - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - .. _biohazard: http://www.cdc.gov/ - -There have been several suggestions for the naming of these -constructs, originally called "substitution references" and -"substitutions". - -1. Candidate names for the reference construct: - - (a) substitution reference - (b) tagging reference - (c) inline directive reference - (d) directive reference - (e) indirect inline directive reference - (f) inline directive placeholder - (g) inline directive insertion reference - (h) directive insertion reference - (i) insertion reference - (j) directive macro reference - (k) macro reference - (l) substitution directive reference - -2. Candidate names for the definition construct: - - (a) substitution - (b) substitution directive - (c) tag - (d) tagged directive - (e) directive target - (f) inline directive - (g) inline directive definition - (h) referenced directive - (i) indirect directive - (j) indirect directive definition - (k) directive definition - (l) indirect inline directive - (m) named directive definition - (n) inline directive insertion definition - (o) directive insertion definition - (p) insertion definition - (q) insertion directive - (r) substitution definition - (s) directive macro definition - (t) macro definition - (u) substitution directive definition - (v) substitution definition - -"Inline directive reference" (1c) seems to be an appropriate term at -first, but the term "inline" is redundant in the case of the -reference. Its counterpart "inline directive definition" (2g) is -awkward, because the directive definition itself is not inline. - -"Directive reference" (1d) and "directive definition" (2k) are too -vague. "Directive definition" could be used to refer to any -directive, not just those used for inline substitutions. - -One meaning of the term "macro" (1k, 2s, 2t) is too -programming-language-specific. Also, macros are typically simple text -substitution mechanisms: the text is substituted first and evaluated -later. reStructuredText substitution definitions are evaluated in -place at parse time and substituted afterwards. - -"Insertion" (1h, 1i, 2n-2q) is almost right, but it implies that -something new is getting added rather than one construct being -replaced by another. - -Which brings us back to "substitution". The overall best names are -"substitution reference" (1a) and "substitution definition" (2v). A -long way to go to add one word! - - -Inline External Targets -======================= - -Currently reStructuredText has two hyperlink syntax variations: - -* Named hyperlinks:: - - This is a named reference_ of one word ("reference"). Here is - a `phrase reference`_. Phrase references may even cross `line - boundaries`_. - - .. _reference: http://www.example.org/reference/ - .. _phrase reference: http://www.example.org/phrase_reference/ - .. _line boundaries: http://www.example.org/line_boundaries/ - - + Advantages: - - - The plaintext is readable. - - Each target may be reused multiple times (e.g., just write - ``"reference_"`` again). - - No syncronized ordering of references and targets is necessary. - - + Disadvantages: - - - The reference text must be repeated as target names; could lead - to mistakes. - - The target URLs may be located far from the references, and hard - to find in the plaintext. - -* Anonymous hyperlinks (in current reStructuredText):: - - This is an anonymous reference__. Here is an anonymous - `phrase reference`__. Phrase references may even cross `line - boundaries`__. - - __ http://www.example.org/reference/ - __ http://www.example.org/phrase_reference/ - __ http://www.example.org/line_boundaries/ - - + Advantages: - - - The plaintext is readable. - - The reference text does not have to be repeated. - - + Disadvantages: - - - References and targets must be kept in sync. - - Targets cannot be reused. - - The target URLs may be located far from the references. - -For comparison and historical background, StructuredText also has two -syntaxes for hyperlinks: - -* First, ``"reference text":URL``:: - - This is a "reference":http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase - reference":http://www.example.org/phrase_reference/. - -* Second, ``"reference text", http://example.com/absolute_URL``:: - - This is a "reference", http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase reference", - http://www.example.org/phrase_reference/. - -Both syntaxes share advantages and disadvantages: - -+ Advantages: - - - The target is specified immediately adjacent to the reference. - -+ Disadvantages: - - - Poor plaintext readability. - - Targets cannot be reused. - - Both syntaxes use double quotes, common in ordinary text. - - In the first syntax, the URL and the last word are stuck - together, exacerbating the line wrap problem. - - The second syntax is too magical; text could easily be written - that way by accident (although only absolute URLs are recognized - here, perhaps because of the potential for ambiguity). - -A new type of "inline external hyperlink" has been proposed. - -1. On 2002-06-28, Simon Budig proposed__ a new syntax for - reStructuredText hyperlinks:: - - This is a reference_(http://www.example.org/reference/) of one - word ("reference"). Here is a `phrase - reference`_(http://www.example.org/phrase_reference/). Are - these examples, (single-underscore), named? If so, `anonymous - references`__(http://www.example.org/anonymous/) using two - underscores would probably be preferable. - - __ http://mail.python.org/pipermail/doc-sig/2002-June/002648.html - - The syntax, advantages, and disadvantages are similar to those of - StructuredText. - - + Advantages: - - - The target is specified immediately adjacent to the reference. - - + Disadvantages: - - - Poor plaintext readability. - - Targets cannot be reused (unless named, but the semantics are - unclear). - - + Problems: - - - The ``"`ref`_(URL)"`` syntax forces the last word of the - reference text to be joined to the URL, making a potentially - very long word that can't be wrapped (URLs can be very long). - The reference and the URL should be separate. This is a - symptom of the following point: - - - The syntax produces a single compound construct made up of two - equally important parts, *with syntax in the middle*, *between* - the reference and the target. This is unprecedented in - reStructuredText. - - - The "inline hyperlink" text is *not* a named reference (there's - no lookup by name), so it shouldn't look like one. - - - According to the IETF standards RFC 2396 and RFC 2732, - parentheses are legal URI characters and curly braces are legal - email characters, making their use prohibitively difficult. - - - The named/anonymous semantics are unclear. - -2. After an analysis__ of the syntax of (1) above, we came up with the - following compromise syntax:: - - This is an anonymous reference__ - __<http://www.example.org/reference/> of one word - ("reference"). Here is a `phrase reference`__ - __<http://www.example.org/phrase_reference/>. `Named - references`_ _<http://www.example.org/anonymous/> use single - underscores. - - __ http://mail.python.org/pipermail/doc-sig/2002-July/002670.html - - The syntax builds on that of the existing "inline internal - targets": ``an _`inline internal target`.`` - - + Advantages: - - - The target is specified immediately adjacent to the reference, - improving maintainability: - - - References and targets are easily kept in sync. - - The reference text does not have to be repeated. - - - The construct is executed in two parts: references identical to - existing references, and targets that are new but not too big a - stretch from current syntax. - - - There's overwhelming precedent for quoting URLs with angle - brackets [#]_. - - + Disadvantages: - - - Poor plaintext readability. - - Lots of "line noise". - - Targets cannot be reused (unless named; see below). - - To alleviate the readability issue slightly, we could allow the - target to appear later, such as after the end of the sentence:: - - This is a named reference__ of one word ("reference"). - __<http://www.example.org/reference/> Here is a `phrase - reference`__. __<http://www.example.org/phrase_reference/> - - Problem: this could only work for one reference at a time - (reference/target pairs must be proximate [refA trgA refB trgB], - not interleaved [refA refB trgA trgB] or nested [refA refB trgB - trgA]). This variation is too problematic; references and inline - external targets will have to be kept imediately adjacent (see (3) - below). - - The ``"reference__ __<target>"`` syntax is actually for "anonymous - inline external targets", emphasized by the double underscores. It - follows that single trailing and leading underscores would lead to - *implicitly named* inline external targets. This would allow the - reuse of targets by name. So after ``"reference_ _<target>"``, - another ``"reference_"`` would point to the same target. - - .. [#] - From RFC 2396 (URI syntax): - - The angle-bracket "<" and ">" and double-quote (") - characters are excluded [from URIs] because they are often - used as the delimiters around URI in text documents and - protocol fields. - - Using <> angle brackets around each URI is especially - recommended as a delimiting style for URI that contain - whitespace. - - From RFC 822 (email headers): - - Angle brackets ("<" and ">") are generally used to indicate - the presence of a one machine-usable reference (e.g., - delimiting mailboxes), possibly including source-routing to - the machine. - -3. If it is best for references and inline external targets to be - immediately adjacent, then they might as well be integrated. - Here's an alternative syntax embedding the target URL in the - reference:: - - This is an anonymous `reference <http://www.example.org - /reference/>`__ of one word ("reference"). Here is a `phrase - reference <http://www.example.org/phrase_reference/>`__. - - Advantages and disadvantages are similar to those in (2). - Readability is still an issue, but the syntax is a bit less - heavyweight (reduced line noise). Backquotes are required, even - for one-word references; the target URL is included within the - reference text, forcing a phrase context. - - We'll call this variant "embedded URIs". - - Problem: how to refer to a title like "HTML Anchors: <a>" (which - ends with an HTML/SGML/XML tag)? We could either require more - syntax on the target (like ``"`reference text - __<http://example.com/>`__"``), or require the odd conflicting - title to be escaped (like ``"`HTML Anchors: \<a>`__"``). The - latter seems preferable, and not too onerous. - - Similarly to (2) above, a single trailing underscore would convert - the reference & inline external target from anonymous to implicitly - named, allowing reuse of targets by name. - - I think this is the least objectionable of the syntax alternatives. - -Other syntax variations have been proposed (by Brett Cannon and Benja -Fallenstein):: - - `phrase reference`->http://www.example.com - - `phrase reference`@http://www.example.com - - `phrase reference`__ ->http://www.example.com - - `phrase reference` [-> http://www.example.com] - - `phrase reference`__ [-> http://www.example.com] - - `phrase reference` <http://www.example.com>_ - -None of these variations are clearly superior to #3 above. Some have -problems that exclude their use. - -With any kind of inline external target syntax it comes down to the -conflict between maintainability and plaintext readability. I don't -see a major problem with reStructuredText's maintainability, and I -don't want to sacrifice plaintext readability to "improve" it. - -The proponents of inline external targets want them for easily -maintainable web pages. The arguments go something like this: - -- Named hyperlinks are difficult to maintain because the reference - text is duplicated as the target name. - - To which I said, "So use anonymous hyperlinks." - -- Anonymous hyperlinks are difficult to maintain becuase the - references and targets have to be kept in sync. - - "So keep the targets close to the references, grouped after each - paragraph. Maintenance is trivial." - -- But targets grouped after paragraphs break the flow of text. - - "Surely less than URLs embedded in the text! And if the intent is - to produce web pages, not readable plaintext, then who cares about - the flow of text?" - -Many participants have voiced their objections to the proposed syntax: - - Garth Kidd: "I strongly prefer the current way of doing it. - Inline is spectactularly messy, IMHO." - - Tony Ibbs: "I vehemently agree... that the inline alternatives - being suggested look messy - there are/were good reasons they've - been taken out... I don't believe I would gain from the new - syntaxes." - - Paul Moore: "I agree as well. The proposed syntax is far too - punctuation-heavy, and any of the alternatives discussed are - ambiguous or too subtle." - -Others have voiced their support: - - fantasai: "I agree with Simon. In many cases, though certainly - not in all, I find parenthesizing the url in plain text flows - better than relegating it to a footnote." - - Ken Manheimer: "I'd like to weigh in requesting some kind of easy, - direct inline reference link." - -(Interesting that those *against* the proposal have been using -reStructuredText for a while, and those *for* the proposal are either -new to the list ["fantasai", background unknown] or longtime -StructuredText users [Ken Manheimer].) - -I was initially ambivalent/against the proposed "inline external -targets". I value reStructuredText's readability very highly, and -although the proposed syntax offers convenience, I don't know if the -convenience is worth the cost in ugliness. Does the proposed syntax -compromise readability too much, or should the choice be left up to -the author? Perhaps if the syntax is *allowed* but its use strongly -*discouraged*, for aesthetic/readability reasons? - -After a great deal of thought and much input from users, I've decided -that there are reasonable use cases for this construct. The -documentation should strongly caution against its use in most -situations, recommending independent block-level targets instead. -Syntax #3 above ("embedded URIs") will be used. - - -Doctree Representation of Transitions -===================================== - -(Although not reStructuredText-specific, this section fits best in -this document.) - -Having added the "horizontal rule" construct to the `reStructuredText -Markup Specification`_, a decision had to be made as to how to reflect -the construct in the implementation of the document tree. Given this -source:: - - Document - ======== - - Paragraph 1 - - -------- - - Paragraph 2 - -The horizontal rule indicates a "transition" (in prose terms) or the -start of a new "division". Before implementation, the parsed document -tree would be:: - - <document> - <section names="document"> - <title> - Document - <paragraph> - Paragraph 1 - -------- <--- error here - <paragraph> - Paragraph 2 - -There are several possibilities for the implementation: - -1. Implement horizontal rules as "divisions" or segments. A - "division" is a title-less, non-hierarchical section. The first - try at an implementation looked like this:: - - <document> - <section names="document"> - <title> - Document - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - But the two paragraphs are really at the same level; they shouldn't - appear to be at different levels. There's really an invisible - "first division". The horizontal rule splits the document body - into two segments, which should be treated uniformly. - -2. Treating "divisions" uniformly brings us to the second - possibility:: - - <document> - <section names="document"> - <title> - Document - <division> - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - With this change, documents and sections will directly contain - divisions and sections, but not body elements. Only divisions will - directly contain body elements. Even without a horizontal rule - anywhere, the body elements of a document or section would be - contained within a division element. This makes the document tree - deeper. This is similar to the way HTML_ treats document contents: - grouped within a ``<body>`` element. - -3. Implement them as "transitions", empty elements:: - - <document> - <section names="document"> - <title> - Document - <paragraph> - Paragraph 1 - <transition> - <paragraph> - Paragraph 2 - - A transition would be a "point element", not containing anything, - only identifying a point within the document structure. This keeps - the document tree flatter, but the idea of a "point element" like - "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. However, transitions are a - practical solution. - -Solution 3 was chosen for incorporation into the document tree model. - -.. _HTML: http://www.w3.org/MarkUp/ - - -Syntax for Line Blocks -====================== - -* An early idea: How about a literal-block-like prefix, perhaps - "``;;``"? (It is, after all, a *semi-literal* literal block, no?) - Example:: - - Take it away, Eric the Orchestra Leader! ;; - - A one, two, a one two three four - - Half a bee, philosophically, - must, *ipso facto*, half not be. - But half the bee has got to be, - *vis a vis* its entity. D'you see? - - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... - - Kinda lame. - -* Another idea: in an ordinary paragraph, if the first line ends with - a backslash (escaping the newline), interpret the entire paragraph - as a verse block? For example:: - - Add just one backslash\ - And this paragraph becomes - An awful haiku - - (Awful, and arguably invalid, since in Japanese the word "haiku" - contains three syllables not two.) - - This idea was superceded by the rules for escaped whitespace, useful - for `character-level inline markup`_. - -* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed - a "plain list" syntax (and also provided a patch):: - - | John Doe - | President, SuperDuper Corp. - | jdoe@example.org - - __ http://thread.gmane.org/gmane.text.docutils.devel/1187 - - This syntax is very natural. However, these "plain lists" seem very - similar to line blocks, and I see so little intrinsic "list-ness" - that I'm loathe to add a new object. I used the term "blurbs" to - remove the "list" connotation from the originally proposed name. - Perhaps line blocks could be refined to add the two properties they - currently lack: - - A) long lines wrap nicely - B) HTML output doesn't look like program code in non-CSS web - browsers - - (A) is an issue of all 3 aspects of Docutils: syntax (construct - behaviour), internal representation, and output. (B) is partly an - issue of internal representation but mostly of output. - -ReStructuredText will redefine line blocks with the "|"-quoting -syntax. The following is my current thinking. - - -Syntax ------- - -Perhaps line block syntax like this would do:: - - | M6: James Bond - | MIB: Mr. J. - | IMF: not decided yet, but probably one of the following: - | Ethan Hunt - | Jim Phelps - | Claire Phelps - | CIA: Felix Leiter - -Note that the "nested" list does not have nested syntax (the "|" are -not further indented); the leading whitespace would still be -significant somehow (more below). As for long lines in the input, -this could suffice:: - - | John Doe - | Founder, President, Chief Executive Officer, Cook, Bottle - Washer, and All-Round Great Guy - | SuperDuper Corp. - | jdoe@example.org - -The lack of "|" on the third line indicates that it's a continuation -of the second line, wrapped. - -I don't see much point in allowing arbitrary nested content. Multiple -paragraphs or bullet lists inside a "blurb" doesn't make sense to me. -Simple nested line blocks should suffice. - - -Internal Representation ------------------------ - -Line blocks are currently represented as text blobs as follows:: - - <!ELEMENT line_block %text.model;> - <!ATTLIST line_block - %basic.atts; - %fixedspace.att;> - -Instead, we could represent each line by a separate element:: - - <!ELEMENT line_block (line+)> - <!ATTLIST line_block %basic.atts;> - - <!ELEMENT line %text.model;> - <!ATTLIST line %basic.atts;> - -We'd keep the significance of the leading whitespace of each line -either by converting it to non-breaking spaces at output, or with a -per-line margin. Non-breaking spaces are simpler (for HTML, anyway) -but kludgey, and wouldn't support indented long lines that wrap. But -should inter-word whitespace (i.e., not leading whitespace) be -preserved? Currently it is preserved in line blocks. - -Representing a more complex line block may be tricky:: - - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - -Perhaps the representation could allow for nested line blocks:: - - <!ELEMENT line_block (line | line_block)+> - -With this model, leading whitespace would no longer be significant. -Instead, left margins are implied by the nesting. The example above -could be represented as follows:: - - <line_block> - <line> - But can a bee be said to be - <line_block> - <line> - or not to be an entire bee, - <line_block> - <line> - when half the bee is not a bee, - <line_block> - <line> - due to some ancient injury? - -I wasn't sure what to do about even more complex line blocks:: - - | Indented - | Not indented - | Indented a bit - | A bit more - | Only one space - -How should that be parsed and nested? Should the first line have -the same nesting level (== indentation in the output) as the fourth -line, or the same as the last line? Mark Nodine suggested that such -line blocks be parsed similarly to complexly-nested block quotes, -which seems reasonable. In the example above, this would result in -the nesting of first line matching the last line's nesting. In -other words, the nesting would be relative to neighboring lines -only. - - -Output ------- - -In HTML, line blocks are currently output as "<pre>" blocks, which -gives us significant whitespace and line breaks, but doesn't allow -long lines to wrap and causes monospaced output without stylesheets. -Instead, we could output "<div>" elements parallelling the -representation above, where each nested <div class="line_block"> would -have an increased left margin (specified in the stylesheet). - -Jarno suggested the following HTML output:: - - <div class="line_block"> - <span class="line">First, top level line</span><br class="hidden"/> - <div class="line_block"><span class="hidden"> </span> - <span class="line">Second, once nested</span><br class="hidden"/> - <span class="line">Third, once nested</span><br class="hidden"/> - ... - </div> - ... - </div> - -The ``<br class="hidden" />`` and ``<span -class="hidden"> </span>`` are meant to support non-CSS and -non-graphical browsers. I understand the case for "br", but I'm not -so sure about hidden " ". I question how much effort should be -put toward supporting non-graphical and especially non-CSS browsers, -at least for html4css1.py output. - -Should the lines themselves be ``<span>`` or ``<div>``? I don't like -mixing inline and block-level elements. - - -Implementation Plan -------------------- - -We'll leave the old implementation in place (via the "line-block" -directive only) until all Writers have been updated to support the new -syntax & implementation. The "line-block" directive can then be -updated to use the new internal representation, and its documentation -will be updated to recommend the new syntax. - - -List-Driven Tables -================== - -The original idea came from Dylan Jay: - - ... to use a two level bulleted list with something to - indicate it should be rendered as a table ... - -It's an interesting idea. It could be implemented in as a directive -which transforms a uniform two-level list into a table. Using a -directive would allow the author to explicitly set the table's -orientation (by column or by row), the presence of row headers, etc. - -Alternatives: - -1. (Implemented in Docutils 0.3.8). - - Bullet-list-tables might look like this:: - - .. list-table:: - - * - Treat - - Quantity - - Description - * - Albatross! - - 299 - - On a stick! - * - Crunchy Frog! - - 1499 - - If we took the bones out, it wouldn't be crunchy, - now would it? - * - Gannet Ripple! - - 199 - - On a stick! - - This list must be written in two levels. This wouldn't work:: - - .. list-table:: - - * Treat - * Albatross! - * Gannet! - * Crunchy Frog! - - * Quantity - * 299 - * 199 - * 1499 - - * Description - * On a stick! - * On a stick! - * If we took the bones out... - - The above is a single list of 12 items. The blank lines are not - significant to the markup. We'd have to explicitly specify how - many columns or rows to use, which isn't a good idea. - -2. Beni Cherniavsky suggested a field list alternative. It could look - like this:: - - .. field-list-table:: - :headrows: 1 - - - :treat: Treat - :quantity: Quantity - :descr: Description - - - :treat: Albatross! - :quantity: 299 - :descr: On a stick! - - - :treat: Crunchy Frog! - :quantity: 1499 - :descr: If we took the bones out, it wouldn't be - crunchy, now would it? - - Column order is determined from the order of fields in the first - row. Field order in all other rows is ignored. As a side-effect, - this allows trivial re-arrangement of columns. By using named - fields, it becomes possible to omit fields in some rows without - losing track of things, which is important for spans. - -3. An alternative to two-level bullet lists would be to use enumerated - lists for the table cells:: - - .. list-table:: - - * 1. Treat - 2. Quantity - 3. Description - * 1. Albatross! - 2. 299 - 3. On a stick! - * 1. Crunchy Frog! - 2. 1499 - 3. If we took the bones out, it wouldn't be crunchy, - now would it? - - That provides better correspondence between cells in the same - column than does bullet-list syntax, but not as good as field list - syntax. I think that were only field-list-tables available, a lot - of users would use the equivalent degenerate case:: - - .. field-list-table:: - - :1: Treat - :2: Quantity - :3: Description - ... - -4. Another natural variant is to allow a description list with field - lists as descriptions:: - - .. list-table:: - :headrows: 1 - - Treat - :quantity: Quantity - :descr: Description - Albatross! - :quantity: 299 - :descr: On a stick! - Crunchy Frog! - :quantity: 1499 - :descr: If we took the bones out, it wouldn't be - crunchy, now would it? - - This would make the whole first column a header column ("stub"). - It's limited to a single column and a single paragraph fitting on - one source line. Also it wouldn't allow for empty cells or row - spans in the first column. But these are limitations that we could - live with, like those of simple tables. - -The List-driven table feature could be done in many ways. Each user -will have their preferred usage. Perhaps a single "list-table" -directive could handle them all, depending on which options and -content are present. - -Issues: - -* How to indicate that there's 1 header row? Perhaps two lists? :: - - .. list-table:: - - + - Treat - - Quantity - - Description - - * - Albatross! - - 299 - - On a stick! - - This is probably too subtle though. Better would be a directive - option, like ``:headrows: 1``. An early suggestion for the header - row(s) was to use a directive option:: - - .. field-list-table:: - :header: - - :treat: Treat - :quantity: Quantity - :descr: Description - - :treat: Albatross! - :quantity: 299 - :descr: On a stick! - - But the table data is at two levels and looks inconsistent. - - In general, we cannot extract the header row from field lists' field - names because field names cannot contain everything one might put in - a table cell. A separate header row also allows shorter field names - and doesn't force one to rewrite the whole table when the header - text changes. But for simpler cases, we can offer a ":header: - fields" option, which does extract header cells from field names:: - - .. field-list-table:: - :header: fields - - - :Treat: Albatross! - :Quantity: 299 - :Description: On a stick! - -* How to indicate the column widths? A directive option? :: - - .. list-table:: - :widths: 15 10 35 - - Automatic defaults from the text used? - -* How to handle row and/or column spans? - - In a field list, column-spans can be indicated by specifying the - first and last fields, separated by space-dash-space or ellipsis:: - - - :foo - baz: quuux - - :foo ... baz: quuux - - Commas were proposed for column spans:: - - - :foo, bar: quux - - But non-adjacent columns become problematic. Should we report an - error, or duplicate the value into each span of adjacent columns (as - was suggested)? The latter suggestion is appealing but may be too - clever. Best perhaps to simply specify the two ends. - - It was suggested that comma syntax should be allowed, too, in order - to allow the user to avoid trouble when changing the column order. - But changing the column order of a table with spans is not trivial; - we shouldn't make it easier to mess up. - - One possible syntax for row-spans is to simply treat any row where a - field is missing as a row-span from the last row where it appeared. - Leaving a field empty would still be possible by writing a field - with empty content. But this is too implicit. - - Another way would be to require an explicit continuation marker - (``...``/``-"-``/``"``?) in all but the first row of a spanned - field. Empty comments could work (".."). If implemented, the same - marker could also be supported in simple tables, which lack - row-spanning abilities. - - Explicit markup like ":rowspan:" and ":colspan:" was also suggested. - - Sometimes in a table, the first header row contains spans. It may - be necessary to provide a way to specify the column field names - independently of data rows. A directive option would do it. - -* We could specify "column-wise" or "row-wise" ordering, with the same - markup structure. For example, with definition data:: - - .. list-table:: - :column-wise: - - Treat - - Albatross! - - Crunchy Frog! - Quantity - - 299 - - 1499 - Description - - On a stick! - - If we took the bones out, it wouldn't be - crunchy, now would it? - -* A syntax for _`stubs in grid tables` is easy to imagine:: - - +------------------------++------------+----------+ - | Header row, column 1 || Header 2 | Header 3 | - +========================++============+==========+ - | body row 1, column 1 || column 2 | column 3 | - +------------------------++------------+----------+ - - Or this idea from Nick Moffitt:: - - +-----+---+---+ - | XOR # T | F | - +=====+===+===+ - | T # F | T | - +-----+---+---+ - | F # T | F | - +-----+---+---+ - - -Auto-Enumerated Lists -===================== - -Implemented 2005-03-24: combination of variation 1 & 2. - -The advantage of auto-numbered enumerated lists would be similar to -that of auto-numbered footnotes: lists could be written and rearranged -without having to manually renumber them. The disadvantages are also -the same: input and output wouldn't match exactly; the markup may be -ugly or confusing (depending on which alternative is chosen). - -1. Use the "#" symbol. Example:: - - #. Item 1. - #. Item 2. - #. Item 3. - - Advantages: simple, explicit. Disadvantage: enumeration sequence - cannot be specified (limited to arabic numerals); ugly. - -2. As a variation on #1, first initialize the enumeration sequence? - For example:: - - a) Item a. - #) Item b. - #) Item c. - - Advantages: simple, explicit, any enumeration sequence possible. - Disadvantages: ugly; perhaps confusing with mixed concrete/abstract - enumerators. - -3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: - - 1. Item 1. - 1. Item 2. - 1. Item 3. - - Advantages: enumeration sequence is explicit (could be multiple - "a." or "(I)" tokens). Disadvantages: perhaps confusing; otherwise - erroneous input (e.g., a duplicate item "1.") would pass silently, - either causing a problem later in the list (if no blank lines - between items) or creating two lists (with blanks). - - Take this input for example:: - - 1. Item 1. - - 1. Unintentional duplicate of item 1. - - 2. Item 2. - - Currently the parser will produce two list, "1" and "1,2" (no - warnings, because of the presence of blank lines). Using Fred's - notation, the current behavior is "1,1,2 -> 1 1,2" (without blank - lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2"). What - should the behavior be with auto-numbering? - - Fred has produced a patch__, whose initial behavior is as follows:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2,3 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2,3 [WARNING] 3 - 1,1,2 -> 1,2 [WARNING] 2 - - (After the "[WARNING]", the "3" would begin a new list.) - - I have mixed feelings about adding this functionality to the spec & - parser. It would certainly be useful to some users (myself - included; I often have to renumber lists). Perhaps it's too - clever, asking the parser to guess too much. What if you *do* want - three one-item lists in a row, each beginning with "1."? You'd - have to use empty comments to force breaks. Also, I question - whether "1,2,2 -> 1,2,3" is optimal behavior. - - In response, Fred came up with "a stricter and more explicit rule - [which] would be to only auto-number silently if *all* the - enumerators of a list were identical". In that case:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2 [WARNING] 2 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2 [WARNING] 2,3 - 1,1,2 -> 1,2 [WARNING] 2 - - Should any start-value be allowed ("3,3,3"), or should - auto-numbered lists be limited to begin with ordinal-1 ("1", "A", - "a", "I", or "i")? - - __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802 - &group_id=38414&atid=422032 - -4. Alternative proposed by Tony Ibbs:: - - #1. First item. - #3. Aha - I edited this in later. - #2. Second item. - - The initial proposal required unique enumerators within a list, but - this limits the convenience of a feature of already limited - applicability and convenience. Not a useful requirement; dropped. - - Instead, simply prepend a "#" to a standard list enumerator to - indicate auto-enumeration. The numbers (or letters) of the - enumerators themselves are not significant, except: - - - as a sequence indicator (arabic, roman, alphabetic; upper/lower), - - - and perhaps as a start value (first list item). - - Advantages: explicit, any enumeration sequence possible. - Disadvantages: a bit ugly. - - ------------------ - Not Implemented ------------------ - -Reworking Footnotes -=================== - -As a further wrinkle (see `Reworking Explicit Markup (Round 1)`_ -above), in the wee hours of 2002-02-28 I posted several ideas for -changes to footnote syntax: - - - Change footnote syntax from ``.. [1]`` to ``_[1]``? ... - - Differentiate (with new DTD elements) author-date "citations" - (``[GVR2002]``) from numbered footnotes? ... - - Render footnote references as superscripts without "[]"? ... - -These ideas are all related, and suggest changes in the -reStructuredText syntax as well as the docutils tree model. - -The footnote has been used for both true footnotes (asides expanding -on points or defining terms) and for citations (references to external -works). Rather than dealing with one amalgam construct, we could -separate the current footnote concept into strict footnotes and -citations. Citations could be interpreted and treated differently -from footnotes. Footnotes would be limited to numerical labels: -manual ("1") and auto-numbered (anonymous "#", named "#label"). - -The footnote is the only explicit markup construct (starts with ".. ") -that directly translates to a visible body element. I've always been -a little bit uncomfortable with the ".. " marker for footnotes because -of this; ".. " has a connotation of "special", but footnotes aren't -especially "special". Printed texts often put footnotes at the bottom -of the page where the reference occurs (thus "foot note"). Some HTML -designs would leave footnotes to be rendered the same positions where -they're defined. Other online and printed designs will gather -footnotes into a section near the end of the document, converting them -to "endnotes" (perhaps using a directive in our case); but this -"special processing" is not an intrinsic property of the footnote -itself, but a decision made by the document author or processing -system. - -Citations are almost invariably collected in a section at the end of a -document or section. Citations "disappear" from where they are -defined and are magically reinserted at some well-defined point. -There's more of a connection to the "special" connotation of the ".. " -syntax. The point at which the list of citations is inserted could be -defined manually by a directive (e.g., ".. citations::"), and/or have -default behavior (e.g., a section automatically inserted at the end of -the document) that might be influenced by options to the Writer. - -Syntax proposals: - -+ Footnotes: - - - Current syntax:: - - .. [1] Footnote 1 - .. [#] Auto-numbered footnote. - .. [#label] Auto-labeled footnote. - - - The syntax proposed in the original 2002-02-28 Doc-SIG post: - remove the ".. ", prefix a "_":: - - _[1] Footnote 1 - _[#] Auto-numbered footnote. - _[#label] Auto-labeled footnote. - - The leading underscore syntax (earlier dropped because - ``.. _[1]:`` was too verbose) is a useful reminder that footnotes - are hyperlink targets. - - - Minimal syntax: remove the ".. [" and "]", prefix a "_", and - suffix a ".":: - - _1. Footnote 1. - _#. Auto-numbered footnote. - _#label. Auto-labeled footnote. - - ``_1.``, ``_#.``, and ``_#label.`` are markers, - like list markers. - - Footnotes could be rendered something like this in HTML - - | 1. This is a footnote. The brackets could be dropped - | from the label, and a vertical bar could set them - | off from the rest of the document in the HTML. - - Two-way hyperlinks on the footnote marker ("1." above) would also - help to differentiate footnotes from enumerated lists. - - If converted to endnotes (by a directive/transform), a horizontal - half-line might be used instead. Page-oriented output formats - would typically use the horizontal line for true footnotes. - -+ Footnote references: - - - Current syntax:: - - [1]_, [#]_, [#label]_ - - - Minimal syntax to match the minimal footnote syntax above:: - - 1_, #_, #label_ - - As a consequence, pure-numeric hyperlink references would not be - possible; they'd be interpreted as footnote references. - -+ Citation references: no change is proposed from the current footnote - reference syntax:: - - [GVR2001]_ - -+ Citations: - - - Current syntax (footnote syntax):: - - .. [GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - - - Possible new syntax:: - - _[GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - - _[DJG2002] - Docutils: Python Documentation Utilities project; Goodger - et al.; http://docutils.sourceforge.net/ - - Without the ".. " marker, subsequent lines would either have to - align as in one of the above, or we'd have to allow loose - alignment (I'd rather not):: - - _[GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - -I proposed adopting the "minimal" syntax for footnotes and footnote -references, and adding citations and citation references to -reStructuredText's repertoire. The current footnote syntax for -citations is better than the alternatives given. - -From a reply by Tony Ibbs on 2002-03-01: - - However, I think easier with examples, so let's create one:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - .. [1] That is, little bits of referenced text at the - bottom of the page. - .. [2] Because Terry himself does, of course [3]_. - .. [3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - .. [4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - and look at it with the second syntax proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - _[1] That is, little bits of referenced text at the - bottom of the page. - _[2] Because Terry himself does, of course [3]_. - _[3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _[4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - (I note here that if I have gotten the indentation of the - footnotes themselves correct, this is clearly not as nice. And if - the indentation should be to the left margin instead, I like that - even less). - - and the third (new) proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes 1_ in their own writings than other people - 2_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style 4_, particularly in emails (not a medium that - lends itself to footnotes). - - _1. That is, little bits of referenced text at the - bottom of the page. - _2. Because Terry himself does, of course 3_. - _3. Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _4. Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - I think I don't, in practice, mind the targets too much (the use - of a dot after the number helps a lot here), but I do have a - problem with the body text, in that I don't naturally separate out - the footnotes as different than the rest of the text - instead I - keep wondering why there are numbers interspered in the text. The - use of brackets around the numbers ([ and ]) made me somehow parse - the footnote references as "odd" - i.e., not part of the body text - - and thus both easier to skip, and also (paradoxically) easier to - pick out so that I could follow them. - - Thus, for the moment (and as always susceptable to argument), I'd - say -1 on the new form of footnote reference (i.e., I much prefer - the existing ``[1]_`` over the proposed ``1_``), and ambivalent - over the proposed target change. - - That leaves David's problem of wanting to distinguish footnotes - and citations - and the only thing I can propose there is that - footnotes are numeric or # and citations are not (which, as a - human being, I can probably cope with!). - -From a reply by Paul Moore on 2002-03-01: - - I think the current footnote syntax ``[1]_`` is *exactly* the - right balance of distinctness vs unobtrusiveness. I very - definitely don't think this should change. - - On the target change, it doesn't matter much to me. - -From a further reply by Tony Ibbs on 2002-03-01, referring to the -"[1]" form and actual usage in email: - - Clearly this is a form people are used to, and thus we should - consider it strongly (in the same way that the usage of ``*..*`` - to mean emphasis was taken partly from email practise). - - Equally clearly, there is something "magical" for people in the - use of a similar form (i.e., ``[1]``) for both footnote reference - and footnote target - it seems natural to keep them similar. - - ... - - I think that this established plaintext usage leads me to strongly - believe we should retain square brackets at both ends of a - footnote. The markup of the reference end (a single trailing - underscore) seems about as minimal as we can get away with. The - markup of the target end depends on how one envisages the thing - - if ".." means "I am a target" (as I tend to see it), then that's - good, but one can also argue that the "_[1]" syntax has a neat - symmetry with the footnote reference itself, if one wishes (in - which case ".." presumably means "hidden/special" as David seems - to think, which is why one needs a ".." *and* a leading underline - for hyperlink targets. - -Given the persuading arguments voiced, we'll leave footnote & footnote -reference syntax alone. Except that these discussions gave rise to -the "auto-symbol footnote" concept, which has been added. Citations -and citation references have also been added. - - -Syntax for Questions & Answers -============================== - -Implement as a generic two-column marked list? As a standalone -(non-directive) construct? (Is the markup ambiguous?) Add support to -parts.contents? - -New elements would be required. Perhaps:: - - <!ELEMENT question_list (question_list_item+)> - <!ATTLIST question_list - numbering (none | local | global) - #IMPLIED - start NUMBER #IMPLIED> - <!ELEMENT question_list_item (question, answer*)> - <!ELEMENT question %text.model;> - <!ELEMENT answer (%body.elements;)+> - -Originally I thought of implementing a Q&A list with special syntax:: - - Q: What am I? - - A: You are a question-and-answer - list. - - Q: What are you? - - A: I am the omniscient "we". - -Where each "Q" and "A" could also be numbered (e.g., "Q1"). However, -a simple enumerated or bulleted list will do just fine for syntax. A -directive could treat the list specially; e.g. the first paragraph -could be treated as a question, the remainder as the answer (multiple -answers could be represented by nested lists). Without special -syntax, this directive becomes low priority. - -As described in the FAQ__, no special syntax or directive is needed -for this application. - -__ http://docutils.sf.net/FAQ.html - #how-can-i-mark-up-a-faq-or-other-list-of-questions-answers - - --------- - Tabled --------- - -Reworking Explicit Markup (Round 2) -=================================== - -See `Reworking Explicit Markup (Round 1)`_ for an earlier discussion. - -In April 2004, a new thread becan on docutils-develop: `Inconsistency -in RST markup`__. Several arguments were made; the first argument -begat later arguments. Below, the arguments are paraphrased "in -quotes", with responses. - -__ http://thread.gmane.org/gmane.text.docutils.devel/1386 - -1. References and targets take this form:: - - targetname_ - - .. _targetname: stuff - - But footnotes, "which generate links just like targets do", are - written as:: - - [1]_ - - .. [1] stuff - - "Footnotes should be written as":: - - [1]_ - - .. _[1]: stuff - - But they're not the same type of animal. That's not a "footnote - target", it's a *footnote*. Being a target is not a footnote's - primary purpose (an arguable point). It just happens to grow a - target automatically, for convenience. Just as a section title:: - - Title - ===== - - isn't a "title target", it's a *title*, which happens to grow a - target automatically. The consistency is there, it's just deeper - than at first glance. - - Also, ".. [1]" was chosen for footnote syntax because it closely - resembles one form of actual footnote rendering. ".. _[1]:" is too - verbose; excessive punctuation is required to get the job done. - - For more of the reasoning behind the syntax, see `Problems With - StructuredText (Hyperlinks) <problems.html#hyperlinks>`__ and - `Reworking Footnotes`_. - -2. "I expect directives to also look like ``.. this:`` [one colon] - because that also closely parallels the link and footnote target - markup." - - There are good reasons for the two-colon syntax: - - Two colons are used after the directive type for these reasons: - - - Two colons are distinctive, and unlikely to be used in common - text. - - - Two colons avoids clashes with common comment text like:: - - .. Danger: modify at your own risk! - - - If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), a - level-3 (error) system message is generated, and the entire - directive block (including the directive itself) will be - included as a literal block. Thus "::" is a natural choice. - - -- `restructuredtext.html#directives - <../../ref/rst/restructuredtext.html#directives>`__ - - The last reason is not particularly compelling; it's more of a - convenient coincidence or mnemonic. - -3. "Comments always seemed too easy. I almost never write comments. - I'd have no problem writing '.. comment:' in front of my comments. - In fact, it would probably be more readable, as comments *should* - be set off strongly, because they are very different from normal - text." - - Many people do use comments though, and some applications of - reStructuredText require it. For example, all reStructuredText - PEPs (and this document!) have an Emacs stanza at the bottom, in a - comment. Having to write ".. comment::" would be very obtrusive. - - Comments *should* be dirt-easy to do. It should be easy to - "comment out" a block of text. Comments in programming languages - and other markup languages are invariably easy. - - Any author is welcome to preface their comments with "Comment:" or - "Do Not Print" or "Note to Editor" or anything they like. A - "comment" directive could easily be implemented. It might be - confused with admonition directives, like "note" and "caution" - though. In unrelated (and unpublished and unfinished) work, adding - a "comment" directive as a true document element was considered:: - - If structure is necessary, we could use a "comment" directive - (to avoid nonsensical DTD changes, the "comment" directive - could produce an untitled topic element). - -4. "One of the goals of reStructuredText is to be *readable* by people - who don't know it. This construction violates that: it is not at - all obvious to the uninitiated that text marked by '..' is a - comment. On the other hand, '.. comment:' would be totally - transparent." - - Totally transparent, perhaps, but also very obtrusive. Another of - `reStructuredText's goals`_ is to be unobtrusive, and - ".. comment::" would violate that. The goals of reStructuredText - are many, and they conflict. Determining the right set of goals - and finding solutions that best fit is done on a case-by-case - basis. - - Even readability is has two aspects. Being readable without any - prior knowledge is one. Being as easily read in raw form as in - processed form is the other. ".." may not contribute to the former - aspect, but ".. comment::" would certainly detract from the latter. - - .. _author's note: - .. _reStructuredText's goals: ../../ref/rst/introduction.html#goals - -5. "Recently I sent someone an rst document, and they got confused; I - had to explain to them that '..' marks comments, *unless* it's a - directive, etc..." - - The explanation of directives *is* roundabout, defining comments in - terms of not being other things. That's definitely a wart. - -6. "Under the current system, a mistyped directive (with ':' instead - of '::') will be silently ignored. This is an error that could - easily go unnoticed." - - A parser option/setting like "--comments-on-stderr" would help. - -7. "I'd prefer to see double-dot-space / command / double-colon as the - standard Docutils markup-marker. It's unusual enough to avoid - being accidently used. Everything that starts with a double-dot - should end with a double-colon." - - That would increase the punctuation verbosity of some constructs - considerably. - -8. Edward Loper proposed the following plan for backwards - compatibility: - - 1. ".. foo" will generate a deprecation warning to stderr, and - nothing in the output (no system messages). - 2. ".. foo: bar" will be treated as a directive foo. If there - is no foo directive, then do the normal error output. - 3. ".. foo:: bar" will generate a deprecation warning to - stderr, and be treated as a directive. Or leave it valid? - - So some existing documents might start printing deprecation - warnings, but the only existing documents that would *break* - would be ones that say something like:: - - .. warning: this should be a comment - - instead of:: - - .. warning:: this should be a comment - - Here, we're trading fairly common a silent error (directive - falsely treated as a comment) for a fairly uncommon explicitly - flagged error (comment falsely treated as directive). To make - things even easier, we could add a sentence to the - unknown-directive error. Something like "If you intended to - create a comment, please use '.. comment:' instead". - -On one hand, I understand and sympathize with the points raised. On -the other hand, I think the current syntax strikes the right balance -(but I acknowledge a possible lack of objectivity). On the gripping -hand, the comment and directive syntax has become well established, so -even if it's a wart, it may be a wart we have to live with. - -Making any of these changes would cause a lot of breakage or at least -deprecation warnings. I'm not sure the benefit is worth the cost. - -For now, we'll treat this as an unresolved legacy issue. - - -------- - To Do -------- - -Nested Inline Markup -==================== - -These are collected notes on a long-discussed issue. The original -mailing list messages should be referred to for details. - -* In a 2001-10-31 discussion I wrote: - - Try, for example, `Ed Loper's 2001-03-21 post`_, which details - some rules for nested inline markup. I think the complexity is - prohibitive for the marginal benefit. (And if you can understand - that tree without going mad, you're a better man than I. ;-) - - Inline markup is already fragile. Allowing nested inline markup - would only be asking for trouble IMHO. If it proves absolutely - necessary, it can be added later. The rules for what can appear - inside what must be well thought out first though. - - .. _Ed Loper's 2001-03-21 post: - http://mail.python.org/pipermail/doc-sig/2001-March/001487.html - - -- http://mail.python.org/pipermail/doc-sig/2001-October/002354.html - -* In a 2001-11-09 Doc-SIG post, I wrote: - - The problem is that in the - what-you-see-is-more-or-less-what-you-get markup language that - is reStructuredText, the symbols used for inline markup ("*", - "**", "`", "``", etc.) may preclude nesting. - - I've rethought this position. Nested markup is not precluded, just - tricky. People and software parse "double and 'single' quotes" all - the time. Continuing, - - I've thought over how we might implement nested inline - markup. The first algorithm ("first identify the outer inline - markup as we do now, then recursively scan for nested inline - markup") won't work; counterexamples were given in my `last post - <http://mail.python.org/pipermail/doc-sig/2001-November/002363.html>`__. - - The second algorithm makes my head hurt:: - - while 1: - scan for start-string - if found: - push on stack - scan for start or end string - if new start string found: - recurse - elif matching end string found: - pop stack - elif non-matching end string found: - if its a markup error: - generate warning - elif the initial start-string was misinterpreted: - # e.g. in this case: ***strong** in emphasis* - restart with the other interpretation - # but it might be several layers back ... - ... - - This is similar to how the parser does section title - recognition, but sections are much more regular and - deterministic. - - Bottom line is, I don't think the benefits are worth the effort, - even if it is possible. I'm not going to try to write the code, - at least not now. If somebody codes up a consistent, working, - general solution, I'll be happy to consider it. - - -- http://mail.python.org/pipermail/doc-sig/2001-November/002388.html - -* In a `2003-05-06 Docutils-Users post`__ Paul Tremblay proposed a new - syntax to allow for easier nesting. It eventually evolved into - this:: - - :role:[inline text] - - The duplication with the existing interpreted text syntax is - problematic though. - - __ http://article.gmane.org/gmane.text.docutils.user/317 - -* Could the parser be extended to parse nested interpreted text? :: - - :emphasis:`Some emphasized text with :strong:`some more - emphasized text` in it and **perhaps** :reference:`a link`` - -* In a `2003-06-18 Docutils-Develop post`__, Mark Nodine reported on - his implementation of a form of nested inline markup in his - Perl-based parser (unpublished). He brought up some interesting - ideas. The implementation was flawed, however, by the change in - semantics required for backslash escapes. - - __ http://article.gmane.org/gmane.text.docutils.devel/795 - -* Docutils-develop threads between David Abrahams, David Goodger, and - Mark Nodine (beginning 2004-01-16__ and 2004-01-19__) hashed out - many of the details of a potentially successful implementation, as - described below. David Abrahams checked in code to the "nesting" - branch of CVS, awaiting thorough review. - - __ http://thread.gmane.org/gmane.text.docutils.devel/1102 - __ http://thread.gmane.org/gmane.text.docutils.devel/1125 - -It may be possible to accomplish nested inline markup in general with -a more powerful inline markup parser. There may be some issues, but -I'm not averse to the idea of nested inline markup in general. I just -don't have the time or inclination to write a new parser now. Of -course, a good patch would be welcome! - -I envisage something like this. Explicit-role interpreted text must -be nestable. Prefix-based is probably preferred, since suffix-based -will look like inline literals:: - - ``text`:role1:`:role2: - -But it can be disambiguated, so it ought to be left up to the author:: - - `\ `text`:role1:`:role2: - -In addition, other forms of inline markup may be nested if -unambiguous:: - - *emphasized ``literal`` and |substitution ref| and link_* - -IOW, the parser ought to be as permissive as possible. - - -Index Entries & Indexes -======================= - -Were I writing a book with an index, I guess I'd need two -different kinds of index targets: inline/implicit and -out-of-line/explicit. For example:: - - In this `paragraph`:index:, several words are being - `marked`:index: inline as implicit `index`:index: - entries. - - .. index:: markup - .. index:: syntax - - The explicit index directives above would refer to - this paragraph. It might also make sense to allow multiple - entries in an ``index`` directive: - - .. index:: - markup - syntax - -The words "paragraph", "marked", and "index" would become index -entries pointing at the words in the first paragraph. The index -entry words appear verbatim in the text. (Don't worry about the -ugly ":index:" part; if indexing is the only/main application of -interpreted text in your documents, it can be implicit and -omitted.) The two directives provide manual indexing, where the -index entry words ("markup" and "syntax") do not appear in the -main text. We could combine the two directives into one:: - - .. index:: markup; syntax - -Semicolons instead of commas because commas could *be* part of the -index target, like:: - - .. index:: van Rossum, Guido - -Another reason for index directives is because other inline markup -wouldn't be possible within inline index targets. - -Sometimes index entries have multiple levels. Given:: - - .. index:: statement syntax: expression statements - -In a hypothetical index, combined with other entries, it might -look like this:: - - statement syntax - expression statements ..... 56 - assignment ................ 57 - simple statements ......... 58 - compound statements ....... 60 - -Inline multi-level index targets could be done too. Perhaps -something like:: - - When dealing with `expression statements <statement syntax:>`, - we must remember ... - -The opposite sense could also be possible:: - - When dealing with `index entries <:multi-level>`, there are - many permutations to consider. - -Also "see / see also" index entries. - -Given:: - - Here's a paragraph. - - .. index:: paragraph - -(The "index" directive above actually targets the *preceding* -object.) The directive should produce something like this XML:: - - <paragraph> - <index_entry text="paragraph"/> - Here's a paragraph. - </paragraph> - -This kind of content model would also allow true inline -index-entries:: - - Here's a `paragraph`:index:. - -If the "index" role were the default for the application, it could be -dropped:: - - Here's a `paragraph`. - -Both of these would result in this XML:: - - <paragraph> - Here's a <index_entry>paragraph</index_entry>. - </paragraph> - - -from 2002-06-24 docutils-develop posts --------------------------------------- - - If all of your index entries will appear verbatim in the text, - this should be sufficient. If not (e.g., if you want "Van Rossum, - Guido" in the index but "Guido van Rossum" in the text), we'll - have to figure out a supplemental mechanism, perhaps using - substitutions. - -I've thought a bit more on this, and I came up with two possibilities: - -1. Using interpreted text, embed the index entry text within the - interpreted text:: - - ... by `Guido van Rossum [Van Rossum, Guido]` ... - - The problem with this is obvious: the text becomes cluttered and - hard to read. The processed output would drop the text in - brackets, which goes against the spirit of interpreted text. - -2. Use substitutions:: - - ... by |Guido van Rossum| ... - - .. |Guido van Rossum| index:: Van Rossum, Guido - - A problem with this is that each substitution definition must have - a unique name. A subsequent ``.. |Guido van Rossum| index:: BDFL`` - would be illegal. Some kind of anonymous substitution definition - mechanism would be required, but I think that's going too far. - -Both of these alternatives are flawed. Any other ideas? - - -------------------- - ... Or Not To Do? -------------------- - -This is the realm of the possible but questionably probable. These -ideas are kept here as a record of what has been proposed, for -posterity and in case any of them prove to be useful. - - -Compound Enumerated Lists -========================= - -Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to -allow for nested enumerated lists without indentation? - - -Indented Lists -============== - -Allow for variant styles by interpreting indented lists as if they -weren't indented? For example, currently the list below will be -parsed as a list within a block quote:: - - paragraph - - * list item 1 - * list item 2 - -But a lot of people seem to write that way, and HTML browsers make it -look as if that's the way it should be. The parser could check the -contents of block quotes, and if they contain only a single list, -remove the block quote wrapper. There would be two problems: - -1. What if we actually *do* want a list inside a block quote? - -2. What if such a list comes immediately after an indented construct, - such as a literal block? - -Both could be solved using empty comments (problem 2 already exists -for a block quote after a literal block). But that's a hack. - -Perhaps a runtime setting, allowing or disabling this convenience, -would be appropriate. But that raises issues too: - - User A, who writes lists indented (and their config file is set up - to allow it), sends a file to user B, who doesn't (and their - config file disables indented lists). The result of processing by - the two users will be different. - -It may seem minor, but it adds ambiguity to the parser, which is bad. - -See the `Doc-SIG discussion starting 2001-04-18`__ with Ed Loper's -"Structuring: a summary; and an attempt at EBNF", item 4 (and -follow-ups, here__ and here__). Also `docutils-users, 2003-02-17`__ -and `beginning 2003-08-04`__. - -__ http://mail.python.org/pipermail/doc-sig/2001-April/001776.html -__ http://mail.python.org/pipermail/doc-sig/2001-April/001789.html -__ http://mail.python.org/pipermail/doc-sig/2001-April/001793.html -__ http://sourceforge.net/mailarchive/message.php?msg_id=3838913 -__ http://sf.net/mailarchive/forum.php?thread_id=2957175&forum_id=11444 - - -Sloppy Indentation of List Items -================================ - -Perhaps the indentation shouldn't be so strict. Currently, this is -required:: - - 1. First line, - second line. - -Anything wrong with this? :: - - 1. First line, - second line. - -Problem? :: - - 1. First para. - - Block quote. (no good: requires some indent relative to first - para) - - Second Para. - - 2. Have to carefully define where the literal block ends:: - - Literal block - - Literal block? - -Hmm... Non-strict indentation isn't such a good idea. - - -Lazy Indentation of List Items -============================== - -Another approach: Going back to the first draft of reStructuredText -(2000-11-27 post to Doc-SIG):: - - - This is the fourth item of the main list (no blank line above). - The second line of this item is not indented relative to the - bullet, which precludes it from having a second paragraph. - -Change that to *require* a blank line above and below, to reduce -ambiguity. This "loosening" may be added later, once the parser's -been nailed down. However, a serious drawback of this approach is to -limit the content of each list item to a single paragraph. - - -David's Idea for Lazy Indentation ---------------------------------- - -Consider a paragraph in a word processor. It is a single logical line -of text which ends with a newline, soft-wrapped arbitrarily at the -right edge of the page or screen. We can think of a plaintext -paragraph in the same way, as a single logical line of text, ending -with two newlines (a blank line) instead of one, and which may contain -arbitrary line breaks (newlines) where it was accidentally -hard-wrapped by an application. We can compensate for the accidental -hard-wrapping by "unwrapping" every unindented second and subsequent -line. The indentation of the first line of a paragraph or list item -would determine the indentation for the entire element. Blank lines -would be required between list items when using lazy indentation. - -The following example shows the lazy indentation of multiple body -elements:: - - - This is the first paragraph - of the first list item. - - Here is the second paragraph - of the first list item. - - - This is the first paragraph - of the second list item. - - Here is the second paragraph - of the second list item. - -A more complex example shows the limitations of lazy indentation:: - - - This is the first paragraph - of the first list item. - - Next is a definition list item: - - Term - Definition. The indentation of the term is - required, as is the indentation of the definition's - first line. - - When the definition extends to more than - one line, lazy indentation may occur. (This is the second - paragraph of the definition.) - - - This is the first paragraph - of the second list item. - - - Here is the first paragraph of - the first item of a nested list. - - So this paragraph would be outside of the nested list, - but inside the second list item of the outer list. - - But this paragraph is not part of the list at all. - -And the ambiguity remains:: - - - Look at the hyphen at the beginning of the next line - - is it a second list item marker, or a dash in the text? - - Similarly, we may want to refer to numbers inside enumerated - lists: - - 1. How many socks in a pair? There are - 2. How many pants in a pair? Exactly - 1. Go figure. - -Literal blocks and block quotes would still require consistent -indentation for all their lines. For block quotes, we might be able -to get away with only requiring that the first line of each contained -element be indented. For example:: - - Here's a paragraph. - - This is a paragraph inside a block quote. - Second and subsequent lines need not be indented at all. - - - A bullet list inside - the block quote. - - Second paragraph of the - bullet list inside the block quote. - -Although feasible, this form of lazy indentation has problems. The -document structure and hierarchy is not obvious from the indentation, -making the source plaintext difficult to read. This will also make -keeping track of the indentation while writing difficult and -error-prone. However, these problems may be acceptable for Wikis and -email mode, where we may be able to rely on less complex structure -(few nested lists, for example). - - -Multiple Roles in Interpreted Text -================================== - -In reStructuredText, inline markup cannot be nested (yet; `see -above`__). This also applies to interpreted text. In order to -simultaneously combine multiple roles for a single piece of text, a -syntax extension would be necessary. Ideas: - -1. Initial idea:: - - `interpreted text`:role1,role2: - -2. Suggested by Jason Diamond:: - - `interpreted text`:role1:role2: - -If a document is so complex as to require nested inline markup, -perhaps another markup system should be considered. By design, -reStructuredText does not have the flexibility of XML. - -__ `Nested Inline Markup`_ - - -Parameterized Interpreted Text -============================== - -In some cases it may be expedient to pass parameters to interpreted -text, analogous to function calls. Ideas: - -1. Parameterize the interpreted text role itself (suggested by Jason - Diamond):: - - `interpreted text`:role1(foo=bar): - - Positional parameters could also be supported:: - - `CSS`:acronym(Cascading Style Sheets): is used for HTML, and - `CSS`:acronym(Content Scrambling System): is used for DVDs. - - Technical problem: current interpreted text syntax does not - recognize roles containing whitespace. Design problem: this smells - like programming language syntax, but reStructuredText is not a - programming language. - -2. Put the parameters inside the interpreted text:: - - `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and - `CSS (Content Scrambling System)`:acronym: is used for DVDs. - - Although this could be defined on an individual basis (per role), - we ought to have a standard. Hyperlinks with embedded URIs already - use angle brackets; perhaps they could be used here too:: - - `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and - `CSS <Content Scrambling System>`:acronym: is used for DVDs. - - Do angle brackets connote URLs too much for this to be acceptable? - How about the "tag" connotation -- does it save them or doom them? - -3. `Nested inline markup`_ could prove useful here:: - - `CSS :def:`Cascading Style Sheets``:acronym: is used for HTML, - and `CSS :def:`Content Scrambling System``:acronym: is used for - DVDs. - - Inline markup roles could even define the default roles of nested - inline markup, allowing this cleaner syntax:: - - `CSS `Cascading Style Sheets``:acronym: is used for HTML, and - `CSS `Content Scrambling System``:acronym: is used for DVDs. - -Does this push inline markup too far? Readability becomes a serious -issue. Substitutions may provide a better alternative (at the expense -of verbosity and duplication) by pulling the details out of the text -flow:: - - |CSS| is used for HTML, and |CSS-DVD| is used for DVDs. - - .. |CSS| acronym:: Cascading Style Sheets - .. |CSS-DVD| acronym:: Content Scrambling System - :text: CSS - ----------------------------------------------------------------------- - -This whole idea may be going beyond the scope of reStructuredText. -Documents requiring this functionality may be better off using XML or -another markup system. - -This argument comes up regularly when pushing the envelope of -reStructuredText syntax. I think it's a useful argument in that it -provides a check on creeping featurism. In many cases, the resulting -verbosity produces such unreadable plaintext that there's a natural -desire *not* to use it unless absolutely necessary. It's a matter of -finding the right balance. - - -Syntax for Interpreted Text Role Bindings -========================================= - -The following syntax (idea from Jeffrey C. Jacobs) could be used to -associate directives with roles:: - - .. :rewrite: class:: rewrite - - `She wore ribbons in her hair and it lay with streaks of - grey`:rewrite: - -The syntax is similar to that of substitution declarations, and the -directive/role association may resolve implementation issues. The -semantics, ramifications, and implementation details would need to be -worked out. - -The example above would implement the "rewrite" role as adding a -``class="rewrite"`` attribute to the interpreted text ("inline" -element). The stylesheet would then pick up on the "class" attribute -to do the actual formatting. - -The advantage of the new syntax would be flexibility. Uses other than -"class" may present themselves. The disadvantage is complexity: -having to implement new syntax for a relatively specialized operation, -and having new semantics in existing directives ("class::" would do -something different). - -The `"role" directive`__ has been implemented. - -__ ../../ref/rst/directives.html#role - - -Character Processing -==================== - -Several people have suggested adding some form of character processing -to reStructuredText: - -* Some sort of automated replacement of ASCII sequences: - - - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). - - Convert quotes to curly quote entities. (Essentially impossible - for HTML? Unnecessary for TeX.) - - Various forms of ``:-)`` to smiley icons. - - ``"\ "`` to . Problem with line-wrapping though: it could - end up escaping the newline. - - Escaped newlines to <BR>. - - Escaped period or quote or dash as a disappearing catalyst to - allow character-level inline markup? - -* XML-style character entities, such as "©" for the copyright - symbol. - -Docutils has no need of a character entity subsystem. Supporting -Unicode and text encodings, character entities should be directly -represented in the text: a copyright symbol should be represented by -the copyright symbol character. If this is not possible in an -authoring environment, a pre-processing stage can be added, or a table -of substitution definitions can be devised. - -A "unicode" directive has been implemented to allow direct -specification of esoteric characters. In combination with the -substitution construct, "include" files defining common sets of -character entities can be defined and used. `A set of character -entity set definition files have been defined`__ (`tarball`__). -There's also `a description and instructions for use`__. - -__ http://docutils.sf.net/tmp/charents/ -__ http://docutils.sf.net/tmp/charents.tgz -__ http://docutils.sf.net/tmp/charents/README.html - -To allow for `character-level inline markup`_, a limited form of -character processing has been added to the spec and parser: escaped -whitespace characters are removed from the processed document. Any -further character processing will be of this functional type, rather -than of the character-encoding type. - -.. _character-level inline markup: - ../../ref/rst/restructuredtext.html#character-level-inline-markup - -* Directive idea:: - - .. text-replace:: "pattern" "replacement" - - - Support Unicode "U+XXXX" codes. - - Support regexps, perhaps with alternative "regexp-replace" - directive. - - Flags for regexps; ":flags:" option, or individuals. - - Specifically, should the default be case-sensistive or - -insensitive? - - -Page Or Line Breaks -=================== - -* Should ^L (or something else in reST) be defined to mean - force/suggest page breaks in whatever output we have? - - A "break" or "page-break" directive would be easy to add. A new - doctree element would be required though (perhaps "break"). The - final behavior would be up to the Writer. The directive argument - could be one of page/column/recto/verso for added flexibility. - - Currently ^L (Python's ``\f``) characters are treated as whitespace. - They're converted to single spaces, actually, as are vertical tabs - (^K, Python's ``\v``). It would be possible to recognize form feeds - as markup, but it requires some thought and discussion first. Are - there any downsides? Many editing environments do not allow the - insertion of control characters. Will it cause any harm? It would - be useful as a shorthand for the directive. - - It's common practice to use ^L before Emacs "Local Variables" - lists:: - - ^L - .. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: - - These are already present in many PEPs and Docutils project - documents. From the Emacs manual (info): - - A "local variables list" goes near the end of the file, in the - last page. (It is often best to put it on a page by itself.) - - It would be unfortunate if this construct caused a final blank page - to be generated (for those Writers that recognize the page breaks). - We'll have to add a transform that looks for a "break" plus zero or - more comments at the end of a document, and removes them. - - Probably a bad idea because there is no such thing as a page in a - generic document format. - -* Could the "break" concept above be extended to inline forms? - E.g. "^L" in the middle of a sentence could cause a line break. - Only recognize it at the end of a line (i.e., ``\f\n``)? - - Or is formfeed inappropriate? Perhaps vertical tab (``\v``), but - even that's a stretch. Can't use carriage returns, since they're - commonly used for line endings. - - Probably a bad idea as well because we do not want to use control - characters for well-readable and well-writable markup, and after all - we have the line block syntax for line breaks. - - -Superscript Markup -================== - -Add ``^superscript^`` inline markup? The only common non-markup uses -of "^" I can think of are as short hand for "superscript" itself and -for describing control characters ("^C to cancel"). The former -supports the proposed syntax, and it could be argued that the latter -ought to be literal text anyhow (e.g. "``^C`` to cancel"). - -However, superscripts are seldom needed, and new syntax would break -existing documents. When it's needed, the ``:superscript:`` -(``:sup:``) role can we used as well. - - -Code Execution -============== - -Add the following directives? - -- "exec": Execute Python code & insert the results. Call it - "python" to allow for other languages? - -- "system": Execute an ``os.system()`` call, and insert the results - (possibly as a literal block). Definitely dangerous! How to make - it safe? Perhaps such processing should be left outside of the - document, in the user's production system (a makefile or a script or - whatever). Or, the directive could be disabled by default and only - enabled with an explicit command-line option or config file setting. - Even then, an interactive prompt may be useful, such as: - - The file.txt document you are processing contains a "system" - directive requesting that the ``sudo rm -rf /`` command be - executed. Allow it to execute? (y/N) - -- "eval": Evaluate an expression & insert the text. At parse - time or at substitution time? Dangerous? Perhaps limit to canned - macros; see text.date_. - - .. _text.date: ../todo.html#text-date - -It's too dangerous (or too complicated in the case of "eval"). We do -not want to have such things in the core. - - -``encoding`` Directive -====================== - -Add an "encoding" directive to specify the character encoding of the -input data? Not a good idea for the following reasons: - -- When it sees the directive, the parser will already have read the - input data, and encoding determination will already have been done. - -- If a file with an "encoding" directive is edited and saved with - a different encoding, the directive may cause data corruption. - - -Support for Annotations -======================= - -Add an "annotation" role, as the equivalent of the HTML "title" -attribute? This is secondary information that may "pop up" when the -pointer hovers over the main text. A corresponding directive would be -required to associate annotations with the original text (by name, or -positionally as in anonymous targets?). - -There have not been many requests for such feature, though. Also, -cluttering WYSIWYG plaintext with annotations may not seem like a good -idea, and there is no "tool tip" in formats other than HTML. - - -``term`` Role -============= - -Add a "term" role for unfamiliar or specialized terminology? Probably -not; there is no real use case, and emphasis is enough for most cases. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/rst/problems.txt b/docutils/docs/dev/rst/problems.txt deleted file mode 100644 index bc0101cbf..000000000 --- a/docutils/docs/dev/rst/problems.txt +++ /dev/null @@ -1,872 +0,0 @@ -============================== - Problems With StructuredText -============================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -There are several problems, unresolved issues, and areas of -controversy within StructuredText_ (Classic and Next Generation). In -order to resolve all these issues, this analysis brings all of the -issues out into the open, enumerates all the alternatives, and -proposes solutions to be incorporated into the reStructuredText_ -specification. - - -.. contents:: - - -Formal Specification -==================== - -The description in the original StructuredText.py has been criticized -for being vague. For practical purposes, "the code *is* the spec." -Tony Ibbs has been working on deducing a `detailed description`_ from -the documentation and code of StructuredTextNG_. Edward Loper's -STMinus_ is another attempt to formalize a spec. - -For this kind of a project, the specification should always precede -the code. Otherwise, the markup is a moving target which can never be -adopted as a standard. Of course, a specification may be revised -during lifetime of the code, but without a spec there is no visible -control and thus no confidence. - - -Understanding and Extending the Code -==================================== - -The original StructuredText_ is a dense mass of sparsely commented -code and inscrutable regular expressions. It was not designed to be -extended and is very difficult to understand. StructuredTextNG_ has -been designed to allow input (syntax) and output extensions, but its -documentation (both internal [comments & docstrings], and external) is -inadequate for the complexity of the code itself. - -For reStructuredText to become truly useful, perhaps even part of -Python's standard library, it must have clear, understandable -documentation and implementation code. For the implementation of -reStructuredText to be taken seriously, it must be a sterling example -of the potential of docstrings; the implementation must practice what -the specification preaches. - - -Section Structure via Indentation -================================= - -Setext_ required that body text be indented by 2 spaces. The original -StructuredText_ and StructuredTextNG_ require that section structure -be indicated through indentation, as "inspired by Python". For -certain structures with a very limited, local extent (such as lists, -block quotes, and literal blocks), indentation naturally indicates -structure or hierarchy. For sections (which may have a very large -extent), structure via indentation is unnecessary, unnatural and -ambiguous. Rather, the syntax of the section title *itself* should -indicate that it is a section title. - -The original StructuredText states that "A single-line paragraph whose -immediately succeeding paragraphs are lower level is treated as a -header." Requiring indentation in this way is: - -- Unnecessary. The vast majority of docstrings and standalone - documents will have no more than one level of section structure. - Requiring indentation for such docstrings is unnecessary and - irritating. - -- Unnatural. Most published works use title style (type size, face, - weight, and position) and/or section/subsection numbering rather - than indentation to indicate hierarchy. This is a tradition with a - very long history. - -- Ambiguous. A StructuredText header is indistinguishable from a - one-line paragraph followed by a block quote (precluding the use of - block quotes). Enumerated section titles are ambiguous (is it a - header? is it a list item?). Some additional adornment must be - required to confirm the line's role as a title, both to a parser and - to the human reader of the source text. - -Python's use of significant whitespace is a wonderful (if not -original) innovation, however requiring indentation in ordinary -written text is hypergeneralization. - -reStructuredText_ indicates section structure through title adornment -style (as exemplified by this document). This is far more natural. -In fact, it is already in widespread use in plain text documents, -including in Python's standard distribution (such as the toplevel -README_ file). - - -Character Escaping Mechanism -============================ - -No matter what characters are chosen for markup, some day someone will -want to write documentation *about* that markup or using markup -characters in a non-markup context. Therefore, any complete markup -language must have an escaping or encoding mechanism. For a -lightweight markup system, encoding mechanisms like SGML/XML's '*' -are out. So an escaping mechanism is in. However, with carefully -chosen markup, it should be necessary to use the escaping mechanism -only infrequently. - -reStructuredText_ needs an escaping mechanism: a way to treat -markup-significant characters as the characters themselves. Currently -there is no such mechanism (although ZWiki uses '!'). What are the -candidates? - -1. ``!`` - (http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping) -2. ``\`` -3. ``~`` -4. doubling of characters - -The best choice for this is the backslash (``\``). It's "the single -most popular escaping character in the world!", therefore familiar and -unsurprising. Since characters only need to be escaped under special -circumstances, which are typically those explaining technical -programming issues, the use of the backslash is natural and -understandable. Python docstrings can be raw (prefixed with an 'r', -as in 'r""'), which would obviate the need for gratuitous doubling-up -of backslashes. - -(On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash -escapes, saying, "'nuff said. Backslash it is." Although neither -legally binding nor irrevocable nor any kind of guarantee of anything, -it is a good sign.) - -The rule would be: An unescaped backslash followed by any markup -character escapes the character. The escaped character represents the -character itself, and is prevented from playing a role in any markup -interpretation. The backslash is removed from the output. A literal -backslash is represented by an "escaped backslash," two backslashes in -a row. - -A carefully constructed set of recognition rules for inline markup -will obviate the need for backslash-escapes in almost all cases; see -`Delimitation of Inline Markup`_ below. - -When an expression (requiring backslashes and other characters used -for markup) becomes too complicated and therefore unreadable, a -literal block may be used instead. Inside literal blocks, no markup -is recognized, therefore backslashes (for the purpose of escaping -markup) become unnecessary. - -We could allow backslashes preceding non-markup characters to remain -in the output. This would make describing regular expressions and -other uses of backslashes easier. However, this would complicate the -markup rules and would be confusing. - - -Blank Lines in Lists -==================== - -Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13) -is the ability to write lists without requiring blank lines between -items. In docstrings, space is at a premium. Authors want to convey -their API or usage information in as compact a form as possible. -StructuredText_ requires blank lines between all body elements, -including list items, even when boundaries are obvious from the markup -itself. - -In reStructuredText, blank lines are optional between list items. -However, in order to eliminate ambiguity, a blank line is required -before the first list item and after the last. Nested lists also -require blank lines before the list start and after the list end. - - -Bullet List Markup -================== - -StructuredText_ includes 'o' as a bullet character. This is dangerous -and counter to the language-independent nature of the markup. There -are many languages in which 'o' is a word. For example, in Spanish:: - - Llamame a la casa - o al trabajo. - - (Call me at home or at work.) - -And in Japanese (when romanized):: - - Senshuu no doyoubi ni tegami - o kakimashita. - - ([I] wrote a letter on Saturday last week.) - -If a paragraph containing an 'o' word wraps such that the 'o' is the -first text on a line, or if a paragraph begins with such a word, it -could be misinterpreted as a bullet list. - -In reStructuredText_, 'o' is not used as a bullet character. '-', -'*', and '+' are the possible bullet characters. - - -Enumerated List Markup -====================== - -StructuredText enumerated lists are allowed to begin with numbers and -letters followed by a period or right-parenthesis, then whitespace. -This has surprising consequences for writing styles. For example, -this is recognized as an enumerated list item by StructuredText:: - - Mr. Creosote. - -People will write enumerated lists in all different ways. It is folly -to try to come up with the "perfect" format for an enumerated list, -and limit the docstring parser's recognition to that one format only. - -Rather, the parser should recognize a variety of enumerator styles. -It is also recommended that the enumerator of the first list item be -ordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not be -able to begin a list at an arbitrary enumeration. - -An initial idea was to require two or more consistent enumerated list -items in a row. This idea proved impractical and was dropped. In -practice, the presence of a proper enumerator is enough to reliably -recognize an enumerated list item; any ambiguities are reported by the -parser. Here's the original idea for posterity: - - The parser should recognize a variety of enumerator styles, mark - each block as a potential enumerated list item (PELI), and - interpret the enumerators of adjacent PELIs to decide whether they - make up a consistent enumerated list. - - If a PELI is labeled with a "1.", and is immediately followed by a - PELI labeled with a "2.", we've got an enumerated list. Or "(A)" - followed by "(B)". Or "i)" followed by "ii)", etc. The chances - of accidentally recognizing two adjacent and consistently labeled - PELIs, are acceptably small. - - For an enumerated list to be recognized, the following must be - true: - - - the list must consist of multiple adjacent list items (2 or - more) - - the enumerators must all have the same format - - the enumerators must be sequential - - -Definition List Markup -====================== - -StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) on -the first line of a paragraph to indicate a definition list item. The -' -- ' serves to separate the term (on the left) from the definition -(on the right). - -Many people use ' -- ' as an em-dash in their text, conflicting with -the StructuredText usage. Although the Chicago Manual of Style says -that spaces should not be used around an em-dash, Peter Funk pointed -out that this is standard usage in German (according to the Duden, the -official German reference), and possibly in other languages as well. -The widespread use of ' -- ' precludes its use for definition lists; -it would violate the "unsurprising" criterion. - -A simpler, and at least equally visually distinctive construct -(proposed by Guido van Rossum, who incidentally is a frequent user of -' -- ') would do just as well:: - - term 1 - Definition. - - term 2 - Definition 2, paragraph 1. - - Definition 2, paragraph 2. - -A reStructuredText definition list item consists of a term and a -definition. A term is a simple one-line paragraph. A definition is a -block indented relative to the term, and may contain multiple -paragraphs and other body elements. No blank line precedes a -definition (this distinguishes definition lists from block quotes). - - -Literal Blocks -============== - -The StructuredText_ specification has literal blocks indicated by -'example', 'examples', or '::' ending the preceding paragraph. STNG -only recognizes '::'; 'example'/'examples' are not implemented. This -is good; it fixes an unnecessary language dependency. The problem is -what to do with the sometimes- unwanted '::'. - -In reStructuredText_ '::' at the end of a paragraph indicates that -subsequent *indented* blocks are treated as literal text. No further -markup interpretation is done within literal blocks (not even -backslash-escapes). If the '::' is preceded by whitespace, '::' is -omitted from the output; if '::' was the sole content of a paragraph, -the entire paragraph is removed (no 'empty' paragraph remains). If -'::' is preceded by a non-whitespace character, '::' is replaced by -':' (i.e., the extra colon is removed). - -Thus, a section could begin with a literal block as follows:: - - Section Title - ------------- - - :: - - print "this is example literal" - - -Tables -====== - -The table markup scheme in classic StructuredText was horrible. Its -omission from StructuredTextNG is welcome, and its markup will not be -repeated here. However, tables themselves are useful in -documentation. Alternatives: - -1. This format is the most natural and obvious. It was independently - invented (no great feat of creation!), and later found to be the - format supported by the `Emacs table mode`_:: - - +------------+------------+------------+--------------+ - | Header 1 | Header 2 | Header 3 | Header 4 | - +============+============+============+==============+ - | Column 1 | Column 2 | Column 3 & 4 span (Row 1) | - +------------+------------+------------+--------------+ - | Column 1 & 2 span | Column 3 | - Column 4 | - +------------+------------+------------+ - Row 2 & 3 | - | 1 | 2 | 3 | - span | - +------------+------------+------------+--------------+ - - Tables are described with a visual outline made up of the - characters '-', '=', '|', and '+': - - - The hyphen ('-') is used for horizontal lines (row separators). - - The equals sign ('=') is optionally used as a header separator - (as of version 1.5.24, this is not supported by the Emacs table - mode). - - The vertical bar ('|') is used for for vertical lines (column - separators). - - The plus sign ('+') is used for intersections of horizontal and - vertical lines. - - Row and column spans are possible simply by omitting the column or - row separators, respectively. The header row separator must be - complete; in other words, a header cell may not span into the table - body. Each cell contains body elements, and may have multiple - paragraphs, lists, etc. Initial spaces for a left margin are - allowed; the first line of text in a cell determines its left - margin. - -2. Below is a simpler table structure. It may be better suited to - manual input than alternative #1, but there is no Emacs editing - mode available. One disadvantage is that it resembles section - titles; a one-column table would look exactly like section & - subsection titles. :: - - ============ ============ ============ ============== - Header 1 Header 2 Header 3 Header 4 - ============ ============ ============ ============== - Column 1 Column 2 Column 3 & 4 span (Row 1) - ------------ ------------ --------------------------- - Column 1 & 2 span Column 3 - Column 4 - ------------------------- ------------ - Row 2 & 3 - 1 2 3 - span - ============ ============ ============ ============== - - The table begins with a top border of equals signs with a space at - each column boundary (regardless of spans). Each row is - underlined. Internal row separators are underlines of '-', with - spaces at column boundaries. The last of the optional head rows is - underlined with '=', again with spaces at column boundaries. - Column spans have no spaces in their underline. Row spans simply - lack an underline at the row boundary. The bottom boundary of the - table consists of '=' underlines. A blank line is required - following a table. - -3. A minimalist alternative is as follows:: - - ==== ===== ======== ======== ======= ==== ===== ===== - Old State Input Action New State Notes - ----------- -------- ----------------- ----------- - ids types new type sys.msg. dupname ids types - ==== ===== ======== ======== ======= ==== ===== ===== - -- -- explicit -- -- new True - -- -- implicit -- -- new False - None False explicit -- -- new True - old False explicit implicit old new True - None True explicit explicit new None True - old True explicit explicit new,old None True [1] - None False implicit implicit new None False - old False implicit implicit new,old None False - None True implicit implicit new None True - old True implicit implicit new old True - ==== ===== ======== ======== ======= ==== ===== ===== - - The table begins with a top border of equals signs with one or more - spaces at each column boundary (regardless of spans). There must - be at least two columns in the table (to differentiate it from - section headers). Each line starts a new row. The rightmost - column is unbounded; text may continue past the edge of the table. - Each row/line must contain spaces at column boundaries, except for - explicit column spans. Underlines of '-' can be used to indicate - column spans, but should be used sparingly if at all. Lines - containing column span underlines may not contain any other text. - The last of the optional head rows is underlined with '=', again - with spaces at column boundaries. The bottom boundary of the table - consists of '=' underlines. A blank line is required following a - table. - - This table sums up the features. Using all the features in such a - small space is not pretty though:: - - ======== ======== ======== - Header 2 & 3 Span - ------------------ - Header 1 Header 2 Header 3 - ======== ======== ======== - Each line is a new row. - Each row consists of one line only. - Row spans are not possible. - The last column may spill over to the right. - Column spans are possible with an underline joining columns. - ---------------------------- - The span is limited to the row above the underline. - ======== ======== ======== - -4. As a variation of alternative 3, bullet list syntax in the first - column could be used to indicate row starts. Multi-line rows are - possible, but row spans are not. For example:: - - ===== ===== - col 1 col 2 - ===== ===== - - 1 Second column of row 1. - - 2 Second column of row 2. - Second line of paragraph. - - 3 Second column of row 3. - - Second paragraph of row 3, - column 2 - ===== ===== - - Column spans would be indicated on the line after the last line of - the row. To indicate a real bullet list within a first-column - cell, simply nest the bullets. - -5. In a further variation, we could simply assume that whitespace in - the first column implies a multi-line row; the text in other - columns is continuation text. For example:: - - ===== ===== - col 1 col 2 - ===== ===== - 1 Second column of row 1. - 2 Second column of row 2. - Second line of paragraph. - 3 Second column of row 3. - - Second paragraph of row 3, - column 2 - ===== ===== - - Limitations of this approach: - - - Cells in the first column are limited to one line of text. - - - Cells in the first column *must* contain some text; blank cells - would lead to a misinterpretation. An empty comment ("..") is - sufficient. - -6. Combining alternative 3 and 4, a bullet list in the first column - could mean multi-line rows, and no bullet list means single-line - rows only. - -Alternatives 1 and 5 has been adopted by reStructuredText. - - -Delimitation of Inline Markup -============================= - -StructuredText specifies that inline markup must begin with -whitespace, precluding such constructs as parenthesized or quoted -emphatic text:: - - "**What?**" she cried. (*exit stage left*) - -The `reStructuredText markup specification`_ allows for such -constructs and disambiguates inline markup through a set of -recognition rules. These recognition rules define the context of -markup start-strings and end-strings, allowing markup characters to be -used in most non-markup contexts without a problem (or a backslash). -So we can say, "Use asterisks (*) around words or phrases to -*emphasisze* them." The '(*)' will not be recognized as markup. This -reduces the need for markup escaping to the point where an escape -character is *almost* (but not quite!) unnecessary. - - -Underlining -=========== - -StructuredText uses '_text_' to indicate underlining. To quote David -Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring -grammar: a very revised proposal": - - The tagging of underlined text with _'s is suboptimal. Underlines - shouldn't be used from a typographic perspective (underlines were - designed to be used in manuscripts to communicate to the - typesetter that the text should be italicized -- no well-typeset - book ever uses underlines), and conflict with double-underscored - Python variable names (__init__ and the like), which would get - truncated and underlined when that effect is not desired. Note - that while *complete* markup would prevent that truncation - ('__init__'), I think of docstring markups much like I think of - type annotations -- they should be optional and above all do no - harm. In this case the underline markup does harm. - -Underlining is not part of the reStructuredText specification. - - -Inline Literals -=============== - -StructuredText's markup for inline literals (text left as-is, -verbatim, usually in a monospaced font; as in HTML <TT>) is single -quotes ('literals'). The problem with single quotes is that they are -too often used for other purposes: - -- Apostrophes: "Don't blame me, 'cause it ain't mine, it's Chris'."; - -- Quoting text: - - First Bruce: "Well Bruce, I heard the prime minister use it. - 'S'hot enough to boil a monkey's bum in 'ere your Majesty,' he - said, and she smiled quietly to herself." - - In the UK, single quotes are used for dialogue in published works. - -- String literals: s = '' - -Alternatives:: - - 'text' \'text\' ''text'' "text" \"text\" ""text"" - #text# @text@ `text` ^text^ ``text'' ``text`` - -The examples below contain inline literals, quoted text, and -apostrophes. Each example should evaluate to the following HTML:: - - Some <TT>code</TT>, with a 'quote', "double", ain't it grand? - Does <TT>a[b] = 'c' + "d" + `2^3`</TT> work? - - 0. Some code, with a quote, double, ain't it grand? - Does a[b] = 'c' + "d" + `2^3` work? - 1. Some 'code', with a \'quote\', "double", ain\'t it grand? - Does 'a[b] = \'c\' + "d" + `2^3`' work? - 2. Some \'code\', with a 'quote', "double", ain't it grand? - Does \'a[b] = 'c' + "d" + `2^3`\' work? - 3. Some ''code'', with a 'quote', "double", ain't it grand? - Does ''a[b] = 'c' + "d" + `2^3`'' work? - 4. Some "code", with a 'quote', \"double\", ain't it grand? - Does "a[b] = 'c' + "d" + `2^3`" work? - 5. Some \"code\", with a 'quote', "double", ain't it grand? - Does \"a[b] = 'c' + "d" + `2^3`\" work? - 6. Some ""code"", with a 'quote', "double", ain't it grand? - Does ""a[b] = 'c' + "d" + `2^3`"" work? - 7. Some #code#, with a 'quote', "double", ain't it grand? - Does #a[b] = 'c' + "d" + `2^3`# work? - 8. Some @code@, with a 'quote', "double", ain't it grand? - Does @a[b] = 'c' + "d" + `2^3`@ work? - 9. Some `code`, with a 'quote', "double", ain't it grand? - Does `a[b] = 'c' + "d" + \`2^3\`` work? - 10. Some ^code^, with a 'quote', "double", ain't it grand? - Does ^a[b] = 'c' + "d" + `2\^3`^ work? - 11. Some ``code'', with a 'quote', "double", ain't it grand? - Does ``a[b] = 'c' + "d" + `2^3`'' work? - 12. Some ``code``, with a 'quote', "double", ain't it grand? - Does ``a[b] = 'c' + "d" + `2^3\``` work? - -Backquotes (#9 & #12) are the best choice. They are unobtrusive and -relatviely rarely used (more rarely than ' or ", anyhow). Backquotes -have the connotation of 'quotes', which other options (like carets, -#10) don't. - -Analogously with ``*emph*`` & ``**strong**``, double-backquotes (#12) -could be used for inline literals. If single-backquotes are used for -'interpreted text' (context-sensitive domain-specific descriptive -markup) such as function name hyperlinks in Python docstrings, then -double-backquotes could be used for absolute-literals, wherein no -processing whatsoever takes place. An advantage of double-backquotes -would be that backslash-escaping would no longer be necessary for -embedded single-backquotes; however, embedded double-backquotes (in an -end-string context) would be illegal. See `Backquotes in -Phrase-Links`__ in `Record of reStructuredText Syntax Alternatives`__. - -__ alternatives.html#backquotes-in-phrase-links -__ alternatives.html - -Alternative choices are carets (#10) and TeX-style quotes (#11). For -examples of TeX-style quoting, see -http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor. - -Some existing uses of backquotes: - -1. As a synonym for repr() in Python. -2. For command-interpolation in shell scripts. -3. Used as open-quotes in TeX code (and carried over into plaintext - by TeXies). - -The inline markup start-string and end-string recognition rules -defined by the `reStructuredText markup specification`_ would allow -all of these cases inside inline literals, with very few exceptions. -As a fallback, literal blocks could handle all cases. - -Outside of inline literals, the above uses of backquotes would require -backslash-escaping. However, these are all prime examples of text -that should be marked up with inline literals. - -If either backquotes or straight single-quotes are used as markup, -TeX-quotes are too troublesome to support, so no special-casing of -TeX-quotes should be done (at least at first). If TeX-quotes have to -be used outside of literals, a single backslash-escaped would suffice: -\``TeX quote''. Ugly, true, but very infrequently used. - -Using literal blocks is a fallback option which removes the need for -backslash-escaping:: - - like this:: - - Here, we can do ``absolutely'' anything `'`'\|/|\ we like! - -No mechanism for inline literals is perfect, just as no escaping -mechanism is perfect. No matter what we use, complicated inline -expressions involving the inline literal quote and/or the backslash -will end up looking ugly. We can only choose the least often ugly -option. - -reStructuredText will use double backquotes for inline literals, and -single backqoutes for interpreted text. - - -Hyperlinks -========== - -There are three forms of hyperlink currently in StructuredText_: - -1. (Absolute & relative URIs.) Text enclosed by double quotes - followed by a colon, a URI, and concluded by punctuation plus white - space, or just white space, is treated as a hyperlink:: - - "Python":http://www.python.org/ - -2. (Absolute URIs only.) Text enclosed by double quotes followed by a - comma, one or more spaces, an absolute URI and concluded by - punctuation plus white space, or just white space, is treated as a - hyperlink:: - - "mail me", mailto:me@mail.com - -3. (Endnotes.) Text enclosed by brackets link to an endnote at the - end of the document: at the beginning of the line, two dots, a - space, and the same text in brackets, followed by the end note - itself:: - - Please refer to the fine manual [GVR2001]. - - .. [GVR2001] Python Documentation, Release 2.1, van Rossum, - Drake, et al., http://www.python.org/doc/ - -The problem with forms 1 and 2 is that they are neither intuitive nor -unobtrusive (they break design goals 5 & 2). They overload -double-quotes, which are too often used in ordinary text (potentially -breaking design goal 4). The brackets in form 3 are also too common -in ordinary text (such as [nested] asides and Python lists like [12]). - -Alternatives: - -1. Have no special markup for hyperlinks. - -2. A. Interpret and mark up hyperlinks as any contiguous text - containing '://' or ':...@' (absolute URI) or '@' (email - address) after an alphanumeric word. To de-emphasize the URI, - simply enclose it in parentheses: - - Python (http://www.python.org/) - - B. Leave special hyperlink markup as a domain-specific extension. - Hyperlinks in ordinary reStructuredText documents would be - required to be standalone (i.e. the URI text inline in the - document text). Processed hyperlinks (where the URI text is - hidden behind the link) are important enough to warrant syntax. - -3. The original Setext_ introduced a mechanism of indirect hyperlinks. - A source link word ('hot word') in the text was given a trailing - underscore:: - - Here is some text with a hyperlink_ built in. - - The hyperlink itself appeared at the end of the document on a line - by itself, beginning with two dots, a space, the link word with a - leading underscore, whitespace, and the URI itself:: - - .. _hyperlink http://www.123.xyz - - Setext used ``underscores_instead_of_spaces_`` for phrase links. - -With some modification, alternative 3 best satisfies the design goals. -It has the advantage of being readable and relatively unobtrusive. -Since each source link must match up to a target, the odd variable -ending in an underscore can be spared being marked up (although it -should generate a "no such link target" warning). The only -disadvantage is that phrase-links aren't possible without some -obtrusive syntax. - -We could achieve phrase-links if we enclose the link text: - -1. in double quotes:: - - "like this"_ - -2. in brackets:: - - [like this]_ - -3. or in backquotes:: - - `like this`_ - -Each gives us somewhat obtrusive markup, but that is unavoidable. The -bracketed syntax (#2) is reminiscent of links on many web pages -(intuitive), although it is somewhat obtrusive. Alternative #3 is -much less obtrusive, and is consistent with interpreted text: the -trailing underscore indicates the interpretation of the phrase, as a -hyperlink. #3 also disambiguates hyperlinks from footnote references. -Alternative #3 wins. - -The same trailing underscore markup can also be used for footnote and -citation references, removing the problem with ordinary bracketed text -and Python lists:: - - Please refer to the fine manual [GVR2000]_. - - .. [GVR2000] Python Documentation, van Rossum, Drake, et al., - http://www.python.org/doc/ - -The two-dots-and-a-space syntax was generalized by Setext for -comments, which are removed from the (visible) processed output. -reStructuredText uses this syntax for comments, footnotes, and link -target, collectively termed "explicit markup". For link targets, in -order to eliminate ambiguity with comments and footnotes, -reStructuredText specifies that a colon always follow the link target -word/phrase. The colon denotes 'maps to'. There is no reason to -restrict target links to the end of the document; they could just as -easily be interspersed. - -Internal hyperlinks (links from one point to another within a single -document) can be expressed by a source link as before, and a target -link with a colon but no URI. In effect, these targets 'map to' the -element immediately following. - -As an added bonus, we now have a perfect candidate for -reStructuredText directives, a simple extension mechanism: explicit -markup containing a single word followed by two colons and whitespace. -The interpretation of subsequent data on the directive line or -following is directive-dependent. - -To summarize:: - - .. This is a comment. - - .. The line below is an example of a directive. - .. version:: 1 - - This is a footnote [1]_. - - This internal hyperlink will take us to the footnotes_ area below. - - Here is a one-word_ external hyperlink. - - Here is `a hyperlink phrase`_. - - .. _footnotes: - .. [1] Footnote text goes here. - - .. external hyperlink target mappings: - .. _one-word: http://www.123.xyz - .. _a hyperlink phrase: http://www.123.xyz - -The presence or absence of a colon after the target link -differentiates an indirect hyperlink from a footnote, respectively. A -footnote requires brackets. Backquotes around a target link word or -phrase are required if the phrase contains a colon, optional -otherwise. - -Below are examples using no markup, the two StructuredText hypertext -styles, and the reStructuredText hypertext style. Each example -contains an indirect link, a direct link, a footnote/endnote, and -bracketed text. In HTML, each example should evaluate to:: - - <P>A <A HREF="http://spam.org">URI</A>, see <A HREF="#eggs2000"> - [eggs2000]</A> (in Bacon [Publisher]). Also see - <A HREF="http://eggs.org">http://eggs.org</A>.</P> - - <P><A NAME="eggs2000">[eggs2000]</A> "Spam, Spam, Spam, Eggs, - Bacon, and Spam"</P> - -1. No markup:: - - A URI http://spam.org, see eggs2000 (in Bacon [Publisher]). - Also see http://eggs.org. - - eggs2000 "Spam, Spam, Spam, Eggs, Bacon, and Spam" - -2. StructuredText absolute/relative URI syntax - ("text":http://www.url.org):: - - A "URI":http://spam.org, see [eggs2000] (in Bacon [Publisher]). - Also see "http://eggs.org":http://eggs.org. - - .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" - - Note that StructuredText does not recognize standalone URIs, - forcing doubling up as shown in the second line of the example - above. - -3. StructuredText absolute-only URI syntax - ("text", mailto:you@your.com):: - - A "URI", http://spam.org, see [eggs2000] (in Bacon - [Publisher]). Also see "http://eggs.org", http://eggs.org. - - .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" - -4. reStructuredText syntax:: - - 4. A URI_, see [eggs2000]_ (in Bacon [Publisher]). - Also see http://eggs.org. - - .. _URI: http:/spam.org - .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" - -The bracketed text '[Publisher]' may be problematic with -StructuredText (syntax 2 & 3). - -reStructuredText's syntax (#4) is definitely the most readable. The -text is separated from the link URI and the footnote, resulting in -cleanly readable text. - -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _detailed description: - http://homepage.ntlworld.com/tibsnjoan/docutils/STNG-format.html -.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html -.. _StructuredTextNG: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG -.. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/ - python/python/dist/src/README -.. _Emacs table mode: http://table.sourceforge.net/ -.. _reStructuredText Markup Specification: - ../../ref/rst/restructuredtext.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/semantics.txt b/docutils/docs/dev/semantics.txt deleted file mode 100644 index cd20e15f6..000000000 --- a/docutils/docs/dev/semantics.txt +++ /dev/null @@ -1,119 +0,0 @@ -===================== - Docstring Semantics -===================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -These are notes for a possible future PEP providing the final piece of -the Python docstring puzzle: docstring semantics or documentation -methodology. `PEP 257`_, Docstring Conventions, sketches out some -guidelines, but does not get into methodology details. - -I haven't explored documentation methodology more because, in my -opinion, it is a completely separate issue from syntax, and it's even -more controversial than syntax. Nobody wants to be told how to lay -out their documentation, a la JavaDoc_. I think the JavaDoc way is -butt-ugly, but it *is* an established standard for the Java world. -Any standard documentation methodology has to be formal enough to be -useful but remain light enough to be usable. If the methodology is -too strict, too heavy, or too ugly, many/most will not want to use it. - -I think a standard methodology could benefit the Python community, but -it would be a hard sell. A PEP would be the place to start. For most -human-readable documentation needs, the free-form text approach is -adequate. We'd only need a formal methodology if we want to extract -the parameters into a data dictionary, index, or summary of some kind. - - -PythonDoc -========= - -(Not to be confused with Daniel Larsson's pythondoc_ project.) - -A Python version of the JavaDoc_ semantics (not syntax). A set of -conventions which are understood by the Docutils. What JavaDoc has -done is to establish a syntax that enables a certain documentation -methodology, or standard *semantics*. JavaDoc is not just syntax; it -prescribes a methodology. - -- Use field lists or definition lists for "tagged blocks". By this I - mean that field lists can be used similarly to JavaDoc's ``@tag`` - syntax. That's actually one of the motivators behind field lists. - For example, we could have:: - - """ - :Parameters: - - `lines`: a list of one-line strings without newlines. - - `until_blank`: Stop collecting at the first blank line if - true (1). - - `strip_indent`: Strip common leading indent if true (1, - default). - - :Return: - - a list of indented lines with mininum indent removed; - - the amount of the indent; - - whether or not the block finished with a blank line or at - the end of `lines`. - """ - - This is taken straight out of docutils/statemachine.py, in which I - experimented with a simple documentation methodology. Another - variation I've thought of exploits the Grouch_-compatible - "classifier" element of definition lists. For example:: - - :Parameters: - `lines` : [string] - List of one-line strings without newlines. - `until_blank` : boolean - Stop collecting at the first blank line if true (1). - `strip_indent` : boolean - Strip common leading indent if true (1, default). - -- Field lists could even be used in a one-to-one correspondence with - JavaDoc ``@tags``, although I doubt if I'd recommend it. Several - ports of JavaDoc's ``@tag`` methodology exist in Python, most - recently Ed Loper's "epydoc_". - - -Other Ideas -=========== - -- Can we extract comments from parsed modules? Could be handy for - documenting function/method parameters:: - - def method(self, - source, # path of input file - dest # path of output file - ): - - This would save having to repeat parameter names in the docstring. - - Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG] - Documentation tool": - - it would be quite hard to add a new param to this method without - realising you should document it - -- Frederic Giacometti's `iPhrase Python documentation conventions`_ is - an attachment to his Doc-SIG post of 2001-05-30. - - -.. _PEP 257: http://www.python.org/peps/pep-0257.html -.. _JavaDoc: http://java.sun.com/j2se/javadoc/ -.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ -.. _Grouch: http://www.mems-exchange.org/software/grouch/ -.. _epydoc: http://epydoc.sf.net/ -.. _iPhrase Python documentation conventions: - http://mail.python.org/pipermail/doc-sig/2001-May/001840.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/testing.txt b/docutils/docs/dev/testing.txt deleted file mode 100644 index bde54116f..000000000 --- a/docutils/docs/dev/testing.txt +++ /dev/null @@ -1,246 +0,0 @@ -=================== - Docutils_ Testing -=================== - -:Author: Felix Wiemann -:Author: David Goodger -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - -When adding new functionality (or fixing bugs), be sure to add test -cases to the test suite. Practise test-first programming; it's fun, -it's addictive, and it works! - -This document describes how to run the Docutils test suite, how the -tests are organized and how to add new tests or modify existing tests. - - -Running the Test Suite -====================== - -Before checking in any changes, run the entire Docutils test suite to -be sure that you haven't broken anything. From a shell:: - - cd docutils/test - ./alltests.py - - -Python Versions -=============== - -The Docutils 0.4 release supports Python 2.1 [#py21]_ or later, with -some features only working (and being tested) with Python 2.3+. -Therefore, you should actually have Pythons 2.1 [#py21]_, 2.2, 2.3, as -well as the latest Python installed and always run the tests on all of -them. (A good way to do that is to always run the test suite through -a short script that runs ``alltests.py`` under each version of -Python.) If you can't afford intalling 3 or more Python versions, the -edge cases (2.1 and 2.3) should cover most of it. - -.. [#py21] Python 2.1 may be used providing the compiler package is - installed. The compiler package can be found in the Tools/ - directory of Python 2.1's source distribution. - -Good resources covering the differences between Python versions: - -* `What's New in Python 2.2`__ -* `What's New in Python 2.3`__ -* `What's New in Python 2.4`__ -* `PEP 290 - Code Migration and Modernization`__ - -__ http://www.python.org/doc/2.2.3/whatsnew/whatsnew22.html -__ http://www.python.org/doc/2.3.5/whatsnew/whatsnew23.html -__ http://www.python.org/doc/2.4.1/whatsnew/whatsnew24.html -__ http://www.python.org/peps/pep-0290.html - -.. _Python Check-in Policies: http://www.python.org/dev/tools.html -.. _sandbox directory: - http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/ -.. _nightly repository tarball: - http://svn.berlios.de/svndumps/docutils-repos.gz - - -Unit Tests -========== - -Unit tests test single functions or modules (i.e. whitebox testing). - -If you are implementing a new feature, be sure to write a test case -covering its functionality. It happens very frequently that your -implementation (or even only a part of it) doesn't work with an older -(or even newer) Python version, and the only reliable way to detect -those cases is using tests. - -Often, it's easier to write the test first and then implement the -functionality required to make the test pass. - - -Writing New Tests ------------------ - -When writing new tests, it very often helps to see how a similar test -is implemented. For example, the files in the -``test_parsers/test_rst/`` directory all look very similar. So when -adding a test, you don't have to reinvent the wheel. - -If there is no similar test, you can write a new test from scratch -using Python's ``unittest`` module. For an example, please have a -look at the following imaginary ``test_square.py``:: - - #! /usr/bin/env python - - # Author: your name - # Contact: your email address - # Revision: $Revision$ - # Date: $Date$ - # Copyright: This module has been placed in the public domain. - - """ - Test module for docutils.square. - """ - - import unittest - import docutils.square - - - class SquareTest(unittest.TestCase): - - def test_square(self): - self.assertEqual(docutils.square.square(0), 0) - self.assertEqual(docutils.square.square(5), 25) - self.assertEqual(docutils.square.square(7), 49) - - def test_square_root(self): - self.assertEqual(docutils.square.sqrt(49), 7) - self.assertEqual(docutils.square.sqrt(0), 0) - self.assertRaises(docutils.square.SquareRootError, - docutils.square.sqrt, 20) - - - if __name__ == '__main__': - unittest.main() - -For more details on how to write tests, please refer to the -documentation of the ``unittest`` module. - - -.. _functional: - -Functional Tests -================ - -The directory ``test/functional/`` contains data for functional tests. - -Performing functional testing means testing the Docutils system as a -whole (i.e. blackbox testing). - - -Directory Structure -------------------- - -+ ``functional/`` The main data directory. - - + ``input/`` The input files. - - - ``some_test.txt``, for example. - - + ``output/`` The actual output. - - - ``some_test.html``, for example. - - + ``expected/`` The expected output. - - - ``some_test.html``, for example. - - + ``tests/`` The config files for processing the input files. - - - ``some_test.py``, for example. - - - ``_default.py``, the `default configuration file`_. - - -The Testing Process -------------------- - -When running ``test_functional.py``, all config files in -``functional/tests/`` are processed. (Config files whose names begin -with an underscore are ignored.) The current working directory is -always Docutils' main test directory (``test/``). - -For example, ``functional/tests/some_test.py`` could read like this:: - - # Source and destination file names. - test_source = "some_test.txt" - test_destination = "some_test.html" - - # Keyword parameters passed to publish_file. - reader_name = "standalone" - parser_name = "rst" - writer_name = "html" - settings_overrides['output-encoding'] = 'utf-8' - # Relative to main ``test/`` directory. - settings_overrides['stylesheet_path'] = '../docutils/writers/html4css1/html4css1.css' - -The two variables ``test_source`` and ``test_destination`` contain the -input file name (relative to ``functional/input/``) and the output -file name (relative to ``functional/output/`` and -``functional/expected/``). Note that the file names can be chosen -arbitrarily. However, the file names in ``functional/output/`` *must* -match the file names in ``functional/expected/``. - -If defined, ``_test_more`` must be a function with the following -signature:: - - def _test_more(expected_dir, output_dir, test_case, parameters): - -This function is called from the test case to perform tests beyond the -simple comparison of expected and actual output files. - -``test_source`` and ``test_destination`` are removed from the -namespace, as are all variables whose names begin with an underscore -("_"). The remaining names are passed as keyword arguments to -``docutils.core.publish_file``, so you can set reader, parser, writer -and anything else you want to configure. Note that -``settings_overrides`` is already initialized as a dictionary *before* -the execution of the config file. - - -Creating New Tests ------------------- - -In order to create a new test, put the input test file into -``functional/input/``. Then create a config file in -``functional/tests/`` which sets at least input and output file names, -reader, parser and writer. - -Now run ``test_functional.py``. The test will fail, of course, -because you do not have an expected output yet. However, an output -file will have been generated in ``functional/output/``. Check this -output file for validity and correctness. Then copy the file to -``functional/expected/``. - -If you rerun ``test_functional.py`` now, it should pass. - -If you run ``test_functional.py`` later and the actual output doesn't -match the expected output anymore, the test will fail. - -If this is the case and you made an intentional change, check the -actual output for validity and correctness, copy it to -``functional/expected/`` (overwriting the old expected output), and -commit the change. - - -.. _default configuration file: - -The Default Configuration File ------------------------------- - -The file ``functional/tests/_default.py`` contains default settings. -It is executed just before the actual configuration files, which has -the same effect as if the contents of ``_default.py`` were prepended -to every configuration file. diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt deleted file mode 100644 index 6f1c6291d..000000000 --- a/docutils/docs/dev/todo.txt +++ /dev/null @@ -1,1964 +0,0 @@ -====================== - Docutils_ To Do List -====================== - -:Author: David Goodger (with input from many); open to all Docutils - developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - - -Priority items are marked with "@" symbols. The more @s, the higher -the priority. Items in question form (containing "?") are ideas which -require more thought and debate; they are potential to-do's. - -Many of these items are awaiting champions. If you see something -you'd like to tackle, please do! If there's something you'd like to -see done but are unable to implement it yourself, please consider -donating to Docutils: |donate| - -.. |donate| image:: http://images.sourceforge.net/images/project-support.jpg - :target: http://sourceforge.net/donate/index.php?group_id=38414 - :align: middle - :width: 88 - :height: 32 - :alt: Support the Docutils project! - -Please see also the Bugs_ document for a list of bugs in Docutils. - -.. _bugs: ../../BUGS.html - - -Release 0.4 -=========== - -We should get Docutils 0.4 out soon, but we shouldn't just cut a -"frozen snapshot" release. Here's a list of features (achievable in -the short term) to include: - -* [DONE in rev. 3901] Move support files to docutils/writers/support. - -* [DONE in rev. 4163] Convert ``docutils/writers/support/*`` into - individual writer packages. - -* [DONE in rev. 3901] Remove docutils.transforms.html.StylesheetCheck - (no longer needed because of the above change). - -* [DONE in rev. 3962] Incorporate new branch policy into the docs. - ("Development strategy" thread on Docutils-develop) - -* [DONE in rev. 4152] Added East-Asian double-width character support. - -* [DONE in rev. 4156] Merge the S5 branch. - -Anything else? - -Once released, - -* Tag it and create a maintenance branch (perhaps "maint-0-4"). - -* Declare that: - - - Docutils 0.4.x is the last version that will support Python 2.1 - (and perhaps higher?) - - - Docutils 0.4.x is the last version that will support (make - compromises for) Netscape Navigator 4 - - -Minimum Requirements for Python Standard Library Candidacy -========================================================== - -Below are action items that must be added and issues that must be -addressed before Docutils can be considered suitable to be proposed -for inclusion in the Python standard library. - -* Support for `document splitting`_. May require some major code - rework. - -* Support for subdocuments (see `large documents`_). - -* `Object numbering and object references`_. - -* `Nested inline markup`_. - -* `Python Source Reader`_. - -* The HTML writer needs to be rewritten (or a second HTML writer - added) to allow for custom classes, and for arbitrary splitting - (stack-based?). - -* Documentation_ of the architecture. Other docs too. - -* Plugin support. - -* A LaTeX writer making use of (La)TeX's power, so that the rendering - of the resulting documents is more easily customizable. (Similar to - what you wrote about a new HTML Writer.) - -* Suitability for `Python module documentation - <http://docutils.sf.net/sandbox/README.html#documenting-python>`_. - - -General -======= - -* Allow different report levels for STDERR and system_messages inside - the document? - -* Change the docutils-update script (in sandbox/infrastructure), to - support arbitrary branch snapshots. - -* Add a generic "container" element, equivalent to "inline", to which - a "class" attribute can be attached. Will require a reST directive - also. - -* Move some general-interest sandboxes out of individuals' - directories, into subprojects? - -* Add option for file (and URL) access restriction to make Docutils - usable in Wikis and similar applications. - - 2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled`` - settings. These partially solve the problem, allowing or disabling - **all** file accesses, but not limited access. - -* Configuration file handling needs discussion: - - - There should be some error checking on the contents of config - files. How much checking should be done? How loudly should - Docutils complain if it encounters an error/problem? - - - Docutils doesn't complain when it doesn't find a configuration - file supplied with the ``--config`` option. Should it? (If yes, - error or warning?) - -* Internationalization: - - - I18n needs refactoring, the language dictionaries are difficult to - maintain. Maybe have a look at gettext or similar tools. - - - Language modules: in accented languages it may be useful to have - both accented and unaccented entries in the - ``bibliographic_fields`` mapping for versatility. - - - Add a "--strict-language" option & setting: no English fallback - for language-dependent features. - - - Add internationalization to _`footer boilerplate text` (resulting - from "--generator", "--source-link", and "--date" etc.), allowing - translations. - -* Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP. - -* In ``docutils.readers.get_reader_class`` (& ``parsers`` & - ``writers`` too), should we be importing "standalone" or - "docutils.readers.standalone"? (This would avoid importing - top-level modules if the module name is not in docutils/readers. - Potential nastiness.) - -* Perhaps store a _`name-to-id mapping file`? This could be stored - permanently, read by subsequent processing runs, and updated with - new entries. ("Persistent ID mapping"?) - -* Perhaps the ``Component.supports`` method should deal with - individual features ("meta" etc.) instead of formats ("html" etc.)? - -* Add _`object numbering and object references` (tables & figures). - These would be the equivalent of DocBook's "formal" elements. - - We may need _`persistent sequences`, such as chapter numbers. See - `OpenOffice.org XML`_ "fields". Should the sequences be automatic - or manual (user-specifyable)? - - We need to name the objects: - - - "name" option for the "figure" directive? :: - - .. figure:: image.png - :name: image's name - - Same for the "table" directive:: - - .. table:: optional title here - :name: table's name - - ===== ===== - x not x - ===== ===== - True False - False True - ===== ===== - - This would also allow other options to be set, like border - styles. The same technique could be used for other objects. - - A preliminary "table" directive has been implemented, supporting - table titles. Perhaps the name should derive from the title. - - - The object could also be done this way:: - - .. _figure name: - - .. figure:: image.png - - This may be a more general solution, equally applicable to tables. - However, explicit naming using an option seems simpler to users. - - - Perhaps the figure name could be incorporated into the figure - definition, as an optional inline target part of the directive - argument:: - - .. figure:: _`figure name` image.png - - Maybe with a delimiter:: - - .. figure:: _`figure name`: image.png - - Or some other, simpler syntax. - - We'll also need syntax for object references. See `OpenOffice.org - XML`_ "reference fields": - - - Parameterized substitutions? For example:: - - See |figure (figure name)| on |page (figure name)|. - - .. |figure (name)| figure-ref:: (name) - .. |page (name)| page-ref:: (name) - - The result would be:: - - See figure 3.11 on page 157. - - But this would require substitution directives to be processed at - reference-time, not at definition-time as they are now. Or, - perhaps the directives could just leave ``pending`` elements - behind, and the transforms do the work? How to pass the data - through? Too complicated. - - - An interpreted text approach is simpler and better:: - - See :figure:`figure name` on :page:`figure name`. - - The "figure" and "page" roles could generate appropriate - boilerplate text. The position of the role (prefix or suffix) - could also be utilized. - - See `Interpreted Text`_ below. - - - We could leave the boilerplate text up to the document:: - - See Figure :fig:`figure name` on page :pg:`figure name`. - - - Reference boilerplate could be specified in the document - (defaulting to nothing):: - - .. fignum:: - :prefix-ref: "Figure " - :prefix-caption: "Fig. " - :suffix-caption: : - - .. _OpenOffice.org XML: http://xml.openoffice.org/ - -* Think about _`large documents` made up of multiple subdocument - files. Issues: continuity (`persistent sequences`_ above), - cross-references (`name-to-id mapping file`_ above and `targets in - other documents`_ below), splitting (`document splitting`_ below). - - When writing a book, the author probably wants to split it up into - files, perhaps one per chapter (but perhaps even more detailed). - However, we'd like to be able to have references from one chapter to - another, and have continuous numbering (pages and chapters, as - applicable). Of course, none of this is implemented yet. There has - been some thought put into some aspects; see `the "include" - directive`__ and the `Reference Merging`_ transform below. - - When I was working with SGML in Japan, we had a system where there - was a top-level coordinating file, book.sgml, which contained the - top-level structure of a book: the <book> element, containing the - book <title> and empty component elements (<preface>, <chapter>, - <appendix>, etc.), each with filename attributes pointing to the - actual source for the component. Something like this:: - - <book id="bk01"> - <title>Title of the Book</title> - <preface inrefid="pr01"></preface> - <chapter inrefid="ch01"></chapter> - <chapter inrefid="ch02"></chapter> - <chapter inrefid="ch03"></chapter> - <appendix inrefid="ap01"></appendix> - </book> - - (The "inrefid" attribute stood for "insertion reference ID".) - - The processing system would process each component separately, but - it would recognize and use the book file to coordinate chapter and - page numbering, and keep a persistent ID to (title, page number) - mapping database for cross-references. Docutils could use a similar - system for large-scale, multipart documents. - - __ ../ref/rst/directives.html#including-an-external-document-fragment - - Aahz's idea: - - First the ToC:: - - .. ToC-list:: - Introduction.txt - Objects.txt - Data.txt - Control.txt - - Then a sample use:: - - .. include:: ToC.txt - - As I said earlier in chapter :chapter:`Objects.txt`, the - reference count gets increased every time a binding is made. - - Which produces:: - - As I said earlier in chapter 2, the - reference count gets increased every time a binding is made. - - The ToC in this form doesn't even need to be references to actual - reST documents; I'm simply doing it that way for a minimum of - future-proofing, in case I do want to add the ability to pick up - references within external chapters. - - Perhaps, instead of ToC (which would overload the "contents" - directive concept already in use), we could use "manifest". A - "manifest" directive might associate local reference names with - files:: - - .. manifest:: - intro: Introduction.txt - objects: Objects.txt - data: Data.txt - control: Control.txt - - Then the sample becomes:: - - .. include:: manifest.txt - - As I said earlier in chapter :chapter:`objects`, the - reference count gets increased every time a binding is made. - -* Add support for _`multiple output files`. - -* Add testing for Docutils' front end tools? - -* Publisher: "Ordinary setup" shouldn't requre specific ordering; at - the very least, there ought to be error checking higher up in the - call chain. [Aahz] - - ``Publisher.get_settings`` requires that all components be set up - before it's called. Perhaps the I/O *objects* shouldn't be set, but - I/O *classes*. Then options are set up (``.set_options``), and - ``Publisher.set_io`` (or equivalent code) is called with source & - destination paths, creating the I/O objects. - - Perhaps I/O objects shouldn't be instantiated until required. For - split output, the Writer may be called multiple times, once for each - doctree, and each doctree should have a separate Output object (with - a different path). Is the "Builder" pattern applicable here? - -* Perhaps I/O objects should become full-fledged components (i.e. - subclasses of ``docutils.Component``, as are Readers, Parsers, and - Writers now), and thus have associated option/setting specs and - transforms. - -* Multiple file I/O suggestion from Michael Hudson: use a file-like - object or something you can iterate over to get file-like objects. - -* Add an "--input-language" option & setting? Specify a different - language module for input (bibliographic fields, directives) than - for output. The "--language" option would set both input & output - languages. - -* Auto-generate reference tables for language-dependent features? - Could be generated from the source modules. A special command-line - option could be added to Docutils front ends to do this. (Idea from - Engelbert Gruber.) - -* Enable feedback of some kind from internal decisions, such as - reporting the successful input encoding. Modify runtime settings? - System message? Simple stderr output? - -* Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings. - -* Merge docs/user/latex.txt info into tools.txt and config.txt. - -* Add an "--include file" command-line option (config setting too?), - equivalent to ".. include:: file" as the first line of the doc text? - Especially useful for character entity sets, text transform specs, - boilerplate, etc. - -* Parameterize the Reporter object or class? See the `2004-02-18 - "rest checking and source path"`_ thread. - - .. _2004-02-18 "rest checking and source path": - http://thread.gmane.org/gmane.text.docutils.user/1112 - -* Add a "disable_transforms" setting? And a dummy Writer subclass - that does nothing when its .write() method is called? Would allow - for easy syntax checking. See the `2004-02-18 "rest checking and - source path"`_ thread. - -* Add a generic meta-stylesheet mechanism? An external file could - associate style names ("class" attributes) with specific elements. - Could be generalized to arbitrary output attributes; useful for HTML - & XMLs. Aahz implemented something like this in - sandbox/aahz/Effective/EffMap.py. - -* .. _classes for table cells: - - William Dode suggested that table cells be assigned "class" - attributes by columns, so that stylesheets can affect text - alignment. Unfortunately, there doesn't seem to be a way (in HTML - at least) to leverage the "colspec" elements (HTML "col" tags) by - adding classes to them. The resulting HTML is very verbose:: - - <td class="col1">111</td> - <td class="col2">222</td> - ... - - At the very least, it should be an option. People who don't use it - shouldn't be penalized by increases in their HTML file sizes. - - Table rows could also be assigned classes (like odd/even). That - would be easier to implement. - - How should it be implemented? - - * There could be writer options (column classes & row classes) with - standard values. - - * The table directive could grow some options. Something like - ":cell-classes: col1 col2 col3" (either must match the number of - columns, or repeat to fill?) and ":row-classes: odd even" (repeat - to fill; body rows only, or header rows too?). - - Probably per-table directive options are best. The "class" values - could be used by any writer, and applying such classes to all tables - in a document with writer options is too broad. - -* Add file-specific settings support to config files, like:: - - [file index.txt] - compact-lists: no - - Is this even possible? Should the criterion be the name of the - input file or the output file? - -* The "validator" support added to OptionParser is very similar to - "traits_" in SciPy_. Perhaps something could be done with them? - (Had I known about traits when I was implementing docutils.frontend, - I may have used them instead of rolling my own.) - - .. _traits: http://code.enthought.com/traits/ - .. _SciPy: http://www.scipy.org/ - -* tools/buildhtml.py: Extend the --prune option ("prune" config - setting) to accept file names (generic path) in addition to - directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should - *not* be converted to HTML). - -* Add support for _`plugins`. - -* _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, & - /etc/docutils.conf are read as configuration files. Proposal: allow - ~/.docutils to be a a configuration *directory*, along with - /etc/docutils/ and ./docutils.conf/. Within these directories, - check for config.txt files. We can also have subdirectories here, - for plugins, S5 themes, components (readers/writers/parsers) etc. - - Docutils will continue to support configuration files for backwards - compatibility. - -* Add support for document decorations other than headers & footers? - For example, top/bottom/side navigation bars for web pages. Generic - decorations? - - Seems like a bad idea as long as it isn't independent from the ouput - format (for example, navigation bars are only useful for web pages). - -* docutils_update: Check for a ``Makefile`` in a directory, and run - ``make`` if found? This would allow for variant processing on - specific source files, such as running rst2s5.py instead of - rst2html.py. - -* Add a "disable table of contents" setting? The S5 writer could set - it as a default. Rationale: - - The ``contents`` (table of contents) directive must not be used - [in S5/HTML documents]. It changes the CSS class of headings - and they won't show up correctly in the screen presentation. - - -- `Easy Slide Shows With reStructuredText & S5 - <../user/slide-shows.html>`_ - - -Documentation -============= - -User Docs ---------- - -* Add a FAQ entry about using Docutils (with reStructuredText) on a - server and that it's terribly slow. See the first paragraphs in - <http://article.gmane.org/gmane.text.docutils.user/1584>. - -* Add document about what Docutils has previously been used for - (web/use-cases.txt?). - - -Developer Docs --------------- - -* Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_. - -* Improve the internal module documentation (docstrings in the code). - Specific deficiencies listed below. - - - docutils.parsers.rst.states.State.build_table: data structure - required (including StringList). - - - docutils.parsers.rst.states: more complete documentation of parser - internals. - -* docs/ref/doctree.txt: DTD element structural relationships, - semantics, and attributes. In progress; element descriptions to be - completed. - -* Document the ``pending`` elements, how they're generated and what - they do. - -* Document the transforms (perhaps in docstrings?): how they're used, - what they do, dependencies & order considerations. - -* Document the HTML classes used by html4css1.py. - -* Write an overview of the Docutils architecture, as an introduction - for developers. What connects to what, why, and how. Either update - PEP 258 (see PEPs_ below) or as a separate doc. - -* Give information about unit tests. Maybe as a howto? - -* Document the docutils.nodes APIs. - -* Complete the docs/api/publisher.txt docs. - - -How-Tos -------- - -* Creating Docutils Writers - -* Creating Docutils Readers - -* Creating Docutils Transforms - -* Creating Docutils Parsers - -* Using Docutils as a Library - - -PEPs ----- - -* Complete PEP 258 Docutils Design Specification. - - - Fill in the blanks in API details. - - - Specify the nodes.py internal data structure implementation? - - [Tibs:] Eventually we need to have direct documentation in - there on how it all hangs together - the DTD is not enough - (indeed, is it still meant to be correct? [Yes, it is. - --DG]). - -* Rework PEP 257, separating style from spec from tools, wrt Docutils? - See Doc-SIG from 2001-06-19/20. - - -Python Source Reader -==================== - -General: - -* Analyze Tony Ibbs' PySource code. - -* Analyze Doug Hellmann's HappyDoc project. - -* Investigate how POD handles literate programming. - -* Take the best ideas and integrate them into Docutils. - -Miscellaneous ideas: - -* Ask Python-dev for opinions (GvR for a pronouncement) on special - variables (__author__, __version__, etc.): convenience vs. namespace - pollution. Ask opinions on whether or not Docutils should recognize - & use them. - -* If we can detect that a comment block begins with ``##``, a la - JavaDoc, it might be useful to indicate interspersed section headers - & explanatory text in a module. For example:: - - """Module docstring.""" - - ## - # Constants - # ========= - - a = 1 - b = 2 - - ## - # Exception Classes - # ================= - - class MyException(Exception): pass - - # etc. - -* Should standalone strings also become (module/class) docstrings? - Under what conditions? We want to prevent arbitrary strings from - becomming docstrings of prior attribute assignments etc. Assume - that there must be no blank lines between attributes and attribute - docstrings? (Use lineno of NEWLINE token.) - - Triple-quotes are sometimes used for multi-line comments (such as - commenting out blocks of code). How to reconcile? - -* HappyDoc's idea of using comment blocks when there's no docstring - may be useful to get around the conflict between `additional - docstrings`_ and ``from __future__ import`` for module docstrings. - A module could begin like this:: - - #!/usr/bin/env python - # :Author: Me - # :Copyright: whatever - - """This is the public module docstring (``__doc__``).""" - - # More docs, in comments. - # All comments at the beginning of a module could be - # accumulated as docstrings. - # We can't have another docstring here, because of the - # ``__future__`` statement. - - from __future__ import division - - Using the JavaDoc convention of a doc-comment block beginning with - ``##`` is useful though. It allows doc-comments and implementation - comments. - - .. _additional docstrings: - ../peps/pep-0258.html#additional-docstrings - -* HappyDoc uses an initial comment block to set "parser configuration - values". Do the same thing for Docutils, to set runtime settings on - a per-module basis? I.e.:: - - # Docutils:setting=value - - Could be used to turn on/off function parameter comment recognition - & other marginal features. Could be used as a general mechanism to - augment config files and command-line options (but which takes - precedence?). - -* Multi-file output should be divisible at arbitrary level. - -* Support all forms of ``import`` statements: - - - ``import module``: listed as "module" - - ``import module as alias``: "alias (module)" - - ``from module import identifier``: "identifier (from module)" - - ``from module import identifier as alias``: "alias (identifier - from module)" - - ``from module import *``: "all identifiers (``*``) from module" - -* Have links to colorized Python source files from API docs? And - vice-versa: backlinks from the colorized source files to the API - docs! - -* In summaries, use the first *sentence* of a docstring if the first - line is not followed by a blank line. - - -reStructuredText Parser -======================= - -Also see the `... Or Not To Do?`__ list. - -__ rst/alternatives.html#or-not-to-do - -* Treat enumerated lists that are not arabic and consist of only one - item in a single line as ordinary paragraphs. See - <http://article.gmane.org/gmane.text.docutils.user/2635>. - -* The citation syntax could use some enhancements. See - <http://thread.gmane.org/gmane.text.docutils.user/2499> and - <http://thread.gmane.org/gmane.text.docutils.user/2443>. - -* The current list-recognition logic has too many false positives, as - in :: - - * Aorta - * V. cava superior - * V. cava inferior - - Here ``V.`` is recognized as an enumerator, which leads to - confusion. We need to find a solution that resolves such problems - without complicating the spec to much. - - See <http://thread.gmane.org/gmane.text.docutils.user/2524>. - -* Add indirect links via citation references & footnote references. - Example:: - - `Goodger (2005)`_ is helpful. - - .. _Goodger (2005): [goodger2005]_ - .. [goodger2005] citation text - - See <http://thread.gmane.org/gmane.text.docutils.user/2499>. - -* Allow multiple block quotes, only separated by attributions - (http://article.gmane.org/gmane.text.docutils.devel/2985), e.g.:: - - quote 1 - - ---Attrib 1 - - quote 2 - - ---Attrib 2 - -* Change the specification so that more punctuation is allowed - before/after inline markup start/end string - (http://article.gmane.org/gmane.text.docutils.cvs/3824). - -* Complain about bad URI characters - (http://article.gmane.org/gmane.text.docutils.user/2046) and - disallow internal whitespace - (http://article.gmane.org/gmane.text.docutils.user/2214). - -* Create ``info``-level system messages for unnecessarily - backslash-escaped characters (as in ``"\something"``, rendered as - "something") to allow checking for errors which silently slipped - through. - -* Add (functional) tests for untested roles. - -* Add test for ":figwidth: image" option of "figure" directive. (Test - code needs to check if PIL is available on the system.) - -* Add support for CJK double-width whitespace (indentation) & - punctuation characters (markup; e.g. double-width "*", "-", "+")? - -* Add motivation sections for constructs in spec. - -* Support generic hyperlink references to _`targets in other - documents`? Not in an HTML-centric way, though (it's trivial to say - ``http://www.example.com/doc#name``, and useless in non-HTML - contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG - 2001-08-10. - -* .. _adaptable file extensions: - - In target URLs, it would be useful to not explicitly specify the - file extension. If we're generating HTML, then ".html" is - appropriate; if PDF, then ".pdf"; etc. How about using ".*" to - indicate "choose the most appropriate filename extension"? For - example:: - - .. _Another Document: another.* - - What is to be done for output formats that don't *have* hyperlinks? - For example, LaTeX targeted at print. Hyperlinks may be "called - out", as footnotes with explicit URLs. - - But then there's also LaTeX targeted at PDFs, which *can* have - links. Perhaps a runtime setting for "*" could explicitly provide - the extension, defaulting to the output file's extension. - - Should the system check for existing files? No, not practical. - - Handle documents only, or objects (images, etc.) also? - - If this handles images also, how to differentiate between document - and image links? Element context (within "image")? Which image - extension to use for which document format? Again, a runtime - setting would suffice. - - This may not be just a parser issue; it may need framework support. - - Mailing list threads: `Images in both HTML and LaTeX`__ (especially - `this summary of Felix's objections`__), `more-universal links?`__, - `Output-format-sensitive link targets?`__ - - __ http://thread.gmane.org/gmane.text.docutils.user/1239 - __ http://article.gmane.org/gmane.text.docutils.user/1278 - __ http://thread.gmane.org/gmane.text.docutils.user/1915 - __ http://thread.gmane.org/gmane.text.docutils.user/2438 - -* Implement the header row separator modification to table.el. (Wrote - to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting - support for "=====" header rows. On 2001-08-17 he replied, saying - he'd put it on his to-do list, but "don't hold your breath".) - -* Fix the parser's indentation handling to conform with the stricter - definition in the spec. (Explicit markup blocks should be strict or - forgiving?) - - .. XXX What does this mean? Can you elaborate, David? - -* Make the parser modular. Allow syntax constructs to be added or - disabled at run-time. Subclassing is probably not enough because it - makes it difficult to apply multiple extensions. - -* Generalize the "doctest block" construct (which is overly - Python-centric) to other interactive sessions? "Doctest block" - could be renamed to "I/O block" or "interactive block", and each of - these could also be recognized as such by the parser: - - - Shell sessions:: - - $ cat example1.txt - A block beginning with a "$ " prompt is interpreted as a shell - session interactive block. As with Doctest blocks, the - interactive block ends with the first blank line, and wouldn't - have to be indented. - - - Root shell sessions:: - - # cat example2.txt - A block beginning with a "# " prompt is interpreted as a root - shell session (the user is or has to be logged in as root) - interactive block. Again, the block ends with a blank line. - - Other standard (and unambiguous) interactive session prompts could - easily be added (such as "> " for WinDOS). - - Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread - "docutils feedback"). - -* The "doctest" element should go away. The construct could simply be - a front-end to generic literal blocks. We could immediately (in - 0.4, or 0.5) remove the doctest node from the doctree, but leave the - syntax in reST. The reST parser could represent doctest blocks as - literal blocks with a class attribute. The syntax could be left in - reST for a set period of time. - -* Add support for pragma (syntax-altering) directives. - - Some pragma directives could be local-scope unless explicitly - specified as global/pragma using ":global:" options. - -* Support whitespace in angle-bracketed standalone URLs according to - Appendix E ("Recommendations for Delimiting URI in Context") of `RFC - 2396`_. - - .. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt - -* Use the vertical spacing of the source text to determine the - corresponding vertical spacing of the output? - -* [From Mark Nodine] For cells in simple tables that comprise a - single line, the justification can be inferred according to the - following rules: - - 1. If the text begins at the leftmost column of the cell, - then left justification, ELSE - 2. If the text begins at the rightmost column of the cell, - then right justification, ELSE - 3. Center justification. - - The onus is on the author to make the text unambiguous by adding - blank columns as necessary. There should be a parser setting to - turn off justification-recognition (normally on would be fine). - - Decimal justification? - - All this shouldn't be done automatically. Only when it's requested - by the user, e.g. with something like this:: - - .. table:: - :auto-indent: - - (Table goes here.) - - Otherwise it will break existing documents. - -* Generate a warning or info message for paragraphs which should have - been lists, like this one:: - - 1. line one - 3. line two - -* Generalize the "target-notes" directive into a command-line option - somehow? See docutils-develop 2003-02-13. - -* Allow a "::"-only paragraph (first line, actually) to introduce a - _`literal block without a blank line`? (Idea from Paul Moore.) :: - - :: - This is a literal block - - Is indentation enough to make the separation between a paragraph - which contains just a ``::`` and the literal text unambiguous? - (There's one problem with this concession: If one wants a definition - list item which defines the term "::", we'd have to escape it.) It - would only be reasonable to apply it to "::"-only paragraphs though. - I think the blank line is visually necessary if there's text before - the "::":: - - The text in this paragraph needs separation - from the literal block following:: - This doesn't look right. - -* Add new syntax for _`nested inline markup`? Or extend the parser to - parse nested inline markup somehow? See the `collected notes - <rst/alternatives.html#nested-inline-markup>`__. - -* Drop the backticks from embedded URIs with omitted reference text? - Should the angle brackets be kept in the output or not? :: - - <file_name>_ - - Probably not worth the trouble. - -* Add _`math markup`. We should try for a general solution, that's - applicable to any output format. Using a standard, such as MathML_, - would be best. TeX (or itex_) would be acceptable as a *front-end* - to MathML. See `the culmination of a relevant discussion - <http://article.gmane.org/gmane.text.docutils.user/118>`__. - - Both a directive and an interpreted text role will be necessary (for - each markup). Directive example:: - - .. itex:: - \alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda) - - The same thing inline:: - - The equation in question is :itex:`\alpha_t(i) = P(O_1, O_2, - \dots O_t, q_t = S_i \lambda)`. - - .. _MathML: http://www.w3.org/TR/MathML2/ - .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html - -* How about a syntax for alternative hyperlink behavior, such as "open - in a new window" (as in HTML's ``<a target="_blank">``)? Double - angle brackets might work for inline targets:: - - The `reference docs <<url>>`__ may be handy. - - But what about explicit targets? - - The MoinMoin wiki uses a caret ("^") at the beginning of the URL - ("^" is not a legal URI character). That could work for both inline - and explicit targets:: - - The `reference docs <^url>`__ may be handy. - - .. _name: ^url - - This may be too specific to HTML. It hasn't been requested very - often either. - -* Add an option to add URI schemes at runtime. - -* _`Segmented lists`:: - - : segment : segment : segment - : segment : segment : very long - segment - : segment : segment : segment - - The initial colon (":") can be thought of as a type of bullet - - We could even have segment titles:: - - :: title : title : title - : segment : segment : segment - : segment : segment : segment - - This would correspond well to DocBook's SegmentedList. Output could - be tabular or "name: value" pairs, as described in DocBook's docs. - -* Allow backslash-escaped colons in field names:: - - :Case Study\: Event Handling: This chapter will be dropped. - -* _`footnote spaces`: - - When supplying the command line options - --footnote-references=brackets and --use-latex-footnotes with the - LaTeX writer (which might very well happen when using configuration - files), the spaces in front of footnote references aren't trimmed. - -* Enable grid _`tables inside XML comments`, where "--" ends comments. - I see three implementation possibilities: - - 1. Make the table syntax characters into "table" directive options. - This is the most flexible but most difficult, and we probably - don't need that much flexibility. - - 2. Substitute "~" for "-" with a specialized directive option - (e.g. ":tildes:"). - - 3. Make the standard table syntax recognize "~" as well as "-", even - without a directive option. Individual tables would have to be - internally consistent. - - Directive options are preferable to configuration settings, because - tables are document-specific. A pragma directive would be another - approach, to set the syntax once for a whole document. - - In the meantime, the list-table_ directive is a good replacement for - grid tables inside XML comments. - - .. _list-table: ../ref/rst/directives.html#list-table - -* Generalize docinfo contents (bibliographic fields): remove specific - fields, and have only a single generic "field"? - - -Directives ----------- - -Directives below are often referred to as "module.directive", the -directive function. The "module." is not part of the directive name -when used in a document. - -* Make the _`directive interface` object-oriented - (http://article.gmane.org/gmane.text.docutils.user/1871). - -* Allow for field lists in list tables. See - <http://thread.gmane.org/gmane.text.docutils.devel/3392>. - -* .. _unify tables: - - Unify table implementations and unify options of table directives - (http://article.gmane.org/gmane.text.docutils.user/1857). - -* Allow directives to be added at run-time? - -* Use the language module for directive option names? - -* Add "substitution_only" and "substitution_ok" function attributes, - and automate context checking? - -* Change directive functions to directive classes? Superclass' - ``__init__()`` could handle all the bookkeeping. - -* Implement options or features on existing directives: - - - Add a "name" option to directives, to set an author-supplied - identifier? - - - All directives that produce titled elements should grow implicit - reference names based on the titles. - - - Allow the _`:trim:` option for all directives when they occur in a - substitution definition, not only the unicode_ directive. - - .. _unicode: ../ref/rst/directives.html#unicode-character-codes - - - _`images.figure`: "title" and "number", to indicate a formal - figure? - - - _`parts.sectnum`: "local"?, "refnum" - - A "local" option could enable numbering for sections from a - certain point down, and sections in the rest of the document are - not numbered. For example, a reference section of a manual might - be numbered, but not the rest. OTOH, an all-or-nothing approach - would probably be enough. - - The "sectnum" directive should be usable multiple times in a - single document. For example, in a long document with "chapter" - and "appendix" sections, there could be a second "sectnum" before - the first appendix, changing the sequence used (from 1,2,3... to - A,B,C...). This is where the "local" concept comes in. This part - of the implementation can be left for later. - - A "refnum" option (better name?) would insert reference names - (targets) consisting of the reference number. Then a URL could be - of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow - internal references by number? Allow name-based *and* - number-based ids at the same time, or only one or the other (which - would the table of contents use)? Usage issue: altering the - section structure of a document could render hyperlinks invalid. - - - _`parts.contents`: Add a "suppress" or "prune" option? It would - suppress contents display for sections in a branch from that point - down. Or a new directive, like "prune-contents"? - - Add an option to include topics in the TOC? Another for sidebars? - The "topic" directive could have a "contents" option, or the - "contents" directive" could have an "include-topics" option. See - docutils-develop 2003-01-29. - - - _`parts.header` & _`parts.footer`: Support multiple, named headers - & footers? For example, separate headers & footers for odd, even, - and the first page of a document. - - This may be too specific to output formats which have a notion of - "pages". - - - _`misc.class`: - - - Add a ``:parent:`` option for setting the parent's class - (http://article.gmane.org/gmane.text.docutils.devel/3165). - - - _`misc.include`: - - - Option to select a range of lines? - - - Option to label lines? - - - How about an environment variable, say RSTINCLUDEPATH or - RSTPATH, for standard includes (as in ``.. include:: <name>``)? - This could be combined with a setting/option to allow - user-defined include directories. - - - Add support for inclusion by URL? :: - - .. include:: - :url: http://www.example.org/inclusion.txt - - - _`misc.raw`: add a "destination" option to the "raw" directive? :: - - .. raw:: html - :destination: head - - <link ...> - - It needs thought & discussion though, to come up with a consistent - set of destination labels and consistent behavior. - - And placing HTML code inside the <head> element of an HTML - document is rather the job of a templating system. - - - _`body.sidebar`: Allow internal section structure? Adornment - styles would be independent of the main document. - - That is really complicated, however, and the document model - greatly benefits from its simplicity. - -* Implement directives. Each of the list items below begins with an - identifier of the form, "module_name.directive_function_name". The - directive name itself could be the same as the - directive_function_name, or it could differ. - - - _`html.imagemap` - - It has the disadvantage that it's only easily implementable for - HTML, so it's specific to one output format. - - (For non-HTML writers, the imagemap would have to be replaced with - the image only.) - - - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_. - - - _`parts.citations`: See `Footnote & Citation Gathering`_. - - - _`misc.language`: Specify (= change) the language of a document at - parse time. - - - _`misc.settings`: Set any(?) Docutils runtime setting from within - a document? Needs much thought and discussion. - - - _`misc.gather`: Gather (move, or copy) all instances of a specific - element. A generalization of the "endnotes" & "citations" ideas. - - - Add a custom "directive" directive, equivalent to "role"? For - example:: - - .. directive:: incr - - .. class:: incremental - - .. incr:: - - "``.. incr::``" above is equivalent to "``.. class:: incremental``". - - Another example:: - - .. directive:: printed-links - - .. topic:: Links - :class: print-block - - .. target-notes:: - :class: print-inline - - This acts like macros. The directive contents will have to be - evaluated when referenced, not when defined. - - * Needs a better name? "Macro", "substitution"? - * What to do with directive arguments & options when the - macro/directive is referenced? - - - .. _conditional directives: - - Docutils already has the ability to say "use this content for - Writer X" (via the "raw" directive), but it doesn't have the - ability to say "use this content for any Writer other than X". It - wouldn't be difficult to add this ability though. - - My first idea would be to add a set of conditional directives. - Let's call them "writer-is" and "writer-is-not" for discussion - purposes (don't worry about implemention details). We might - have:: - - .. writer-is:: text-only - - :: - - +----------+ - | SNMP | - +----------+ - | UDP | - +----------+ - | IP | - +----------+ - | Ethernet | - +----------+ - - .. writer-is:: pdf - - .. figure:: protocol_stack.eps - - .. writer-is-not:: text-only pdf - - .. figure:: protocol_stack.png - - This could be an interface to the Filter transform - (docutils.transforms.components.Filter). - - The ideas in `adaptable file extensions`_ above may also be - applicable here. - - SVG's "switch" statement may provide inspiration. - - Here's an example of a directive that could produce multiple - outputs (*both* raw troff pass-through *and* a GIF, for example) - and allow the Writer to select. :: - - .. eqn:: - - .EQ - delim %% - .EN - %sum from i=o to inf c sup i~=~lim from {m -> inf} - sum from i=0 to m sup i% - .EQ - delim off - .EN - - - _`body.example`: Examples; suggested by Simon Hefti. Semantics as - per Docbook's "example"; admonition-style, numbered, reference, - with a caption/title. - - - _`body.index`: Index targets. - - See `Index Entries & Indexes - <./rst/alternatives.html#index-entries-indexes>`__. - - - _`body.literal`: Literal block, possibly "formal" (see `object - numbering and object references`_ above). Possible options: - - - "highlight" a range of lines - - - include only a specified range of lines - - - "number" or "line-numbers" - - - "styled" could indicate that the directive should check for - style comments at the end of lines to indicate styling or - markup. - - Specific derivatives (i.e., a "python-interactive" directive) - could interpret style based on cues, like the ">>> " prompt and - "input()"/"raw_input()" calls. - - See docutils-users 2003-03-03. - - - _`body.listing`: Code listing with title (to be numbered - eventually), equivalent of "figure" and "table" directives. - - - _`colorize.python`: Colorize Python code. Fine for HTML output, - but what about other formats? Revert to a literal block? Do we - need some kind of "alternate" mechanism? Perhaps use a "pending" - transform, which could switch its output based on the "format" in - use. Use a factory function "transformFF()" which returns either - "HTMLTransform()" instance or "GenericTransform" instance? - - If we take a Python-to-HTML pretty-printer and make it output a - Docutils internal doctree (as per nodes.py) instead of HTML, then - each output format's stylesheet (or equivalent) mechanism could - take care of the rest. The pretty-printer code could turn this - doctree fragment:: - - <literal_block xml:space="preserve"> - print 'This is Python code.' - for i in range(10): - print i - </literal_block> - - into something like this ("</>" is end-tag shorthand):: - - <literal_block xml:space="preserve" class="python"> - <keyword>print</> <string>'This is Python code.'</> - <keyword>for</> <identifier>i</> <keyword - >in</> <expression>range(10)</>: - <keyword>print</> <expression>i</> - </literal_block> - - But I'm leaning toward adding a single new general-purpose - element, "phrase", equivalent to HTML's <span>. Here's the - example rewritten using the generic "phrase":: - - <literal_block xml:space="preserve" class="python"> - <phrase class="keyword">print</> <phrase - class="string">'This is Python code.'</> - <phrase class="keyword">for</> <phrase - class="identifier">i</> <phrase class="keyword">in</> <phrase - class="expression">range(10)</>: - <phrase class="keyword">print</> <phrase - class="expression">i</> - </literal_block> - - It's more verbose but more easily extensible and more appropriate - for the case at hand. It allows us to edit style sheets to add - support for new formats, not the Docutils code itself. - - Perhaps a single directive with a format parameter would be - better:: - - .. colorize:: python - - print 'This is Python code.' - for i in range(10): - print i - - But directives can have synonyms for convenience. "format:: - python" was suggested, but "format" seems too generic. - - - _`pysource.usage`: Extract a usage message from the program, - either by running it at the command line with a ``--help`` option - or through an exposed API. [Suggestion for Optik.] - - -Interpreted Text ----------------- - -Interpreted text is entirely a reStructuredText markup construct, a -way to get around built-in limitations of the medium. Some roles are -intended to introduce new doctree elements, such as "title-reference". -Others are merely convenience features, like "RFC". - -All supported interpreted text roles must already be known to the -Parser when they are encountered in a document. Whether pre-defined -in core/client code, or in the document, doesn't matter; the roles -just need to have already been declared. Adding a new role may -involve adding a new element to the DTD and may require extensive -support, therefore such additions should be well thought-out. There -should be a limited number of roles. - -The only place where no limit is placed on variation is at the start, -at the Reader/Parser interface. Transforms are inserted by the Reader -into the Transformer's queue, where non-standard elements are -converted. Once past the Transformer, no variation from the standard -Docutils doctree is possible. - -An example is the Python Source Reader, which will use interpreted -text extensively. The default role will be "Python identifier", which -will be further interpreted by namespace context into <class>, -<method>, <module>, <attribute>, etc. elements (see pysource.dtd), -which will be transformed into standard hyperlink references, which -will be processed by the various Writers. No Writer will need to have -any knowledge of the Python-Reader origin of these elements. - -* Add explicit interpreted text roles for the rest of the implicit - inline markup constructs: named-reference, anonymous-reference, - footnote-reference, citation-reference, substitution-reference, - target, uri-reference (& synonyms). - -* Add directives for each role as well? This would allow indirect - nested markup:: - - This text contains |nested inline markup|. - - .. |nested inline markup| emphasis:: - - nested ``inline`` markup - -* Implement roles: - - - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text - around role contents. - - For example, the following reStructuredText source ... :: - - .. role:: red(raw-formatting) - :prefix: - :html: <font color="red"> - :latex: {\color{red} - :suffix: - :html: </font> - :latex: } - - colored :red:`text` - - ... will yield the following document fragment:: - - <paragraph> - colored - <inline classes="red"> - <raw format="html"> - <font color="red"> - <raw format="latex"> - {\color{red} - <inline classes="red"> - text - <raw format="html"> - </font> - <raw format="latex"> - } - - Possibly without the intermediate "inline" node. - - - "acronym" and "abbreviation": Associate the full text with a short - form. Jason Diamond's description: - - I want to translate ```reST`:acronym:`` into ``<acronym - title='reStructuredText'>reST</acronym>``. The value of the - title attribute has to be defined out-of-band since you can't - parameterize interpreted text. Right now I have them in a - separate file but I'm experimenting with creating a directive - that will use some form of reST syntax to let you define them. - - Should Docutils complain about undefined acronyms or - abbreviations? - - What to do if there are multiple definitions? How to - differentiate between CSS (Content Scrambling System) and CSS - (Cascading Style Sheets) in a single document? David Priest - responds, - - The short answer is: you don't. Anyone who did such a thing - would be writing very poor documentation indeed. (Though I - note that `somewhere else in the docs`__, there's mention of - allowing replacement text to be associated with the - abbreviation. That takes care of the duplicate - acronyms/abbreviations problem, though a writer would be - foolish to ever need it.) - - __ `inline parameter syntax`_ - - How to define the full text? Possibilities: - - 1. With a directive and a definition list? :: - - .. acronyms:: - - reST - reStructuredText - DPS - Docstring Processing System - - Would this list remain in the document as a glossary, or would - it simply build an internal lookup table? A "glossary" - directive could be used to make the intention clear. - Acronyms/abbreviations and glossaries could work together. - - Then again, a glossary could be formed by gathering individual - definitions from around the document. - - 2. Some kind of `inline parameter syntax`_? :: - - `reST <reStructuredText>`:acronym: is `WYSIWYG <what you - see is what you get>`:acronym: plaintext markup. - - .. _inline parameter syntax: - rst/alternatives.html#parameterized-interpreted-text - - 3. A combination of 1 & 2? - - The multiple definitions issue could be handled by establishing - rules of priority. For example, directive-based lookup tables - have highest priority, followed by the first inline definition. - Multiple definitions in directive-based lookup tables would - trigger warnings, similar to the rules of `implicit hyperlink - targets`__. - - __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets - - 4. Using substitutions? :: - - .. |reST| acronym:: reST - :text: reStructuredText - - What do we do for other formats than HTML which do not support - tool tips? Put the full text in parentheses? - - - "figure", "table", "listing", "chapter", "page", etc: See `object - numbering and object references`_ above. - - - "glossary-term": This would establish a link to a glossary. It - would require an associated "glossary-entry" directive, whose - contents could be a definition list:: - - .. glossary-entry:: - - term1 - definition1 - term2 - definition2 - - This would allow entries to be defined anywhere in the document, - and collected (via a "glossary" directive perhaps) at one point. - - -Unimplemented Transforms -======================== - -* _`Footnote & Citation Gathering` - - Collect and move footnotes & citations to the end of a document. - (Separate transforms.) - -* _`Reference Merging` - - When merging two or more subdocuments (such as docstrings), - conflicting references may need to be resolved. There may be: - - * duplicate reference and/or substitution names that need to be made - unique; and/or - * duplicate footnote numbers that need to be renumbered. - - Should this be done before or after reference-resolving transforms - are applied? What about references from within one subdocument to - inside another? - -* _`Document Splitting` - - If the processed document is written to multiple files (possibly in - a directory tree), it will need to be split up. Internal references - will have to be adjusted. - - (HTML only? Initially, yes. Eventually, anything should be - splittable.) - - Ideas: - - - Insert a "destination" attribute into the root element of each - split-out document, containing the path/filename. The Output - object or Writer will recognize this attribute and split out the - files accordingly. Must allow for common headers & footers, - prev/next, breadcrumbs, etc. - - - Transform a single-root document into a document containing - multiple subdocuments, recursively. The content model of the - "document" element would have to change to:: - - <!ELEMENT document - ( (title, subtitle?)?, - decoration?, - (docinfo, transition?)?, - %structure.model;, - document* )> - - (I.e., add the last line -- 0 or more document elements.) - - Let's look at the case of hierarchical (directories and files) - HTML output. Each document element containing further document - elements would correspond to a directory (with an index.html file - for the content preceding the subdocuments). Each document - element containing no subdocuments (i.e., structure model elements - only) corresponds to a concrete file with no directory. - - The natural transform would be to map sections to subdocuments, - but possibly only a given number of levels deep. - -* _`Navigation` - - If a document is split up, each segment will need navigation links: - parent, children (small TOC), previous (preorder), next (preorder). - Part of `Document Splitting`_? - -* _`List of System Messages` - - The ``system_message`` elements are inserted into the document tree, - adjacent to the problems themselves where possible. Some (those - generated post-parse) are kept until later, in - ``document.messages``, and added as a special final section, - "Docutils System Messages". - - Docutils could be made to generate hyperlinks to all known - system_messages and add them to the document, perhaps to the end of - the "Docutils System Messages" section. - - Fred L. Drake, Jr. wrote: - - I'd like to propose that both parse- and transformation-time - messages are included in the "Docutils System Messages" section. - If there are no objections, I can make the change. - - The advantage of the current way of doing things is that parse-time - system messages don't require a transform; they're already in the - document. This is valuable for testing (unit tests, - tools/quicktest.py). So if we do decide to make a change, I think - the insertion of parse-time system messages ought to remain as-is - and the Messages transform ought to move all parse-time system - messages (remove from their originally inserted positions, insert in - System Messages section). - -* _`Index Generation` - - -HTML Writer -=========== - -* Add support for _`multiple stylesheets`. See - <http://thread.gmane.org/gmane.text.docutils.cvs/4336>. - -* Idea for field-list rendering: hanging indent:: - - Field name (bold): First paragraph of field body begins - with the field name inline. - - If the first item of a field body is not a paragraph, - it would begin on the following line. - -* Add more support for <link> elements, especially for navigation - bars. - - The framework does not have a notion of document relationships, so - probably raw.destination_ should be used. - - We'll have framework support for document relationships when support - for `multiple output files`_ is added. The HTML writer could - automatically generate <link> elements then. - - .. _raw.destination: misc.raw_ - -* Base list compaction on the spacing of source list? Would require - parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.) - -* Add a tool tip ("title" attribute?) to footnote back-links - identifying them as such. Text in Docutils language module. - - -PEP/HTML Writer -=============== - -* Remove the generic style information (duplicated from html4css1.css) - from pep.css to avoid redundancy. - - We need support for `multiple stylesheets`_ first, though. - - -LaTeX writer -============ - -* Add an ``--embed-stylesheet`` (and ``--link-stylesheet``) option. - - -HTML SlideShow Writer -===================== - -Add a Writer for presentations, derivative of the HTML Writer. Given -an input document containing one section per slide, the output would -consist of a master document for the speaker, and a slide file (or set -of filess, one (or more) for each slide). Each slide would contain -the slide text (large, stylesheet-controlled) and images, plus "next" -and "previous" links in consistent places. The speaker's master -document would contain a small version of the slide text with -speaker's notes interspersed. The master document could use -``target="whatever"`` to direct links to a separate window on a second -monitor (e.g., a projector). - -Ideas: - -* Base the output on |S5|_. I discovered |S5| a few weeks before it - appeared on Slashdot, after writing most of this section. It turns - out that |S5| does most of what I wanted. - - Chris Liechti has `integrated S5 with the HTML writer - <http://homepage.hispeed.ch/py430/python/index.html#rst2s5>`__. - - .. |S5| replace:: S\ :sup:`5` - .. _S5: http://www.meyerweb.com/eric/tools/s5/ - -Below, "[S5]" indicates that |S5| already implements the feature or -may implement all or part of the feature. "[S5 1.1]" indicates that -|S5| version 1.1 implements the feature (a preview of the 1.1 beta is -available in the `S5 testbed`_). - -.. _S5 testbed: http://meyerweb.com/eric/tools/s5/testbed/ - -Features & issues: - -* [S5 1.1] Incremental slides, where each slide adds to the one before - (ticking off items in a list, delaying display of later items). The - speaker's master document would list each transition in the TOC and - provide links in the content. - - * Use transitions to separate stages. Problem with transitions is - that they can't be used everywhere -- not, for example, within a - list (see the example below). - - * Use a special directive to separate stages. Possible names: - pause, delay, break, cut, continue, suspend, hold, stay, stop. - Should the directive be available in all contexts (and ineffectual - in all but SlideShow context), or added at runtime by the - SlideShow Writer? Probably such a "pause" directive should only - be available for slide shows; slide shows are too much of a - special case to justify adding a directive (and node?) to the - core. - - The directive could accept text content, which would be rendered - while paused but would disappear when the slide is continued (the - text could also be a link to the next slide). In the speaker's - master document, the text "paused:" could appear, prefixed to the - directive text. - - * Use a special directive or class to declare incremental content. - This works best with the S5 ideas. For example:: - - Slide Title - =========== - - .. incremental:: - - * item one - * item two - * item three - - Add an option to make all bullet lists implicitly incremental? - -* Speaker's notes -- how to intersperse? Could use reST comments - (".."), but make them visible in the speaker's master document. If - structure is necessary, we could use a "comment" directive (to avoid - nonsensical DTD changes, the "comment" directive could produce an - untitled topic element). - - The speaker's notes could (should?) be separate from S5's handout - content. - -* The speaker's master document could use frames for easy navigation: - TOC on the left, content on the right. - - - It would be nice if clicking in the TOC frame simultaneously - linked to both the speaker's notes frame and to the slide window, - synchronizing both. Needs JavaScript? - - - TOC would have to be tightly formatted -- minimal indentation. - - - TOC auto-generated, as in the PEP Reader. (What if there already - is a "contents" directive in the document?) - - - There could be another frame on the left (top-left or bottom-left) - containing a single "Next" link, always pointing to the next slide - (synchronized, of course). Also "Previous" link? FF/Rew go to - the beginning of the next/current parent section? First/Last - also? Tape-player-style buttons like ``|<< << < > >> >>|``? - -* [S5] Need to support templating of some kind, for uniform slide - layout. S5 handles this via CSS. - - Build in support for limited features? E.g., top/bottom or - left/right banners, images on each page, background color and/or - image, etc. - -* [S5?] One layout for all slides, or allow some variation? - - While S5 seems to support only one style per HTML file, it's - pretty easy to split a presentation in different files and - insert a hyperlink to the last slide of the first part and load - the second part by a click on it. - - -- Chris Liechti - -* For nested sections, do we show the section's ancestry on each - slide? Optional? No -- leave the implementation to someone who - wants it. - -* [S5] Stylesheets for slides: - - - Tweaked for different resolutions, 1024x768 etc. - - Some layout elements have fixed positions. - - Text must be quite large. - - Allow 10 lines of text per slide? 15? - - Title styles vary by level, but not so much? - -* [not required with S5.] Need a transform to number slides for - output filenames?, and for hyperlinks? - -* Directive to begin a new, untitled (blank) slide? - -* Directive to begin a new slide, continuation, using the same title - as the previous slide? (Unnecessary?) - -* Have a timeout on incremental items, so the colour goes away after 1 - second. - -Here's an example that I was hoping to show at PyCon DC 2005:: - - ======================== - The Docutils SlideShow - ======================== - - Welcome To The Docutils SlideShow! - ================================== - - .. pause:: - - David Goodger - - goodger@python.org - - http://python.net/~goodger - - .. (introduce yourself) - - Hi, I'm David Goodger from Montreal, Canada. - - I've been working on Docutils since 2000. - Time flies! - - .. pause:: - - Docutils - - http://docutils.sourceforge.net - - .. I also volunteer as a Python Enhancement Proposal (or PEP) - editor. - - .. SlideShow is a new feature of Docutils. This presentation was - written using the Docutils SlideShow system. The slides you - are seeing are HTML, rendered by a standard Mozilla Firefox - browser. - - - The Docutils SlideShow System - ============================= - - .. The Docutils SlideShow System provides - - Easy and open presentations. - - - Features - ======== - - * reStructuredText-based input files. - - .. reStructuredText is a what-you-see-is-what-you-get - plaintext format. Easy to read & write, non-proprietary, - editable in your favourite text editor. - - .. Parsers for other markup languages can be added to Docutils. - In the future, I hope some are. - - .. pause:: ... - - * Stylesheet-driven HTML output. - - .. The format of all elements of the output slides are - controlled by CSS (cascading stylesheets). - - .. pause:: ... - - * Works with any modern browser. - - .. that supports CSS, frames, and JavaScript. - Tested with Mozilla Firefox. - - .. pause:: ... - - * Works on any OS. - - - Etc. - ==== - - That's as far as I got, but you get the idea... - - -Front-End Tools -=============== - -* What about if we don't know which Reader and/or Writer we are - going to use? If the Reader/Writer is specified on the - command-line? (Will this ever happen?) - - Perhaps have different types of front ends: - - a) _`Fully qualified`: Reader and Writer are hard-coded into the - front end (e.g. ``pep2html [options]``, ``pysource2pdf - [options]``). - - b) _`Partially qualified`: Reader is hard-coded, and the Writer is - specified a sub-command (e.g. ``pep2 html [options]``, - ``pysource2 pdf [options]``). The Writer is known before option - processing happens, allowing the OptionParser to be built - dynamically. Alternatively, the Writer could be hard-coded and - the Reader specified as a sub-command (e.g. ``htmlfrom pep - [options]``). - - c) _`Unqualified`: Reader and Writer are specified as subcommands - (e.g. ``publish pep html [options]``, ``publish pysource pdf - [options]``). A single front end would be sufficient, but - probably only useful for testing purposes. - - d) _`Dynamic`: Reader and/or Writer are specified by options, with - defaults if unspecified (e.g. ``publish --writer pdf - [options]``). Is this possible? The option parser would have - to be told about new options it needs to handle, on the fly. - Component-specific options would have to be specified *after* - the component-specifying option. - - Allow common options before subcommands, as in CVS? Or group all - options together? In the case of the `fully qualified`_ - front ends, all the options will have to be grouped together - anyway, so there's no advantage (we can't use it to avoid - conflicts) to splitting common and component-specific options - apart. - -* Parameterize help text & defaults somehow? Perhaps a callback? Or - initialize ``settings_spec`` in ``__init__`` or ``init_options``? - -* Disable common options that don't apply? - -* Add ``--section-numbering`` command line option. The "sectnum" - directive should override the ``--no-section-numbering`` command - line option then. - -* Create a single dynamic_ or unqualified_ front end that can be - installed? - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/website.txt b/docutils/docs/dev/website.txt deleted file mode 100644 index 193e9c0f2..000000000 --- a/docutils/docs/dev/website.txt +++ /dev/null @@ -1,46 +0,0 @@ -=================== - Docutils Web Site -=================== - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -The Docutils web site, <http://docutils.sourceforge.net/>, is -maintained automatically by the ``docutils-update`` script, run as an -hourly cron job on shell.berlios.de (by user "felixwiemann"). The -script will process any .txt file which is newer than the -corresponding .html file in the project's web directory on -shell.berlios.de (``/home/groups/docutils/htdocs/aux/htdocs/``) and -upload the changes to the web site at SourceForge. For a new .txt -file, just SSH to ``<username>@shell.berlios.de`` and :: - - cd /home/groups/docutils/htdocs/aux/htdocs/ - touch filename.html - chmod g+w filename.html - sleep 1 - touch filename.txt - -The script will take care of the rest within an hour. Thereafter -whenever the .txt file is modified (checked in to SVN), the .html will -be regenerated automatically. - -After adding directories to SVN, allow the script to run once to -create the directories in the filesystem before preparing for HTML -processing as described above. - -The docutils-update__ script is located at -``sandbox/infrastructure/docutils-update``. - -__ http://docutils.sf.net/sandbox/infrastructure/docutils-update - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/howto/html-stylesheets.txt b/docutils/docs/howto/html-stylesheets.txt deleted file mode 100644 index 9369f2d3c..000000000 --- a/docutils/docs/howto/html-stylesheets.txt +++ /dev/null @@ -1,76 +0,0 @@ -============================================== - Writing HTML (CSS) Stylesheets for Docutils_ -============================================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - - -The look of Docutils' HTML output is customizable via a CSS -stylesheet. The default stylesheet is called ``html4css1.css`` and -can be found in the ``writers/html4css1/`` directory of the Docutils -installation. Use the command ``rst2html.py --help`` and look at the -description of the ``--stylesheet-path`` command-line option for the -exact machine-specific location. - -To customize the stylesheet, first copy ``html4css1.css`` to the same -place as your output HTML files will go. Next, place a new file -(e.g. called ``my-docutils.css``) in the same directory and use the -following template:: - - /* - :Author: Your Name - :Contact: Your Email Address - :Copyright: This stylesheet has been placed in the public domain. - - Stylesheet for use with Docutils. [Optionally place a more - detailed description here.] - */ - - @import url(html4css1.css); - - /* Your customizations go here. For example: */ - - h1, h2, h3, h4, h5, h6, p.topic-title { - font-family: sans-serif } - -For help on the CSS syntax, please see `the WDG's guide to Cascading -Style Sheets`__ and, in particular, their `list of CSS1 properties`__. - -__ http://www.htmlhelp.com/reference/css/ -__ http://www.htmlhelp.com/reference/css/all-properties.html - -It is important that you do not edit a copy of ``html4css1.css`` -directly because ``html4css1.css`` is frequently updated with each new -release of Docutils. - -Also make sure that you import ``html4css1.css`` (using "``@import -url(html4css1.css);``") because the definitions contained in the -default stylesheet are required for correct rendering (margins, -alignment, etc.). - -If you think your stylesheet is fancy and you would like to let others -benefit from your efforts, you are encouraged to post the stylesheet -to the Docutils-users_ mailing list. We can upload it to the -`Docutils repository`__ if you would like us to do so. - -If you decide to share you stylesheet with other users of Docutils, -please keep website-specific customizations not applicable to -Docutils' HTML code in a separate stylesheet. - -.. _Docutils-users: ../user/mailing-lists.html#docutils-users -__ http://docutils.sourceforge.net/sandbox/stylesheets/ - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/howto/i18n.txt b/docutils/docs/howto/i18n.txt deleted file mode 100644 index 4a5b1de5a..000000000 --- a/docutils/docs/howto/i18n.txt +++ /dev/null @@ -1,191 +0,0 @@ -================================ - Docutils_ Internationalization -================================ - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - - -.. contents:: - - -This document describes the internationalization facilities of the -Docutils_ project. `Introduction to i18n`_ by Tomohiro KUBOTA is a -good general reference. "Internationalization" is often abbreviated -as "i18n": "i" + 18 letters + "n". - -.. Note:: - - The i18n facilities of Docutils should be considered a "first - draft". They work so far, but improvements are welcome. - Specifically, standard i18n facilities like "gettext" have yet to - be explored. - -Docutils is designed to work flexibly with text in multiple languages -(one language at a time). Language-specific features are (or should -be [#]_) fully parameterized. To enable a new language, two modules -have to be added to the project: one for Docutils itself (the -`Docutils Language Module`_) and one for the reStructuredText parser -(the `reStructuredText Language Module`_). - -.. [#] If anything in Docutils is insufficiently parameterized, it - should be considered a bug. Please report bugs to the Docutils - project bug tracker on SourceForge at - http://sourceforge.net/tracker/?group_id=38414&atid=422030. - -.. _Docutils: http://docutils.sourceforge.net/ -.. _Introduction to i18n: - http://www.debian.org/doc/manuals/intro-i18n/ - - -Language Module Names -===================== - -Language modules are named using a case-insensitive language -identifier as defined in `RFC 1766`_, converting hyphens to -underscores [#]_. A typical language identifier consists of a -2-letter language code from `ISO 639`_ (3-letter codes can be used if -no 2-letter code exists; RFC 1766 is currently being revised to allow -3-letter codes). The language identifier can have an optional subtag, -typically for variations based on country (from `ISO 3166`_ 2-letter -country codes). If no language identifier is specified, the default -is "en" for English. Examples of module names include ``en.py``, -``fr.py``, ``ja.py``, and ``pt_br.py``. - -.. [#] Subtags are separated from primary tags by underscores instead - of hyphens, to conform to Python naming rules. - -.. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html -.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html -.. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/ - 02iso-3166-code-lists/index.html - - -Python Code -=========== - -All Python code in Docutils will be ASCII-only. In language modules, -Unicode-escapes will have to be used for non-ASCII characters. -Although it may be possible for some developers to store non-ASCII -characters directly in strings, it will cause problems for other -developers whose locales are set up differently. - -`PEP 263`_ introduces source code encodings to Python modules, -implemented beginning in Python 2.3. Until PEP 263 is fully -implemented as a well-established convention, proven robust in daily -use, and the tools (editors, CVS, email, etc.) recognize this -convention, Docutils shall remain conservative. - -As mentioned in the note above, developers are invited to explore -"gettext" and other i18n technologies. - -.. _PEP 263: http://www.python.org/peps/pep-0263.html - - -Docutils Language Module -======================== - -Modules in ``docutils/languages`` contain language mappings for -markup-independent language-specific features of Docutils. To make a -new language module, just copy the ``en.py`` file, rename it with the -code for your language (see `Language Module Names`_ above), and -translate the terms as described below. - -Each Docutils language module contains three module attributes: - -``labels`` - This is a mapping of node class names to language-dependent - boilerplate label text. The label text is used by Writer - components when they encounter document tree elements whose class - names are the mapping keys. - - The entry values (*not* the keys) should be translated to the - target language. - -``bibliographic_fields`` - This is a mapping of language-dependent field names (converted to - lower case) to canonical field names (keys of - ``DocInfo.biblio_notes`` in ``docutils.transforms.frontmatter``). - It is used when transforming bibliographic fields. - - The keys should be translated to the target language. - -``author_separators`` - This is a list of strings used to parse the 'Authors' - bibliographic field. They separate individual authors' names, and - are tried in order (i.e., earlier items take priority, and the - first item that matches wins). The English-language module - defines them as ``[';', ',']``; semi-colons can be used to - separate names like "Arthur Pewtie, Esq.". - - Most languages won't have to "translate" this list. - - -reStructuredText Language Module -================================ - -Modules in ``docutils/parsers/rst/languages`` contain language -mappings for language-specific features of the reStructuredText -parser. To make a new language module, just copy the ``en.py`` file, -rename it with the code for your language (see `Language Module -Names`_ above), and translate the terms as described below. - -Each reStructuredText language module contains two module attributes: - -``directives`` - This is a mapping from language-dependent directive names to - canonical directive names. The canonical directive names are - registered in ``docutils/parsers/rst/directives/__init__.py``, in - ``_directive_registry``. - - The keys should be translated to the target language. Synonyms - (multiple keys with the same values) are allowed; this is useful - for abbreviations. - -``roles`` - This is a mapping language-dependent role names to canonical role - names for interpreted text. The canonical directive names are - registered in ``docutils/parsers/rst/states.py``, in - ``Inliner._interpreted_roles`` (this may change). - - The keys should be translated to the target language. Synonyms - (multiple keys with the same values) are allowed; this is useful - for abbreviations. - - -Testing the Language Modules -============================ - -Whenever a new language module is added or an existing one modified, -the unit tests should be run. The test modules can be found in the -docutils/test directory from CVS_ or from the `latest CVS snapshot`_. - -The ``test_language.py`` module can be run as a script. With no -arguments, it will test all language modules. With one or more -language codes, it will test just those languages. For example:: - - $ python test_language.py en - .. - ---------------------------------------- - Ran 2 tests in 0.095s - - OK - -Use the "alltests.py" script to run all test modules, exhaustively -testing the parser and other parts of the Docutils system. - -.. _CVS: http://sourceforge.net/cvs/?group_id=38414 -.. _latest CVS snapshot: http://docutils.sf.net/docutils-snapshot.tgz - - -Submitting the Language Modules -=============================== - -If you do not have CVS write access and want to contribute your -language modules, feel free to submit them at the `SourceForge patch -tracker`__. - -__ http://sourceforge.net/tracker/?group_id=38414&atid=422032 diff --git a/docutils/docs/howto/rst-directives.txt b/docutils/docs/howto/rst-directives.txt deleted file mode 100644 index 6210940c8..000000000 --- a/docutils/docs/howto/rst-directives.txt +++ /dev/null @@ -1,399 +0,0 @@ -====================================== - Creating reStructuredText Directives -====================================== - -:Authors: Dethe Elza, David Goodger -:Contact: delza@enfoldingsystems.com -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -Directives are the primary extension mechanism of reStructuredText. -This document aims to make the creation of new directives as easy and -understandable as possible. There are only a couple of -reStructuredText-specific features the developer needs to know to -create a basic directive. - -The syntax of directives is detailed in the `reStructuredText Markup -Specification`_, and standard directives are described in -`reStructuredText Directives`_. - -Directives are a reStructuredText markup/parser concept. There is no -"directive" element, no single element that corresponds exactly to the -concept of directives. Instead, choose the most appropriate elements -from the existing Docutils elements. Directives build structures -using the existing building blocks. See `The Docutils Document Tree`_ -and the ``docutils.nodes`` module for more about the building blocks -of Docutils documents. - -.. _reStructuredText Markup Specification: - ../ref/rst/restructuredtext.html#directives -.. _reStructuredText Directives: ../ref/rst/directives.html -.. _The Docutils Document Tree: ../ref/doctree.html - - -.. contents:: Table of Contents - - -Define the Directive Function -============================= - -The directive function does any processing that the directive -requires. This may require the use of other parts of the -reStructuredText parser. This is where the directive actually *does* -something. - -The directive implementation itself is a callback function whose -signature is as follows:: - - def directive_fn(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - code... - - # Set function attributes: - directive_fn.arguments = ... - directive_fn.options = ... - direcitve_fn.content = ... - -Function attributes are described below (see `Specify Directive -Arguments, Options, and Content`_). The directive function parameters -are as follows: - -- ``name`` is the directive type or name. - -- ``arguments`` is a list of positional arguments, as specified in the - ``arguments`` function attribute. - -- ``options`` is a dictionary mapping option names to values. The - options handled by a directive function are specified in the - ``options`` function attribute. - -- ``content`` is a list of strings, the directive content. Use the - ``content`` function attribute to allow directive content. - -- ``lineno`` is the line number of the first line of the directive. - -- ``content_offset`` is the line offset of the first line of the - content from the beginning of the current input. Used when - initiating a nested parse. - -- ``block_text`` is a string containing the entire directive. Include - it as the content of a literal block in a system message if there is - a problem. - -- ``state`` is the state which called the directive function. - -- ``state_machine`` is the state machine which controls the state - which called the directive function. - -Directive functions return a list of nodes which will be inserted into -the document tree at the point where the directive was encountered. -This can be an empty list if there is nothing to insert. For ordinary -directives, the list must contain body elements or structural -elements. Some directives are intended specifically for substitution -definitions, and must return a list of ``Text`` nodes and/or inline -elements (suitable for inline insertion, in place of the substitution -reference). Such directives must verify substitution definition -context, typically using code like this:: - - if not isinstance(state, states.SubstitutionDef): - error = state_machine.reporter.error( - 'Invalid context: the "%s" directive can only be used ' - 'within a substitution definition.' % (name), - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - - -Specify Directive Arguments, Options, and Content -================================================= - -Function attributes are interpreted by the directive parser (from the -``docutils.parsers.rst.states.Body.run_directive()`` method). If -unspecified, directive function attributes are assumed to have the -value ``None``. Three directive function attributes are recognized: - -- ``arguments``: A 3-tuple specifying the expected positional - arguments, or ``None`` if the directive has no arguments. The 3 - items in the tuple are: - - 1. The number of required arguments. - 2. The number of optional arguments. - 3. A boolean, indicating if the final argument may contain whitespace. - - Arguments are normally single whitespace-separated words. The final - argument may contain whitespace when indicated by the value 1 (True) - for the third item in the argument spec tuple. In this case, the - final argument in the ``arguments`` parameter to the directive - function will contain spaces and/or newlines, preserved from the - input text. - - If the form of the arguments is more complex, specify only one - argument (either required or optional) and indicate that final - whitespace is OK (1/True); the client code must do any - context-sensitive parsing. - -- ``options``: The option specification. ``None`` or an empty dict - implies no options to parse. - - An option specification must be defined detailing the options - available to the directive. An option spec is a mapping of option - name to conversion function; conversion functions are applied to - each option value to check validity and convert them to the expected - type. Python's built-in conversion functions are often usable for - this, such as ``int``, ``float``, and ``bool`` (included in Python - from version 2.2.1). Other useful conversion functions are included - in the ``docutils.parsers.rst.directives`` package (in the - ``__init__.py`` module): - - - ``flag``: For options with no option arguments. Checks for an - argument (raises ``ValueError`` if found), returns ``None`` for - valid flag options. - - - ``unchanged_required``: Returns the text argument, unchanged. - Raises ``ValueError`` if no argument is found. - - - ``unchanged``: Returns the text argument, unchanged. Returns an - empty string ("") if no argument is found. - - - ``path``: Returns the path argument unwrapped (with newlines - removed). Raises ``ValueError`` if no argument is found. - - - ``uri``: Returns the URI argument with whitespace removed. Raises - ``ValueError`` if no argument is found. - - - ``nonnegative_int``: Checks for a nonnegative integer argument, - and raises ``ValueError`` if not. - - - ``class_option``: Converts the argument into an ID-compatible - string and returns it. Raises ``ValueError`` if no argument is - found. - - - ``unicode_code``: Convert a Unicode character code to a Unicode - character. - - - ``single_char_or_unicode``: A single character is returned as-is. - Unicode characters codes are converted as in ``unicode_code``. - - - ``single_char_or_whitespace_or_unicode``: As with - ``single_char_or_unicode``, but "tab" and "space" are also - supported. - - - ``positive_int``: Converts the argument into an integer. Raises - ValueError for negative, zero, or non-integer values. - - - ``positive_int_list``: Converts a space- or comma-separated list - of integers into a Python list of integers. Raises ValueError for - non-positive-integer values. - - - ``encoding``: Verfies the encoding argument by lookup. Raises - ValueError for unknown encodings. - - A further utility function, ``choice``, is supplied to enable - options whose argument must be a member of a finite set of possible - values. A custom conversion function must be written to use it. - For example:: - - from docutils.parsers.rst import directives - - def yesno(argument): - return directives.choice(argument, ('yes', 'no')) - - For example, here is an option spec for a directive which allows two - options, "name" and "value", each with an option argument:: - - directive_fn.options = {'name': unchanged, 'value': int} - -- ``content``: A boolean; true if content is allowed. Directive - functions must handle the case where content is required but not - present in the input text (an empty content list will be supplied). - -The final step of the ``run_directive()`` method is to call the -directive function itself. - - -Register the Directive -====================== - -If the directive is a general-use addition to the Docutils core, it -must be registered with the parser and language mappings added: - -1. Register the new directive using its canonical name in - ``docutils/parsers/rst/directives/__init__.py``, in the - ``_directive_registry`` dictionary. This allows the - reStructuredText parser to find and use the directive. - -2. Add an entry to the ``directives`` dictionary in - ``docutils/parsers/rst/languages/en.py`` for the directive, mapping - the English name to the canonical name (both lowercase). Usually - the English name and the canonical name are the same. - -3. Update all the other language modules as well. For languages in - which you are proficient, please add translations. For other - languages, add the English directive name plus "(translation - required)". - -If the directive is application-specific, use the -``register_directive`` function:: - - from docutils.parsers.rst import directives - directives.register_directive(directive_name, directive_function) - - -Examples -======== - -For the most direct and accurate information, "Use the Source, Luke!". -All standard directives are documented in `reStructuredText -Directives`_, and the source code implementing them is located in the -``docutils/parsers/rst/directives`` package. The ``__init__.py`` -module contains a mapping of directive name to module & function name. -Several representative directives are described below. - - -Admonitions ------------ - -Admonition directives, such as "note" and "caution", are quite simple. -They have no directive arguments or options. Admonition directive -content is interpreted as ordinary reStructuredText. The directive -function simply hands off control to a generic directive function:: - - def note(*args): - return admonition(nodes.note, *args) - - attention.content = 1 - -Note that the only thing distinguishing the various admonition -directives is the element (node class) generated. In the code above, -the node class is passed as the first argument to the generic -directive function (early version), where the actual processing takes -place:: - - def admonition(node_class, name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - text = '\n'.join(content) - admonition_node = node_class(text) - if text: - state.nested_parse(content, content_offset, admonition_node) - return [admonition_node] - else: - warning = state_machine.reporter.warning( - 'The "%s" admonition is empty; content required.' - % (name), '', - nodes.literal_block(block_text, block_text), line=lineno) - return [warning] - -Three things are noteworthy in the function above: - -1. The ``admonition_node = node_class(text)`` line creates the wrapper - element, using the class passed in from the initial (stub) - directive function. - -2. The call to ``state.nested_parse()`` is what does the actual - processing. It parses the directive content and adds any generated - elements as child elements of ``admonition_node``. - -3. If there was no directive content, a warning is generated and - returned. The call to ``state_machine.reporter.warning()`` - includes a literal block containing the entire directive text - (``block_text``) and the line (``lineno``) of the top of the - directive. - - -"image" -------- - -The "image" directive is used to insert a picture into a document. -This directive has one argument, the path to the image file, and -supports several options. There is no directive content. Here's an -early version of the image directive function:: - - def image(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - reference = directives.uri(arguments[0]) - options['uri'] = reference - image_node = nodes.image(block_text, **options) - return [image_node] - - image.arguments = (1, 0, 1) - image.options = {'alt': directives.unchanged, - 'height': directives.nonnegative_int, - 'width': directives.nonnegative_int, - 'scale': directives.nonnegative_int, - 'align': align} - -Several things are noteworthy in the code above: - -1. The "image" directive requires a single argument, which is allowed - to contain whitespace (see the argument spec above, - ``image.arguments = (1, 0, 1)``). This is to allow for long URLs - which may span multiple lines. The first line of the ``image`` - function joins the URL, discarding any embedded whitespace. - -2. The reference is added to the ``options`` dictionary under the - "uri" key; this becomes an attribute of the ``nodes.image`` element - object. Any other attributes have already been set explicitly in - the source text. - -3. The "align" option depends on the following definitions (which - actually occur earlier in the source code):: - - align_values = ('top', 'middle', 'bottom', 'left', 'center', - 'right') - - def align(argument): - return directives.choice(argument, align_values) - - -"contents" ----------- - -The "contents" directive is used to insert an auto-generated table of -contents (TOC) into a document. It takes one optional argument, a -title for the TOC. If no title is specified, a default title is used -instead. The directive also handles several options. Here's an early -version of the code:: - - def contents(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Table of contents.""" - if arguments: - title_text = arguments[0] - text_nodes, messages = state.inline_text(title_text, lineno) - title = nodes.title(title_text, '', *text_nodes) - else: - messages = [] - title = None - pending = nodes.pending(parts.Contents, {'title': title}, - block_text) - pending.details.update(options) - state_machine.document.note_pending(pending) - return [pending] + messages - - contents.arguments = (0, 1, 1) - contents.options = {'depth': directives.nonnegative_int, - 'local': directives.flag, - 'backlinks': backlinks} - -Aspects of note include: - -1. The ``contents.arguments = (0, 1, 1)`` function attribute specifies - a single, *optional* argument. If no argument is present, the - ``arguments`` parameter to the directive function will be an empty - list. - -2. If an argument *is* present, its text is passed to - ``state.inline_text()`` for parsing. Titles may contain inline - markup, such as emphasis or inline literals. - -3. The table of contents is not generated right away. Typically, a - TOC is placed near the beginning of a document, and is a summary or - outline of the section structure of the document. The entire - document must already be processed before a summary can be made. - This directive leaves a ``nodes.pending`` placeholder element in - the document tree, marking the position of the TOC and including a - ``details`` internal attribute containing all the directive - options, effectively communicating the options forward. The actual - table of contents processing is performed by a transform, - ``docutils.transforms.parts.Contents``, after the rest of the - document has been parsed. diff --git a/docutils/docs/howto/rst-roles.txt b/docutils/docs/howto/rst-roles.txt deleted file mode 100644 index f8ce08bca..000000000 --- a/docutils/docs/howto/rst-roles.txt +++ /dev/null @@ -1,228 +0,0 @@ -================================================== - Creating reStructuredText Interpreted Text Roles -================================================== - -:Authors: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -Interpreted text roles are an extension mechanism for inline markup in -reStructuredText. This document aims to make the creation of new -roles as easy and understandable as possible. - -Standard roles are described in `reStructuredText Interpreted Text -Roles`_. See the `Interpreted Text`_ section in the `reStructuredText -Markup Specification`_ for syntax details. - -.. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html -.. _Interpreted Text: - ../ref/rst/restructuredtext.html#interpreted-text -.. _reStructuredText Markup Specification: - ../ref/rst/restructuredtext.html - - -.. contents:: - - -Define the Role Function -======================== - -The role function creates and returns inline elements (nodes) and does -any additional processing required. Its signature is as follows:: - - def role_fn(name, rawtext, text, lineno, inliner, - options={}, content=[]): - code... - - # Set function attributes for customization: - role_fn.options = ... - role_fn.content = ... - -Function attributes are described below (see `Specify Role Function -Options and Content`_). The role function parameters are as follows: - -* ``name``: The local name of the interpreted role, the role name - actually used in the document. - -* ``rawtext``: A string containing the enitre interpreted text input, - including the role and markup. Return it as a ``problematic`` node - linked to a system message if a problem is encountered. - -* ``text``: The interpreted text content. - -* ``lineno``: The line number where the interpreted text begins. - -* ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that - called role_fn. It contains the several attributes useful for error - reporting and document tree access. - -* ``options``: A dictionary of directive options for customization - (from the `"role" directive`_), to be interpreted by the role - function. Used for additional attributes for the generated elements - and other functionality. - -* ``content``: A list of strings, the directive content for - customization (from the `"role" directive`_). To be interpreted by - the role function. - -Role functions return a tuple of two values: - -* A list of nodes which will be inserted into the document tree at the - point where the interpreted role was encountered (can be an empty - list). - -* A list of system messages, which will be inserted into the document tree - immediately after the end of the current block (can also be empty). - - -Specify Role Function Options and Content -========================================= - -Function attributes are for customization, and are interpreted by the -`"role" directive`_. If unspecified, role function attributes are -assumed to have the value ``None``. Two function attributes are -recognized: - -- ``options``: The option specification. All role functions - implicitly support the "class" option, unless disabled with an - explicit ``{'class': None}``. - - An option specification must be defined detailing the options - available to the "role" directive. An option spec is a mapping of - option name to conversion function; conversion functions are applied - to each option value to check validity and convert them to the - expected type. Python's built-in conversion functions are often - usable for this, such as ``int``, ``float``, and ``bool`` (included - in Python from version 2.2.1). Other useful conversion functions - are included in the ``docutils.parsers.rst.directives`` package. - For further details, see `Creating reStructuredText Directives`_. - -- ``content``: A boolean; true if "role" directive content is allowed. - Role functions must handle the case where content is required but - not supplied (an empty content list will be supplied). - - As of this writing, no roles accept directive content. - -Note that unlike directives, the "arguments" function attribute is not -supported for role customization. Directive arguments are handled by -the "role" directive itself. - -.. _"role" directive: ../ref/rst/directives.html#role -.. _Creating reStructuredText Directives: - rst-directives.html#specify-directive-arguments-options-and-content - - -Register the Role -================= - -If the role is a general-use addition to the Docutils core, it must be -registered with the parser and language mappings added: - -1. Register the new role using the canonical name:: - - from docutils.parsers.rst import roles - roles.register_canonical_role(name, role_function) - - This code is normally placed immediately after the definition of - the role funtion. - -2. Add an entry to the ``roles`` dictionary in - ``docutils/parsers/rst/languages/en.py`` for the role, mapping the - English name to the canonical name (both lowercase). Usually the - English name and the canonical name are the same. Abbreviations - and other aliases may also be added here. - -3. Update all the other language modules as well. For languages in - which you are proficient, please add translations. For other - languages, add the English role name plus "(translation required)". - -If the role is application-specific, use the ``register_local_role`` -function:: - - from docutils.parsers.rst import roles - roles.register_local_role(name, role_function) - - -Examples -======== - -For the most direct and accurate information, "Use the Source, Luke!". -All standard roles are documented in `reStructuredText Interpreted -Text Roles`_, and the source code implementing them is located in the -``docutils/parsers/rst/roles.py`` module. Several representative -roles are described below. - - -Generic Roles -------------- - -Many roles simply wrap a given element around the text. There's a -special helper function, ``register_generic_role``, which generates a -role function from the canonical role name and node class:: - - register_generic_role('emphasis', nodes.emphasis) - -For the implementation of ``register_generic_role``, see the -``docutils.parsers.rst.roles`` module. - - -RFC Reference Role ------------------- - -This role allows easy references to RFCs_ (Request For Comments -documents) by automatically providing the base URL, -http://www.faqs.org/rfcs/, and appending the RFC document itself -(rfcXXXX.html, where XXXX is the RFC number). For example:: - - See :RFC:`2822` for information about email headers. - -This is equivalent to:: - - See `RFC 2822`__ for information about email headers. - - __ http://www.faqs.org/rfcs/rfc2822.html - -Here is the implementation of the role:: - - def rfc_reference_role(role, rawtext, text, lineno, inliner, - options={}, content=[]): - try: - rfcnum = int(text) - if rfcnum <= 0: - raise ValueError - except ValueError: - msg = inliner.reporter.error( - 'RFC number must be a number greater than or equal to 1; ' - '"%s" is invalid.' % text, line=lineno) - prb = inliner.problematic(rawtext, rawtext, msg) - return [prb], [msg] - # Base URL mainly used by inliner.rfc_reference, so this is correct: - ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum - set_classes(options) - node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref, - **options) - return [node], [] - - register_canonical_role('rfc-reference', rfc_reference_role) - -Noteworthy in the code above are: - -1. The interpreted text itself should contain the RFC number. The - ``try`` clause verifies by converting it to an integer. If the - conversion fails, the ``except`` clause is executed: a system - message is generated, the entire interpreted text construct (in - ``rawtext``) is wrapped in a ``problematic`` node (linked to the - system message), and the two are returned. - -2. The RFC reference itself is constructed from a stock URI, set as - the "refuri" attribute of a "reference" element. - -3. The ``options`` function parameter, a dictionary, may contain a - "class" customization attribute; it is interpreted and replaced - with a "classes" attribute by the ``set_classes()`` function. The - resulting "classes" attribute is passed through to the "reference" - element node constructor. - -.. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search diff --git a/docutils/docs/index.txt b/docutils/docs/index.txt deleted file mode 100644 index 18761f312..000000000 --- a/docutils/docs/index.txt +++ /dev/null @@ -1,236 +0,0 @@ -========================================== - Docutils_ Project Documentation Overview -========================================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -The latest working documents may be accessed individually below, or -from the ``docs`` directory of the `Docutils distribution`_. - -.. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils distribution: http://docutils.sourceforge.net/#download - -.. contents:: - - -Docutils Stakeholders -===================== - -Docutils stakeholders can be categorized in several groups: - -1. End-users: users of reStructuredText and the Docutils tools. - Although some are developers (e.g. Python developers utilizing - reStructuredText for docstrings in their source), many are not. - -2. Client-developers: developers using Docutils as a library, - programmers developing *with* Docutils. - -3. Component-developers: those who implement application-specific - components, directives, and/or roles, separately from Docutils. - -4. Core-developers: developers of the Docutils codebase and - participants in the Docutils project community. - -5. Re-implementers: developers of alternate implementations of - Docutils. - -There's a lot of overlap between these groups. Most (perhaps all) -core-developers, component-developers, client-developers, and -re-implementers are also end-users. Core-developers are also -client-developers, and may also be component-developers in other -projects. Component-developers are also client-developers. - - -Project Fundamentals -==================== - -These files are for all Docutils stakeholders. They are kept at the -top level of the Docutils project directory. - -:README.txt_: Project overview: quick-start, requirements, - installation, and usage. -:COPYING.txt_: Conditions for Docutils redistribution, with links to - licenses. -:FAQ.txt_: Docutils Frequently Asked Questions. If you have a - question or issue, there's a good chance it's already - answered here. -:BUGS.txt_: A list of known bugs, and how to report a bug. -:RELEASE-NOTES.txt_: Summary of the major changes in recent releases. -:HISTORY.txt_: Detailed change history log. -:THANKS.txt_: Acknowledgements. - -.. _README.txt: ../README.html -.. _BUGS.txt: ../BUGS.html -.. _COPYING.txt: ../COPYING.html -.. _Docutils FAQ: -.. _FAQ.txt: ../FAQ.html -.. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html -.. _HISTORY.txt: ../HISTORY.html -.. _THANKS.txt: ../THANKS.html - - -.. _user: - -``user/``: Introductory & Tutorial Material for End-Users -========================================================= - -Docutils-general: - -* `Docutils Front-End Tools <user/tools.html>`__ -* `Docutils Configuration Files <user/config.html>`__ -* `Docutils Mailing Lists <user/mailing-lists.html>`__ -* `Docutils Link List <user/links.html>`__ - -Writer-specific: - -* `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__ -* `Docutils LaTeX Writer <user/latex.html>`__ - -`reStructuredText <http://docutils.sourceforge.net/rst.html>`_: - -* `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or - `text source <user/rst/quickstart.txt>`__) -* `Quick reStructuredText <user/rst/quickref.html>`__ (user reference) -* `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text - only; 1 page for syntax, 1 page directive & role reference) -* `reStructuredText Demonstration <user/rst/demo.html>`_ (a - demonstration of most reStructuredText features; you can also have a - look at the `text source <user/rst/demo.txt>`__) - -Editor support: - -* `Emacs support for reStructuredText <user/emacs.html>`_ - - -.. _ref: - -``ref/``: Reference Material for All Groups -=========================================== - -Many of these files began as developer specifications, but now that -they're mature and used by end-users and client-developers, they have -become reference material. Successful specs evolve into refs. - -Docutils-general: - -* `The Docutils Document Tree <ref/doctree.html>`__ (incomplete) -* `Docutils Transforms <ref/transforms.html>`__ -* `Docutils Generic DTD <ref/docutils.dtd>`__ -* `OASIS XML Exchange Table Model Declaration Module - <ref/soextblx.dtd>`__ (CALS tables DTD module) - -Although not in the "ref" directory, `PEP 258`_ is a must-read -reference for any Docutils developer. - -reStructuredText_: - -* `An Introduction to reStructuredText <ref/rst/introduction.html>`__ - (includes the `Goals <ref/rst/introduction.html#goals>`__ and - `History <ref/rst/introduction.html#history>`__ of reStructuredText) -* `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__ -* `reStructuredText Directives <ref/rst/directives.html>`__ -* `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__ -* `reStructuredText Standard Definition Files - <ref/rst/definitions.html>`_ - -Prehistoric: - -* `Setext Documents Mirror - <http://docutils.sourceforge.net/mirror/setext.html>`__ - - -.. _peps: - -``peps/``: Python Enhancement Proposals -======================================= - -* `PEP 256: Docstring Processing System Framework`__ is a high-level - generic proposal. [`PEP 256`__ in the `master repository`_] -* `PEP 257: Docstring Conventions`__ addresses docstring style and - touches on content. [`PEP 257`__ in the `master repository`_] -* `PEP 258: Docutils Design Specification`__ is an overview of the - architecture of Docutils. It documents design issues and - implementation details. [`PEP 258`__ in the `master repository`_] -* `PEP 287: reStructuredText Docstring Format`__ proposes a standard - markup syntax. [`PEP 287`__ in the `master repository`_] - -Please note that PEPs in the `master repository`_ may not be current, -whereas the local versions are. - -__ peps/pep-0256.html -__ http://www.python.org/peps/pep-0256.html -__ peps/pep-0257.html -__ http://www.python.org/peps/pep-0257.html -.. _PEP 258: -__ peps/pep-0258.html -__ http://www.python.org/peps/pep-0258.html -__ peps/pep-0287.html -__ http://www.python.org/peps/pep-0287.html -.. _master repository: http://www.python.org/peps/ - - -.. _api: - -``api/``: API Reference Material for Client-Developers -====================================================== - -* `The Docutils Publisher <api/publisher.html>`__ -* `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__ -* `Docutils Runtime Settings <api/runtime-settings.html>`__ -* (`Docutils Transforms <ref/transforms.html>`__ should be moved here) - -`PEP 258`_ is an overview of the architecture of Docutils. - - -.. _howto: - -``howto/``: Instructions for Developers -======================================= - -* `Writing HTML (CSS) Stylesheets for Docutils - <howto/html-stylesheets.html>`__ -* `Docutils Internationalization <howto/i18n.html>`__ -* `Creating reStructuredText Directives <howto/rst-directives.html>`__ -* `Creating reStructuredText Interpreted Text Roles - <howto/rst-roles.html>`__ - - -.. _dev: - -``dev/``: Development Notes and Plans for Core-Developers -========================================================= - -Docutils-general: - -* `Docutils Hacker's Guide <dev/hacking.html>`__ -* `Docutils Distributor's Guide <dev/distributing.html>`__ -* `Docutils To Do List <dev/todo.html>`__ -* `Docutils Project Policies <dev/policies.html>`__ -* `Docutils Web Site <dev/website.html>`__ -* `Docutils Release Procedure <dev/release.html>`__ -* `The Docutils Subversion Repository <dev/repository.html>`__ -* `Docutils Testing <dev/testing.html>`__ -* `Docstring Semantics <dev/semantics.html>`__ (incomplete) -* `Python Source Reader <dev/pysource.html>`_ (incomplete) -* `Docutils Python DTD <dev/pysource.dtd>`_ (experimental) -* `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_ -* `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_ - -reStructuredText_: - -* `A Record of reStructuredText Syntax Alternatives - <dev/rst/alternatives.html>`__ -* `Problems With StructuredText <dev/rst/problems.html>`__ - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/peps/pep-0256.txt b/docutils/docs/peps/pep-0256.txt deleted file mode 100644 index 1e5e87e35..000000000 --- a/docutils/docs/peps/pep-0256.txt +++ /dev/null @@ -1,297 +0,0 @@ -PEP: 256 -Title: Docstring Processing System Framework -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net> -Discussions-To: <doc-sig@python.org> -Status: Draft -Type: Standards Track -Content-Type: text/x-rst -Created: 01-Jun-2001 -Post-History: 13-Jun-2001 - - -Abstract -======== - -Python lends itself to inline documentation. With its built-in -docstring syntax, a limited form of `Literate Programming`_ is easy to -do in Python. However, there are no satisfactory standard tools for -extracting and processing Python docstrings. The lack of a standard -toolset is a significant gap in Python's infrastructure; this PEP aims -to fill the gap. - -The issues surrounding docstring processing have been contentious and -difficult to resolve. This PEP proposes a generic Docstring -Processing System (DPS) framework, which separates out the components -(program and conceptual), enabling the resolution of individual issues -either through consensus (one solution) or through divergence (many). -It promotes standard interfaces which will allow a variety of plug-in -components (input context readers, markup parsers, and output format -writers) to be used. - -The concepts of a DPS framework are presented independently of -implementation details. - - -Road Map to the Docstring PEPs -============================== - -There are many aspects to docstring processing. The "Docstring PEPs" -have broken up the issues in order to deal with each of them in -isolation, or as close as possible. The individual aspects and -associated PEPs are as follows: - -* Docstring syntax. PEP 287, "reStructuredText Docstring Format" - [#PEP-287]_, proposes a syntax for Python docstrings, PEPs, and - other uses. - -* Docstring semantics consist of at least two aspects: - - - Conventions: the high-level structure of docstrings. Dealt with - in PEP 257, "Docstring Conventions" [#PEP-257]_. - - - Methodology: rules for the informational content of docstrings. - Not addressed. - -* Processing mechanisms. This PEP (PEP 256) outlines the high-level - issues and specification of an abstract docstring processing system - (DPS). PEP 258, "Docutils Design Specification" [#PEP-258]_, is an - overview of the design and implementation of one DPS under - development. - -* Output styles: developers want the documentation generated from - their source code to look good, and there are many different ideas - about what that means. PEP 258 touches on "Stylist Transforms". - This aspect of docstring processing has yet to be fully explored. - -By separating out the issues, we can form consensus more easily -(smaller fights ;-), and accept divergence more readily. - - -Rationale -========= - -There are standard inline documentation systems for some other -languages. For example, Perl has POD_ ("Plain Old Documentation") and -Java has Javadoc_, but neither of these mesh with the Pythonic way. -POD syntax is very explicit, but takes after Perl in terms of -readability. Javadoc is HTML-centric; except for "``@field``" tags, -raw HTML is used for markup. There are also general tools such as -Autoduck_ and Web_ (Tangle & Weave), useful for multiple languages. - -There have been many attempts to write auto-documentation systems -for Python (not an exhaustive list): - -- Marc-Andre Lemburg's doc.py_ - -- Daniel Larsson's pythondoc_ & gendoc_ - -- Doug Hellmann's HappyDoc_ - -- Laurence Tratt's Crystal (no longer available on the web) - -- Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard - library; see below) - -- Tony Ibbs' docutils_ (Tony has donated this name to the `Docutils - project`_) - -- Edward Loper's STminus_ formalization and related efforts - -These systems, each with different goals, have had varying degrees of -success. A problem with many of the above systems was over-ambition -combined with inflexibility. They provided a self-contained set of -components: a docstring extraction system, a markup parser, an -internal processing system and one or more output format writers with -a fixed style. Inevitably, one or more aspects of each system had -serious shortcomings, and they were not easily extended or modified, -preventing them from being adopted as standard tools. - -It has become clear (to this author, at least) that the "all or -nothing" approach cannot succeed, since no monolithic self-contained -system could possibly be agreed upon by all interested parties. A -modular component approach designed for extension, where components -may be multiply implemented, may be the only chance for success. -Standard inter-component APIs will make the DPS components -comprehensible without requiring detailed knowledge of the whole, -lowering the barrier for contributions, and ultimately resulting in a -rich and varied system. - -Each of the components of a docstring processing system should be -developed independently. A "best of breed" system should be chosen, -either merged from existing systems, and/or developed anew. This -system should be included in Python's standard library. - - -PyDoc & Other Existing Systems ------------------------------- - -PyDoc became part of the Python standard library as of release 2.1. -It extracts and displays docstrings from within the Python interactive -interpreter, from the shell command line, and from a GUI window into a -web browser (HTML). Although a very useful tool, PyDoc has several -deficiencies, including: - -- In the case of the GUI/HTML, except for some heuristic hyperlinking - of identifier names, no formatting of the docstrings is done. They - are presented within ``<p><small><tt>`` tags to avoid unwanted line - wrapping. Unfortunately, the result is not attractive. - -- PyDoc extracts docstrings and structural information (class - identifiers, method signatures, etc.) from imported module objects. - There are security issues involved with importing untrusted code. - Also, information from the source is lost when importing, such as - comments, "additional docstrings" (string literals in non-docstring - contexts; see PEP 258 [#PEP-258]_), and the order of definitions. - -The functionality proposed in this PEP could be added to or used by -PyDoc when serving HTML pages. The proposed docstring processing -system's functionality is much more than PyDoc needs in its current -form. Either an independent tool will be developed (which PyDoc may -or may not use), or PyDoc could be expanded to encompass this -functionality and *become* the docstring processing system (or one -such system). That decision is beyond the scope of this PEP. - -Similarly for other existing docstring processing systems, their -authors may or may not choose compatibility with this framework. -However, if this framework is accepted and adopted as the Python -standard, compatibility will become an important consideration in -these systems' future. - - -Specification -============= - -The docstring processing system framework is broken up as follows: - -1. Docstring conventions. Documents issues such as: - - - What should be documented where. - - - First line is a one-line synopsis. - - PEP 257 [#PEP-257]_ documents some of these issues. - -2. Docstring processing system design specification. Documents - issues such as: - - - High-level spec: what a DPS does. - - - Command-line interface for executable script. - - - System Python API. - - - Docstring extraction rules. - - - Readers, which encapsulate the input context. - - - Parsers. - - - Document tree: the intermediate internal data structure. The - output of the Parser and Reader, and the input to the Writer all - share the same data structure. - - - Transforms, which modify the document tree. - - - Writers for output formats. - - - Distributors, which handle output management (one file, many - files, or objects in memory). - - These issues are applicable to any docstring processing system - implementation. PEP 258 [#PEP-258]_ documents these issues. - -3. Docstring processing system implementation. - -4. Input markup specifications: docstring syntax. PEP 287 [#PEP-287]_ - proposes a standard syntax. - -5. Input parser implementations. - -6. Input context readers ("modes": Python source code, PEP, standalone - text file, email, etc.) and implementations. - -7. Stylists: certain input context readers may have associated - stylists which allow for a variety of output document styles. - -8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer - implementations. - -Components 1, 2/3/5, and 4 are the subject of individual companion -PEPs. If there is another implementation of the framework or -syntax/parser, additional PEPs may be required. Multiple -implementations of each of components 6 and 7 will be required; the -PEP mechanism may be overkill for these components. - - -Project Web Site -================ - -A SourceForge project has been set up for this work at -http://docutils.sourceforge.net/. - - -References and Footnotes -======================== - -.. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger - (http://www.python.org/peps/pep-0287.html) - -.. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum - (http://www.python.org/peps/pep-0257.html) - -.. [#PEP-258] PEP 258, Docutils Design Specification, Goodger - (http://www.python.org/peps/pep-0258.html) - -.. _Literate Programming: http://www.literateprogramming.com/ - -.. _POD: http://perldoc.perl.org/perlpod.html - -.. _Javadoc: http://java.sun.com/j2se/javadoc/ - -.. _Autoduck: - http://www.helpmaster.com/hlp-developmentaids-autoduck.htm - -.. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html - -.. _doc.py: - http://www.egenix.com/files/python/SoftwareDescriptions.html#doc.py - -.. _pythondoc: -.. _gendoc: http://starship.python.net/crew/danilo/pythondoc/ - -.. _HappyDoc: http://happydoc.sourceforge.net/ - -.. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html - -.. _docutils: http://www.tibsnjoan.co.uk/docutils.html - -.. _Docutils project: http://docutils.sourceforge.net/ - -.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/ - -.. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/ - - -Copyright -========= - -This document has been placed in the public domain. - - -Acknowledgements -================ - -This document borrows ideas from the archives of the `Python -Doc-SIG`_. Thanks to all members past & present. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/peps/pep-0257.txt b/docutils/docs/peps/pep-0257.txt deleted file mode 100644 index 23094c56a..000000000 --- a/docutils/docs/peps/pep-0257.txt +++ /dev/null @@ -1,328 +0,0 @@ -PEP: 257 -Title: Docstring Conventions -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net>, - Guido van Rossum <guido@python.org> -Discussions-To: doc-sig@python.org -Status: Active -Type: Informational -Content-Type: text/x-rst -Created: 29-May-2001 -Post-History: 13-Jun-2001 - - -Abstract -======== - -This PEP documents the semantics and conventions associated with -Python docstrings. - - -Rationale -========= - -The aim of this PEP is to standardize the high-level structure of -docstrings: what they should contain, and how to say it (without -touching on any markup syntax within docstrings). The PEP contains -conventions, not laws or syntax. - - "A universal convention supplies all of maintainability, clarity, - consistency, and a foundation for good programming habits too. - What it doesn't do is insist that you follow it against your will. - That's Python!" - - -- Tim Peters on comp.lang.python, 2001-06-16 - -If you violate these conventions, the worst you'll get is some dirty -looks. But some software (such as the Docutils_ docstring processing -system [1]_ [2]_) will be aware of the conventions, so following them -will get you the best results. - - -Specification -============= - -What is a Docstring? --------------------- - -A docstring is a string literal that occurs as the first statement in -a module, function, class, or method definition. Such a docstring -becomes the ``__doc__`` special attribute of that object. - -All modules should normally have docstrings, and all functions and -classes exported by a module should also have docstrings. Public -methods (including the ``__init__`` constructor) should also have -docstrings. A package may be documented in the module docstring of -the ``__init__.py`` file in the package directory. - -String literals occurring elsewhere in Python code may also act as -documentation. They are not recognized by the Python bytecode -compiler and are not accessible as runtime object attributes (i.e. not -assigned to ``__doc__``), but two types of extra docstrings may be -extracted by software tools: - -1. String literals occurring immediately after a simple assignment at - the top level of a module, class, or ``__init__`` method are called - "attribute docstrings". - -2. String literals occurring immediately after another docstring are - called "additional docstrings". - -Please see PEP 258, "Docutils Design Specification" [2]_, for a -detailed description of attribute and additional docstrings. - -XXX Mention docstrings of 2.2 properties. - -For consistency, always use ``"""triple double quotes"""`` around -docstrings. Use ``r"""raw triple double quotes"""`` if you use any -backslashes in your docstrings. For Unicode docstrings, use -``u"""Unicode triple-quoted strings"""``. - -There are two forms of docstrings: one-liners and multi-line -docstrings. - - -One-line Docstrings --------------------- - -One-liners are for really obvious cases. They should really fit on -one line. For example:: - - def kos_root(): - """Return the pathname of the KOS root directory.""" - global _kos_root - if _kos_root: return _kos_root - ... - -Notes: - -- Triple quotes are used even though the string fits on one line. - This makes it easy to later expand it. - -- The closing quotes are on the same line as the opening quotes. This - looks better for one-liners. - -- There's no blank line either before or after the docstring. - -- The docstring is a phrase ending in a period. It prescribes the - function or method's effect as a command ("Do this", "Return that"), - not as a description; e.g. don't write "Returns the pathname ...". - -- The one-line docstring should NOT be a "signature" reiterating the - function/method parameters (which can be obtained by introspection). - Don't do:: - - def function(a, b): - """function(a, b) -> list""" - - This type of docstring is only appropriate for C functions (such as - built-ins), where introspection is not possible. However, the - nature of the *return value* cannot be determined by introspection, - so it should be mentioned. The preferred form for such a docstring - would be something like:: - - def function(a, b): - """Do X and return a list.""" - - (Of course "Do X" should be replaced by a useful description!) - - -Multi-line Docstrings ----------------------- - -Multi-line docstrings consist of a summary line just like a one-line -docstring, followed by a blank line, followed by a more elaborate -description. The summary line may be used by automatic indexing -tools; it is important that it fits on one line and is separated from -the rest of the docstring by a blank line. The summary line may be on -the same line as the opening quotes or on the next line. The entire -docstring is indented the same as the quotes at its first line (see -example below). - -Insert a blank line before and after all docstrings (one-line or -multi-line) that document a class -- generally speaking, the class's -methods are separated from each other by a single blank line, and the -docstring needs to be offset from the first method by a blank line; -for symmetry, put a blank line between the class header and the -docstring. Docstrings documenting functions or methods generally -don't have this requirement, unless the function or method's body is -written as a number of blank-line separated sections -- in this case, -treat the docstring as another section, and precede it with a blank -line. - -The docstring of a script (a stand-alone program) should be usable as -its "usage" message, printed when the script is invoked with incorrect -or missing arguments (or perhaps with a "-h" option, for "help"). -Such a docstring should document the script's function and command -line syntax, environment variables, and files. Usage messages can be -fairly elaborate (several screens full) and should be sufficient for a -new user to use the command properly, as well as a complete quick -reference to all options and arguments for the sophisticated user. - -The docstring for a module should generally list the classes, -exceptions and functions (and any other objects) that are exported by -the module, with a one-line summary of each. (These summaries -generally give less detail than the summary line in the object's -docstring.) The docstring for a package (i.e., the docstring of the -package's ``__init__.py`` module) should also list the modules and -subpackages exported by the package. - -The docstring for a function or method should summarize its behavior -and document its arguments, return value(s), side effects, exceptions -raised, and restrictions on when it can be called (all if applicable). -Optional arguments should be indicated. It should be documented -whether keyword arguments are part of the interface. - -The docstring for a class should summarize its behavior and list the -public methods and instance variables. If the class is intended to be -subclassed, and has an additional interface for subclasses, this -interface should be listed separately (in the docstring). The class -constructor should be documented in the docstring for its ``__init__`` -method. Individual methods should be documented by their own -docstring. - -If a class subclasses another class and its behavior is mostly -inherited from that class, its docstring should mention this and -summarize the differences. Use the verb "override" to indicate that a -subclass method replaces a superclass method and does not call the -superclass method; use the verb "extend" to indicate that a subclass -method calls the superclass method (in addition to its own behavior). - -*Do not* use the Emacs convention of mentioning the arguments of -functions or methods in upper case in running text. Python is case -sensitive and the argument names can be used for keyword arguments, so -the docstring should document the correct argument names. It is best -to list each argument on a separate line. For example:: - - def complex(real=0.0, imag=0.0): - """Form a complex number. - - Keyword arguments: - real -- the real part (default 0.0) - imag -- the imaginary part (default 0.0) - - """ - if imag == 0.0 and real == 0.0: return complex_zero - ... - -The BDFL [3]_ recommends inserting a blank line between the last -paragraph in a multi-line docstring and its closing quotes, placing -the closing quotes on a line by themselves. This way, Emacs' -``fill-paragraph`` command can be used on it. - - -Handling Docstring Indentation ------------------------------- - -Docstring processing tools will strip a uniform amount of indentation -from the second and further lines of the docstring, equal to the -minimum indentation of all non-blank lines after the first line. Any -indentation in the first line of the docstring (i.e., up to the first -newline) is insignificant and removed. Relative indentation of later -lines in the docstring is retained. Blank lines should be removed -from the beginning and end of the docstring. - -Since code is much more precise than words, here is an implementation -of the algorithm:: - - def trim(docstring): - if not docstring: - return '' - # Convert tabs to spaces (following the normal Python rules) - # and split into a list of lines: - lines = docstring.expandtabs().splitlines() - # Determine minimum indentation (first line doesn't count): - indent = sys.maxint - for line in lines[1:]: - stripped = line.lstrip() - if stripped: - indent = min(indent, len(line) - len(stripped)) - # Remove indentation (first line is special): - trimmed = [lines[0].strip()] - if indent < sys.maxint: - for line in lines[1:]: - trimmed.append(line[indent:].rstrip()) - # Strip off trailing and leading blank lines: - while trimmed and not trimmed[-1]: - trimmed.pop() - while trimmed and not trimmed[0]: - trimmed.pop(0) - # Return a single string: - return '\n'.join(trimmed) - -The docstring in this example contains two newline characters and is -therefore 3 lines long. The first and last lines are blank:: - - def foo(): - """ - This is the second line of the docstring. - """ - -To illustrate:: - - >>> print repr(foo.__doc__) - '\n This is the second line of the docstring.\n ' - >>> foo.__doc__.splitlines() - ['', ' This is the second line of the docstring.', ' '] - >>> trim(foo.__doc__) - 'This is the second line of the docstring.' - -Once trimmed, these docstrings are equivalent:: - - def foo(): - """A multi-line - docstring. - """ - - def bar(): - """ - A multi-line - docstring. - """ - - -References and Footnotes -======================== - -.. [1] PEP 256, Docstring Processing System Framework, Goodger - (http://www.python.org/peps/pep-0256.html) - -.. [2] PEP 258, Docutils Design Specification, Goodger - (http://www.python.org/peps/pep-0258.html) - -.. [3] Guido van Rossum, Python's creator and Benevolent Dictator For - Life. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. _Python Style Guide: - http://www.python.org/doc/essays/styleguide.html - -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - - -Copyright -========= - -This document has been placed in the public domain. - - -Acknowledgements -================ - -The "Specification" text comes mostly verbatim from the `Python Style -Guide`_ essay by Guido van Rossum. - -This document borrows ideas from the archives of the Python Doc-SIG_. -Thanks to all members past and present. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - fill-column: 70 - sentence-end-double-space: t - End: diff --git a/docutils/docs/peps/pep-0258.txt b/docutils/docs/peps/pep-0258.txt deleted file mode 100644 index 0d646bb82..000000000 --- a/docutils/docs/peps/pep-0258.txt +++ /dev/null @@ -1,1029 +0,0 @@ -PEP: 258 -Title: Docutils Design Specification -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net> -Discussions-To: <doc-sig@python.org> -Status: Draft -Type: Standards Track -Content-Type: text/x-rst -Requires: 256, 257 -Created: 31-May-2001 -Post-History: 13-Jun-2001 - - -========== - Abstract -========== - -This PEP documents design issues and implementation details for -Docutils, a Python Docstring Processing System (DPS). The rationale -and high-level concepts of a DPS are documented in PEP 256, "Docstring -Processing System Framework" [#PEP-256]_. Also see PEP 256 for a -"Road Map to the Docstring PEPs". - -Docutils is being designed modularly so that any of its components can -be replaced easily. In addition, Docutils is not limited to the -processing of Python docstrings; it processes standalone documents as -well, in several contexts. - -No changes to the core Python language are required by this PEP. Its -deliverables consist of a package for the standard library and its -documentation. - - -=============== - Specification -=============== - -Docutils Project Model -====================== - -Project components and data flow:: - - +---------------------------+ - | Docutils: | - | docutils.core.Publisher, | - | docutils.core.publish_*() | - +---------------------------+ - / | \ - / | \ - 1,3,5 / 6 | \ 7 - +--------+ +-------------+ +--------+ - | READER | ----> | TRANSFORMER | ====> | WRITER | - +--------+ +-------------+ +--------+ - / \\ | - / \\ | - 2 / 4 \\ 8 | - +-------+ +--------+ +--------+ - | INPUT | | PARSER | | OUTPUT | - +-------+ +--------+ +--------+ - -The numbers above each component indicate the path a document's data -takes. Double-width lines between Reader & Parser and between -Transformer & Writer indicate that data sent along these paths should -be standard (pure & unextended) Docutils doc trees. Single-width -lines signify that internal tree extensions or completely unrelated -representations are possible, but they must be supported at both ends. - - -Publisher ---------- - -The ``docutils.core`` module contains a "Publisher" facade class and -several convenience functions: "publish_cmdline()" (for command-line -front ends), "publish_file()" (for programmatic use with file-like -I/O), and "publish_string()" (for programmatic use with string I/O). -The Publisher class encapsulates the high-level logic of a Docutils -system. The Publisher class has overall responsibility for -processing, controlled by the ``Publisher.publish()`` method: - -1. Set up internal settings (may include config files & command-line - options) and I/O objects. - -2. Call the Reader object to read data from the source Input object - and parse the data with the Parser object. A document object is - returned. - -3. Set up and apply transforms via the Transformer object attached to - the document. - -4. Call the Writer object which translates the document to the final - output format and writes the formatted data to the destination - Output object. Depending on the Output object, the output may be - returned from the Writer, and then from the ``publish()`` method. - -Calling the "publish" function (or instantiating a "Publisher" object) -with component names will result in default behavior. For custom -behavior (customizing component settings), create custom component -objects first, and pass *them* to the Publisher or ``publish_*`` -convenience functions. - - -Readers -------- - -Readers understand the input context (where the data is coming from), -send the whole input or discrete "chunks" to the parser, and provide -the context to bind the chunks together back into a cohesive whole. - -Each reader is a module or package exporting a "Reader" class with a -"read" method. The base "Reader" class can be found in the -``docutils/readers/__init__.py`` module. - -Most Readers will have to be told what parser to use. So far (see the -list of examples below), only the Python Source Reader ("PySource"; -still incomplete) will be able to determine the parser on its own. - -Responsibilities: - -* Get input text from the source I/O. - -* Pass the input text to the parser, along with a fresh `document - tree`_ root. - -Examples: - -* Standalone (Raw/Plain): Just read a text file and process it. - The reader needs to be told which parser to use. - - The "Standalone Reader" has been implemented in module - ``docutils.readers.standalone``. - -* Python Source: See `Python Source Reader`_ below. This Reader is - currently in development in the Docutils sandbox. - -* Email: RFC-822 headers, quoted excerpts, signatures, MIME parts. - -* PEP: RFC-822 headers, "PEP xxxx" and "RFC xxxx" conversion to URIs. - The "PEP Reader" has been implemented in module - ``docutils.readers.pep``; see PEP 287 and PEP 12. - -* Wiki: Global reference lookups of "wiki links" incorporated into - transforms. (CamelCase only or unrestricted?) Lazy - indentation? - -* Web Page: As standalone, but recognize meta fields as meta tags. - Support for templates of some sort? (After ``<body>``, before - ``</body>``?) - -* FAQ: Structured "question & answer(s)" constructs. - -* Compound document: Merge chapters into a book. Master manifest - file? - - -Parsers -------- - -Parsers analyze their input and produce a Docutils `document tree`_. -They don't know or care anything about the source or destination of -the data. - -Each input parser is a module or package exporting a "Parser" class -with a "parse" method. The base "Parser" class can be found in the -``docutils/parsers/__init__.py`` module. - -Responsibilities: Given raw input text and a doctree root node, -populate the doctree by parsing the input text. - -Example: The only parser implemented so far is for the -reStructuredText markup. It is implemented in the -``docutils/parsers/rst/`` package. - -The development and integration of other parsers is possible and -encouraged. - - -.. _transforms: - -Transformer ------------ - -The Transformer class, in ``docutils/transforms/__init__.py``, stores -transforms and applies them to documents. A transformer object is -attached to every new document tree. The Publisher_ calls -``Transformer.apply_transforms()`` to apply all stored transforms to -the document tree. Transforms change the document tree from one form -to another, add to the tree, or prune it. Transforms resolve -references and footnote numbers, process interpreted text, and do -other context-sensitive processing. - -Some transforms are specific to components (Readers, Parser, Writers, -Input, Output). Standard component-specific transforms are specified -in the ``default_transforms`` attribute of component classes. After -the Reader has finished processing, the Publisher_ calls -``Transformer.populate_from_components()`` with a list of components -and all default transforms are stored. - -Each transform is a class in a module in the ``docutils/transforms/`` -package, a subclass of ``docutils.tranforms.Transform``. Transform -classes each have a ``default_priority`` attribute which is used by -the Transformer to apply transforms in order (low to high). The -default priority can be overridden when adding transforms to the -Transformer object. - -Transformer responsibilities: - -* Apply transforms to the document tree, in priority order. - -* Store a mapping of component type name ('reader', 'writer', etc.) to - component objects. These are used by certain transforms (such as - "components.Filter") to determine suitability. - -Transform responsibilities: - -* Modify a doctree in-place, either purely transforming one structure - into another, or adding new structures based on the doctree and/or - external data. - -Examples of transforms (in the ``docutils/transforms/`` package): - -* frontmatter.DocInfo: Conversion of document metadata (bibliographic - information). - -* references.AnonymousHyperlinks: Resolution of anonymous references - to corresponding targets. - -* parts.Contents: Generates a table of contents for a document. - -* document.Merger: Combining multiple populated doctrees into one. - (Not yet implemented or fully understood.) - -* document.Splitter: Splits a document into a tree-structure of - subdocuments, perhaps by section. It will have to transform - references appropriately. (Neither implemented not remotely - understood.) - -* components.Filter: Includes or excludes elements which depend on a - specific Docutils component. - - -Writers -------- - -Writers produce the final output (HTML, XML, TeX, etc.). Writers -translate the internal `document tree`_ structure into the final data -format, possibly running Writer-specific transforms_ first. - -By the time the document gets to the Writer, it should be in final -form. The Writer's job is simply (and only) to translate from the -Docutils doctree structure to the target format. Some small -transforms may be required, but they should be local and -format-specific. - -Each writer is a module or package exporting a "Writer" class with a -"write" method. The base "Writer" class can be found in the -``docutils/writers/__init__.py`` module. - -Responsibilities: - -* Translate doctree(s) into specific output formats. - - - Transform references into format-native forms. - -* Write the translated output to the destination I/O. - -Examples: - -* XML: Various forms, such as: - - - Docutils XML (an expression of the internal document tree, - implemented as ``docutils.writers.docutils_xml``). - - - DocBook (being implemented in the Docutils sandbox). - -* HTML (XHTML implemented as ``docutils.writers.html4css1``). - -* PDF (a ReportLabs interface is being developed in the Docutils - sandbox). - -* TeX (a LaTeX Writer is being implemented in the sandbox). - -* Docutils-native pseudo-XML (implemented as - ``docutils.writers.pseudoxml``, used for testing). - -* Plain text - -* reStructuredText? - - -Input/Output ------------- - -I/O classes provide a uniform API for low-level input and output. -Subclasses will exist for a variety of input/output mechanisms. -However, they can be considered an implementation detail. Most -applications should be satisfied using one of the convenience -functions associated with the Publisher_. - -I/O classes are currently in the preliminary stages; there's a lot of -work yet to be done. Issues: - -* How to represent multi-file input (files & directories) in the API? - -* How to represent multi-file output? Perhaps "Writer" variants, one - for each output distribution type? Or Output objects with - associated transforms? - -Responsibilities: - -* Read data from the input source (Input objects) or write data to the - output destination (Output objects). - -Examples of input sources: - -* A single file on disk or a stream (implemented as - ``docutils.io.FileInput``). - -* Multiple files on disk (``MultiFileInput``?). - -* Python source files: modules and packages. - -* Python strings, as received from a client application - (implemented as ``docutils.io.StringInput``). - -Examples of output destinations: - -* A single file on disk or a stream (implemented as - ``docutils.io.FileOutput``). - -* A tree of directories and files on disk. - -* A Python string, returned to a client application (implemented as - ``docutils.io.StringOutput``). - -* No output; useful for programmatic applications where only a portion - of the normal output is to be used (implemented as - ``docutils.io.NullOutput``). - -* A single tree-shaped data structure in memory. - -* Some other set of data structures in memory. - - -Docutils Package Structure -========================== - -* Package "docutils". - - - Module "__init__.py" contains: class "Component", a base class for - Docutils components; class "SettingsSpec", a base class for - specifying runtime settings (used by docutils.frontend); and class - "TransformSpec", a base class for specifying transforms. - - - Module "docutils.core" contains facade class "Publisher" and - convenience functions. See `Publisher`_ above. - - - Module "docutils.frontend" provides runtime settings support, for - programmatic use and front-end tools (including configuration file - support, and command-line argument and option processing). - - - Module "docutils.io" provides a uniform API for low-level input - and output. See `Input/Output`_ above. - - - Module "docutils.nodes" contains the Docutils document tree - element class library plus tree-traversal Visitor pattern base - classes. See `Document Tree`_ below. - - - Module "docutils.statemachine" contains a finite state machine - specialized for regular-expression-based text filters and parsers. - The reStructuredText parser implementation is based on this - module. - - - Module "docutils.urischemes" contains a mapping of known URI - schemes ("http", "ftp", "mail", etc.). - - - Module "docutils.utils" contains utility functions and classes, - including a logger class ("Reporter"; see `Error Handling`_ - below). - - - Package "docutils.parsers": markup parsers_. - - - Function "get_parser_class(parser_name)" returns a parser module - by name. Class "Parser" is the base class of specific parsers. - (``docutils/parsers/__init__.py``) - - - Package "docutils.parsers.rst": the reStructuredText parser. - - - Alternate markup parsers may be added. - - See `Parsers`_ above. - - - Package "docutils.readers": context-aware input readers. - - - Function "get_reader_class(reader_name)" returns a reader module - by name or alias. Class "Reader" is the base class of specific - readers. (``docutils/readers/__init__.py``) - - - Module "docutils.readers.standalone" reads independent document - files. - - - Module "docutils.readers.pep" reads PEPs (Python Enhancement - Proposals). - - - Module "docutils.readers.doctree" is used to re-read a - previously stored document tree for reprocessing. - - - Readers to be added for: Python source code (structure & - docstrings), email, FAQ, and perhaps Wiki and others. - - See `Readers`_ above. - - - Package "docutils.writers": output format writers. - - - Function "get_writer_class(writer_name)" returns a writer module - by name. Class "Writer" is the base class of specific writers. - (``docutils/writers/__init__.py``) - - - Package "docutils.writers.html4css1" is a simple HyperText - Markup Language document tree writer for HTML 4.01 and CSS1. - - - Package "docutils.writers.pep_html" generates HTML from - reStructuredText PEPs. - - - Package "docutils.writers.s5_html" generates S5/HTML slide - shows. - - - Package "docutils.writers.latex2e" writes LaTeX. - - - Package "docutils.writers.newlatex2e" also writes LaTeX; it is a - new implementation. - - - Module "docutils.writers.docutils_xml" writes the internal - document tree in XML form. - - - Module "docutils.writers.pseudoxml" is a simple internal - document tree writer; it writes indented pseudo-XML. - - - Module "docutils.writers.null" is a do-nothing writer; it is - used for specialized purposes such as storing the internal - document tree. - - - Writers to be added: HTML 3.2 or 4.01-loose, XML (various forms, - such as DocBook), PDF, plaintext, reStructuredText, and perhaps - others. - - Subpackages of "docutils.writers" contain modules and data files - (such as stylesheets) that support the individual writers. - - See `Writers`_ above. - - - Package "docutils.transforms": tree transform classes. - - - Class "Transformer" stores transforms and applies them to - document trees. (``docutils/transforms/__init__.py``) - - - Class "Transform" is the base class of specific transforms. - (``docutils/transforms/__init__.py``) - - - Each module contains related transform classes. - - See `Transforms`_ above. - - - Package "docutils.languages": Language modules contain - language-dependent strings and mappings. They are named for their - language identifier (as defined in `Choice of Docstring Format`_ - below), converting dashes to underscores. - - - Function "get_language(language_code)", returns matching - language module. (``docutils/languages/__init__.py``) - - - Modules: en.py (English), de.py (German), fr.py (French), it.py - (Italian), sk.py (Slovak), sv.py (Swedish). - - - Other languages to be added. - -* Third-party modules: "extras" directory. These modules are - installed only if they're not already present in the Python - installation. - - - ``extras/optparse.py`` and ``extras/textwrap.py`` provide - option parsing and command-line help; from Greg Ward's - http://optik.sf.net/ project, included for convenience. - - - ``extras/roman.py`` contains Roman numeral conversion routines. - - -Front-End Tools -=============== - -The ``tools/`` directory contains several front ends for common -Docutils processing. See `Docutils Front-End Tools`_ for details. - -.. _Docutils Front-End Tools: - http://docutils.sourceforge.net/docs/user/tools.html - - -Document Tree -============= - -A single intermediate data structure is used internally by Docutils, -in the interfaces between components; it is defined in the -``docutils.nodes`` module. It is not required that this data -structure be used *internally* by any of the components, just -*between* components as outlined in the diagram in the `Docutils -Project Model`_ above. - -Custom node types are allowed, provided that either (a) a transform -converts them to standard Docutils nodes before they reach the Writer -proper, or (b) the custom node is explicitly supported by certain -Writers, and is wrapped in a filtered "pending" node. An example of -condition (a) is the `Python Source Reader`_ (see below), where a -"stylist" transform converts custom nodes. The HTML ``<meta>`` tag is -an example of condition (b); it is supported by the HTML Writer but -not by others. The reStructuredText "meta" directive creates a -"pending" node, which contains knowledge that the embedded "meta" node -can only be handled by HTML-compatible writers. The "pending" node is -resolved by the ``docutils.transforms.components.Filter`` transform, -which checks that the calling writer supports HTML; if it doesn't, the -"pending" node (and enclosed "meta" node) is removed from the -document. - -The document tree data structure is similar to a DOM tree, but with -specific node names (classes) instead of DOM's generic nodes. The -schema is documented in an XML DTD (eXtensible Markup Language -Document Type Definition), which comes in two parts: - -* the Docutils Generic DTD, docutils.dtd_, and - -* the OASIS Exchange Table Model, soextbl.dtd_. - -The DTD defines a rich set of elements, suitable for many input and -output formats. The DTD retains all information necessary to -reconstruct the original input text, or a reasonable facsimile -thereof. - -See `The Docutils Document Tree`_ for details (incomplete). - - -Error Handling -============== - -When the parser encounters an error in markup, it inserts a system -message (DTD element "system_message"). There are five levels of -system messages: - -* Level-0, "DEBUG": an internal reporting issue. There is no effect - on the processing. Level-0 system messages are handled separately - from the others. - -* Level-1, "INFO": a minor issue that can be ignored. There is little - or no effect on the processing. Typically level-1 system messages - are not reported. - -* Level-2, "WARNING": an issue that should be addressed. If ignored, - there may be minor problems with the output. Typically level-2 - system messages are reported but do not halt processing. - -* Level-3, "ERROR": a major issue that should be addressed. If - ignored, the output will contain unpredictable errors. Typically - level-3 system messages are reported but do not halt processing. - -* Level-4, "SEVERE": a critical error that must be addressed. - Typically level-4 system messages are turned into exceptions which - do halt processing. If ignored, the output will contain severe - errors. - -Although the initial message levels were devised independently, they -have a strong correspondence to `VMS error condition severity -levels`_; the names in quotes for levels 1 through 4 were borrowed -from VMS. Error handling has since been influenced by the `log4j -project`_. - - -Python Source Reader -==================== - -The Python Source Reader ("PySource") is the Docutils component that -reads Python source files, extracts docstrings in context, then -parses, links, and assembles the docstrings into a cohesive whole. It -is a major and non-trivial component, currently under experimental -development in the Docutils sandbox. High-level design issues are -presented here. - - -Processing Model ----------------- - -This model will evolve over time, incorporating experience and -discoveries. - -1. The PySource Reader uses an Input class to read in Python packages - and modules, into a tree of strings. - -2. The Python modules are parsed, converting the tree of strings into - a tree of abstract syntax trees with docstring nodes. - -3. The abstract syntax trees are converted into an internal - representation of the packages/modules. Docstrings are extracted, - as well as code structure details. See `AST Mining`_ below. - Namespaces are constructed for lookup in step 6. - -4. One at a time, the docstrings are parsed, producing standard - Docutils doctrees. - -5. PySource assembles all the individual docstrings' doctrees into a - Python-specific custom Docutils tree paralleling the - package/module/class structure; this is a custom Reader-specific - internal representation (see the `Docutils Python Source DTD`_). - Namespaces must be merged: Python identifiers, hyperlink targets. - -6. Cross-references from docstrings (interpreted text) to Python - identifiers are resolved according to the Python namespace lookup - rules. See `Identifier Cross-References`_ below. - -7. A "Stylist" transform is applied to the custom doctree (by the - Transformer_), custom nodes are rendered using standard nodes as - primitives, and a standard document tree is emitted. See `Stylist - Transforms`_ below. - -8. Other transforms are applied to the standard doctree by the - Transformer_. - -9. The standard doctree is sent to a Writer, which translates the - document into a concrete format (HTML, PDF, etc.). - -10. The Writer uses an Output class to write the resulting data to its - destination (disk file, directories and files, etc.). - - -AST Mining ----------- - -Abstract Syntax Tree mining code will be written (or adapted) that -scans a parsed Python module, and returns an ordered tree containing -the names, docstrings (including attribute and additional docstrings; -see below), and additional info (in parentheses below) of all of the -following objects: - -* packages -* modules -* module attributes (+ initial values) -* classes (+ inheritance) -* class attributes (+ initial values) -* instance attributes (+ initial values) -* methods (+ parameters & defaults) -* functions (+ parameters & defaults) - -(Extract comments too? For example, comments at the start of a module -would be a good place for bibliographic field lists.) - -In order to evaluate interpreted text cross-references, namespaces for -each of the above will also be required. - -See the python-dev/docstring-develop thread "AST mining", started on -2001-08-14. - - -Docstring Extraction Rules --------------------------- - -1. What to examine: - - a) If the "``__all__``" variable is present in the module being - documented, only identifiers listed in "``__all__``" are - examined for docstrings. - - b) In the absence of "``__all__``", all identifiers are examined, - except those whose names are private (names begin with "_" but - don't begin and end with "__"). - - c) 1a and 1b can be overridden by runtime settings. - -2. Where: - - Docstrings are string literal expressions, and are recognized in - the following places within Python modules: - - a) At the beginning of a module, function definition, class - definition, or method definition, after any comments. This is - the standard for Python ``__doc__`` attributes. - - b) Immediately following a simple assignment at the top level of a - module, class definition, or ``__init__`` method definition, - after any comments. See `Attribute Docstrings`_ below. - - c) Additional string literals found immediately after the - docstrings in (a) and (b) will be recognized, extracted, and - concatenated. See `Additional Docstrings`_ below. - - d) @@@ 2.2-style "properties" with attribute docstrings? Wait for - syntax? - -3. How: - - Whenever possible, Python modules should be parsed by Docutils, not - imported. There are several reasons: - - - Importing untrusted code is inherently insecure. - - - Information from the source is lost when using introspection to - examine an imported module, such as comments and the order of - definitions. - - - Docstrings are to be recognized in places where the byte-code - compiler ignores string literal expressions (2b and 2c above), - meaning importing the module will lose these docstrings. - - Of course, standard Python parsing tools such as the "parser" - library module should be used. - - When the Python source code for a module is not available - (i.e. only the ``.pyc`` file exists) or for C extension modules, to - access docstrings the module can only be imported, and any - limitations must be lived with. - -Since attribute docstrings and additional docstrings are ignored by -the Python byte-code compiler, no namespace pollution or runtime bloat -will result from their use. They are not assigned to ``__doc__`` or -to any other attribute. The initial parsing of a module may take a -slight performance hit. - - -Attribute Docstrings -'''''''''''''''''''' - -(This is a simplified version of PEP 224 [#PEP-224]_.) - -A string literal immediately following an assignment statement is -interpreted by the docstring extraction machinery as the docstring of -the target of the assignment statement, under the following -conditions: - -1. The assignment must be in one of the following contexts: - - a) At the top level of a module (i.e., not nested inside a compound - statement such as a loop or conditional): a module attribute. - - b) At the top level of a class definition: a class attribute. - - c) At the top level of the "``__init__``" method definition of a - class: an instance attribute. Instance attributes assigned in - other methods are assumed to be implementation details. (@@@ - ``__new__`` methods?) - - d) A function attribute assignment at the top level of a module or - class definition. - - Since each of the above contexts are at the top level (i.e., in the - outermost suite of a definition), it may be necessary to place - dummy assignments for attributes assigned conditionally or in a - loop. - -2. The assignment must be to a single target, not to a list or a tuple - of targets. - -3. The form of the target: - - a) For contexts 1a and 1b above, the target must be a simple - identifier (not a dotted identifier, a subscripted expression, - or a sliced expression). - - b) For context 1c above, the target must be of the form - "``self.attrib``", where "``self``" matches the "``__init__``" - method's first parameter (the instance parameter) and "attrib" - is a simple identifier as in 3a. - - c) For context 1d above, the target must be of the form - "``name.attrib``", where "``name``" matches an already-defined - function or method name and "attrib" is a simple identifier as - in 3a. - -Blank lines may be used after attribute docstrings to emphasize the -connection between the assignment and the docstring. - -Examples:: - - g = 'module attribute (module-global variable)' - """This is g's docstring.""" - - class AClass: - - c = 'class attribute' - """This is AClass.c's docstring.""" - - def __init__(self): - """Method __init__'s docstring.""" - - self.i = 'instance attribute' - """This is self.i's docstring.""" - - def f(x): - """Function f's docstring.""" - return x**2 - - f.a = 1 - """Function attribute f.a's docstring.""" - - -Additional Docstrings -''''''''''''''''''''' - -(This idea was adapted from PEP 216 [#PEP-216]_.) - -Many programmers would like to make extensive use of docstrings for -API documentation. However, docstrings do take up space in the -running program, so some programmers are reluctant to "bloat up" their -code. Also, not all API documentation is applicable to interactive -environments, where ``__doc__`` would be displayed. - -Docutils' docstring extraction tools will concatenate all string -literal expressions which appear at the beginning of a definition or -after a simple assignment. Only the first strings in definitions will -be available as ``__doc__``, and can be used for brief usage text -suitable for interactive sessions; subsequent string literals and all -attribute docstrings are ignored by the Python byte-code compiler and -may contain more extensive API information. - -Example:: - - def function(arg): - """This is __doc__, function's docstring.""" - """ - This is an additional docstring, ignored by the byte-code - compiler, but extracted by Docutils. - """ - pass - -.. topic:: Issue: ``from __future__ import`` - - This would break "``from __future__ import``" statements introduced - in Python 2.1 for multiple module docstrings (main docstring plus - additional docstring(s)). The Python Reference Manual specifies: - - A future statement must appear near the top of the module. The - only lines that can appear before a future statement are: - - * the module docstring (if any), - * comments, - * blank lines, and - * other future statements. - - Resolution? - - 1. Should we search for docstrings after a ``__future__`` - statement? Very ugly. - - 2. Redefine ``__future__`` statements to allow multiple preceding - string literals? - - 3. Or should we not even worry about this? There probably - shouldn't be ``__future__`` statements in production code, after - all. Perhaps modules with ``__future__`` statements will simply - have to put up with the single-docstring limitation. - - -Choice of Docstring Format --------------------------- - -Rather than force everyone to use a single docstring format, multiple -input formats are allowed by the processing system. A special -variable, ``__docformat__``, may appear at the top level of a module -before any function or class definitions. Over time or through -decree, a standard format or set of formats should emerge. - -A module's ``__docformat__`` variable only applies to the objects -defined in the module's file. In particular, the ``__docformat__`` -variable in a package's ``__init__.py`` file does not apply to objects -defined in subpackages and submodules. - -The ``__docformat__`` variable is a string containing the name of the -format being used, a case-insensitive string matching the input -parser's module or package name (i.e., the same name as required to -"import" the module or package), or a registered alias. If no -``__docformat__`` is specified, the default format is "plaintext" for -now; this may be changed to the standard format if one is ever -established. - -The ``__docformat__`` string may contain an optional second field, -separated from the format name (first field) by a single space: a -case-insensitive language identifier as defined in RFC 1766. A -typical language identifier consists of a 2-letter language code from -`ISO 639`_ (3-letter codes used only if no 2-letter code exists; RFC -1766 is currently being revised to allow 3-letter codes). If no -language identifier is specified, the default is "en" for English. -The language identifier is passed to the parser and can be used for -language-dependent markup features. - - -Identifier Cross-References ---------------------------- - -In Python docstrings, interpreted text is used to classify and mark up -program identifiers, such as the names of variables, functions, -classes, and modules. If the identifier alone is given, its role is -inferred implicitly according to the Python namespace lookup rules. -For functions and methods (even when dynamically assigned), -parentheses ('()') may be included:: - - This function uses `another()` to do its work. - -For class, instance and module attributes, dotted identifiers are used -when necessary. For example (using reStructuredText markup):: - - class Keeper(Storer): - - """ - Extend `Storer`. Class attribute `instances` keeps track - of the number of `Keeper` objects instantiated. - """ - - instances = 0 - """How many `Keeper` objects are there?""" - - def __init__(self): - """ - Extend `Storer.__init__()` to keep track of instances. - - Keep count in `Keeper.instances`, data in `self.data`. - """ - Storer.__init__(self) - Keeper.instances += 1 - - self.data = [] - """Store data in a list, most recent last.""" - - def store_data(self, data): - """ - Extend `Storer.store_data()`; append new `data` to a - list (in `self.data`). - """ - self.data = data - -Each of the identifiers quoted with backquotes ("`") will become -references to the definitions of the identifiers themselves. - - -Stylist Transforms ------------------- - -Stylist transforms are specialized transforms specific to the PySource -Reader. The PySource Reader doesn't have to make any decisions as to -style; it just produces a logically constructed document tree, parsed -and linked, including custom node types. Stylist transforms -understand the custom nodes created by the Reader and convert them -into standard Docutils nodes. - -Multiple Stylist transforms may be implemented and one can be chosen -at runtime (through a "--style" or "--stylist" command-line option). -Each Stylist transform implements a different layout or style; thus -the name. They decouple the context-understanding part of the Reader -from the layout-generating part of processing, resulting in a more -flexible and robust system. This also serves to "separate style from -content", the SGML/XML ideal. - -By keeping the piece of code that does the styling small and modular, -it becomes much easier for people to roll their own styles. The -"barrier to entry" is too high with existing tools; extracting the -stylist code will lower the barrier considerably. - - -========================== - References and Footnotes -========================== - -.. [#PEP-256] PEP 256, Docstring Processing System Framework, Goodger - (http://www.python.org/peps/pep-0256.html) - -.. [#PEP-224] PEP 224, Attribute Docstrings, Lemburg - (http://www.python.org/peps/pep-0224.html) - -.. [#PEP-216] PEP 216, Docstring Format, Zadka - (http://www.python.org/peps/pep-0216.html) - -.. _docutils.dtd: - http://docutils.sourceforge.net/docs/ref/docutils.dtd - -.. _soextbl.dtd: - http://docutils.sourceforge.net/docs/ref/soextblx.dtd - -.. _The Docutils Document Tree: - http://docutils.sourceforge.net/docs/ref/doctree.html - -.. _VMS error condition severity levels: - http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html - #error_cond_severity - -.. _log4j project: http://logging.apache.org/log4j/docs/index.html - -.. _Docutils Python Source DTD: - http://docutils.sourceforge.net/docs/dev/pysource.dtd - -.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html - -.. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/ - - - -================== - Project Web Site -================== - -A SourceForge project has been set up for this work at -http://docutils.sourceforge.net/. - - -=========== - Copyright -=========== - -This document has been placed in the public domain. - - -================== - Acknowledgements -================== - -This document borrows ideas from the archives of the `Python -Doc-SIG`_. Thanks to all members past & present. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/peps/pep-0287.txt b/docutils/docs/peps/pep-0287.txt deleted file mode 100644 index 689d6b919..000000000 --- a/docutils/docs/peps/pep-0287.txt +++ /dev/null @@ -1,815 +0,0 @@ -PEP: 287 -Title: reStructuredText Docstring Format -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net> -Discussions-To: <doc-sig@python.org> -Status: Draft -Type: Informational -Content-Type: text/x-rst -Created: 25-Mar-2002 -Post-History: 02-Apr-2002 -Replaces: 216 - - -Abstract -======== - -When plaintext hasn't been expressive enough for inline documentation, -Python programmers have sought out a format for docstrings. This PEP -proposes that the `reStructuredText markup`_ be adopted as a standard -markup format for structured plaintext documentation in Python -docstrings, and for PEPs and ancillary documents as well. -reStructuredText is a rich and extensible yet easy-to-read, -what-you-see-is-what-you-get plaintext markup syntax. - -Only the low-level syntax of docstrings is addressed here. This PEP -is not concerned with docstring semantics or processing at all (see -PEP 256 for a "Road Map to the Docstring PEPs"). Nor is it an attempt -to deprecate pure plaintext docstrings, which are always going to be -legitimate. The reStructuredText markup is an alternative for those -who want more expressive docstrings. - - -Benefits -======== - -Programmers are by nature a lazy breed. We reuse code with functions, -classes, modules, and subsystems. Through its docstring syntax, -Python allows us to document our code from within. The "holy grail" -of the Python Documentation Special Interest Group (Doc-SIG_) has been -a markup syntax and toolset to allow auto-documentation, where the -docstrings of Python systems can be extracted in context and processed -into useful, high-quality documentation for multiple purposes. - -Document markup languages have three groups of customers: the authors -who write the documents, the software systems that process the data, -and the readers, who are the final consumers and the most important -group. Most markups are designed for the authors and software -systems; readers are only meant to see the processed form, either on -paper or via browser software. ReStructuredText is different: it is -intended to be easily readable in source form, without prior knowledge -of the markup. ReStructuredText is entirely readable in plaintext -format, and many of the markup forms match common usage (e.g., -``*emphasis*``), so it reads quite naturally. Yet it is rich enough -to produce complex documents, and extensible so that there are few -limits. Of course, to write reStructuredText documents some prior -knowledge is required. - -The markup offers functionality and expressivity, while maintaining -easy readability in the source text. The processed form (HTML etc.) -makes it all accessible to readers: inline live hyperlinks; live links -to and from footnotes; automatic tables of contents (with live -links!); tables; images for diagrams etc.; pleasant, readable styled -text. - -The reStructuredText parser is available now, part of the Docutils_ -project. Standalone reStructuredText documents and PEPs can be -converted to HTML; other output format writers are being worked on and -will become available over time. Work is progressing on a Python -source "Reader" which will implement auto-documentation from -docstrings. Authors of existing auto-documentation tools are -encouraged to integrate the reStructuredText parser into their -projects, or better yet, to join forces to produce a world-class -toolset for the Python standard library. - -Tools will become available in the near future, which will allow -programmers to generate HTML for online help, XML for multiple -purposes, and eventually PDF, DocBook, and LaTeX for printed -documentation, essentially "for free" from the existing docstrings. -The adoption of a standard will, at the very least, benefit docstring -processing tools by preventing further "reinventing the wheel". - -Eventually PyDoc, the one existing standard auto-documentation tool, -could have reStructuredText support added. In the interim it will -have no problem with reStructuredText markup, since it treats all -docstrings as preformatted plaintext. - - -Goals -===== - -These are the generally accepted goals for a docstring format, as -discussed in the Doc-SIG: - -1. It must be readable in source form by the casual observer. - -2. It must be easy to type with any standard text editor. - -3. It must not need to contain information which can be deduced from - parsing the module. - -4. It must contain sufficient information (structure) so it can be - converted to any reasonable markup format. - -5. It must be possible to write a module's entire documentation in - docstrings, without feeling hampered by the markup language. - -reStructuredText meets and exceeds all of these goals, and sets its -own goals as well, even more stringent. See `Docstring-Significant -Features`_ below. - -The goals of this PEP are as follows: - -1. To establish reStructuredText as a standard structured plaintext - format for docstrings (inline documentation of Python modules and - packages), PEPs, README-type files and other standalone documents. - "Accepted" status will be sought through Python community consensus - and eventual BDFL pronouncement. - - Please note that reStructuredText is being proposed as *a* - standard, not *the only* standard. Its use will be entirely - optional. Those who don't want to use it need not. - -2. To solicit and address any related concerns raised by the Python - community. - -3. To encourage community support. As long as multiple competing - markups are out there, the development community remains fractured. - Once a standard exists, people will start to use it, and momentum - will inevitably gather. - -4. To consolidate efforts from related auto-documentation projects. - It is hoped that interested developers will join forces and work on - a joint/merged/common implementation. - -Once reStructuredText is a Python standard, effort can be focused on -tools instead of arguing for a standard. Python needs a standard set -of documentation tools. - -With regard to PEPs, one or both of the following strategies may be -applied: - -a) Keep the existing PEP section structure constructs (one-line - section headers, indented body text). Subsections can either be - forbidden, or supported with reStructuredText-style underlined - headers in the indented body text. - -b) Replace the PEP section structure constructs with the - reStructuredText syntax. Section headers will require underlines, - subsections will be supported out of the box, and body text need - not be indented (except for block quotes). - -Strategy (b) is recommended, and its implementation is complete. - -Support for RFC 2822 headers has been added to the reStructuredText -parser for PEPs (unambiguous given a specific context: the first -contiguous block of the document). It may be desired to concretely -specify what over/underline styles are allowed for PEP section -headers, for uniformity. - - -Rationale -========= - -The lack of a standard syntax for docstrings has hampered the -development of standard tools for extracting and converting docstrings -into documentation in standard formats (e.g., HTML, DocBook, TeX). -There have been a number of proposed markup formats and variations, -and many tools tied to these proposals, but without a standard -docstring format they have failed to gain a strong following and/or -floundered half-finished. - -Throughout the existence of the Doc-SIG, consensus on a single -standard docstring format has never been reached. A lightweight, -implicit markup has been sought, for the following reasons (among -others): - -1. Docstrings written within Python code are available from within the - interactive interpreter, and can be "print"ed. Thus the use of - plaintext for easy readability. - -2. Programmers want to add structure to their docstrings, without - sacrificing raw docstring readability. Unadorned plaintext cannot - be transformed ("up-translated") into useful structured formats. - -3. Explicit markup (like XML or TeX) is widely considered unreadable - by the uninitiated. - -4. Implicit markup is aesthetically compatible with the clean and - minimalist Python syntax. - -Many alternative markups for docstrings have been proposed on the -Doc-SIG over the years; a representative sample is listed below. Each -is briefly analyzed in terms of the goals stated above. Please note -that this is *not* intended to be an exclusive list of all existing -markup systems; there are many other markups (Texinfo, Doxygen, TIM, -YODL, AFT, ...) which are not mentioned. - -- XML_, SGML_, DocBook_, HTML_, XHTML_ - - XML and SGML are explicit, well-formed meta-languages suitable for - all kinds of documentation. XML is a variant of SGML. They are - best used behind the scenes, because to untrained eyes they are - verbose, difficult to type, and too cluttered to read comfortably as - source. DocBook, HTML, and XHTML are all applications of SGML - and/or XML, and all share the same basic syntax and the same - shortcomings. - -- TeX_ - - TeX is similar to XML/SGML in that it's explicit, but not very easy - to write, and not easy for the uninitiated to read. - -- `Perl POD`_ - - Most Perl modules are documented in a format called POD (Plain Old - Documentation). This is an easy-to-type, very low level format with - strong integration with the Perl parser. Many tools exist to turn - POD documentation into other formats: info, HTML and man pages, - among others. However, the POD syntax takes after Perl itself in - terms of readability. - -- JavaDoc_ - - Special comments before Java classes and functions serve to document - the code. A program to extract these, and turn them into HTML - documentation is called javadoc, and is part of the standard Java - distribution. However, JavaDoc has a very intimate relationship - with HTML, using HTML tags for most markup. Thus it shares the - readability problems of HTML. - -- Setext_, StructuredText_ - - Early on, variants of Setext (Structure Enhanced Text), including - Zope Corp's StructuredText, were proposed for Python docstring - formatting. Hereafter these variants will collectively be called - "STexts". STexts have the advantage of being easy to read without - special knowledge, and relatively easy to write. - - Although used by some (including in most existing Python - auto-documentation tools), until now STexts have failed to become - standard because: - - - STexts have been incomplete. Lacking "essential" constructs that - people want to use in their docstrings, STexts are rendered less - than ideal. Note that these "essential" constructs are not - universal; everyone has their own requirements. - - - STexts have been sometimes surprising. Bits of text are - unexpectedly interpreted as being marked up, leading to user - frustration. - - - SText implementations have been buggy. - - - Most STexts have have had no formal specification except for the - implementation itself. A buggy implementation meant a buggy spec, - and vice-versa. - - - There has been no mechanism to get around the SText markup rules - when a markup character is used in a non-markup context. In other - words, no way to escape markup. - -Proponents of implicit STexts have vigorously opposed proposals for -explicit markup (XML, HTML, TeX, POD, etc.), and the debates have -continued off and on since 1996 or earlier. - -reStructuredText is a complete revision and reinterpretation of the -SText idea, addressing all of the problems listed above. - - -Specification -============= - -The specification and user documentaton for reStructuredText is -quite extensive. Rather than repeating or summarizing it all -here, links to the originals are provided. - -Please first take a look at `A ReStructuredText Primer`_, a short and -gentle introduction. The `Quick reStructuredText`_ user reference -quickly summarizes all of the markup constructs. For complete and -extensive details, please refer to the following documents: - -- `An Introduction to reStructuredText`_ - -- `reStructuredText Markup Specification`_ - -- `reStructuredText Directives`_ - -In addition, `Problems With StructuredText`_ explains many markup -decisions made with regards to StructuredText, and `A Record of -reStructuredText Syntax Alternatives`_ records markup decisions made -independently. - - -Docstring-Significant Features -============================== - -- A markup escaping mechanism. - - Backslashes (``\``) are used to escape markup characters when needed - for non-markup purposes. However, the inline markup recognition - rules have been constructed in order to minimize the need for - backslash-escapes. For example, although asterisks are used for - *emphasis*, in non-markup contexts such as "*" or "(*)" or "x * y", - the asterisks are not interpreted as markup and are left unchanged. - For many non-markup uses of backslashes (e.g., describing regular - expressions), inline literals or literal blocks are applicable; see - the next item. - -- Markup to include Python source code and Python interactive - sessions: inline literals, literal blocks, and doctest blocks. - - Inline literals use ``double-backquotes`` to indicate program I/O or - code snippets. No markup interpretation (including backslash-escape - [``\``] interpretation) is done within inline literals. - - Literal blocks (block-level literal text, such as code excerpts or - ASCII graphics) are indented, and indicated with a double-colon - ("::") at the end of the preceding paragraph (right here -->):: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - - Doctest blocks begin with ">>> " and end with a blank line. Neither - indentation nor literal block double-colons are required. For - example:: - - Here's a doctest block: - - >>> print 'Python-specific usage examples; begun with ">>>"' - Python-specific usage examples; begun with ">>>" - >>> print '(cut and pasted from interactive sessions)' - (cut and pasted from interactive sessions) - -- Markup that isolates a Python identifier: interpreted text. - - Text enclosed in single backquotes is recognized as "interpreted - text", whose interpretation is application-dependent. In the - context of a Python docstring, the default interpretation of - interpreted text is as Python identifiers. The text will be marked - up with a hyperlink connected to the documentation for the - identifier given. Lookup rules are the same as in Python itself: - LGB namespace lookups (local, global, builtin). The "role" of the - interpreted text (identifying a class, module, function, etc.) is - determined implicitly from the namespace lookup. For example:: - - class Keeper(Storer): - - """ - Keep data fresher longer. - - Extend `Storer`. Class attribute `instances` keeps track - of the number of `Keeper` objects instantiated. - """ - - instances = 0 - """How many `Keeper` objects are there?""" - - def __init__(self): - """ - Extend `Storer.__init__()` to keep track of - instances. Keep count in `self.instances` and data - in `self.data`. - """ - Storer.__init__(self) - self.instances += 1 - - self.data = [] - """Store data in a list, most recent last.""" - - def storedata(self, data): - """ - Extend `Storer.storedata()`; append new `data` to a - list (in `self.data`). - """ - self.data = data - - Each piece of interpreted text is looked up according to the local - namespace of the block containing its docstring. - -- Markup that isolates a Python identifier and specifies its type: - interpreted text with roles. - - Although the Python source context reader is designed not to require - explicit roles, they may be used. To classify identifiers - explicitly, the role is given along with the identifier in either - prefix or suffix form:: - - Use :method:`Keeper.storedata` to store the object's data in - `Keeper.data`:instance_attribute:. - - The syntax chosen for roles is verbose, but necessarily so (if - anyone has a better alternative, please post it to the Doc-SIG_). - The intention of the markup is that there should be little need to - use explicit roles; their use is to be kept to an absolute minimum. - -- Markup for "tagged lists" or "label lists": field lists. - - Field lists represent a mapping from field name to field body. - These are mostly used for extension syntax, such as "bibliographic - field lists" (representing document metadata such as author, date, - and version) and extension attributes for directives (see below). - They may be used to implement methodologies (docstring semantics), - such as identifying parameters, exceptions raised, etc.; such usage - is beyond the scope of this PEP. - - A modified RFC 2822 syntax is used, with a colon *before* as well as - *after* the field name. Field bodies are more versatile as well; - they may contain multiple field bodies (even nested field lists). - For example:: - - :Date: 2002-03-22 - :Version: 1 - :Authors: - - Me - - Myself - - I - - Standard RFC 2822 header syntax cannot be used for this construct - because it is ambiguous. A word followed by a colon at the - beginning of a line is common in written text. - -- Markup extensibility: directives and substitutions. - - Directives are used as an extension mechanism for reStructuredText, - a way of adding support for new block-level constructs without - adding new syntax. Directives for images, admonitions (note, - caution, etc.), and tables of contents generation (among others) - have been implemented. For example, here's how to place an image:: - - .. image:: mylogo.png - - Substitution definitions allow the power and flexibility of - block-level directives to be shared by inline text. For example:: - - The |biohazard| symbol must be used on containers used to - dispose of medical waste. - - .. |biohazard| image:: biohazard.png - -- Section structure markup. - - Section headers in reStructuredText use adornment via underlines - (and possibly overlines) rather than indentation. For example:: - - This is a Section Title - ======================= - - This is a Subsection Title - -------------------------- - - This paragraph is in the subsection. - - This is Another Section Title - ============================= - - This paragraph is in the second section. - - -Questions & Answers -=================== - -1. Is reStructuredText rich enough? - - Yes, it is for most people. If it lacks some construct that is - required for a specific application, it can be added via the - directive mechanism. If a useful and common construct has been - overlooked and a suitably readable syntax can be found, it can be - added to the specification and parser. - -2. Is reStructuredText *too* rich? - - For specific applications or individuals, perhaps. In general, no. - - Since the very beginning, whenever a docstring markup syntax has - been proposed on the Doc-SIG_, someone has complained about the - lack of support for some construct or other. The reply was often - something like, "These are docstrings we're talking about, and - docstrings shouldn't have complex markup." The problem is that a - construct that seems superfluous to one person may be absolutely - essential to another. - - reStructuredText takes the opposite approach: it provides a rich - set of implicit markup constructs (plus a generic extension - mechanism for explicit markup), allowing for all kinds of - documents. If the set of constructs is too rich for a particular - application, the unused constructs can either be removed from the - parser (via application-specific overrides) or simply omitted by - convention. - -3. Why not use indentation for section structure, like StructuredText - does? Isn't it more "Pythonic"? - - Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post: - - I still think that using indentation to indicate sectioning is - wrong. If you look at how real books and other print - publications are laid out, you'll notice that indentation is - used frequently, but mostly at the intra-section level. - Indentation can be used to offset lists, tables, quotations, - examples, and the like. (The argument that docstrings are - different because they are input for a text formatter is wrong: - the whole point is that they are also readable without - processing.) - - I reject the argument that using indentation is Pythonic: text - is not code, and different traditions and conventions hold. - People have been presenting text for readability for over 30 - centuries. Let's not innovate needlessly. - - See `Section Structure via Indentation`__ in `Problems With - StructuredText`_ for further elaboration. - - __ http://docutils.sourceforge.net/docs/dev/rst/problems.html - #section-structure-via-indentation - -4. Why use reStructuredText for PEPs? What's wrong with the existing - standard? - - The existing standard for PEPs is very limited in terms of general - expressibility, and referencing is especially lacking for such a - reference-rich document type. PEPs are currently converted into - HTML, but the results (mostly monospaced text) are less than - attractive, and most of the value-added potential of HTML - (especially inline hyperlinks) is untapped. - - Making reStructuredText a standard markup for PEPs will enable much - richer expression, including support for section structure, inline - markup, graphics, and tables. In several PEPs there are ASCII - graphics diagrams, which are all that plaintext documents can - support. Since PEPs are made available in HTML form, the ability - to include proper diagrams would be immediately useful. - - Current PEP practices allow for reference markers in the form "[1]" - in the text, and the footnotes/references themselves are listed in - a section toward the end of the document. There is currently no - hyperlinking between the reference marker and the - footnote/reference itself (it would be possible to add this to - pep2html.py, but the "markup" as it stands is ambiguous and - mistakes would be inevitable). A PEP with many references (such as - this one ;-) requires a lot of flipping back and forth. When - revising a PEP, often new references are added or unused references - deleted. It is painful to renumber the references, since it has to - be done in two places and can have a cascading effect (insert a - single new reference 1, and every other reference has to be - renumbered; always adding new references to the end is suboptimal). - It is easy for references to go out of sync. - - PEPs use references for two purposes: simple URL references and - footnotes. reStructuredText differentiates between the two. A PEP - might contain references like this:: - - Abstract - - This PEP proposes adding frungible doodads [1] to the core. - It extends PEP 9876 [2] via the BCA [3] mechanism. - - ... - - References and Footnotes - - [1] http://www.example.org/ - - [2] PEP 9876, Let's Hope We Never Get Here - http://www.python.org/peps/pep-9876.html - - [3] "Bogus Complexity Addition" - - Reference 1 is a simple URL reference. Reference 2 is a footnote - containing text and a URL. Reference 3 is a footnote containing - text only. Rewritten using reStructuredText, this PEP could look - like this:: - - Abstract - ======== - - This PEP proposes adding `frungible doodads`_ to the core. It - extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism. - - ... - - References & Footnotes - ====================== - - .. _frungible doodads: http://www.example.org/ - - .. [#pep9876] PEP 9876, Let's Hope We Never Get Here - - .. [#] "Bogus Complexity Addition" - - URLs and footnotes can be defined close to their references if - desired, making them easier to read in the source text, and making - the PEPs easier to revise. The "References and Footnotes" section - can be auto-generated with a document tree transform. Footnotes - from throughout the PEP would be gathered and displayed under a - standard header. If URL references should likewise be written out - explicitly (in citation form), another tree transform could be - used. - - URL references can be named ("frungible doodads"), and can be - referenced from multiple places in the document without additional - definitions. When converted to HTML, references will be replaced - with inline hyperlinks (HTML <a> tags). The two footnotes are - automatically numbered, so they will always stay in sync. The - first footnote also contains an internal reference name, "pep9876", - so it's easier to see the connection between reference and footnote - in the source text. Named footnotes can be referenced multiple - times, maintaining consistent numbering. - - The "#pep9876" footnote could also be written in the form of a - citation:: - - It extends PEP 9876 [PEP9876]_ ... - - .. [PEP9876] PEP 9876, Let's Hope We Never Get Here - - Footnotes are numbered, whereas citations use text for their - references. - -5. Wouldn't it be better to keep the docstring and PEP proposals - separate? - - The PEP markup proposal may be removed if it is deemed that there - is no need for PEP markup, or it could be made into a separate PEP. - If accepted, PEP 1, PEP Purpose and Guidelines [#PEP-1]_, and PEP - 9, Sample PEP Template [#PEP-9]_ will be updated. - - It seems natural to adopt a single consistent markup standard for - all uses of structured plaintext in Python, and to propose it all - in one place. - -6. The existing pep2html.py script converts the existing PEP format to - HTML. How will the new-format PEPs be converted to HTML? - - A new version of pep2html.py with integrated reStructuredText - parsing has been completed. The Docutils project supports PEPs - with a "PEP Reader" component, including all functionality - currently in pep2html.py (auto-recognition of PEP & RFC references, - email masking, etc.). - -7. Who's going to convert the existing PEPs to reStructuredText? - - PEP authors or volunteers may convert existing PEPs if they like, - but there is no requirement to do so. The reStructuredText-based - PEPs will coexist with the old PEP standard. The pep2html.py - mentioned in answer 6 processes both old and new standards. - -8. Why use reStructuredText for README and other ancillary files? - - The reasoning given for PEPs in answer 4 above also applies to - README and other ancillary files. By adopting a standard markup, - these files can be converted to attractive cross-referenced HTML - and put up on python.org. Developers of other projects can also - take advantage of this facility for their own documentation. - -9. Won't the superficial similarity to existing markup conventions - cause problems, and result in people writing invalid markup (and - not noticing, because the plaintext looks natural)? How forgiving - is reStructuredText of "not quite right" markup? - - There will be some mis-steps, as there would be when moving from - one programming language to another. As with any language, - proficiency grows with experience. Luckily, reStructuredText is a - very little language indeed. - - As with any syntax, there is the possibility of syntax errors. It - is expected that a user will run the processing system over their - input and check the output for correctness. - - In a strict sense, the reStructuredText parser is very unforgiving - (as it should be; "In the face of ambiguity, refuse the temptation - to guess" [#Zen]_ applies to parsing markup as well as computer - languages). Here's design goal 3 from `An Introduction to - reStructuredText`_: - - Unambiguous. The rules for markup must not be open for - interpretation. For any given input, there should be one and - only one possible output (including error output). - - While unforgiving, at the same time the parser does try to be - helpful by producing useful diagnostic output ("system messages"). - The parser reports problems, indicating their level of severity - (from least to most: debug, info, warning, error, severe). The - user or the client software can decide on reporting thresholds; - they can ignore low-level problems or cause high-level problems to - bring processing to an immediate halt. Problems are reported - during the parse as well as included in the output, often with - two-way links between the source of the problem and the system - message explaining it. - -10. Will the docstrings in the Python standard library modules be - converted to reStructuredText? - - No. Python's library reference documentation is maintained - separately from the source. Docstrings in the Python standard - library should not try to duplicate the library reference - documentation. The current policy for docstrings in the Python - standard library is that they should be no more than concise - hints, simple and markup-free (although many *do* contain ad-hoc - implicit markup). - -11. I want to write all my strings in Unicode. Will anything - break? - - The parser fully supports Unicode. Docutils supports arbitrary - input and output encodings. - -12. Why does the community need a new structured text design? - - The existing structured text designs are deficient, for the - reasons given in "Rationale" above. reStructuredText aims to be a - complete markup syntax, within the limitations of the "readable - plaintext" medium. - -13. What is wrong with existing documentation methodologies? - - What existing methodologies? For Python docstrings, there is - **no** official standard markup format, let alone a documentation - methodology akin to JavaDoc. The question of methodology is at a - much higher level than syntax (which this PEP addresses). It is - potentially much more controversial and difficult to resolve, and - is intentionally left out of this discussion. - - -References & Footnotes -====================== - -.. [#PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton - (http://www.python.org/peps/pep-0001.html) - -.. [#PEP-9] PEP 9, Sample PEP Template, Warsaw - (http://www.python.org/peps/pep-0009.html) - -.. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just - "``import this``" in Python) - -__ http://www.python.org/doc/Humor.html#zen - -.. [#PEP-216] PEP 216, Docstring Format, Zadka - (http://www.python.org/peps/pep-0216.html) - -.. _reStructuredText markup: http://docutils.sourceforge.net/rst.html - -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - -.. _XML: http://www.w3.org/XML/ - -.. _SGML: http://www.oasis-open.org/cover/general.html - -.. _DocBook: http://docbook.org/tdg/en/html/docbook.html - -.. _HTML: http://www.w3.org/MarkUp/ - -.. _XHTML: http://www.w3.org/MarkUp/#xhtml1 - -.. _TeX: http://www.tug.org/interest.html - -.. _Perl POD: http://perldoc.perl.org/perlpod.html - -.. _JavaDoc: http://java.sun.com/j2se/javadoc/ - -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html - -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage - -.. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/user/rst/quickstart.html - -.. _Quick reStructuredText: - http://docutils.sourceforge.net/docs/user/rst/quickref.html - -.. _An Introduction to reStructuredText: - http://docutils.sourceforge.net/docs/ref/rst/introduction.html - -.. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html - -.. _reStructuredText Directives: - http://docutils.sourceforge.net/docs/ref/rst/directives.html - -.. _Problems with StructuredText: - http://docutils.sourceforge.net/docs/dev/rst/problems.html - -.. _A Record of reStructuredText Syntax Alternatives: - http://docutils.sourceforge.net/docs/dev/rst/alternatives.html - -.. _Docutils: http://docutils.sourceforge.net/ - - -Copyright -========= - -This document has been placed in the public domain. - - -Acknowledgements -================ - -Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by -Moshe Zadka. - -Special thanks to all members past & present of the Python Doc-SIG_. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt deleted file mode 100644 index 25e5f9594..000000000 --- a/docutils/docs/ref/doctree.txt +++ /dev/null @@ -1,4970 +0,0 @@ -============================ - The Docutils Document Tree -============================ - -A Guide to the Docutils DTD -*************************** - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - - -.. contents:: :depth: 1 - - -This document describes the XML data structure of Docutils_ documents: -the relationships and semantics of elements and attributes. The -Docutils document structure is formally defined by the `Docutils -Generic DTD`_ XML document type definition, docutils.dtd_, which is -the definitive source for details of element structural relationships. - -This document does not discuss implementation details. Those can be -found in internal documentation (docstrings) for the -``docutils.nodes`` module, where the document tree data structure is -implemented in a class library. - -The reader is assumed to have some familiarity with XML or SGML, and -an understanding of the data structure meaning of "tree". For a list -of introductory articles, see `Introducing the Extensible Markup -Language (XML)`_. - -The reStructuredText_ markup is used for illustrative examples -throughout this document. For a gentle introduction, see `A -ReStructuredText Primer`_. For complete technical details, see the -`reStructuredText Markup Specification`_. - - -.. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils Generic DTD: -.. _Docutils DTD: -.. _docutils.dtd: docutils.dtd -.. _Introducing the Extensible Markup Language (XML): - http://xml.coverpages.org/xmlIntro.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _A ReStructuredText Primer: ../user/rst/quickstart.html -.. _reStructuredText Markup Specification: rst/restructuredtext.html - - -------------------- - Element Hierarchy -------------------- - -.. contents:: :local: - -Below is a simplified diagram of the hierarchy of elements in the -Docutils document tree structure. An element may contain any other -elements immediately below it in the diagram. Notes are written in -square brackets. Element types in parentheses indicate recursive or -one-to-many relationships; sections may contain (sub)sections, tables -contain further body elements, etc. :: - - +--------------------------------------------------------------------+ - | document [may begin with a title, subtitle, decoration, docinfo] | - | +--------------------------------------+ - | | sections [each begins with a title] | - +-----------------------------+-------------------------+------------+ - | [body elements:] | (sections) | - | | - literal | - lists | | - hyperlink +------------+ - | | blocks | - tables | | targets | - | para- | - doctest | - block | foot- | - sub. defs | - | graphs | blocks | quotes | notes | - comments | - +---------+-----------+----------+-------+--------------+ - | [text]+ | [text] | (body elements) | [text] | - | (inline +-----------+------------------+--------------+ - | markup) | - +---------+ - -The Docutils document model uses a simple, recursive model for section -structure. A document_ node may contain body elements and section_ -elements. Sections in turn may contain body elements and sections. -The level (depth) of a section element is determined from its physical -nesting level; unlike other document models (``<h1>`` in HTML_, -``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not -incorporated into the element name. - -The Docutils document model uses strict element content models. Every -element has a unique structure and semantics, but elements may be -classified into general categories (below). Only elements which are -meant to directly contain text data have a mixed content model, where -text data and inline elements may be intermixed. This is unlike the -much looser HTML_ document model, where paragraphs and text data may -occur at the same level. - - -Structural Elements -=================== - -Structural elements may only contain child elements; they do not -directly contain text data. Structural elements may contain body -elements or further structural elements. Structural elements can only -be child elements of other structural elements. - -Category members: document_, section_, topic_, sidebar_ - - -Structural Subelements ----------------------- - -Structural subelements are child elements of structural elements. -Simple structuctural subelements (title_, subtitle_) contain text -data; the others are compound and do not directly contain text data. - -Category members: title_, subtitle_, decoration_, docinfo_, -transition_ - - -Bibliographic Elements -`````````````````````` - -The docinfo_ element is an optional child of document_. It groups -bibliographic elements together. All bibliographic elements except -authors_ and field_ contain text data. authors_ contains further -bibliographic elements (most notably author_). field_ contains -field_name_ and field_body_ body subelements. - -Category members: address_, author_, authors_, contact_, copyright_, -date_, field_, organization_, revision_, status_, version_ - - -Decorative Elements -``````````````````` - -The decoration_ element is also an optional child of document_. It -groups together elements used to generate page headers and footers. - -Category members: footer_, header_ - - -Body Elements -============= - -Body elements are contained within structural elements and compound -body elements. There are two subcategories of body elements: simple -and compound. - -Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, comment_, compound_, container_, danger_, -definition_list_, doctest_block_, enumerated_list_, error_, -field_list_, figure_, footnote_, hint_, image_, important_, -line_block_, literal_block_, note_, option_list_, paragraph_, -pending_, raw_, rubric_, substitution_definition_, system_message_, -table_, target_, tip_, warning_ - - -Simple Body Elements --------------------- - -Simple body elements are empty or directly contain text data. Those -that contain text data may also contain inline elements. Such -elements therefore have a "mixed content model". - -Category members: comment_, doctest_block_, image_, literal_block_, -paragraph_, pending_, raw_, rubric_, substitution_definition_, target_ - - -Compound Body Elements ----------------------- - -Compound body elements contain local substructure (body subelements) -and further body elements. They do not directly contain text data. - -Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, compound_, container_, danger_, definition_list_, -enumerated_list_, error_, field_list_, figure_, footnote_, hint_, -important_, line_block, note_, option_list_, system_message_, table_, -tip_, warning_ - - -Body Subelements -```````````````` - -Compound body elements contain specific subelements (e.g. bullet_list_ -contains list_item_). Subelements may themselves be compound elements -(containing further child elements, like field_) or simple data -elements (containing text data, like field_name_). These subelements -always occur within specific parent elements, never at the body -element level (beside paragraphs, etc.). - -Category members (simple): attribution_, caption_, classifier_, -colspec_, field_name_, label_, line_, option_argument_, -option_string_, term_ - -Category members (compound): definition_, definition_list_item_, -description_, entry_, field_, field_body_, legend_, list_item_, -option_, option_group_, option_list_item_, row_, tbody_, tgroup_, -thead_ - - -Inline Elements -=============== - -Inline elements directly contain text data, and may also contain -further inline elements. Inline elements are contained within simple -body elements. Most inline elements have a "mixed content model". - -Category members: abbreviation_, acronym_, citation_reference_, -emphasis_, footnote_reference_, generated_, image_, inline_, literal_, -problematic_, reference_, strong_, subscript_, -substitution_reference_, superscript_, target_, title_reference_, raw_ - - -.. _HTML: http://www.w3.org/MarkUp/ -.. _DocBook: http://docbook.org/tdg/en/html/docbook.html -.. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm - - -------------------- - Element Reference -------------------- - -.. contents:: :local: - :depth: 1 - -Each element in the DTD (document type definition) is described in its -own section below. Each section contains an introduction plus the -following subsections: - -* Details (of element relationships and semantics): - - - Category: One or more references to the element categories in - `Element Hierarchy`_ above. Some elements belong to more than one - category. - - - Parents: A list of elements which may contain the element. - - - Children: A list of elements which may occur within the element. - - - Analogues: Describes analogous elements in well-known document - models such as HTML_ or DocBook_. Lists similarities and - differences. - - - Processing: Lists formatting or rendering recommendations for the - element. - -* Content Model: - - The formal XML content model from the `Docutils DTD`_, followed by: - - - Attributes: Describes (or refers to descriptions of) the possible - values and semantics of each attribute. - - - Parameter Entities: Lists the parameter entities which directly or - indirectly include the element. - -* Examples: reStructuredText_ examples are shown along with - fragments of the document trees resulting from parsing. - _`Pseudo-XML` is used for the results of parsing and processing. - Pseudo-XML is a representation of XML where nesting is indicated by - indentation and end-tags are not shown. Some of the precision of - real XML is given up in exchange for easier readability. For - example, the following are equivalent: - - - Real XML:: - - <document> - <section ids="a-title" names="a title"> - <title>A Title</title> - <paragraph>A paragraph.</paragraph> - </section> - </document> - - - Pseudo-XML:: - - <document> - <section ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - --------------------- - -Many of the element reference sections below are marked "_`to be -completed`". Please help complete this document by contributing to -its writing. - - -``abbreviation`` -================ - -`To be completed`_. - - -``acronym`` -=========== - -`To be completed`_. - - -``address`` -=========== - -The ``address`` element holds the surface mailing address information -for the author (individual or group) of the document, or a third-party -contact address. Its structure is identical to that of the -literal_block_ element: whitespace is significant, especially -newlines. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - The following elements may contain ``address``: docinfo_, authors_ - -:Children: - ``address`` elements contain text data plus `inline elements`_. - -:Analogues: - ``address`` is analogous to the DocBook "address" element. - -:Processing: - As with the literal_block_ element, newlines and other whitespace - is significant and must be preserved. However, a monospaced - typeface need not be used. - - See also docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``address`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``address``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Address: 123 Example Ave. - Example, EX - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <address> - 123 Example Ave. - Example, EX - -See docinfo_ for a more complete example, including processing -context. - - -``admonition`` -============== - -This element is a generic, titled admonition. Also see the specific -admonition elements Docutils offers (in alphabetical order): caution_, -danger_, error_, hint_, important_, note_, tip_, warning_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``admonition``. - -:Children: - ``admonition`` elements begin with a title_ and may contain one or - more `body elements`_. - -:Analogues: - ``admonition`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.). - - -Content Model -------------- - -.. parsed-literal:: - - (title_, (`%body.elements;`_)+) - -:Attributes: - The ``admonition`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``admonition``. The `%structure.model;`_ parameter entity - indirectly includes ``admonition``. - - -Examples --------- - -reStructuredText source:: - - .. admonition:: And, by the way... - - You can make up your own admonition too. - -Pseudo-XML_ fragment from simple parsing:: - - <admonition class="admonition-and-by-the-way"> - <title> - And, by the way... - <paragraph> - You can make up your own admonition too. - - -``attention`` -============= - -The ``attention`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): caution_, danger_, error_, -hint_, important_, note_, tip_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``attention``. - -:Children: - ``attention`` elements contain one or more `body elements`_. - -:Analogues: - ``attention`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Attention!" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``attention`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``attention``. The `%structure.model;`_ parameter entity - indirectly includes ``attention``. - - -Examples --------- - -reStructuredText source:: - - .. Attention:: All your base are belong to us. - -Pseudo-XML_ fragment from simple parsing:: - - <attention> - <paragraph> - All your base are belong to us. - - -``attribution`` -=============== - -`To be completed`_. - - -``author`` -========== - -The ``author`` element holds the name of the author of the document. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - The following elements may contain ``author``: docinfo_, authors_ - -:Children: - ``author`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``author`` is analogous to the DocBook "author" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``author`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``author``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Author: J. Random Hacker - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <author> - J. Random Hacker - -See docinfo_ for a more complete example, including processing -context. - - -``authors`` -=========== - -The ``authors`` element is a container for author information for -documents with multiple authors. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``authors``. - -:Children: - ``authors`` elements may contain the following elements: author_, - organization_, address_, contact_ - -:Analogues: - ``authors`` is analogous to the DocBook "authors" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - ((author_, organization_?, address_?, contact_?)+) - -:Attributes: - The ``authors`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``authors``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Authors: J. Random Hacker; Jane Doe - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <authors> - <author> - J. Random Hacker - <author> - Jane Doe - -In reStructuredText, multiple author's names are separated with -semicolons (";") or commas (","); semicolons take precedence. There -is currently no way to represent the author's organization, address, -or contact in a reStructuredText "Authors" field. - -See docinfo_ for a more complete example, including processing -context. - - -``block_quote`` -=============== - -The ``block_quote`` element is used for quotations set off from the -main text (standalone). - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``block_quote``. - -:Children: - ``block_quote`` elements contain `body elements`_ followed by an - optional attribution_ element. - -:Analogues: - ``block_quote`` is analogous to the "blockquote" element in both - HTML and DocBook. - -:Processing: - ``block_quote`` elements serve to set their contents off from the - main text, typically with indentation and/or other decoration. - - -Content Model -------------- - -.. parsed-literal:: - - ((`%body.elements;`_)+, attribution_?) - -:Attributes: - The ``block_quote`` element contains only the `common - attributes`_: ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``block_quote``. The `%structure.model;`_ parameter entity - indirectly includes ``block_quote``. - - -Examples --------- - -reStructuredText source:: - - As a great paleontologist once said, - - This theory, that is mine, is mine. - - -- Anne Elk (Miss) - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - As a great paleontologist once said, - <block_quote> - <paragraph> - This theory, that is mine, is mine. - <attribution> - Anne Elk (Miss) - - -``bullet_list`` -=============== - -The ``bullet_list`` element contains list_item_ elements which are -uniformly marked with bullets. Bullets are typically simple dingbats -(symbols) such as circles and squares. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``bullet_list``. - -:Children: - ``bullet_list`` elements contain one or more list_item_ elements. - -:Analogues: - ``bullet_list`` is analogous to the HTML "ul" element and to the - DocBook "itemizedlist" element. HTML's "ul" is short for - "unordered list", which we consider to be a misnomer. "Unordered" - implies that the list items may be randomly rearranged without - affecting the meaning of the list. Bullet lists *are* often - ordered; the ordering is simply left implicit. - -:Processing: - Each list item should begin a new vertical block, prefaced by a - bullet/dingbat. - - -Content Model -------------- - -.. parsed-literal:: - - (list_item_ +) - -:Attributes: - The ``bullet_list`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus bullet_. - - ``bullet`` is used to record the style of bullet from the input - data. In documents processed from reStructuredText_, it contains - one of "-", "+", or "*". It may be ignored in processing. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``bullet_list``. The `%structure.model;`_ parameter entity - indirectly includes ``bullet_list``. - - -Examples --------- - -reStructuredText_ source:: - - - Item 1, paragraph 1. - - Item 1, paragraph 2. - - - Item 2. - -Pseudo-XML_ fragment from simple parsing:: - - <bullet_list bullet="-"> - <list_item> - <paragraph> - Item 1, paragraph 1. - <paragraph> - Item 1, paragraph 2. - <list_item> - <paragraph> - Item 2. - -See list_item_ for another example. - - -``caption`` -=========== - -`To be completed`_. - - -``caution`` -=========== - -The ``caution`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, danger_, error_, -hint_, important_, note_, tip_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``caution``. - -:Children: - ``caution`` elements contain one or more `body elements`_. - -:Analogues: - ``caution`` is analogous to the DocBook "caution" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Caution" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``caution`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``caution``. The `%structure.model;`_ parameter entity - indirectly includes ``caution``. - - -Examples --------- - -reStructuredText source:: - - .. Caution:: Don't take any wooden nickels. - -Pseudo-XML_ fragment from simple parsing:: - - <caution> - <paragraph> - Don't take any wooden nickels. - - -``citation`` -============ - -`To be completed`_. - - -``citation_reference`` -====================== - -`To be completed`_. - - -``classifier`` -============== - -The ``classifier`` element contains the classification or type of the -term_ being defined in a definition_list_. For example, it can be -used to indicate the type of a variable. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the definition_list_item_ element contains ``classifier``. - -:Children: - ``classifier`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``classifier`` has no direct analogues in common DTDs. It can be - emulated with primitives or type effects. - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``classifier`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -Here is a hypothetical data dictionary. reStructuredText_ source:: - - name : string - Customer name. - i : int - Temporary index variable. - -Pseudo-XML_ fragment from simple parsing:: - - <definition_list> - <definition_list_item> - <term> - name - <classifier> - string - <definition> - <paragraph> - Customer name. - <definition_list_item> - <term> - i - <classifier> - int - <definition> - <paragraph> - Temporary index variable. - - -``colspec`` -=========== - -`To be completed`_. - - -``comment`` -=========== - -`To be completed`_. - - -``compound`` -============ - -`To be completed`_. - - -``contact`` -=========== - -The ``contact`` element holds contact information for the author -(individual or group) of the document, or a third-party contact. It -is typically used for an email or web address. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - The following elements may contain ``contact``: docinfo_, authors_ - -:Children: - ``contact`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``contact`` is analogous to the DocBook "email" element. The HTML - "address" element serves a similar purpose. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``contact`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``contact``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Contact: jrh@example.com - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <contact> - <reference refuri="mailto:jrh@example.com"> - jrh@example.com - -See docinfo_ for a more complete example, including processing -context. - - -``container`` -============= - -`To be completed`_. - - -``copyright`` -============= - -The ``copyright`` element contains the document's copyright statement. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``copyright``. - -:Children: - ``copyright`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``copyright`` is analogous to the DocBook "copyright" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``copyright`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``copyright``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Copyright: This document has been placed in the public domain. - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <copyright> - This document has been placed in the public domain. - -See docinfo_ for a more complete example, including processing -context. - - -``danger`` -========== - -The ``danger`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, error_, -hint_, important_, note_, tip_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``danger``. - -:Children: - ``danger`` elements contain one or more `body elements`_. - -:Analogues: - ``danger`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "!DANGER!" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``danger`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``danger``. The `%structure.model;`_ parameter entity - indirectly includes ``danger``. - - -Examples --------- - -reStructuredText source:: - - .. DANGER:: Mad scientist at work! - -Pseudo-XML_ fragment from simple parsing:: - - <danger> - <paragraph> - Mad scientist at work! - - -``date`` -======== - -The ``date`` element contains the date of publication, release, or -last modification of the document. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``date``. - -:Children: - ``date`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``date`` is analogous to the DocBook "date" element. - -:Processing: - Often used with the RCS/CVS keyword "Date". See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``date`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``date``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Date: 2002-08-20 - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <date> - 2002-08-20 - -See docinfo_ for a more complete example, including processing -context. - - -``decoration`` -============== - -The ``decoration`` element is a container for header_ and footer_ -elements and potential future extensions. These elements are used for -notes, time/datestamp, processing information, etc. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - Only the document_ element contains ``decoration``. - -:Children: - ``decoration`` elements may contain `decorative elements`_. - -:Analogues: - There are no direct analogies to ``decoration`` in HTML or in - DocBook. Equivalents are typically constructed from primitives - and/or generated by the processing system. - -:Processing: - See the individual `decorative elements`_. - - -Content Model -------------- - -.. parsed-literal:: - - (header_?, footer_?) - -Although the content model doesn't specifically require contents, no -empty ``decoration`` elements are ever created. - -:Attributes: - The ``decoration`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - A paragraph. - -Complete pseudo-XML_ result after parsing and applying transforms, -assuming that the datestamp command-line option or configuration -setting has been supplied:: - - <document> - <decoration> - <footer> - <paragraph> - Generated on: 2002-08-20. - <paragraph> - A paragraph. - - -``definition`` -============== - -The ``definition`` element is a container for the body elements used -to define a term_ in a definition_list_. - - -Details -------- - -:Category: - `Body Subelements`_ (compound) - -:Parents: - Only definition_list_item_ elements contain ``definition``. - -:Children: - ``definition`` elements may contain `body elements`_. - -:Analogues: - ``definition`` is analogous to the HTML "dd" element and to the - DocBook "listitem" element (inside a "variablelistentry" element). - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``definition`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the definition_list_, definition_list_item_, and -classifier_ elements. - - -``definition_list`` -=================== - -The ``definition_list`` element contains a list of terms and their -definitions. It can be used for glossaries or dictionaries, to -describe or classify things, for dialogues, or to itemize subtopics -(such as in this reference). - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``definition_list``. - -:Children: - ``definition_list`` elements contain one or more - definition_list_item_ elements. - -:Analogues: - ``definition_list`` is analogous to the HTML "dl" element and to - the DocBook "variablelist" element. - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - (definition_list_item_ +) - -:Attributes: - The ``definition_list`` element contains only the `common - attributes`_: ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``definition_list``. The `%structure.model;`_ parameter entity - indirectly includes ``definition_list``. - - -Examples --------- - -reStructuredText_ source:: - - Term - Definition. - - Term : classifier - The ' : ' indicates a classifier in - definition list item terms only. - -Pseudo-XML_ fragment from simple parsing:: - - <definition_list> - <definition_list_item> - <term> - Term - <definition> - <paragraph> - Definition. - <definition_list_item> - <term> - Term - <classifier> - classifier - <definition> - <paragraph> - The ' : ' indicates a classifier in - definition list item terms only. - -See definition_list_item_ and classifier_ for further examples. - - -``definition_list_item`` -======================== - -The ``definition_list_item`` element contains a single -term_/definition_ pair (with optional classifier_). - - -Details -------- - -:Category: - `Body Subelements`_ (compound) - -:Parents: - Only the definition_list_ element contains - ``definition_list_item``. - -:Children: - ``definition_list_item`` elements each contain a single term_, - an optional classifier_, and a definition_. - -:Analogues: - ``definition_list_item`` is analogous to the DocBook - "variablelistentry" element. - -:Processing: - The optional classifier_ can be rendered differently from the - term_. They should be separated visually, typically by spaces - plus a colon or dash. - - -Content Model -------------- - -.. parsed-literal:: - - (term_, classifier_?, definition_) - -:Attributes: - The ``definition_list_item`` element contains only the `common - attributes`_: ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - Tyrannosaurus Rex : carnivore - Big and scary; the "Tyrant King". - - Brontosaurus : herbivore - All brontosauruses are thin at one end, - much much thicker in the middle - and then thin again at the far end. - - -- Anne Elk (Miss) - -Pseudo-XML_ fragment from simple parsing:: - - <definition_list> - <definition_list_item> - <term> - Tyrannosaurus Rex - <classifier> - carnivore - <definition> - <paragraph> - Big and scary; the "Tyrant King". - <definition_list_item> - <term> - Brontosaurus - <classifier> - herbivore - <definition> - <paragraph> - All brontosauruses are thin at one end, - much much thicker in the middle - and then thin again at the far end. - <paragraph> - -- Anne Elk (Miss) - -See definition_list_ and classifier_ for further examples. - - -``description`` -=============== - -The ``description`` element contains body elements, describing the -purpose or effect of a command-line option or group of options. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_list_item_ element contains ``description``. - -:Children: - ``description`` elements may contain `body elements`_. - -:Analogues: - ``description`` has no direct analogues in common DTDs. - -:Processing: - See option_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``description`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``docinfo`` -=========== - -The ``docinfo`` element is a container for document bibliographic -data, or meta-data (data about the document). It corresponds to the -front matter of a book, such as the title page and copyright page. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - Only the document_ element contains ``docinfo``. - -:Children: - ``docinfo`` elements contain `bibliographic elements`_. - -:Analogues: - ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" - etc.). There are no directly analogous HTML elements; the "meta" - element carries some of the same information, albeit invisibly. - -:Processing: - The ``docinfo`` element may be rendered as a two-column table or - in other styles. It may even be invisible or omitted from the - processed output. Meta-data may be extracted from ``docinfo`` - children; for example, HTML ``<meta>`` tags may be constructed. - - When Docutils_ transforms a reStructuredText_ field_list_ into a - ``docinfo`` element (see the examples below), RCS/CVS keywords are - normally stripped from simple (one paragraph) field bodies. For - complete details, please see `RCS Keywords`_ in the - `reStructuredText Markup Specification`_. - - .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords - - -Content Model -------------- - -.. parsed-literal:: - - (`%bibliographic.elements;`_)+ - -:Attributes: - The ``docinfo`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -Docinfo is represented in reStructuredText_ by a field_list_ in a -bibliographic context: the first non-comment element of a document_, -after any document title_/subtitle_. The field list is transformed -into a ``docinfo`` element and its children by a transform. Source:: - - Docinfo Example - =============== - - :Author: J. Random Hacker - :Contact: jrh@example.com - :Date: 2002-08-18 - :Status: Work In Progress - :Version: 1 - :Filename: $RCSfile$ - :Copyright: This document has been placed in the public domain. - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="docinfo-example" names="docinfo example"> - <title> - Docinfo Example - <docinfo> - <author> - J. Random Hacker - <contact> - <reference refuri="mailto:jrh@example.com"> - jrh@example.com - <date> - 2002-08-18 - <status> - Work In Progress - <version> - 1 - <field> - <field_name> - Filename - <field_body> - <paragraph> - doctree.txt - <copyright> - This document has been placed in the public domain. - -Note that "Filename" is a non-standard ``docinfo`` field, so becomes a -generic ``field`` element. Also note that the "RCSfile" keyword -syntax has been stripped from the "Filename" data. - -See field_list_ for an example in a non-bibliographic context. Also -see the individual examples for the various `bibliographic elements`_. - - -``doctest_block`` -================= - -The ``doctest_block`` element is a Python-specific variant of -literal_block_. It is a block of text where line breaks and -whitespace are significant and must be preserved. ``doctest_block`` -elements are used for interactive Python interpreter sessions, which -are distinguished by their input prompt: ``>>>``. They are meant to -illustrate usage by example, and provide an elegant and powerful -testing environment via the `doctest module`_ in the Python standard -library. - -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html - - -Details -------- - -:Category: - `Simple Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``doctest_block``. - -:Children: - ``doctest_block`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``doctest_block`` is analogous to the HTML "pre" element and to - the DocBook "programlisting" and "screen" elements. - -:Processing: - As with literal_block_, ``doctest_block`` elements are typically - rendered in a monospaced typeface. It is crucial that all - whitespace and line breaks are preserved in the rendered form. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``doctest_block`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``doctest_block``. The `%structure.model;`_ parameter entity - indirectly includes ``doctest_block``. - - -Examples --------- - -reStructuredText source:: - - This is an ordinary paragraph. - - >>> print 'this is a Doctest block' - this is a Doctest block - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - This is an ordinary paragraph. - <doctest_block xml:space="preserve"> - >>> print 'this is a Doctest block' - this is a Doctest block - - -``document`` -============ - -The ``document`` element is the root (topmost) element of the Docutils -document tree. ``document`` is the direct or indirect ancestor of -every other element in the tree. It encloses the entire document -tree. It is the starting point for a document. - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The ``document`` element has no parents. - -:Children: - ``document`` elements may contain `structural subelements`_, - `structural elements`_, and `body elements`_. - -:Analogues: - ``document`` is analogous to the HTML "html" element and to - several DocBook elements such as "book". - - -Content Model -------------- - -.. parsed-literal:: - - ( (title_, subtitle_?)?, - decoration_?, - (docinfo_, transition_?)?, - `%structure.model;`_ ) - -Depending on the source of the data and the stage of processing, the -"document" may not initially contain a "title". A document title is -not directly representable in reStructuredText_. Instead, a lone -top-level section may have its title promoted to become the document -title_, and similarly for a lone second-level (sub)section's title to -become the document subtitle_. - -The contents of "decoration_" may be specified in a document, -constructed programmatically, or both. The "docinfo_" may be -transformed from an initial field_list_. - -See the `%structure.model;`_ parameter entity for details of the body -of a ``document``. - -:Attributes: - The ``document`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus an optional title__ - attribute which stores the document title metadata. - - __ `title (attribute)`_ - - -Examples --------- - -reStructuredText_ source:: - - A Title - ======= - - A paragraph. - -Complete pseudo-XML_ result from simple parsing:: - - <document> - <section ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - -After applying transforms, the section title is promoted to become the -document title:: - - <document ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - - -``emphasis`` -============ - -`To be completed`_. - - -``entry`` -========= - -`To be completed`_. - - -``enumerated_list`` -=================== - -The ``enumerated_list`` element contains list_item_ elements which are -uniformly marked with enumerator labels. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``enumerated_list``. - -:Children: - ``enumerated_list`` elements contain one or more list_item_ - elements. - -:Analogues: - ``enumerated_list`` is analogous to the HTML "ol" element and to - the DocBook "orderedlist" element. - -:Processing: - Each list item should begin a new vertical block, prefaced by a - enumeration marker (such as "1."). - - -Content Model -------------- - -.. parsed-literal:: - - (list_item_ +) - -:Attributes: - The ``enumerated_list`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus enumtype_, - prefix_, suffix_, and start_. - - ``enumtype`` is used to record the intended enumeration sequence, - one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), - "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., - mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., - MMMMCMXCIX [4999]). - - ``prefix`` stores the formatting characters used before the - enumerator. In documents originating from reStructuredText_ data, - it will contain either "" (empty string) or "(" (left - parenthesis). It may or may not affect processing. - - ``suffix`` stores the formatting characters used after the - enumerator. In documents originating from reStructuredText_ data, - it will contain either "." (period) or ")" (right parenthesis). - Depending on the capabilities of the output format, this attribute - may or may not affect processing. - - ``start`` contains the ordinal value of the first item in the - list, in decimal. For lists beginning at value 1 ("1", "a", "A", - "i", or "I"), this attribute may be omitted. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``enumerated_list``. The `%structure.model;`_ parameter entity - indirectly includes ``enumerated_list``. - - -Examples --------- - -reStructuredText_ source:: - - 1. Item 1. - - (A) Item A. - (B) Item B. - (C) Item C. - - 2. Item 2. - -Pseudo-XML_ fragment from simple parsing:: - - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item 1. - <enumerated_list enumtype="upperalpha" prefix="(" suffix=")"> - <list_item> - <paragraph> - Item A. - <list_item> - <paragraph> - Item B. - <list_item> - <paragraph> - Item C. - <list_item> - <paragraph> - Item 2. - -See list_item_ for another example. - - -``error`` -========= - -The ``error`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, hint_, important_, note_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``error``. - -:Children: - ``error`` elements contain one or more `body elements`_. - -:Analogues: - ``error`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Error" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``error`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``error``. The `%structure.model;`_ parameter entity indirectly - includes ``error``. - - -Examples --------- - -reStructuredText source:: - - .. Error:: Does not compute. - -Pseudo-XML_ fragment from simple parsing:: - - <error> - <paragraph> - Does not compute. - - -``field`` -========= - -The ``field`` element contains a pair of field_name_ and field_body_ -elements. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - The following elements may contain ``field``: docinfo_, - field_list_ - -:Children: - Each ``field`` element contains one field_name_ and one - field_body_ element. - -:Analogues: - ``field`` has no direct analogues in common DTDs. - -:Processing: - See field_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (field_name_, field_body_) - -:Attributes: - The ``field`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``field``. - - -Examples --------- - -See the examples for the field_list_ and docinfo_ elements. - - -``field_body`` -============== - -The ``field_body`` element contains body elements. It is analogous to -a database field's data. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the field_ element contains ``field_body``. - -:Children: - ``field_body`` elements may contain `body elements`_. - -:Analogues: - ``field_body`` has no direct analogues in common DTDs. - -:Processing: - See field_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)* - -:Attributes: - The ``field_body`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the field_list_ and docinfo_ elements. - - -``field_list`` -============== - -The ``field_list`` element contains two-column table-like structures -resembling database records (label & data pairs). Field lists are -often meant for further processing. In reStructuredText_, field lists -are used to represent bibliographic fields (contents of the docinfo_ -element) and directive options. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``field_list``. - -:Children: - ``field_list`` elements contain one or more field_ elements. - -:Analogues: - ``field_list`` has no direct analogues in common DTDs. It can be - emulated with primitives such as tables. - -:Processing: - A ``field_list`` is typically rendered as a two-column list, where - the first column contains "labels" (usually with a colon suffix). - However, field lists are often used for extension syntax or - special processing. Such structures do not survive as field lists - to be rendered. - - -Content Model -------------- - -.. parsed-literal:: - - (field_ +) - -:Attributes: - The ``field_list`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``field_list``. The `%structure.model;`_ parameter entity - indirectly includes ``field_list``. - - -Examples --------- - -reStructuredText_ source:: - - :Author: Me - :Version: 1 - :Date: 2001-08-11 - :Parameter i: integer - -Pseudo-XML_ fragment from simple parsing:: - - <field_list> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - integer - - -``field_name`` -============== - -The ``field_name`` element contains text; it is analogous to a -database field's name. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the field_ element contains ``field_name``. - -:Children: - ``field_name`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``field_name`` has no direct analogues in common DTDs. - -:Processing: - See field_list_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``field_name`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the field_list_ and docinfo_ elements. - - -``figure`` -========== - -`To be completed`_. - - -``footer`` -========== - -The ``footer`` element is a container element whose contents are meant -to appear at the bottom of a web page, or repeated at the bottom of -every printed page. The ``footer`` element may contain processing -information (datestamp, a link to Docutils_, etc.) as well as custom -content. - - -Details -------- - -:Category: - `Decorative Elements`_ - -:Parents: - Only the decoration_ element contains ``footer``. - -:Children: - ``footer`` elements may contain `body elements`_. - -:Analogues: - There are no direct analogies to ``footer`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``footer`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - A paragraph. - -Complete pseudo-XML_ result after parsing and applying transforms, -assuming that the datestamp command-line option or configuration -setting has been supplied:: - - <document> - <decoration> - <footer> - <paragraph> - Generated on: 2002-08-20. - <paragraph> - A paragraph. - - -``footnote`` -============ - -`To be completed`_. - - -``footnote_reference`` -====================== - -`To be completed`_. - - -``generated`` -============= - -Docutils wraps ``generated`` elements around text that is inserted -(generated) by Docutils; i.e., text that was not in the document, like -section numbers inserted by the "sectnum" directive. - -`To be completed`_. - - -``header`` -========== - -The ``header`` element is a container element whose contents are meant -to appear at the top of a web page, or at the top of every printed -page. - - -Details -------- - -:Category: - `Decorative Elements`_ - -:Parents: - Only the decoration_ element contains ``header``. - -:Children: - ``header`` elements may contain `body elements`_. - -:Analogues: - There are no direct analogies to ``header`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``header`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText source fragment:: - - .. header:: This space for rent. - -Pseudo-XML_ fragment from simple parsing:: - - <document> - <decoration> - <header> - <paragraph> - This space for rent. - - -``hint`` -======== - -The ``hint`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, important_, note_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``hint``. - -:Children: - ``hint`` elements contain one or more `body elements`_. - -:Analogues: - ``hint`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Hint" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``hint`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``hint``. The `%structure.model;`_ parameter entity indirectly - includes ``hint``. - - -Examples --------- - -reStructuredText source:: - - .. Hint:: It's bigger than a bread box. - -Pseudo-XML_ fragment from simple parsing:: - - <hint> - <paragraph> - It's bigger than a bread box. - - -``image`` -========= - -`To be completed`_. - - -``important`` -============= - -The ``important`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, note_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``important``. - -:Children: - ``important`` elements contain one or more `body elements`_. - -:Analogues: - ``important`` is analogous to the DocBook "important" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Important" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``important`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``important``. The `%structure.model;`_ parameter entity - indirectly includes ``important``. - - -Examples --------- - -reStructuredText source:: - - .. Important:: - - * Wash behind your ears. - * Clean up your room. - * Back up your data. - * Call your mother. - -Pseudo-XML_ fragment from simple parsing:: - - <important> - <bullet_list> - <list_item> - <paragraph> - Wash behind your ears. - <list_item> - <paragraph> - Clean up your room. - <list_item> - <paragraph> - Back up your data. - <list_item> - <paragraph> - Call your mother. - - -``inline`` -========== - -`To be completed`_. - - -``label`` -========= - -`To be completed`_. - - -``legend`` -========== - -`To be completed`_. - - -``line`` -======== - -The ``line`` element contains a single line of text, part of a -`line_block`_. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the `line_block`_ element contains ``line``. - -:Children: - ``line`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``line`` has no direct analogues in common DTDs. It can be - emulated with primitives or type effects. - -:Processing: - See `line_block`_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``line`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus `xml:space`_. - - -Examples --------- - -See `line_block`_. - - -``line_block`` -============== - -The ``line_block`` element contains a sequence of lines and nested -line blocks. Line breaks (implied between elements) and leading -whitespace (indicated by nesting) is significant and must be -preserved. ``line_block`` elements are commonly used for verse and -addresses. See `literal_block`_ for an alternative useful for program -listings and interactive computer sessions. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``line_block``. - -:Children: - ``line_block`` elements may contain line_ elements and nested - ``line_block`` elements. - -:Analogues: - ``line_block`` is analogous to the DocBook "literallayout" element - and to the HTML "pre" element (with modifications to typeface - styles). - -:Processing: - Unline ``literal_block``, ``line_block`` elements are typically - rendered in an ordinary text typeface. It is crucial that leading - whitespace and line breaks are preserved in the rendered form. - - -Content Model -------------- - -.. parsed-literal:: - - (line_ | line_block_)+ - -:Attributes: - The ``line_block`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``line_block``. The `%structure.model;`_ parameter entity - indirectly includes ``line_block``. - - -Examples --------- - -reStructuredText uses a directive to indicate a ``line_block``. -Example source:: - - Take it away, Eric the Orchestra Leader! - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - Take it away, Eric the Orchestra Leader! - <line_block> - <line> - A one, two, a one two three four - <line> - <line> - Half a bee, philosophically, - <line_block> - <line> - must, - <emphasis> - ipso facto - , half not be. - <line> - But half the bee has got to be, - <line_block> - <line> - <emphasis> - vis a vis - its entity. D'you see? - <line> - <line> - But can a bee be said to be - <line_block> - <line> - or not to be an entire bee, - <line_block> - <line> - when half the bee is not a bee, - <line_block> - <line> - due to some ancient injury? - <line> - <line> - Singing... - - -``list_item`` -============= - -The ``list_item`` element is a container for the elements of a list -item. - - -Details -------- - -:Category: - `Body Subelements`_ (compound) - -:Parents: - The bullet_list_ and enumerated_list_ elements contain - ``list_item``. - -:Children: - ``list_item`` elements may contain `body elements`_. - -:Analogues: - ``list_item`` is analogous to the HTML "li" element and to the - DocBook "listitem" element. - -:Processing: - See bullet_list_ or enumerated_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)* - -:Attributes: - The ``list_item`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - 1. Outer list, item 1. - - * Inner list, item 1. - * Inner list, item 2. - - 2. Outer list, item 2. - -Pseudo-XML_ fragment from simple parsing:: - - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Outer list, item 1. - <bullet_list bullet="*"> - <list_item> - <paragraph> - Inner list, item 1. - <list_item> - <paragraph> - Inner list, item 2. - <list_item> - <paragraph> - Outer list, item 2. - -See bullet_list_ or enumerated_list_ for further examples. - - -``literal`` -=========== - -`To be completed`_. - - -``literal_block`` -================= - -The ``literal_block`` element contains a block of text where line -breaks and whitespace are significant and must be preserved. -``literal_block`` elements are commonly used for program listings and -interactive computer sessions. See `line_block`_ for an alternative -useful for verse and addresses. - - -Details -------- - -:Category: - `Simple Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``literal_block``. - -:Children: - ``literal_block`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``literal_block`` is analogous to the HTML "pre" element and to - the DocBook "programlisting" and "screen" elements. - -:Processing: - ``literal_block`` elements are typically rendered in a monospaced - typeface. It is crucial that all whitespace and line breaks are - preserved in the rendered form. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``literal_block`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``literal_block``. The `%structure.model;`_ parameter entity - indirectly includes ``literal_block``. - - -Examples --------- - -reStructuredText source:: - - Here is a literal block:: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - Here is a literal block: - <literal_block xml:space="preserve"> - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - - -``note`` -======== - -The ``note`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, important_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``note``. - -:Children: - ``note`` elements contain one or more `body elements`_. - -:Analogues: - ``note`` is analogous to the DocBook "note" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Note" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``note`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``note``. The `%structure.model;`_ parameter entity indirectly - includes ``note``. - - -Examples --------- - -reStructuredText source:: - - .. Note:: Admonitions can be handy to break up a - long boring technical document. - -Pseudo-XML_ fragment from simple parsing:: - - <note> - <paragraph> - Admonitions can be handy to break up a - long boring technical document. - -``option`` -========== - -The ``option`` element groups an option string together with zero or -more option argument placeholders. Note that reStructuredText_ -currently supports only one argument per option. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_group_ element contains ``option``. - -:Children: - Each ``option`` element contains one option_string_ and zero or - more option_argument_ elements. - -:Analogues: - ``option`` has no direct analogues in common DTDs. - -:Processing: - See option_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (option_string_, option_argument_ \*) - -:Attributes: - The ``option`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_argument`` -=================== - -The ``option_argument`` element contains placeholder text for option -arguments. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_ element contains ``option_argument``. - -:Children: - ``option_argument`` elements contain text data only. - -:Analogues: - ``option_argument`` has no direct analogues in common DTDs. - -:Processing: - The value of the "delimiter" attribute is prefixed to the - ``option_argument``, separating it from its option_string_ or a - preceding ``option_argument``. The ``option_argument`` text is - typically rendered in a monospaced typeface, possibly italicized - or otherwise altered to indicate its placeholder nature. - - -Content Model -------------- - -.. parsed-literal:: - - (#PCDATA) - -:Attributes: - The ``option_argument`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus delimiter_. - - ``delimiter`` contains the text preceding the ``option_argument``: - either the text separating it from the option_string_ (typically - either "=" or " ") or the text between option arguments (typically - either "," or " "). - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_group`` -================ - -The ``option_group`` element groups together one or more option_ -elements, all synonyms. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_list_item_ element contains ``option_group``. - -:Children: - ``option_group`` elements contain one or more option_ elements. - - ``option_group`` is an empty element and has no children. - - Each ``option_group`` element contains one _ and - one _ element. - -:Analogues: - ``option_group`` has no direct analogues in common DTDs. - -:Processing: - Typically option_ elements within an ``option_group`` are joined - together in a comma-separated list. - - -Content Model -------------- - -.. parsed-literal:: - - (option_group_, description_) - -:Attributes: - The ``option_group`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_list`` -=============== - -Each ``option_list`` element contains a two-column list of -command-line options and descriptions, documenting a program's -options. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``option_list``. - -:Children: - ``option_list`` elements contain one or more option_list_item_ - elements. - -:Analogues: - ``option_list`` has no direct analogues in common DTDs. It can be - emulated with primitives such as tables. - -:Processing: - An ``option_list`` is typically rendered as a two-column list, - where the first column contains option strings and arguments, and - the second column contains descriptions. - - -Content Model -------------- - -.. parsed-literal:: - - (option_list_item_ +) - -:Attributes: - The ``option_list`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``option_list``. The `%structure.model;`_ parameter entity - indirectly includes ``option_list``. - - -Examples --------- - -reStructuredText_ source:: - - -a command-line option "a" - -1 file, --one=file, --two file - Multiple options with arguments. - -Pseudo-XML_ fragment from simple parsing:: - - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - command-line option "a" - <option_list_item> - <option_group> - <option> - <option_string> - -1 - <option_argument delimiter=" "> - file - <option> - <option_string> - --one - <option_argument delimiter="="> - file - <option> - <option_string> - --two - <option_argument delimiter=" "> - file - <description> - <paragraph> - Multiple options with arguments. - - -``option_list_item`` -==================== - -The ``option_list_item`` element is a container for a pair of -option_group_ and description_ elements. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_list_ element contains ``option_list_item``. - -:Children: - Each ``option_list_item`` element contains one option_group_ and - one description_ element. - -:Analogues: - ``option_list_item`` has no direct analogues in common DTDs. - -:Processing: - See option_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (option_group_, description_) - -:Attributes: - The ``option_list_item`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_string`` -================= - -The ``option_string`` element contains the text of a command-line -option. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_ element contains ``option_string``. - -:Children: - ``option_string`` elements contain text data only. - -:Analogues: - ``option_string`` has no direct analogues in common DTDs. - -:Processing: - The ``option_string`` text is typically rendered in a monospaced - typeface. - - -Content Model -------------- - -.. parsed-literal:: - - (#PCDATA) - -:Attributes: - The ``option_string`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``organization`` -================ - -The ``organization`` element contains the name of document author's -organization, or the organization responsible for the document. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``organization``. - -:Children: - ``organization`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``organization`` is analogous to the DocBook "orgname", - "corpname", or "publishername" elements. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``organization`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``organization``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Organization: Humankind - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <organization> - Humankind - -See docinfo_ for a more complete example, including processing -context. - - -``paragraph`` -============= - -The ``paragraph`` element contains the text and inline elements of a -single paragraph, a fundamental building block of documents. - - -Details -------- - -:Category: - `Simple Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``paragraph``. - -:Children: - ``paragraph`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``paragraph`` is analogous to the HTML "p" element and to the - DocBook "para" elements. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``paragraph`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``paragraph``. The `%structure.model;`_ parameter entity - indirectly includes ``paragraph``. - - -Examples --------- - -reStructuredText_ source:: - - A paragraph. - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - A paragraph. - - -``pending`` -=========== - -`To be completed`_. - - -``problematic`` -=============== - -`To be completed`_. - - -``raw`` -======= - -`To be completed`_. - - -``reference`` -============= - -`To be completed`_. - - -``revision`` -============ - -The ``revision`` element contains the revision number of the document. -It can be used alone or in conjunction with version_. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``revision``. - -:Children: - ``revision`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``revision`` is analogous to but simpler than the DocBook - "revision" element. It closely matches the DocBook "revnumber" - element, but in a simpler context. - -:Processing: - Often used with the RCS/CVS keyword "Revision". See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``revision`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``revision``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Version: 1 - :Revision: b - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <version> - 1 - <revision> - b - -See docinfo_ for a more complete example, including processing -context. - - -``row`` -======= - -`To be completed`_. - - -``rubric`` -========== - - rubric n. 1. a title, heading, or the like, in a manuscript, - book, statute, etc., written or printed in red or otherwise - distinguished from the rest of the text. ... - - -- Random House Webster's College Dictionary, 1991 - -A rubric is like an informal heading that doesn't correspond to the -document's structure. - -`To be completed`_. - - -``section`` -=========== - -The ``section`` element is the main unit of hierarchy for Docutils -documents. Docutils ``section`` elements are a recursive structure; a -``section`` may contain other ``section`` elements, without limit. -Paragraphs and other body elements may occur before a ``section``, but -not after it. - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The following elements may contain ``section``: document_, - section_ - -:Children: - ``section`` elements begin with a title_, and may contain `body - elements`_ as well as transition_, topic_, and sidebar_ elements. - -:Analogues: - ``section`` is analogous to DocBook recursive "section" elements, - and to HTML "div" elements combined with "h1" etc. title elements. - - -Content Model -------------- - -.. parsed-literal:: - - (title_, - `%structure.model;`_) - -See the `%structure.model;`_ parameter entity for details of the body -of a ``section``. - -:Attributes: - The ``section`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%section.elements;`_ parameter entity directly includes - ``section``. The `%structure.model;`_ parameter entity indirectly - includes ``section``. - - -Examples --------- - -reStructuredText_ source:: - - Title 1 - ======= - Paragraph 1. - - Title 2 - ------- - Paragraph 2. - - Title 3 - ======= - Paragraph 3. - - Title 4 - ------- - Paragraph 4. - -Complete pseudo-XML_ result after parsing:: - - <document> - <section ids="title-1" names="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title 4"> - <title> - Title 4 - <paragraph> - Paragraph 4. - - -``sidebar`` -=========== - -Sidebars are like miniature, parallel documents that occur inside -other documents, providing related or reference material. A -``sidebar`` is typically offset by a border and "floats" to the side -of the page; the document's main text may flow around it. Sidebars -can also be likened to super-footnotes; their content is outside of -the flow of the document's main text. - -The ``sidebar`` element is a nonrecursive section_-like construct -which may occur at the top level of a section_ wherever a body element -(list, table, etc.) is allowed. In other words, ``sidebar`` elements -cannot nest inside body elements, so you can't have a ``sidebar`` -inside a ``table`` or a ``list``, or inside another ``sidebar`` (or -topic_). - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The following elements may contain ``sidebar``: document_, - section_ - -:Children: - ``sidebar`` elements begin with a title_ and an optional subtitle_ - and contain `body elements`_ and topic_ elements. - -:Analogues: - ``sidebar`` is analogous to the DocBook "sidebar" element. - -:Processing: - A ``sidebar`` element should be set off from the rest of the - document somehow, typically with a border. Sidebars typically - "float" to the side of the page and the document's main text flows - around them. - - -Content Model -------------- - -.. parsed-literal:: - - (title_, subtitle_?, - (`%body.elements;`_ | topic_)+) - -:Attributes: - The ``sidebar`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%structure.model;`_ parameter entity directly includes - ``sidebar``. - - -Examples --------- - -The `"sidebar" directive`_ is used to create a ``sidebar`` element. -reStructuredText_ source:: - - .. sidebar:: Title - :subtitle: If Desired - - Body. - -Pseudo-XML_ fragment from simple parsing:: - - <sidebar> - <title> - Title - <subtitle> - If Desired - <paragraph> - Body. - -.. _"sidebar" directive: rst/directives.html#sidebar - - -``status`` -========== - -The ``status`` element contains a status statement for the document, -such as "Draft", "Final", "Work In Progress", etc. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``status``. - -:Children: - ``status`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``status`` is analogous to the DocBook "status" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``status`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``status``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Status: Work In Progress - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <status> - Work In Progress - -See docinfo_ for a more complete example, including processing -context. - - -``strong`` -========== - -`To be completed`_. - - -``subscript`` -============= - -`To be completed`_. - - -``substitution_definition`` -=========================== - -`To be completed`_. - - -``substitution_reference`` -========================== - -`To be completed`_. - - -``subtitle`` -============ - -The ``subtitle`` element stores the subtitle of a document_. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - The document_ and sidebar_ elements may contain ``subtitle``. - -:Children: - ``subtitle`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``subtitle`` is analogous to HTML header elements ("h2" etc.) and - to the DocBook "subtitle" element. - -:Processing: - A document's subtitle is usually rendered smaller than its title_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``subtitle`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - ======= - Title - ======= - ---------- - Subtitle - ---------- - - A paragraph. - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="title" names="title"> - <title> - Title - <subtitle ids="subtitle" names="subtitle"> - Subtitle - <paragraph> - A paragraph. - -Note how two section levels have collapsed, promoting their titles to -become the document's title and subtitle. Since there is only one -structural element (document), the subsection's ``ids`` and ``names`` -attributes are stored in the ``subtitle`` element. - - -``superscript`` -=============== - -`To be completed`_. - - -``system_message`` -================== - -`To be completed`_. - - -``table`` -========= - -`To be completed`_. - - -``target`` -========== - -`To be completed`_. - - -``tbody`` -========= - -`To be completed`_. - - -``term`` -======== - -The ``term`` element contains a word or phrase being defined in a -definition_list_. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the definition_list_item_ element contains ``term``. - -:Children: - ``term`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``term`` is analogous to the HTML "dt" element and to the DocBook - "term" element. - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``term`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the definition_list_, definition_list_item_, and -classifier_ elements. - - -``tgroup`` -========== - -`To be completed`_. - - -``thead`` -========= - -`To be completed`_. - - -``tip`` -======= - -The ``tip`` element is an admonition, a distinctive and self-contained -notice. Also see the other admonition elements Docutils offers (in -alphabetical order): attention_, caution_, danger_, error_, hint_, -important_, note_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``tip``. - -:Children: - ``tip`` elements contain one or more `body elements`_. - -:Analogues: - ``tip`` is analogous to the DocBook "tip" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Tip" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``tip`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes ``tip``. - The `%structure.model;`_ parameter entity indirectly includes - ``tip``. - - -Examples --------- - -reStructuredText source:: - - .. Tip:: 15% if the service is good. - -Pseudo-XML_ fragment from simple parsing:: - - <tip> - <paragraph> - 15% if the service is good. - - -.. _title: - -``title`` -========= - -The ``title`` element stores the title of a document_, section_, -topic_, sidebar_, or generic admonition_. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - The following elements may contain ``title``: document_, section_, - topic_, sidebar_, admonition_ - -:Children: - ``title`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``title`` is analogous to HTML "title" and header ("h1" etc.) - elements, and to the DocBook "title" element. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``title`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus refid_ and auto_. - - ``refid`` is used as a backlink to a table of contents entry. - - ``auto`` is used to indicate (with value "1") that the ``title`` - has been numbered automatically. - - -Examples --------- - -reStructuredText_ source:: - - A Title - ======= - - A paragraph. - -Pseudo-XML_ fragment from simple parsing:: - - <section ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - - -``title_reference`` -=================== - -`To be completed`_. - - -``topic`` -========= - -The ``topic`` element is a nonrecursive section_-like construct which -may occur at the top level of a section_ wherever a body element -(list, table, etc.) is allowed. In other words, ``topic`` elements -cannot nest inside body elements, so you can't have a ``topic`` inside -a ``table`` or a ``list``, or inside another ``topic``. - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The following elements may contain ``topic``: document_, section_, - sidebar_ - -:Children: - ``topic`` elements begin with a title_ and may contain `body - elements`_. - -:Analogues: - ``topic`` is analogous to the DocBook "simplesect" element. - -:Processing: - A ``topic`` element should be set off from the rest of the - document somehow, such as with indentation or a border. - - -Content Model -------------- - -.. parsed-literal:: - - (title_?, - (`%body.elements;`_)+) - -:Attributes: - The ``topic`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%structure.model;`_ parameter entity directly includes - ``topic``. - - -Examples --------- - -The `"topic" directive`_ is used to create a ``topic`` element. -reStructuredText_ source:: - - .. topic:: Title - - Body. - -Pseudo-XML_ fragment from simple parsing:: - - <topic> - <title> - Title - <paragraph> - Body. - -.. _"topic" directive: rst/directives.html#topic - - -``transition`` -============== - -The ``transition`` element is commonly seen in novels and short -fiction, as a gap spanning one or more lines, with or without a type -ornament such as a row of asterisks. Transitions separate body -elements and sections, dividing a section into untitled divisions. A -transition may not begin or end a section [#]_ or document, nor may -two transitions be immediately adjacent. - -See `Doctree Representation of Transitions`__ in `A Record of -reStructuredText Syntax Alternatives`__. - -.. [#] In reStructuredText markup, a transition may appear to fall at - the end of a section immediately before another section. A - transform recognizes this case and moves the transition so it - separates the sections. - -__ ../dev/rst/alternatives.html#doctree-representation-of-transitions -__ ../dev/rst/alternatives.html - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - The following elements may contain ``transition``: document_, - section_ - -:Children: - ``transition`` is an empty element and has no children. - -:Analogues: - ``transition`` is analogous to the HTML "hr" element. - -:Processing: - The ``transition`` element is typically rendered as vertical - whitespace (more than that separating paragraphs), with or without - a horizontal line or row of asterisks. In novels, transitions are - often represented as a row of three well-spaced asterisks with - vertical space above and below. - - -Content Model -------------- - -:: - - EMPTY - -The ``transition`` element has no content; it is a "point element". - -:Attributes: - The ``transition`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%structure.model;`_ parameter entity directly includes - ``transition``. - - -Examples --------- - -reStructuredText_ source:: - - Paragraph 1. - - -------- - - Paragraph 2. - -Complete pseudo-XML_ result after parsing:: - - <document> - <paragraph> - Paragraph 1. - <transition> - <paragraph> - Paragraph 2. - - -``version`` -=========== - -The ``version`` element contains the version number of the document. -It can be used alone or in conjunction with revision_. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``version``. - -:Children: - ``version`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``version`` may be considered analogous to the DocBook "revision", - "revnumber", or "biblioid" elements. - -:Processing: - Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ - and revision_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``version`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``version``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Version: 1.1 - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <version> - 1.1 - -See docinfo_ for a more complete example, including processing -context. - - -``warning`` -=========== - -The ``warning`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, important_, note_, tip_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``warning``. - -:Children: - ``warning`` elements contain one or more `body elements`_. - -:Analogues: - ``warning`` is analogous to the DocBook "warning" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Warning" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``warning`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``warning``. The `%structure.model;`_ parameter entity indirectly - includes ``warning``. - - -Examples --------- - -reStructuredText source:: - - .. WARNING:: Reader discretion is strongly advised. - -Pseudo-XML_ fragment from simple parsing:: - - <warning> - <paragraph> - Reader discretion is strongly advised. - - ---------------------- - Attribute Reference ---------------------- - -.. contents:: :local: - :depth: 1 - -_`Common Attributes`: Through the `%basic.atts;`_ parameter entity, -all elements contain the following attributes: ids_, names_, dupnames_, -source_, and classes_. - -.. _attribute type: - -Attribute types: - -``CDATA`` - Character data. ``CDATA`` attributes may contain arbitrary text. - -``ID`` - Like a ``NMTOKEN``, but it must begin with a letter (a "name - production"). Identical ``ID`` values must not appear more than - once in a document; i.e., ID values must uniquely identify their - elements. - -``IDREF`` - A reference to an ``ID`` value (a name production) of another - element. - -``IDREFS`` - One or more space-separated ``ID`` references (name productions). - -``NMTOKEN`` - A "name token". One or more of letters, digits, ".", "-", and - "_". - -``NMTOKENS`` - One or more space-separated ``NMTOKEN`` names. - -``%yesorno;`` - No if zero ("0"), yes if any other value. This is a parameter - entity which resolves to a ``NMTOKEN`` attribute type. - -``%number;`` - This emphasizes that the attribute value must be a number. This - is a parameter entity which resolves to a ``NMTOKEN`` attribute - type. - -enumeration - The attribute value may be one of a specified list of values. - - -``anonymous`` -============= - -`Attribute type`_: ``%yesorno;``. Default value: none (implies no). - -The ``anonymous`` attribute is used for unnamed hyperlinks in the -target_ and reference_ elements (via the `%anonymous.att;`_ parameter -entity). - - -``auto`` -======== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``auto`` attribute is used to indicate automatically-numbered -footnote_, footnote_reference_ and title_ elements (via the -`%auto.att;`_ parameter entity). - - -``backrefs`` -============ - -`Attribute type`_: ``IDREFS``. Default value: none. - -The ``backrefs`` attribute contains a space-separated list of ids_ -references, used for backlinks from footnote_, citation_, and -system_message_ elements (via the `%backrefs.att;`_ parameter entity). - - -``bullet`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``bullet`` attribute is used in the bullet_list_ element. - - -``classes`` -=========== - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``classes`` attribute is a list containing one or more names used -to classify an element. The purpose of the attribute is to indicate -an "is-a" variant relationship, to allow an extensible way of defining -sub-classes of existing elements. It can be used to carry context -forward between a Docutils Reader and Writer, when a custom structure -is reduced to a standardized document tree. One common use is in -conjunction with stylesheets, to add selection criteria. It should -not be used to carry formatting instructions or arbitrary content. - -The ``classes`` attribute's contents should be ignorable. Writers that -are not familiar with the variant expressed should be able to ignore -the attribute. - -``classes`` is one of the `common attributes`_, shared by all Docutils -elements. - - -``delimiter`` -============= - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``delimiter`` attribute is used in the option_argument_ element. - - -``dupnames`` -============ - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``dupnames`` attribute is a list containing the names of an -element when there has been a naming conflict. The contents of the -``dupnames`` attribute would have been transferred from the `names`_ -attribute. An element may have at most one of the ``names`` or -``dupnames`` attributes, but not both. ``dupnames`` is one of the -`common attributes`_, shared by all Docutils elements. - - -``enumtype`` -============ - -`Attribute type`_: enumeration, one of "arabic", "loweralpha", -"upperalpha", "lowerroman", or "upperroman". Default value: none. - -The ``enumtype`` attribute is used in the enumerated_list_ element. - - -``ids`` -======= - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``ids`` attribute is a list containing one or more unique -identifier keys. ``ids`` is one of the `common attributes`_, shared -by all Docutils elements. - - -``names`` -========= - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``names`` attribute is a list containing the names of an element, -typically originating from the element's title or content. Each name -in ``names`` must be unique; if there are name conflicts (two or more -elements want to the same name), the contents will be transferred to -the `dupnames`_ attribute on the duplicate elements. An element may -have at most one of the ``names`` or ``dupnames`` attributes, but not -both. ``names`` is one of the `common attributes`_, shared by all -Docutils elements. - - -``prefix`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``prefix`` attribute is used in the enumerated_list_ element. - - -``refid`` -========= - -`Attribute type`_: ``IDREF``. Default value: none. - -The ``refid`` attribute contains references to `ids`_ attributes in -other elements. It is used by the target_, reference_, -footnote_reference_, citation_reference_, title_ and problematic_ -elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter -entities). - - -``refname`` -=========== - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``refname`` attribute contains an internal reference to the -`names`_ attribute of another element. On a `target`_ element, -``refname`` indicates an indirect target which may resolve to either -an internal or external reference. ``refname`` is used by the -target_, reference_, footnote_reference_, citation_reference_, and -substitution_reference_ elements (via the `%refname.att;`_ and -`%reference.atts;`_ parameter entities). - - -``refuri`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``refuri`` attribute contains an external reference to a URI/URL. -It is used by the target_, reference_, footnote_reference_, and -citation_reference_ elements (via the `%reference.atts;`_ parameter -entity). - - -``source`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``source`` attribute is used to store the path or URL to the -source text that was used to produce the document tree. It is one of -the `common attributes`_, shared by all Docutils elements. - - -``start`` -========= - -`Attribute type`_: ``%number;``. Default value: none. - -The ``start`` attribute is used in the enumerated_list_ element. - - -``suffix`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``suffix`` attribute is used in the enumerated_list_ element. - - -``xml:space`` -============= - -`Attribute type`_: one of "default" or "preserve". Default value: -"preserve" (fixed). - -The ``xml:space`` attribute is a standard XML attribute for -whitespace-preserving elements. It is used by the literal_block_, -line_block_, doctest_block_, comment_, and raw_ elements (via the -`%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant -to communicate to an XML parser that the element contains significant -whitespace. The attribute value should not be set in a document -instance. - - -.. _title (attribute): - -``title`` -========= - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``title`` attribute stores the title metadata of a document. This -title is typically not part of the rendered document. It may for -example be used in HTML's ``title`` element. - - ----------------------------- - Parameter Entity Reference ----------------------------- - -.. contents:: :local: - :depth: 1 - -Parameter entities are used to simplify the DTD (to share definitions -and reduce duplication) and to allow the DTD to be customized by -wrapper DTDs (external client DTDs that use or import the Docutils -DTD). Parameter entities may be overridden by wrapper DTDs, replacing -the definitions below with custom definitions. Parameter entities -whose names begin with "additional" are meant to allow easy extension -by wrapper DTDs. - - -``%anonymous.att;`` -=================== - -The ``%anonymous.att;`` parameter entity contains the anonymous_ -attribute, used for unnamed hyperlinks. - -Entity definition: - -.. parsed-literal:: - - anonymous_ %yesorno; #IMPLIED - -The reference_ and target_ elements directly employ the -``%anonymous.att;`` parameter entity in their attribute lists. - - -``%auto.att;`` -============== - -The ``%auto.att;`` parameter entity contains the auto_ attribute, used -to indicate an automatically-numbered footnote or title. - -Entity definition: - -.. parsed-literal:: - - auto_ CDATA #IMPLIED - -The footnote_, footnote_reference_, and title_ elements directly -employ the ``%auto.att;`` parameter entity in their attribute lists. - - -``%backrefs.att;`` -================== - -The ``%backrefs.att;`` parameter entity contains the backrefs_ -attribute, a space-separated list of id references, for backlinks. - -Entity definition: - -.. parsed-literal:: - - backrefs_ IDREFS #IMPLIED - -The citation_, footnote_, and system_message_ elements directly employ -the ``%backrefs.att;`` parameter entity in their attribute lists. - - -``%basic.atts;`` -================ - -The ``%basic.atts;`` parameter entity lists attributes common to all -Docutils elements. See `Common Attributes`_. - -Entity definition: - -.. parsed-literal:: - - ids_ NMTOKENS #IMPLIED - names_ CDATA #IMPLIED - dupnames_ CDATA #IMPLIED - source_ CDATA #IMPLIED - classes_ NMTOKENS #IMPLIED - %additional.basic.atts; - -The ``%additional.basic.atts;`` parameter entity can be used by -wrapper DTDs to extend ``%basic.atts;``. - - -``%bibliographic.elements;`` -============================ - -The ``%bibliographic.elements;`` parameter entity contains an OR-list of all -`bibliographic elements`_. - -Entity definition: - -.. parsed-literal:: - - author_ | authors_ | organization_ | contact_ | address_ - | version_ | revision_ | status_ | date_ | copyright_ - | field_ - %additional.bibliographic.elements; - -The ``%additional.bibliographic.elements;`` parameter entity can be used by -wrapper DTDs to extend ``%bibliographic.elements;``. - -Only the docinfo_ element directly employs the -``%bibliographic.elements;`` parameter entity in its content model. - - -``%body.elements;`` -=================== - -The ``%body.elements;`` parameter entity contains an OR-list of all -`body elements`_. ``%body.elements;`` is itself contained within the -`%structure.model;`_ parameter entity. - -Entity definition: - -.. parsed-literal:: - - paragraph_ | compound_ | container_ | literal_block_ | doctest_block_ - | line_block_ | block_quote_ - | table_ | figure_ | image_ | footnote_ | citation_ | rubric_ - | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ - | option_list_ - | attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_ - | tip_ | warning_ | admonition_ - | reference_ | target_ | substitution_definition_ | comment_ | pending_ - | system_message_ | raw_ - %additional.body.elements; - -The ``%additional.body.elements;`` parameter entity can be used by -wrapper DTDs to extend ``%body.elements;``. - -The ``%body.elements;`` parameter entity is directly employed in the -content models of the following elements: admonition_, attention_, -block_quote_, caution_, citation_, compound_, danger_, definition_, -description_, entry_, error_, field_body_, footer_, footnote_, -header_, hint_, important_, legend_, list_item_, note_, sidebar_, -system_message_, tip_, topic_, warning_ - -Via `%structure.model;`_, the ``%body.elements;`` parameter entity is -indirectly employed in the content models of the document_ and -section_ elements. - - -``%fixedspace.att;`` -==================== - -The ``%fixedspace.att;`` parameter entity contains the `xml:space`_ -attribute, a standard XML attribute for whitespace-preserving -elements. - -Entity definition: - -.. parsed-literal:: - - `xml:space`_ (default | preserve) #FIXED 'preserve' - -The ``%fixedspace.att;`` parameter entity is directly employed in the -attribute lists of the following elements: address_, comment_, -doctest_block_, line_block_, literal_block_, raw_ - - -``%inline.elements;`` -===================== - -The ``%inline.elements;`` parameter entity contains an OR-list of all -`inline elements`_. - -Entity definition: - -.. parsed-literal:: - - emphasis_ | strong_ | literal_ - | reference_ | footnote_reference_ | citation_reference_ - | substitution_reference_ | title_reference_ - | abbreviation_ | acronym_ | subscript_ | superscript_ - | inline_ | problematic_ | generated_ - | target_ | image_ | raw_ - %additional.inline.elements; - -The ``%additional.inline.elements;`` parameter entity can be used by -wrapper DTDs to extend ``%inline.elements;``. - -Via `%text.model;`_, the ``%inline.elements;`` parameter entity is -indirectly employed in the content models of the following elements: -abbreviation_, acronym_, address_, attribution_, author_, caption_, -classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, -generated_, inline_, line_block_, literal_block_, organization_, -paragraph_, problematic_, raw_, reference_, revision_, rubric_, -status_, strong_, subscript_, substitution_definition_, -substitution_reference_, subtitle_, superscript_, target_, term_, -title_, title_reference_, version_ - - -``%reference.atts;`` -==================== - -The ``%reference.atts;`` parameter entity groups together the refuri_, -refid_, and refname_ attributes. - -Entity definition: - -.. parsed-literal:: - - `%refuri.att;`_ - `%refid.att;`_ - `%refname.att;`_ - %additional.reference.atts; - -The ``%additional.reference.atts;`` parameter entity can be used by -wrapper DTDs to extend ``%additional.reference.atts;``. - -The citation_reference_, footnote_reference_, reference_, and target_ -elements directly employ the ``%reference.att;`` parameter entity in -their attribute lists. - - -``%refid.att;`` -================ - -The ``%refid.att;`` parameter entity contains the refid_ attribute, an -internal reference to the `ids`_ attribute of another element. - -Entity definition: - -.. parsed-literal:: - - refid_ CDATA #IMPLIED - -The title_ and problematic_ elements directly employ the -``%refid.att;`` parameter entity in their attribute lists. - -Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is -indirectly employed in the attribute lists of the citation_reference_, -footnote_reference_, reference_, and target_ elements. - - -``%refname.att;`` -================= - -The ``%refname.att;`` parameter entity contains the refname_ -attribute, an internal reference to the `names`_ attribute of another -element. On a `target`_ element, ``refname`` indicates an indirect -target which may resolve to either an internal or external -reference. - -Entity definition: - -.. parsed-literal:: - - refname_ NMTOKENS #IMPLIED - -The substitution_reference_ element directly employs the -``%refname.att;`` parameter entity in its attribute list. - -Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is -indirectly employed in the attribute lists of the citation_reference_, -footnote_reference_, reference_, and target_ elements. - - -``%refuri.att;`` -================ - -The ``%refuri.att;`` parameter entity contains the refuri_ attribute, -an external reference to a URI/URL. - -Entity definition: - -.. parsed-literal:: - - refuri_ CDATA #IMPLIED - -Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is -indirectly employed in the attribute lists of the citation_reference_, -footnote_reference_, reference_, and target_ elements. - - -``%section.elements;`` -====================== - -The ``%section.elements;`` parameter entity contains an OR-list of all -section_-equivalent elements. ``%section.elements;`` is itself -contained within the `%structure.model;`_ parameter entity. - -Entity definition: - -.. parsed-literal:: - - section_ - %additional.section.elements; - -The ``%additional.section.elements;`` parameter entity can be used -by wrapper DTDs to extend ``%section.elements;``. - -Via `%structure.model;`_, the ``%section.elements;`` parameter entity -is indirectly employed in the content models of the document_ and -section_ elements. - - -``%structure.model;`` -===================== - -The ``%structure.model;`` parameter entity encapsulates the -hierarchical structure of a document and of its constituent parts. -See the discussion of the `element hierarchy`_ above. - -Entity definition: - -.. parsed-literal:: - - ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*, - ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) - -Each document_ or section_ contains zero or more body elements, -topics, and/or sidebars, optionally interspersed with single -transitions, followed by zero or more sections (whose contents are -recursively the same as this model) optionally interspersed with -transitions. - -The following restrictions are imposed by this model: - -* Transitions must be separated by other elements (body elements, - sections, etc.). In other words, a transition may not be - immediately adjacent to another transition. - -* A transition may not occur at the beginning of a document or - section. - -An additional restriction, which cannot be expressed in the language -of DTDs, is imposed by software: - -* A transition may not occur at the end of a document or section. - -The `%structure.model;`_ parameter entity is directly employed in the -content models of the document_ and section_ elements. - - -``%text.model;`` -================ - -The ``%text.model;`` parameter entity is used by many elements to -represent text data mixed with `inline elements`_. - -Entity definition: - -.. parsed-literal:: - - (#PCDATA | `%inline.elements;`_)* - -The ``%text.model;`` parameter entity is directly employed in the -content models of the following elements: abbreviation_, acronym_, -address_, author_, caption_, classifier_, contact_, copyright_, date_, -doctest_block_, emphasis_, field_name_, generated_, line_block_, -literal_block_, organization_, paragraph_, problematic_, raw_, -reference_, revision_, status_, strong_, substitution_definition_, -substitution_reference_, subtitle_, target_, term_, title_, version_ - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/docutils.dtd b/docutils/docs/ref/docutils.dtd deleted file mode 100644 index 154566033..000000000 --- a/docutils/docs/ref/docutils.dtd +++ /dev/null @@ -1,606 +0,0 @@ -<!-- -====================================================================== - Docutils Generic DTD -====================================================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This DTD has been placed in the public domain. -:Filename: docutils.dtd - -More information about this DTD (document type definition) and the -Docutils project can be found at http://docutils.sourceforge.net/. -The latest version of this DTD is available from -http://docutils.sourceforge.net/docs/ref/docutils.dtd. - -The formal public identifier for this DTD is:: - - +//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML ---> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Parameter Entities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Parameter entities are used to simplify the DTD (reduce duplication) -and to allow the DTD to be customized by wrapper DTDs. Parameter -entities beginning with "additional" are meant to allow easy extension -by wrapper DTDs. ---> - -<!-- Attributes -================================================================== --> - -<!-- Boolean: no if zero(s), yes if any other value. --> -<!ENTITY % yesorno "NMTOKEN"> - -<!-- Emphasize that the attribute value must be a number. --> -<!ENTITY % number "NMTOKEN"> - -<!-- A number which may be immediately followed by a unit. --> -<!ENTITY % measure "NMTOKEN"> - -<!ENTITY % additional.basic.atts ""> -<!-- -Attributes shared by all elements in this DTD: - -- `id` is a unique identifier, typically assigned by the system. -- `name` is an identifier assigned in the markup. -- `dupname` is the same as `name`, used when it's a duplicate. -- `source` is the name of the source of this document or fragment. -- `class` is used to transmit individuality information forward. ---> -<!ENTITY % basic.atts - " ids NMTOKENS #IMPLIED - names CDATA #IMPLIED - dupnames CDATA #IMPLIED - source CDATA #IMPLIED - classes NMTOKENS #IMPLIED - %additional.basic.atts; "> - -<!-- External reference to a URI/URL. --> -<!ENTITY % refuri.att - " refuri CDATA #IMPLIED "> - -<!-- Internal reference to the `id` attribute of an element. --> -<!ENTITY % refid.att - " refid IDREF #IMPLIED "> - -<!-- Space-separated list of id references, for backlinks. --> -<!ENTITY % backrefs.att - " backrefs IDREFS #IMPLIED "> - -<!-- -Internal reference to the `name` attribute of an element. On a -'target' element, 'refname' indicates an indirect target which may -resolve to either an internal or external reference. ---> -<!ENTITY % refname.att - " refname NMTOKENS #IMPLIED "> - -<!ENTITY % additional.reference.atts ""> -<!-- Collected hyperlink reference attributes. --> -<!ENTITY % reference.atts - " %refuri.att; - %refid.att; - %refname.att; - %additional.reference.atts; "> - -<!-- Unnamed hyperlink. --> -<!ENTITY % anonymous.att - " anonymous %yesorno; #IMPLIED "> - -<!-- Auto-numbered footnote or title. --> -<!ENTITY % auto.att - " auto CDATA #IMPLIED "> - -<!-- XML standard attribute for whitespace-preserving elements. --> -<!ENTITY % fixedspace.att - " xml:space (default | preserve) #FIXED 'preserve' "> - -<!ENTITY % align-h.att - " align (left | center | right) #IMPLIED "> - -<!ENTITY % align-hv.att - " align (top | middle | bottom | left | center | right) #IMPLIED "> - - -<!-- Element OR-Lists -============================================================= --> - -<!ENTITY % additional.bibliographic.elements ""> -<!ENTITY % bibliographic.elements - " author | authors | organization | address | contact - | version | revision | status | date | copyright - | field - %additional.bibliographic.elements; "> - -<!ENTITY % additional.section.elements ""> -<!ENTITY % section.elements - " section - %additional.section.elements; "> - -<!ENTITY % additional.body.elements ""> -<!ENTITY % body.elements - " paragraph | compound | container | literal_block | doctest_block - | line_block | block_quote - | table | figure | image | footnote | citation | rubric - | bullet_list | enumerated_list | definition_list | field_list - | option_list - | attention | caution | danger | error | hint | important | note - | tip | warning | admonition - | reference | target | substitution_definition | comment | pending - | system_message | raw - %additional.body.elements; "> - -<!ENTITY % additional.inline.elements ""> -<!ENTITY % inline.elements - " emphasis | strong | literal - | reference | footnote_reference | citation_reference - | substitution_reference | title_reference - | abbreviation | acronym | subscript | superscript - | inline | problematic | generated - | target | image | raw - %additional.inline.elements; "> - - -<!-- Element Content Models -================================================================== --> - -<!-- The structure model may not end with a transition. --> -<!ENTITY % structure.model - " ( ( (%body.elements; | topic | sidebar)+, transition? )*, - ( (%section.elements;), (transition?, (%section.elements;) )* )? )"> - -<!ENTITY % text.model - " (#PCDATA | %inline.elements;)* "> - - -<!-- Table Model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This DTD uses the Exchange subset of the CALS-table model (OASIS -Technical Memorandum 9901:1999 "XML Exchange Table Model DTD", -http://www.oasis-open.org/html/tm9901.htm). ---> - -<!ENTITY % calstblx PUBLIC - "-//OASIS//DTD XML Exchange Table Model 19990315//EN" - "soextblx.dtd"> - -<!-- These parameter entities customize the table model DTD. --> -<!ENTITY % bodyatt " %basic.atts; "> <!-- table elt --> -<!ENTITY % tbl.tgroup.att " %basic.atts; "> -<!ENTITY % tbl.thead.att " %basic.atts; "> -<!ENTITY % tbl.tbody.att " %basic.atts; "> -<!ENTITY % tbl.colspec.att - " %basic.atts; - stub %yesorno; #IMPLIED "> -<!ENTITY % tbl.row.att " %basic.atts; "> -<!ENTITY % tbl.entry.mdl " (%body.elements;)* "> -<!ENTITY % tbl.entry.att - " %basic.atts; - morecols %number; #IMPLIED "> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Root Element -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!-- Optional elements may be generated by internal processing. --> -<!ELEMENT document - ( (title, subtitle?)?, - decoration?, - (docinfo, transition?)?, - %structure.model; )> -<!ATTLIST document - %basic.atts; - title CDATA #IMPLIED> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Title Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT title %text.model;> -<!ATTLIST title - %basic.atts; - %refid.att; - %auto.att;> - -<!ELEMENT subtitle %text.model;> -<!ATTLIST subtitle %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Bibliographic Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!-- Container for bibliographic elements. May not be empty. --> -<!ELEMENT docinfo (%bibliographic.elements;)+> -<!ATTLIST docinfo %basic.atts;> - -<!-- Container for bibliographic elements. May not be empty. -Eventual replacement for docinfo? --> -<!ELEMENT info (%bibliographic.elements;)+> -<!ATTLIST info %basic.atts;> - -<!ELEMENT author %text.model;> -<!ATTLIST author %basic.atts;> - -<!ELEMENT authors (author, organization?, address?, contact?)+> -<!ATTLIST authors %basic.atts;> - -<!ELEMENT organization %text.model;> -<!ATTLIST organization %basic.atts;> - -<!ELEMENT address %text.model;> -<!ATTLIST address - %basic.atts; - %fixedspace.att;> - -<!ELEMENT contact %text.model;> -<!ATTLIST contact %basic.atts;> - -<!ELEMENT version %text.model;> -<!ATTLIST version %basic.atts;> - -<!ELEMENT revision %text.model;> -<!ATTLIST revision %basic.atts;> - -<!ELEMENT status %text.model;> -<!ATTLIST status %basic.atts;> - -<!ELEMENT date %text.model;> -<!ATTLIST date %basic.atts;> - -<!ELEMENT copyright %text.model;> -<!ATTLIST copyright %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Decoration Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT decoration (header?, footer?)> -<!ATTLIST decoration %basic.atts;> - -<!ELEMENT header (%body.elements;)+> -<!ATTLIST header %basic.atts;> - -<!ELEMENT footer (%body.elements;)+> -<!ATTLIST footer %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Structural Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT section - (title, subtitle?, info?, decoration?, %structure.model;)> -<!ATTLIST section %basic.atts;> - -<!ELEMENT topic (title?, (%body.elements;)+)> -<!ATTLIST topic %basic.atts;> - -<!ELEMENT sidebar (title, subtitle?, (%body.elements; | topic)+)> -<!ATTLIST sidebar %basic.atts;> - -<!ELEMENT transition EMPTY> -<!ATTLIST transition %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Body Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT paragraph %text.model;> -<!ATTLIST paragraph %basic.atts;> - -<!ELEMENT compound (%body.elements;)+> -<!ATTLIST compound %basic.atts;> - -<!ELEMENT container (%body.elements;)+> -<!ATTLIST container %basic.atts;> - -<!ELEMENT bullet_list (list_item+)> -<!ATTLIST bullet_list - %basic.atts; - bullet CDATA #IMPLIED> - -<!ELEMENT enumerated_list (list_item+)> -<!ATTLIST enumerated_list - %basic.atts; - enumtype (arabic | loweralpha | upperalpha - | lowerroman | upperroman) - #IMPLIED - prefix CDATA #IMPLIED - suffix CDATA #IMPLIED - start %number; #IMPLIED> - -<!ELEMENT list_item (%body.elements;)*> -<!ATTLIST list_item %basic.atts;> - -<!ELEMENT definition_list (definition_list_item+)> -<!ATTLIST definition_list %basic.atts;> - -<!ELEMENT definition_list_item (term, classifier*, definition)> -<!ATTLIST definition_list_item %basic.atts;> - -<!ELEMENT term %text.model;> -<!ATTLIST term %basic.atts;> - -<!ELEMENT classifier %text.model;> -<!ATTLIST classifier %basic.atts;> - -<!ELEMENT definition (%body.elements;)+> -<!ATTLIST definition %basic.atts;> - -<!ELEMENT field_list (field+)> -<!ATTLIST field_list %basic.atts;> - -<!ELEMENT field (field_name, field_body)> -<!ATTLIST field %basic.atts;> - -<!ELEMENT field_name %text.model;> -<!ATTLIST field_name %basic.atts;> - -<!-- May be empty. --> -<!ELEMENT field_body (%body.elements;)*> -<!ATTLIST field_body %basic.atts;> - -<!ELEMENT option_list (option_list_item+)> -<!ATTLIST option_list %basic.atts;> - -<!ELEMENT option_list_item (option_group, description)> -<!ATTLIST option_list_item %basic.atts;> - -<!ELEMENT option_group (option+)> -<!ATTLIST option_group %basic.atts;> - -<!ELEMENT option (option_string, option_argument*)> -<!ATTLIST option %basic.atts;> - -<!ELEMENT option_string (#PCDATA)> -<!ATTLIST option_string %basic.atts;> - -<!-- -`delimiter` contains the text preceding the `option_argument`: either -the text separating it from the `option_string` (typically either "=" -or " ") or the text between option arguments (typically either "," or -" "). ---> -<!ELEMENT option_argument (#PCDATA)> -<!ATTLIST option_argument - %basic.atts; - delimiter CDATA #IMPLIED> - -<!ELEMENT description (%body.elements;)+> -<!ATTLIST description %basic.atts;> - -<!ELEMENT literal_block %text.model;> -<!ATTLIST literal_block - %basic.atts; - %fixedspace.att;> - -<!ELEMENT line_block (line | line_block)+> -<!ATTLIST line_block %basic.atts;> - -<!ELEMENT line %text.model;> -<!ATTLIST line %basic.atts;> - -<!ELEMENT block_quote ((%body.elements;)+, attribution?)> -<!ATTLIST block_quote %basic.atts;> - -<!ELEMENT attribution %text.model;> -<!ATTLIST attribution %basic.atts;> - -<!ELEMENT doctest_block %text.model;> -<!ATTLIST doctest_block - %basic.atts; - %fixedspace.att;> - -<!ELEMENT attention (%body.elements;)+> -<!ATTLIST attention %basic.atts;> - -<!ELEMENT caution (%body.elements;)+> -<!ATTLIST caution %basic.atts;> - -<!ELEMENT danger (%body.elements;)+> -<!ATTLIST danger %basic.atts;> - -<!ELEMENT error (%body.elements;)+> -<!ATTLIST error %basic.atts;> - -<!ELEMENT hint (%body.elements;)+> -<!ATTLIST hint %basic.atts;> - -<!ELEMENT important (%body.elements;)+> -<!ATTLIST important %basic.atts;> - -<!ELEMENT note (%body.elements;)+> -<!ATTLIST note %basic.atts;> - -<!ELEMENT tip (%body.elements;)+> -<!ATTLIST tip %basic.atts;> - -<!ELEMENT warning (%body.elements;)+> -<!ATTLIST warning %basic.atts;> - -<!ELEMENT admonition (title, (%body.elements;)+)> -<!ATTLIST admonition %basic.atts;> - -<!ELEMENT footnote (label?, (%body.elements;)+)> -<!ATTLIST footnote - %basic.atts; - %backrefs.att; - %auto.att;> - -<!ELEMENT citation (label, (%body.elements;)+)> -<!ATTLIST citation - %basic.atts; - %backrefs.att;> - -<!ELEMENT label (#PCDATA)> -<!ATTLIST label %basic.atts;> - -<!ELEMENT rubric %text.model;> -<!ATTLIST rubric %basic.atts;> - -<!-- Empty except when used as an inline element. --> -<!ELEMENT target %text.model;> -<!ATTLIST target - %basic.atts; - %reference.atts; - %anonymous.att;> - -<!ELEMENT substitution_definition %text.model;> -<!ATTLIST substitution_definition - %basic.atts; - ltrim %yesorno; #IMPLIED - rtrim %yesorno; #IMPLIED> - -<!ELEMENT comment (#PCDATA)> -<!ATTLIST comment - %basic.atts; - %fixedspace.att;> - -<!ELEMENT pending EMPTY> -<!ATTLIST pending %basic.atts;> - -<!ELEMENT figure (image, ((caption, legend?) | legend)) > -<!ATTLIST figure - %basic.atts; - %align-h.att; - width %number; #IMPLIED> - -<!-- Also an inline element. --> -<!ELEMENT image EMPTY> -<!ATTLIST image - %basic.atts; - %align-hv.att; - uri CDATA #REQUIRED - alt CDATA #IMPLIED - height %measure; #IMPLIED - width %measure; #IMPLIED - scale %number; #IMPLIED> - -<!ELEMENT caption %text.model;> -<!ATTLIST caption %basic.atts;> - -<!ELEMENT legend (%body.elements;)+> -<!ATTLIST legend %basic.atts;> - -<!-- -Table elements: table, tgroup, colspec, thead, tbody, row, entry. ---> -%calstblx; - -<!-- Used to record processing information. --> -<!ELEMENT system_message (%body.elements;)+> -<!ATTLIST system_message - %basic.atts; - %backrefs.att; - level %number; #IMPLIED - line %number; #IMPLIED - type NMTOKEN #IMPLIED> - -<!-- Used to pass raw data through the system. Also inline. --> -<!ELEMENT raw %text.model;> -<!ATTLIST raw - %basic.atts; - %fixedspace.att; - format NMTOKENS #IMPLIED> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Inline Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Inline elements occur within the text contents of body elements. Some -nesting of inline elements is allowed by these definitions, with the -following caveats: - -- An inline element may not contain a nested element of the same type - (e.g. <strong> may not contain another <strong>). -- Nested inline elements may or may not be supported by individual - applications using this DTD. -- The inline elements <footnote_reference>, <citation_reference>, - <literal>, and <image> do not support nesting. ---> - -<!ELEMENT emphasis %text.model;> -<!ATTLIST emphasis %basic.atts;> - -<!ELEMENT strong %text.model;> -<!ATTLIST strong %basic.atts;> - -<!ELEMENT literal (#PCDATA)> -<!ATTLIST literal %basic.atts;> - -<!-- Can also be a body element, when it contains an "image" element. --> -<!ELEMENT reference %text.model;> -<!ATTLIST reference - %basic.atts; - %reference.atts; - %anonymous.att;> - -<!ELEMENT footnote_reference (#PCDATA)> -<!ATTLIST footnote_reference - %basic.atts; - %refid.att; - %refname.att; - %auto.att;> - -<!ELEMENT citation_reference (#PCDATA)> -<!ATTLIST citation_reference - %basic.atts; - %refid.att; - %refname.att;> - -<!ELEMENT substitution_reference %text.model;> -<!ATTLIST substitution_reference - %basic.atts; - %refname.att;> - -<!ELEMENT title_reference %text.model;> -<!ATTLIST title_reference %basic.atts;> - -<!ELEMENT abbreviation %text.model;> -<!ATTLIST abbreviation %basic.atts;> - -<!ELEMENT acronym %text.model;> -<!ATTLIST acronym %basic.atts;> - -<!ELEMENT superscript %text.model;> -<!ATTLIST superscript %basic.atts;> - -<!ELEMENT subscript %text.model;> -<!ATTLIST subscript %basic.atts;> - -<!ELEMENT inline %text.model;> -<!ATTLIST inline %basic.atts;> - -<!ELEMENT problematic %text.model;> -<!ATTLIST problematic - %basic.atts; - %refid.att;> - -<!ELEMENT generated %text.model;> -<!ATTLIST generated %basic.atts;> - -<!-- -Local Variables: -mode: sgml -indent-tabs-mode: nil -fill-column: 70 -End: ---> diff --git a/docutils/docs/ref/rst/definitions.txt b/docutils/docs/ref/rst/definitions.txt deleted file mode 100644 index 78a2bf8da..000000000 --- a/docutils/docs/ref/rst/definitions.txt +++ /dev/null @@ -1,180 +0,0 @@ -============================================ - reStructuredText Standard Definition Files -============================================ -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -This document describes standard definition files, such as sets of -substitution definitions and interpreted text roles, that can be -included in reStructuredText documents. The `"include" directive`__ -has a special syntax for these standard definition files, angle -brackets around the file name:: - - .. include:: <filename.txt> - -__ directives.html#include - -The individual data files are stored with the Docutils source code in -the "docutils" package, in the ``docutils/parsers/rst/include`` -directory. - - -Substitution Definitions -======================== - -Many of the standard definition files contain sets of `substitution -definitions`__, which can be used in documents via `substitution -references`__. For example, the copyright symbol is defined in -``isonum.txt`` as "copy":: - - .. include:: <isonum.txt> - - Copyright |copy| 2003 by John Q. Public, all rights reserved. - -__ restructuredtext.html#substitution-definitions -__ restructuredtext.html#substitution-references - -Individual substitution definitions can also be copied from definition -files and pasted into documents. This has two advantages: it removes -dependencies, and it saves processing of unused definitions. However, -multiple substitution definitions add clutter to the document. - -Substitution references require separation from the surrounding text -with whitespace or punctuation. To use a substitution without -intervening whitespace, you can use the disappearing-whitespace escape -sequence, backslash-space:: - - .. include:: isonum.txt - - Copyright |copy| 2003, BogusMegaCorp\ |trade|. - -Custom substitution definitions may use the `"unicode" directive`__. -Whitespace is ignored and removed, effectively sqeezing together the -text:: - - .. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - - Copyright |copy| 2003, |BogusMegaCorp (TM)|. - -__ directives.html#unicode - -In addition, the "ltrim", "rtrim", and "trim" options may be used with -the "unicode" directive to automatically trim spaces from the left, -right, or both sides (respectively) of substitution references:: - - .. |---| unicode:: U+02014 .. em dash - :trim: - - -Character Entity Sets ---------------------- - -The following files contain substitution definitions corresponding to -XML character entity sets, from the following standards: ISO 8879 & -ISO 9573-13 (combined), MathML, and XHTML1. They were generated by -the ``tools/dev/unicode2rstsubs.py`` program from the input file -unicode.xml__, which is maintained as part of the MathML 2 -Recommentation XML source. - -__ http://www.w3.org/2003/entities/xml/ - -=================== ================================================= -Entity Set File Description -=================== ================================================= -isoamsa.txt_ Added Mathematical Symbols: Arrows -isoamsb.txt_ Added Mathematical Symbols: Binary Operators -isoamsc.txt_ Added Mathematical Symbols: Delimiters -isoamsn.txt_ Added Mathematical Symbols: Negated Relations -isoamso.txt_ Added Mathematical Symbols: Ordinary -isoamsr.txt_ Added Mathematical Symbols: Relations -isobox.txt_ Box and Line Drawing -isocyr1.txt_ Russian Cyrillic -isocyr2.txt_ Non-Russian Cyrillic -isodia.txt_ Diacritical Marks -isogrk1.txt_ Greek Letters -isogrk2.txt_ Monotoniko Greek -isogrk3.txt_ Greek Symbols -isogrk4.txt_ [1]_ Alternative Greek Symbols -isolat1.txt_ Added Latin 1 -isolat2.txt_ Added Latin 2 -isomfrk.txt_ [1]_ Mathematical Fraktur -isomopf.txt_ [1]_ Mathematical Openface (Double-struck) -isomscr.txt_ [1]_ Mathematical Script -isonum.txt_ Numeric and Special Graphic -isopub.txt_ Publishing -isotech.txt_ General Technical -mmlalias.txt_ MathML aliases for entities from other sets -mmlextra.txt_ [1]_ Extra names added by MathML -xhtml1-lat1.txt_ XHTML Latin 1 -xhtml1-special.txt_ XHTML Special Characters -xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters -=================== ================================================= - -.. [1] There are ``*-wide.txt`` variants for each of these character - entity set files, containing characters outside of the Unicode - basic multilingual plane or BMP (wide-Unicode; code points greater - than U+FFFF). Most pre-built Python distributions are "narrow" and - do not support wide-Unicode characters. Python *can* be built with - wide-Unicode support though; consult the Python build instructions - for details. - -For example, the copyright symbol is defined as the XML character -entity ``©``. The equivalent reStructuredText substitution -reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is -``|copy|``. - -.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt -.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt -.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt -.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt -.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt -.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt -.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt -.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt -.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt -.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt -.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt -.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt -.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt -.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt -.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt -.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt -.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt -.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt -.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt -.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt -.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt -.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt -.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt -.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt -.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt -.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt -.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt - - -S5/HTML Definitions -=================== - -The "s5defs.txt_" standard definition file contains interpreted text -roles (classes) and other definitions for documents destined to become -`S5/HTML slide shows`_. - -.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt -.. _S5/HTML slide shows: ../../user/slide-shows.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt deleted file mode 100644 index af88a3d4e..000000000 --- a/docutils/docs/ref/rst/directives.txt +++ /dev/null @@ -1,1727 +0,0 @@ -============================= - reStructuredText Directives -============================= -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -This document describes the directives implemented in the reference -reStructuredText parser. - -Directives have the following syntax:: - - +-------+-------------------------------+ - | ".. " | directive type "::" directive | - +-------+ block | - | | - +-------------------------------+ - -Directives begin with an explicit markup start (two periods and a -space), followed by the directive type and two colons (collectively, -the "directive marker"). The directive block begins immediately after -the directive marker, and includes all subsequent indented lines. The -directive block is divided into arguments, options (a field list), and -content (in that order), any of which may appear. See the Directives_ -section in the `reStructuredText Markup Specification`_ for syntax -details. - -Descriptions below list "doctree elements" (document tree element -names; XML DTD generic identifiers) corresponding to individual -directives. For details on the hierarchy of elements, please see `The -Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. For directive implementation details, see `Creating -reStructuredText Directives`_. - -.. _Directives: restructuredtext.html#directives -.. _reStructuredText Markup Specification: restructuredtext.html -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Directives: - ../../howto/rst-directives.html - - -------------- - Admonitions -------------- - -.. _attention: -.. _caution: -.. _danger: -.. _error: -.. _hint: -.. _important: -.. _note: -.. _tip: -.. _warning: - -Specific Admonitions -==================== - -:Directive Types: "attention", "caution", "danger", "error", "hint", - "important", "note", "tip", "warning", "admonition" -:Doctree Elements: attention, caution, danger, error, hint, important, - note, tip, warning, admonition, title -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -Admonitions are specially marked "topics" that can appear anywhere an -ordinary body element can. They contain arbitrary body elements. -Typically, an admonition is rendered as an offset block in a document, -sometimes outlined or shaded, with a title matching the admonition -type. For example:: - - .. DANGER:: - Beware killer rabbits! - -This directive might be rendered something like this:: - - +------------------------+ - | !DANGER! | - | | - | Beware killer rabbits! | - +------------------------+ - -The following admonition directives have been implemented: - -- attention -- caution -- danger -- error -- hint -- important -- note -- tip -- warning - -Any text immediately following the directive indicator (on the same -line and/or indented on following lines) is interpreted as a directive -block and is parsed for normal body elements. For example, the -following "note" admonition directive contains one paragraph and a -bullet list consisting of two list items:: - - .. note:: This is a note admonition. - This is the second line of the first paragraph. - - - The note contains all indented body elements - following. - - It includes this bullet list. - - -.. _admonition: - -Generic Admonition -================== - -:Directive Type: "admonition" -:Doctree Elements: admonition, title -:Directive Arguments: One, required (admonition title) -:Directive Options: Possible. -:Directive Content: Interpreted as body elements. - -This is a generic, titled admonition. The title may be anything the -author desires. - -The author-supplied title is also used as a "class" attribute value -after being converted into a valid identifier form (down-cased; -non-alphanumeric characters converted to single hyphens; "admonition-" -prefixed). For example, this admonition:: - - .. admonition:: And, by the way... - - You can make up your own admonition too. - -becomes the following document tree (pseudo-XML):: - - <document source="test data"> - <admonition class="admonition-and-by-the-way"> - <title> - And, by the way... - <paragraph> - You can make up your own admonition too. - -The following option is recognized: - -``class`` : text - Override the computed "class" attribute value. See the class_ - directive below. - - --------- - Images --------- - -There are two image directives: "image" and "figure". - - -Image -===== - -:Directive Type: "image" -:Doctree Element: image -:Directive Arguments: One, required (image URI). -:Directive Options: Possible. -:Directive Content: None. - -An "image" is a simple picture:: - - .. image:: picture.png - -The URI for the image source file is specified in the directive -argument. As with hyperlink targets, the image URI may begin on the -same line as the explicit markup start and target name, or it may -begin in an indented text block immediately following, with no -intervening blank lines. If there are multiple lines in the link -block, they are stripped of leading and trailing whitespace and joined -together. - -Optionally, the image link block may contain a flat field list, the -_`image options`. For example:: - - .. image:: picture.jpeg - :height: 100 - :width: 200 - :scale: 50 - :alt: alternate text - :align: right - -The following options are recognized: - -``alt`` : text - Alternate text: a short description of the image, displayed by - applications that cannot display images, or spoken by applications - for visually impaired users. - -``height`` : integer - The desired height of the image in pixels, used to reserve space - or scale the image vertically. When the "scale" option is also - specified, they are combined. For example, a height of 200 and a - scale of 50 is equivalent to a height of 100 with no scale. - - New in Docutils 0.3.10: It is also possible to specify a `length - value`_. - -``width`` : integer - The width of the image in pixels, used to reserve space or scale - the image horizontally. As with "height" above, when the "scale" - option is also specified, they are combined. - - New in Docutils 0.3.10: It is also possible to specify a length_ - or `percentage value`_ (which is relative to the current line - width). - - .. _length: - .. _length value: restructuredtext.html#length-units - .. _percentage value: restructuredtext.html#percentage-units - -``scale`` : integer - The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size, and is - equivalent to omitting a "scale" option. - - If no "height" or "width" options are specified, PIL [#PIL]_ may - be used to determine them, if PIL is installed and the image file - is available. - -``align`` : "top", "middle", "bottom", "left", "center", or "right" - The alignment of the image, equivalent to the HTML ``<img>`` tag's - "align" attribute. The values "top", "middle", and "bottom" - control an image's vertical alignment (relative to the text - baseline); they are only useful for inline images (substitutions). - The values "left", "center", and "right" control an image's - horizontal alignment, allowing the image to float and have the - text flow around it. The specific behavior depends upon the - browser or rendering software used. - -``target`` : text (URI or reference name) - Makes the image into a hyperlink reference ("clickable"). The - option argument may be a URI (relative or absolute), or a - reference name with underscore suffix (e.g. ``name_``). - -``class`` : text - Set a "class" attribute value on the image element. See the - class_ directive below. - - -Figure -====== - -:Directive Type: "figure" -:Doctree Elements: figure, image, caption, legend -:Directive Arguments: One, required (image URI). -:Directive Options: Possible. -:Directive Content: Interpreted as the figure caption and an optional - legend. - -A "figure" consists of image_ data (including `image options`_), an -optional caption (a single paragraph), and an optional legend -(arbitrary body elements):: - - .. figure:: picture.png - :scale: 50 - :alt: map to buried treasure - - This is the caption of the figure (a simple paragraph). - - The legend consists of all elements after the caption. In this - case, the legend consists of this paragraph and the following - table: - - +-----------------------+-----------------------+ - | Symbol | Meaning | - +=======================+=======================+ - | .. image:: tent.png | Campground | - +-----------------------+-----------------------+ - | .. image:: waves.png | Lake | - +-----------------------+-----------------------+ - | .. image:: peak.png | Mountain | - +-----------------------+-----------------------+ - -There must be blank lines before the caption paragraph and before the -legend. To specify a legend without a caption, use an empty comment -("..") in place of the caption. - -The "figure" directive supports all of the options of the "image" -directive (see `image options`_ above). In addition, the following -options are recognized: - -``figwidth`` : integer or "image" - The width of the figure in pixels, to limit the horizontal space - used. A special value of "image" is allowed, in which case the - included image's actual width is used (requires PIL [#PIL]_). If - the image file is not found or the required software is - unavailable, this option is ignored. - - Sets the "width" attribute of the "figure" doctree element. - - This option does not scale the included image; use the "width" - `image`_ option for that. :: - - +---------------------------+ - | figure | - | | - |<------ figwidth --------->| - | | - | +---------------------+ | - | | image | | - | | | | - | |<--- width --------->| | - | +---------------------+ | - | | - |The figure's caption should| - |wrap at this width. | - +---------------------------+ - -``figclass`` : text - Set a "class" attribute value on the figure element. See the - class_ directive below. - -``align`` : "left", "center", or "right" - The horizontal alignment of the figure, allowing the image to - float and have the text flow around it. The specific behavior - depends upon the browser or rendering software used. - -.. [#PIL] `Python Imaging Library`_. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - - ---------------- - Body Elements ---------------- - -Topic -===== - -:Directive Type: "topic" -:Doctree Element: topic -:Directive Arguments: 1, required (topic title). -:Directive Options: Possible. -:Directive Content: Interpreted as the topic body. - -A topic is like a block quote with a title, or a self-contained -section with no subsections. Use the "topic" directive to indicate a -self-contained idea that is separate from the flow of the document. -Topics may occur anywhere a section or transition may occur. Body -elements and topics may not contain nested topics. - -The directive's sole argument is interpreted as the topic title; the -next line must be blank. All subsequent lines make up the topic body, -interpreted as body elements. For example:: - - .. topic:: Topic Title - - Subsequent indented lines comprise - the body of the topic, and are - interpreted as body elements. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the topic element. See the - class_ directive below. - - -Sidebar -======= - -:Directive Type: "sidebar" -:Doctree Element: sidebar -:Directive Arguments: One, required (sidebar title). -:Directive Options: Possible. -:Directive Content: Interpreted as the sidebar body. - -Sidebars are like miniature, parallel documents that occur inside -other documents, providing related or reference material. A sidebar -is typically offset by a border and "floats" to the side of the page; -the document's main text may flow around it. Sidebars can also be -likened to super-footnotes; their content is outside of the flow of -the document's main text. - -Sidebars may occur anywhere a section or transition may occur. Body -elements (including sidebars) may not contain nested sidebars. - -The directive's sole argument is interpreted as the sidebar title, -which may be followed by a subtitle option (see below); the next line -must be blank. All subsequent lines make up the sidebar body, -interpreted as body elements. For example:: - - .. sidebar:: Sidebar Title - :subtitle: Optional Sidebar Subtitle - - Subsequent indented lines comprise - the body of the sidebar, and are - interpreted as body elements. - -The following options are recognized: - -``subtitle`` : text - The sidebar's subtitle. - -``class`` : text - Set a "class" attribute value on the sidebar element. See the - class_ directive below. - - -Line Block -========== - -.. admonition:: Deprecated - - The "line-block" directive is deprecated. Use the `line block - syntax`_ instead. - - .. _line block syntax: restructuredtext.html#line-blocks - -:Directive Type: "line-block" -:Doctree Element: line_block -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Becomes the body of the line block. - -The "line-block" directive constructs an element where line breaks and -initial indentation is significant and inline markup is supported. It -is equivalent to a `parsed literal block`_ with different rendering: -typically in an ordinary serif typeface instead of a -typewriter/monospaced face, and not automatically indented. (Have the -line-block directive begin a block quote to get an indented line -block.) Line blocks are useful for address blocks and verse (poetry, -song lyrics), where the structure of lines is significant. For -example, here's a classic:: - - "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by - Ewan McTeagle (for Lassie O'Shea): - - .. line-block:: - - Lend us a couple of bob till Thursday. - I'm absolutely skint. - But I'm expecting a postal order and I can pay you back - as soon as it comes. - Love, Ewan. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the line_block element. See the - class_ directive below. - - -.. _parsed-literal: - -Parsed Literal Block -==================== - -:Directive Type: "parsed-literal" -:Doctree Element: literal_block -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Becomes the body of the literal block. - -Unlike an ordinary literal block, the "parsed-literal" directive -constructs a literal block where the text is parsed for inline markup. -It is equivalent to a `line block`_ with different rendering: -typically in a typewriter/monospaced typeface, like an ordinary -literal block. Parsed literal blocks are useful for adding hyperlinks -to code examples. - -However, care must be taken with the text, because inline markup is -recognized and there is no protection from parsing. Backslash-escapes -may be necessary to prevent unintended parsing. And because the -markup characters are removed by the parser, care must also be taken -with vertical alignment. Parsed "ASCII art" is tricky, and extra -whitespace may be necessary. - -For example, all the element names in this content model are links:: - - .. parsed-literal:: - - ( (title_, subtitle_?)?, - decoration_?, - (docinfo_, transition_?)?, - `%structure.model;`_ ) - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the literal_block element. See - the class_ directive below. - - -Rubric -====== - -:Directive Type: "rubric" -:Doctree Element: rubric -:Directive Arguments: 1, required (rubric text). -:Directive Options: Possible. -:Directive Content: None. - -.. - - rubric n. 1. a title, heading, or the like, in a manuscript, - book, statute, etc., written or printed in red or otherwise - distinguished from the rest of the text. ... - - -- Random House Webster's College Dictionary, 1991 - -The "rubric" directive inserts a "rubric" element into the document -tree. A rubric is like an informal heading that doesn't correspond to -the document's structure. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the rubric element. See the - class_ directive below. - - -Epigraph -======== - -:Directive Type: "epigraph" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -An epigraph is an apposite (suitable, apt, or pertinent) short -inscription, often a quotation or poem, at the beginning of a document -or section. - -The "epigraph" directive produces an "epigraph"-class block quote. -For example, this input:: - - .. epigraph:: - - No matter where you go, there you are. - - -- Buckaroo Banzai - -becomes this document tree fragment:: - - <block_quote class="epigraph"> - <paragraph> - No matter where you go, there you are. - <attribution> - Buckaroo Banzai - - -Highlights -========== - -:Directive Type: "highlights" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -Highlights summarize the main points of a document or section, often -consisting of a list. - -The "highlights" directive produces a "highlights"-class block quote. -See Epigraph_ above for an analogous example. - - -Pull-Quote -========== - -:Directive Type: "pull-quote" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -A pull-quote is a small selection of text "pulled out and quoted", -typically in a larger typeface. Pull-quotes are used to attract -attention, especially in long articles. - -The "pull-quote" directive produces a "pull-quote"-class block quote. -See Epigraph_ above for an analogous example. - - -.. _compound: - -Compound Paragraph -================== - -:Directive Type: "compound" -:Doctree Element: compound -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.6) - -The "compound" directive is used to create a compound paragraph, which -is a single logical paragraph containing multiple physical body -elements such as simple paragraphs, literal blocks, tables, lists, -etc., instead of directly containing text and inline elements. For -example:: - - .. compound:: - - The 'rm' command is very dangerous. If you are logged - in as root and enter :: - - cd / - rm -rf * - - you will erase the entire contents of your file system. - -In the example above, a literal block is "embedded" within a sentence -that begins in one physical paragraph and ends in another. - -.. note:: - - The "compound" directive is *not* a generic block-level container - like HTML's ``<div>`` element. Do not use it only to group a - sequence of elements, or you may get unexpected results. - - If you need a generic block-level container, please use the - container_ directive, described below. - -Compound paragraphs are typically rendered as multiple distinct text -blocks, with the possibility of variations to emphasize their logical -unity: - -* If paragraphs are rendered with a first-line indent, only the first - physical paragraph of a compound paragraph should have that indent - -- second and further physical paragraphs should omit the indents; -* vertical spacing between physical elements may be reduced; -* and so on. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the compound element. See the - class_ directive below. - - -Container -========= - -:Directive Type: "container" -:Doctree Element: container -:Directive Arguments: One or more, optional (class names). -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.10) - -The "container" directive surrounds its contents (arbitrary body -elements) with a generic block-level "container" element. Combined -with the optional "class_" attribute argument(s), this is an extension -mechanism for users & applications. For example:: - - .. container:: custom - - This paragraph might be rendered in a custom way. - -Parsing the above results in the following pseudo-XML:: - - <container classes="custom"> - <paragraph> - This paragraph might be rendered in a custom way. - -The "container" directive is the equivalent of HTML's ``<div>`` -element. It may be used to group a sequence of elements for user- or -application-specific purposes. - - --------- - Tables --------- - -Formal tables need more structure than the reStructuredText syntax -supplies. Tables may be given titles with the table_ directive. -Sometimes reStructuredText tables are inconvenient to write, or table -data in a standard format is readily available. The csv-table_ -directive supports CSV data. - - -Table -===== - -:Directive Type: "table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A normal reStructuredText table. - -(New in Docutils 0.3.1) - -The "table" directive is used to create a titled table, to associate a -title with a table:: - - .. table:: Truth table for "not" - - ===== ===== - A not A - ===== ===== - False True - True False - ===== ===== - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - - -.. _csv-table: - -CSV Table -========= - -:Directive Type: "csv-table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A CSV (comma-separated values) table. - -.. WARNING:: - - The "csv-table" directive's ":file:" and ":url:" options represent - a potential security holes. They can be disabled with the - "file_insertion_enabled_" runtime setting. - -.. Note:: - - The "csv-table" directive requires the ``csv.py`` module of the - Python standard library, which was added in Python 2.3. It will - not work with earlier versions of Python. Using the "csv-table" - directive in a document will make the document **incompatible** - with systems using Python 2.1 or 2.2. - -(New in Docutils 0.3.4) - -The "csv-table" directive is used to create a table from CSV -(comma-separated values) data. CSV is a common data format generated -by spreadsheet applications and commercial databases. The data may be -internal (an integral part of the document) or external (a separate -file). - -Example:: - - .. csv-table:: Frozen Delights! - :header: "Treat", "Quantity", "Description" - :widths: 15, 10, 30 - - "Albatross", 2.99, "On a stick!" - "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be - crunchy, now would it?" - "Gannet Ripple", 1.99, "On a stick!" - -Block markup and inline markup within cells is supported. Line ends -are recognized within cells. - -Working limitations: - -* Whitespace delimiters are supported only for external CSV files. - -* There is no support for checking that the number of columns in each - row is the same. However, this directive supports CSV generators - that do not insert "empty" entries at the end of short rows, by - automatically adding empty entries. - - .. Add "strict" option to verify input? - -The following options are recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - -``widths`` : integer [, integer...] - A comma- or space-separated list of relative column widths. The - default is equal-width columns (100%/#columns). - -``header-rows`` : integer - The number of rows of CSV data to use in the table header. - Defaults to 0. - -``stub-columns`` : integer - The number of table columns to use as stubs (row titles, on the - left). Defaults to 0. - -``header`` : CSV data - Supplemental data for the table header, added independently of and - before any ``header-rows`` from the main CSV data. Must use the - same CSV format as the main CSV data. - -``file`` : string (newlines removed) - The local filesystem path to a CSV data file. - -``url`` : string (whitespace removed) - An Internet URL reference to a CSV data file. - -``encoding`` : name of text encoding - The text encoding of the external CSV data (file or URL). - Defaults to the document's encoding (if specified). - -``delim`` : char | "tab" | "space" - A one-character string used to separate fields. Defaults to ``,`` - (comma). May be specified as a Unicode code point; see the - unicode_ directive for syntax details. - -``quote`` : char - A one-character string used to quote elements containing the - delimiter or which start with the quote character. Defaults to - ``"`` (quote). May be specified as a Unicode code point; see the - unicode_ directive for syntax details. - -``keepspace`` : flag - Treat whitespace immediately following the delimiter as - significant. The default is to ignore such whitespace. - -``escape`` : char - A one-character string used to escape the delimiter or quote - characters. May be specified as a Unicode code point; see the - unicode_ directive for syntax details. Used when the delimiter is - used in an unquoted field, or when quote characters are used - within a field. The default is to double-up the character, - e.g. "He said, ""Hi!""" - - .. Add another possible value, "double", to explicitly indicate - the default case? - - -List Table -========== - -:Directive Type: "list-table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A uniform two-level bullet list. - -(New in Docutils 0.3.8. This is an initial implementation; `further -ideas`__ may be implemented in the future.) - -__ ../../dev/rst/alternatives.html#list-driven-tables - -The "list-table" directive is used to create a table from data in a -uniform two-level bullet list. "Uniform" means that each sublist -(second-level list) must contain the same number of list items. - -Example:: - - .. list-table:: Frozen Delights! - :widths: 15 10 30 - :header-rows: 1 - - * - Treat - - Quantity - - Description - * - Albatross - - 2.99 - - On a stick! - * - Crunchy Frog - - 1.49 - - If we took the bones out, it wouldn't be - crunchy, now would it? - * - Gannet Ripple - - 1.99 - - On a stick! - -The following options are recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - -``widths`` : integer [integer...] - A comma- or space-separated list of relative column widths. The - default is equal-width columns (100%/#columns). - -``header-rows`` : integer - The number of rows of list data to use in the table header. - Defaults to 0. - -``stub-columns`` : integer - The number of table columns to use as stubs (row titles, on the - left). Defaults to 0. - - ----------------- - Document Parts ----------------- - -.. _contents: - -Table of Contents -================= - -:Directive Type: "contents" -:Doctree Elements: pending, topic -:Directive Arguments: One, optional: title. -:Directive Options: Possible. -:Directive Content: None. - -The "contents" directive generates a table of contents (TOC) in a -topic_. Topics, and therefore tables of contents, may occur anywhere -a section or transition may occur. Body elements and topics may not -contain tables of contents. - -Here's the directive in its simplest form:: - - .. contents:: - -Language-dependent boilerplate text will be used for the title. The -English default title text is "Contents". - -An explicit title may be specified:: - - .. contents:: Table of Contents - -The title may span lines, although it is not recommended:: - - .. contents:: Here's a very long Table of - Contents title - -Options may be specified for the directive, using a field list:: - - .. contents:: Table of Contents - :depth: 2 - -If the default title is to be used, the options field list may begin -on the same line as the directive marker:: - - .. contents:: :depth: 2 - -The following options are recognized: - -``depth`` : integer - The number of section levels that are collected in the table of - contents. The default is unlimited depth. - -``local`` : flag (empty) - Generate a local table of contents. Entries will only include - subsections of the section in which the directive is given. If no - explicit title is given, the table of contents will not be titled. - -``backlinks`` : "entry" or "top" or "none" - Generate links from section headers back to the table of contents - entries, the table of contents itself, or generate no backlinks. - -``class`` : text - Set a "class" attribute value on the topic element. See the - class_ directive below. - - -.. _sectnum: -.. _section-autonumbering: - -Automatic Section Numbering -=========================== - -:Directive Type: "sectnum" or "section-autonumbering" (synonyms) -:Doctree Elements: pending, generated -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: None. - -The "sectnum" (or "section-autonumbering") directive automatically -numbers sections and subsections in a document. Section numbers are -of the "multiple enumeration" form, where each level has a number, -separated by periods. For example, the title of section 1, subsection -2, subsubsection 3 would have "1.2.3" prefixed. - -The "sectnum" directive does its work in two passes: the initial parse -and a transform. During the initial parse, a "pending" element is -generated which acts as a placeholder, storing any options internally. -At a later stage in the processing, the "pending" element triggers a -transform, which adds section numbers to titles. Section numbers are -enclosed in a "generated" element, and titles have their "auto" -attribute set to "1". - -The following options are recognized: - -``depth`` : integer - The number of section levels that are numbered by this directive. - The default is unlimited depth. - -``prefix`` : string - An arbitrary string that is prefixed to the automatically - generated section numbers. It may be something like "3.2.", which - will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that - any separating punctuation (in the example, a period, ".") must be - explicitly provided. The default is no prefix. - -``suffix`` : string - An arbitrary string that is appended to the automatically - generated section numbers. The default is no suffix. - -``start`` : integer - The value that will be used for the first section number. - Combined with ``prefix``, this may be used to force the right - numbering for a document split over several source files. The - default is 1. - - -.. _header: -.. _footer: - -Document Header & Footer -======================== - -:Directive Types: "header" and "footer" -:Doctree Elements: decoration, header, footer -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.8) - -The "header" and "footer" directives create document decorations, -useful for page navigation, notes, time/datestamp, etc. For example:: - - .. header:: This space for rent. - -This will add a paragraph to the document header, which will appear at -the top of the generated web page or at the top of every printed page. - -These directives may be used multiple times, cumulatively. There is -currently support for only one header and footer. - -.. note:: - - While it is possible to use the "header" and "footer" directives to - create navigational elements for web pages, you should be aware - that Docutils is meant to be used for *document* processing, and - that a navigation bar is not typically part of a document. - - Thus, you may soon find Docutils' abilities to be insufficient for - these purposes. At that time, you should consider using a - templating system (like ht2html_) rather than the "header" and - "footer" directives. - - .. _ht2html: http://ht2html.sourceforge.net/ - -In addition to the use of these directives to populate header and -footer content, content may also be added automatically by the -processing system. For example, if certain runtime settings are -enabled, the document footer is populated with processing information -such as a datestamp, a link to `the Docutils website`_, etc. - -.. _the Docutils website: http://docutils.sourceforge.net - - ------------- - References ------------- - -.. _target-notes: - -Target Footnotes -================ - -:Directive Type: "target-notes" -:Doctree Elements: pending, footnote, footnote_reference -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: None. - -The "target-notes" directive creates a footnote for each external -target in the text, and corresponding footnote references after each -reference. For every explicit target (of the form, ``.. _target name: -URL``) in the text, a footnote will be generated containing the -visible URL as content. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on all footnote_reference elements. - See the class_ directive below. - - -Footnotes -========= - -**NOT IMPLEMENTED YET** - -:Directive Type: "footnotes" -:Doctree Elements: pending, topic -:Directive Arguments: None? -:Directive Options: Possible? -:Directive Content: None. - -@@@ - - -Citations -========= - -**NOT IMPLEMENTED YET** - -:Directive Type: "citations" -:Doctree Elements: pending, topic -:Directive Arguments: None? -:Directive Options: Possible? -:Directive Content: None. - -@@@ - - ---------------- - HTML-Specific ---------------- - -Meta -==== - -:Directive Type: "meta" -:Doctree Element: meta (non-standard) -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Must contain a flat field list. - -The "meta" directive is used to specify HTML metadata stored in HTML -META tags. "Metadata" is data about data, in this case data about web -pages. Metadata is used to describe and classify web pages in the -World Wide Web, in a form that is easy for search engines to extract -and collate. - -Within the directive block, a flat field list provides the syntax for -metadata. The field name becomes the contents of the "name" attribute -of the META tag, and the field body (interpreted as a single string -without inline markup) becomes the contents of the "content" -attribute. For example:: - - .. meta:: - :description: The reStructuredText plaintext markup language - :keywords: plaintext, markup language - -This would be converted to the following HTML:: - - <meta name="description" - content="The reStructuredText plaintext markup language"> - <meta name="keywords" content="plaintext, markup language"> - -Support for other META attributes ("http-equiv", "scheme", "lang", -"dir") are provided through field arguments, which must be of the form -"attr=value":: - - .. meta:: - :description lang=en: An amusing story - :description lang=fr: Un histoire amusant - -And their HTML equivalents:: - - <meta name="description" lang="en" content="An amusing story"> - <meta name="description" lang="fr" content="Un histoire amusant"> - -Some META tags use an "http-equiv" attribute instead of the "name" -attribute. To specify "http-equiv" META tags, simply omit the name:: - - .. meta:: - :http-equiv=Content-Type: text/html; charset=ISO-8859-1 - -HTML equivalent:: - - <meta http-equiv="Content-Type" - content="text/html; charset=ISO-8859-1"> - - -Imagemap -======== - -**NOT IMPLEMENTED YET** - -Non-standard element: imagemap. - - ------------------------------------------ - Directives for Substitution Definitions ------------------------------------------ - -The directives in this section may only be used in substitution -definitions. They may not be used directly, in standalone context. -The `image`_ directive may be used both in substitution definitions -and in the standalone context. - - -.. _replace: - -Replacement Text -================ - -:Directive Type: "replace" -:Doctree Element: Text & inline elements -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: A single paragraph; may contain inline markup. - -The "replace" directive is used to indicate replacement text for a -substitution reference. It may be used within substitution -definitions only. For example, this directive can be used to expand -abbreviations:: - - .. |reST| replace:: reStructuredText - - Yes, |reST| is a long word, so I can't blame anyone for wanting to - abbreviate it. - -As reStructuredText doesn't support nested inline markup, the only way -to create a reference with styled text is to use substitutions with -the "replace" directive:: - - I recommend you try |Python|_. - - .. |Python| replace:: Python, *the* best language around - .. _Python: http://www.python.org/ - - -.. _unicode: - -Unicode Character Codes -======================= - -:Directive Type: "unicode" -:Doctree Element: Text -:Directive Arguments: One or more, required (Unicode character codes, - optional text, and comments). -:Directive Options: Possible. -:Directive Content: None. - -The "unicode" directive converts Unicode character codes (numerical -values) to characters, and may be used in substitution definitions -only. - -The arguments, separated by spaces, can be: - -* **character codes** as - - - decimal numbers or - - - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``, - ``u``, or ``\u`` or as XML-style hexadecimal character entities, - e.g. ``ᨫ`` - -* **text**, which is used as-is. - -Text following " .. " is a comment and is ignored. The spaces between -the arguments are ignored and thus do not appear in the output. -Hexadecimal codes are case-insensitive. - -For example, the following text:: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -results in: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -The following options are recognized: - -``ltrim`` : flag - Whitespace to the left of the substitution reference is removed. - -``rtrim`` : flag - Whitespace to the right of the substitution reference is removed. - -``trim`` : flag - Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides - of the substitution reference is removed. - - -Date -==== - -:Directive Type: "date" -:Doctree Element: Text -:Directive Arguments: One, optional (date format). -:Directive Options: None. -:Directive Content: None. - -The "date" directive generates the current local date and inserts it -into the document as text. This directive may be used in substitution -definitions only. - -The optional directive content is interpreted as the desired date -format, using the same codes as Python's time.strftime function. The -default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also -be used. Examples:: - - .. |date| date:: - .. |time| date:: %H:%M - - Today's date is |date|. - - This document was generated on |date| at |time|. - - ---------------- - Miscellaneous ---------------- - -.. _include: - -Including an External Document Fragment -======================================= - -:Directive Type: "include" -:Doctree Elements: depend on data being included -:Directive Arguments: One, required (path to the file to include). -:Directive Options: Possible. -:Directive Content: None. - -.. WARNING:: - - The "include" directive represents a potential security hole. It - can be disabled with the "file_insertion_enabled_" runtime setting. - - .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled - -The "include" directive reads a reStructuredText-formatted text file -and parses it in the current document's context at the point of the -directive. The directive argument is the path to the file to be -included, relative to the document containing the directive. For -example:: - - This first example will be parsed at the document level, and can - thus contain any construct, including section headers. - - .. include:: inclusion.txt - - Back in the main document. - - This second example will be parsed in a block quote context. - Therefore it may only contain body elements. It may not - contain section headers. - - .. include:: inclusion.txt - -If an included document fragment contains section structure, the title -adornments must match those of the master document. - -Standard data files intended for inclusion in reStructuredText -documents are distributed with the Docutils source code, located in -the "docutils" package in the ``docutils/parsers/rst/include`` -directory. To access these files, use the special syntax for standard -"include" data files, angle brackets around the file name:: - - .. include:: <isonum.txt> - -The current set of standard "include" data files consists of sets of -substitution definitions. See `reStructuredText Standard Substitution -Definition Sets`__ for details of the available standard data files. - -__ substitutions.html - -The following options are recognized: - -``literal`` : flag (empty) - The entire included text is inserted into the document as a single - literal block (useful for program listings). - -``encoding`` : name of text encoding - The text encoding of the external data file. Defaults to the - document's encoding (if specified). - - -.. _raw: - -Raw Data Pass-Through -===================== - -:Directive Type: "raw" -:Doctree Element: raw -:Directive Arguments: One or more, required (output format types). -:Directive Options: Possible. -:Directive Content: Stored verbatim, uninterpreted. None (empty) if a - "file" or "url" option given. - -.. WARNING:: - - The "raw" directive represents a potential security hole. It can - be disabled with the "raw_enabled_" or "file_insertion_enabled_" - runtime settings. - - .. _raw_enabled: ../../user/config.html#raw-enabled - -.. Caution:: - - The "raw" directive is a stop-gap measure allowing the author to - bypass reStructuredText's markup. It is a "power-user" feature - that should not be overused or abused. The use of "raw" ties - documents to specific output formats and makes them less portable. - - If you often need to use the "raw" directive or a "raw"-derived - interpreted text role, that is a sign either of overuse/abuse or - that functionality may be missing from reStructuredText. Please - describe your situation in a message to the Docutils-users_ mailing - list. - -.. _Docutils-users: ../../user/mailing-lists.html#docutils-users - -The "raw" directive indicates non-reStructuredText data that is to be -passed untouched to the Writer. The names of the output formats are -given in the directive arguments. The interpretation of the raw data -is up to the Writer. A Writer may ignore any raw output not matching -its format. - -For example, the following input would be passed untouched by an HTML -Writer:: - - .. raw:: html - - <hr width=50 size=10> - -A LaTeX Writer could insert the following raw content into its -output stream:: - - .. raw:: latex - - \setlength{\parindent}{0pt} - -Raw data can also be read from an external file, specified in a -directive option. In this case, the content block must be empty. For -example:: - - .. raw:: html - :file: inclusion.html - -The following options are recognized: - -``file`` : string (newlines removed) - The local filesystem path of a raw data file to be included. - -``url`` : string (whitespace removed) - An Internet URL reference to a raw data file to be included. - -``encoding`` : name of text encoding - The text encoding of the external raw data (file or URL). - Defaults to the document's encoding (if specified). - - -Class -===== - -:Directive Type: "class" -:Doctree Element: pending -:Directive Arguments: One or more, required (class names / attribute - values). -:Directive Options: None. -:Directive Content: Optional. If present, it is interpreted as body - elements. - -The "class" directive sets the "class" attribute value on its content -or on the first immediately following non-comment element [#]_. For -details of the "class" attribute, see `its entry`__ in `The Docutils -Document Tree`_. The directive argument consists of one or more -space-separated class names, which are converted to lowercase and all -non-alphanumeric characters are converted to hyphens. (For the -rationale, see below.) - -__ ../doctree.html#class - -Examples:: - - .. class:: special - - This is a "special" paragraph. - - .. class:: exceptional remarkable - - An Exceptional Section - ====================== - - This is an ordinary paragraph. - - .. class:: multiple - - First paragraph. - - Second paragraph. - -The text above is parsed and transformed into this doctree fragment:: - - <paragraph class="special"> - This is a "special" paragraph. - <section class="exceptional remarkable"> - <title> - An Exceptional Section - <paragraph> - This is an ordinary paragraph. - <paragraph class="multiple"> - First paragraph. - <paragraph class="multiple"> - Second paragraph. - -.. [#] To set a "class" attribute value on a block quote, the "class" - directive must be followed by an empty comment:: - - .. class:: highlights - .. - - Block quote text. - - The directive doesn't allow content, therefore an empty comment is - required to terminate the directive. Without the empty comment, - the block quote text would be interpreted as the "class" - directive's content, and the parser would complain. - -.. topic:: Rationale for Class Attribute Value Conversion - - Docutils identifiers are converted to conform to the regular - expression ``[a-z](-?[a-z0-9]+)*``. For CSS compatibility, - identifiers (the "class" and "id" attributes) should have no - underscores, colons, or periods. Hyphens may be used. - - - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens: - - ID and NAME tokens must begin with a letter ([A-Za-z]) and - may be followed by any number of letters, digits ([0-9]), - hyphens ("-"), underscores ("_"), colons (":"), and periods - ("."). - - - However the `CSS1 spec`_ defines identifiers based on the "name" - token, a tighter interpretation ("flex" tokenizer notation - below; "latin1" and "escape" 8-bit characters have been replaced - with entities):: - - unicode \\[0-9a-f]{1,4} - latin1 [¡-ÿ] - escape {unicode}|\\[ -~¡-ÿ] - nmchar [-a-z0-9]|{latin1}|{escape} - name {nmchar}+ - - The CSS1 "nmchar" rule does not include underscores ("_"), colons - (":"), or periods ("."), therefore "class" and "id" attributes - should not contain these characters. They should be replaced with - hyphens ("-"). Combined with HTML's requirements (the first - character must be a letter; no "unicode", "latin1", or "escape" - characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern. - - .. _HTML 4.01 spec: http://www.w3.org/TR/html401/ - .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 - - -.. _role: - -Custom Interpreted Text Roles -============================= - -:Directive Type: "role" -:Doctree Element: None; affects subsequent parsing. -:Directive Arguments: Two; one required (new role name), one optional - (base role name, in parentheses). -:Directive Options: Possible (depends on base role). -:Directive Content: depends on base role. - -(New in Docutils 0.3.2) - -The "role" directive dynamically creates a custom interpreted text -role and registers it with the parser. This means that after -declaring a role like this:: - - .. role:: custom - -the document may use the new "custom" role:: - - An example of using :custom:`interpreted text` - -This will be parsed into the following document tree fragment:: - - <paragraph> - An example of using - <inline class="custom"> - interpreted text - -The role must be declared in a document before it can be used. - -The new role may be based on an existing role, specified as a second -argument in parentheses (whitespace optional):: - - .. role:: custom(emphasis) - - :custom:`text` - -The parsed result is as follows:: - - <paragraph> - <emphasis class="custom"> - text - -If no base role is explicitly specified, a generic custom role is -automatically used. Subsequent interpreted text will produce an -"inline" element with a "class" attribute, as in the first example -above. - -With most roles, the ":class:" option can be used to set a "class" -attribute that is different from the role name. For example:: - - .. role:: custom - :class: special - - :custom:`interpreted text` - -This is the parsed result:: - - <paragraph> - <inline class="special"> - interpreted text - -.. _role class: - -The following option is recognized by the "role" directive for most -base roles: - -``class`` : text - Set a "class" attribute value on the element produced (``inline``, - or element associated with a base class) when the custom - interpreted text role is used. If no directive options are - specified, a "class" option with the directive argument (role - name) as the value is implied. See the class_ directive above. - -Specific base roles may support other options and/or directive -content. See the `reStructuredText Interpreted Text Roles`_ document -for details. - -.. _reStructuredText Interpreted Text Roles: roles.html - - -.. _default-role: - -Setting the Default Interpreted Text Role -========================================= - -:Directive Type: "default-role" -:Doctree Element: None; affects subsequent parsing. -:Directive Arguments: One, optional (new default role name). -:Directive Options: None. -:Directive Content: None. - -(New in Docutils 0.3.10) - -The "default-role" directive sets the default interpreted text role, -the role that is used for interpreted text without an explicit role. -For example, after setting the default role like this:: - - .. default-role:: subscript - -any subsequent use of implicit-role interpreted text in the document -will use the "subscript" role:: - - An example of a `default` role. - -This will be parsed into the following document tree fragment:: - - <paragraph> - An example of a - <subscript> - default - role. - -Custom roles may be used (see the "role_" directive above), but it -must have been declared in a document before it can be set as the -default role. See the `reStructuredText Interpreted Text Roles`_ -document for details of built-in roles. - -The directive may be used without an argument to restore the initial -default interpreted text role, which is application-dependent. The -initial default interpreted text role of the standard reStructuredText -parser is "title-reference". - - -.. _title: - -Metadata Document Title -======================= - -:Directive Type: "title" -:Doctree Element: None. -:Directive Arguments: 1, required (the title text). -:Directive Options: None. -:Directive Content: None. - -The "title" directive specifies the document title as metadata, which -does not become part of the document body. It overrides a -document-supplied title. For example, in HTML output the metadata -document title appears in the title bar of the browser window. - - -Restructuredtext-Test-Directive -=============================== - -:Directive Type: "restructuredtext-test-directive" -:Doctree Element: system_warning -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as a literal block. - -This directive is provided for test purposes only. (Nobody is -expected to type in a name *that* long!) It is converted into a -level-1 (info) system message showing the directive data, possibly -followed by a literal block containing the rest of the directive -block. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/introduction.txt b/docutils/docs/ref/rst/introduction.txt deleted file mode 100644 index b7829816e..000000000 --- a/docutils/docs/ref/rst/introduction.txt +++ /dev/null @@ -1,314 +0,0 @@ -===================================== - An Introduction to reStructuredText -===================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get -plaintext markup syntax and parser system. It is useful for inline -program documentation (such as Python docstrings), for quickly -creating simple web pages, and for standalone documents. -reStructuredText_ is a proposed revision and reinterpretation of the -StructuredText_ and Setext_ lightweight markup systems. - -reStructuredText is designed for extensibility for specific -application domains. Its parser is a component of Docutils_. - -This document defines the goals_ of reStructuredText and provides a -history_ of the project. It is written using the reStructuredText -markup, and therefore serves as an example of its use. For a gentle -introduction to using reStructuredText, please read `A -ReStructuredText Primer`_. The `Quick reStructuredText`_ user -reference is also useful. The `reStructuredText Markup -Specification`_ is the definitive reference. There is also an -analysis of the `Problems With StructuredText`_. - -ReStructuredText's web page is -http://docutils.sourceforge.net/rst.html. - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _A ReStructuredText Primer: ../../user/rst/quickstart.html -.. _Quick reStructuredText: ../../user/rst/quickref.html -.. _reStructuredText Markup Specification: restructuredtext.html -.. _Problems with StructuredText: ../../dev/rst/problems.html - - -Goals -===== - -The primary goal of reStructuredText_ is to define a markup syntax for -use in Python docstrings and other documentation domains, that is -readable and simple, yet powerful enough for non-trivial use. The -intended purpose of the reStructuredText markup is twofold: - -- the establishment of a set of standard conventions allowing the - expression of structure within plaintext, and - -- the conversion of such documents into useful structured data - formats. - -The secondary goal of reStructuredText is to be accepted by the Python -community (by way of being blessed by PythonLabs and the BDFL [#]_) as -a standard for Python inline documentation (possibly one of several -standards, to account for taste). - -.. [#] Python's creator and "Benevolent Dictator For Life", - Guido van Rossum. - -To clarify the primary goal, here are specific design goals, in order, -beginning with the most important: - -1. Readable. The marked-up text must be easy to read without any - prior knowledge of the markup language. It should be as easily - read in raw form as in processed form. - -2. Unobtrusive. The markup that is used should be as simple and - unobtrusive as possible. The simplicity of markup constructs - should be roughly proportional to their frequency of use. The most - common constructs, with natural and obvious markup, should be the - simplest and most unobtrusive. Less common constructs, for which - there is no natural or obvious markup, should be distinctive. - -3. Unambiguous. The rules for markup must not be open for - interpretation. For any given input, there should be one and only - one possible output (including error output). - -4. Unsurprising. Markup constructs should not cause unexpected output - upon processing. As a fallback, there must be a way to prevent - unwanted markup processing when a markup construct is used in a - non-markup context (for example, when documenting the markup syntax - itself). - -5. Intuitive. Markup should be as obvious and easily remembered as - possible, for the author as well as for the reader. Constructs - should take their cues from such naturally occurring sources as - plaintext email messages, newsgroup postings, and text - documentation such as README.txt files. - -6. Easy. It should be easy to mark up text using any ordinary text - editor. - -7. Scalable. The markup should be applicable regardless of the length - of the text. - -8. Powerful. The markup should provide enough constructs to produce a - reasonably rich structured document. - -9. Language-neutral. The markup should apply to multiple natural (as - well as artificial) languages, not only English. - -10. Extensible. The markup should provide a simple syntax and - interface for adding more complex general markup, and custom - markup. - -11. Output-format-neutral. The markup will be appropriate for - processing to multiple output formats, and will not be biased - toward any particular format. - -The design goals above were used as criteria for accepting or -rejecting syntax, or selecting between alternatives. - -It is emphatically *not* the goal of reStructuredText to define -docstring semantics, such as docstring contents or docstring length. -These issues are orthogonal to the markup syntax and beyond the scope -of this specification. - -Also, it is not the goal of reStructuredText to maintain compatibility -with StructuredText_ or Setext_. reStructuredText shamelessly steals -their great ideas and ignores the not-so-great. - -Author's note: - - Due to the nature of the problem we're trying to solve (or, - perhaps, due to the nature of the proposed solution), the above - goals unavoidably conflict. I have tried to extract and distill - the wisdom accumulated over the years in the Python Doc-SIG_ - mailing list and elsewhere, to come up with a coherent and - consistent set of syntax rules, and the above goals by which to - measure them. - - There will inevitably be people who disagree with my particular - choices. Some desire finer control over their markup, others - prefer less. Some are concerned with very short docstrings, - others with full-length documents. This specification is an - effort to provide a reasonably rich set of markup constructs in a - reasonably simple form, that should satisfy a reasonably large - group of reasonable people. - - David Goodger (goodger@users.sourceforge.net), 2001-04-20 - -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - - -History -======= - -reStructuredText_, the specification, is based on StructuredText_ and -Setext_. StructuredText was developed by Jim Fulton of `Zope -Corporation`_ (formerly Digital Creations) and first released in 1996. -It is now released as a part of the open-source "Z Object Publishing -Environment" (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ -specification was either an influence on StructuredText or, by their -similarities, at least evidence of the correctness of this approach. - -I discovered StructuredText_ in late 1999 while searching for a way to -document the Python modules in one of my projects. Version 1.1 of -StructuredText was included in Daniel Larsson's pythondoc_. Although -I was not able to get pythondoc to work for me, I found StructuredText -to be almost ideal for my needs. I joined the Python Doc-SIG_ -(Documentation Special Interest Group) mailing list and found an -ongoing discussion of the shortcomings of the StructuredText -"standard". This discussion has been going on since the inception of -the mailing list in 1996, and possibly predates it. - -I decided to modify the original module with my own extensions and -some suggested by the Doc-SIG members. I soon realized that the -module was not written with extension in mind, so I embarked upon a -general reworking, including adapting it to the "re" regular -expression module (the original inspiration for the name of this -project). Soon after I completed the modifications, I discovered that -StructuredText.py was up to version 1.23 in the ZOPE distribution. -Implementing the new syntax extensions from version 1.23 proved to be -an exercise in frustration, as the complexity of the module had become -overwhelming. - -In 2000, development on StructuredTextNG_ ("Next Generation") began at -`Zope Corporation`_ (then Digital Creations). It seems to have many -improvements, but still suffers from many of the problems of classic -StructuredText. - -I decided that a complete rewrite was in order, and even started a -`reStructuredText SourceForge project`_ (now inactive). My -motivations (the "itches" I aim to "scratch") are as follows: - -- I need a standard format for inline documentation of the programs I - write. This inline documentation has to be convertible to other - useful formats, such as HTML. I believe many others have the same - need. - -- I believe in the Setext/StructuredText idea and want to help - formalize the standard. However, I feel the current specifications - and implementations have flaws that desperately need fixing. - -- reStructuredText could form part of the foundation for a - documentation extraction and processing system, greatly benefitting - Python. But it is only a part, not the whole. reStructuredText is - a markup language specification and a reference parser - implementation, but it does not aspire to be the entire system. I - don't want reStructuredText or a hypothetical Python documentation - processor to die stillborn because of over-ambition. - -- Most of all, I want to help ease the documentation chore, the bane - of many a programmer. - -Unfortunately I was sidetracked and stopped working on this project. -In November 2000 I made the time to enumerate the problems of -StructuredText and possible solutions, and complete the first draft of -a specification. This first draft was posted to the Doc-SIG in three -parts: - -- `A Plan for Structured Text`__ -- `Problems With StructuredText`__ -- `reStructuredText: Revised Structured Text Specification`__ - -__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html - -In March 2001 a flurry of activity on the Doc-SIG spurred me to -further revise and refine my specification, the result of which you -are now reading. An offshoot of the reStructuredText project has been -the realization that a single markup scheme, no matter how well -thought out, may not be enough. In order to tame the endless debates -on Doc-SIG, a flexible `Docstring Processing System framework`_ needed -to be constructed. This framework has become the more important of -the two projects; reStructuredText_ has found its place as one -possible choice for a single component of the larger framework. - -The project web site and the first project release were rolled out in -June 2001, including posting the second draft of the spec [#spec-2]_ -and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the -Doc-SIG. These documents and the project implementation proceeded to -evolve at a rapid pace. Implementation history details can be found -in the `project history file`_. - -In November 2001, the reStructuredText parser was nearing completion. -Development of the parser continued with the addition of small -convenience features, improvements to the syntax, the filling in of -gaps, and bug fixes. After a long holiday break, in early 2002 most -development moved over to the other Docutils components, the -"Readers", "Writers", and "Transforms". A "standalone" reader -(processes standalone text file documents) was completed in February, -and a basic HTML writer (producing HTML 4.01, using CSS-1) was -completed in early March. - -`PEP 287`_, "reStructuredText Standard Docstring Format", was created -to formally propose reStructuredText as a standard format for Python -docstrings, PEPs, and other files. It was first posted to -comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02. - -Version 0.4 of the reStructuredText__ and `Docstring Processing -System`_ projects were released in April 2002. The two projects were -immediately merged, renamed to "Docutils_", and a 0.1 release soon -followed. - -.. __: `reStructuredText SourceForge project`_ - -.. [#spec-2] The second draft of the spec: - - - `An Introduction to reStructuredText`__ - - `Problems With StructuredText`__ - - `reStructuredText Markup Specification`__ - - `Python Extensions to the reStructuredText Markup - Specification`__ - - __ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html - -.. [#peps-1] First drafts of the PEPs: - - - `PEP 256: Docstring Processing System Framework`__ - - `PEP 258: DPS Generic Implementation Details`__ - - `PEP 257: Docstring Conventions`__ - - Current working versions of the PEPs can be found in - http://docutils.sourceforge.net/docs/peps/, and official versions - can be found in the `master PEP repository`_. - - __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html - - -.. _Zope Corporation: http://www.zope.com -.. _ZOPE: http://www.zope.org -.. _reStructuredText SourceForge project: - http://structuredtext.sourceforge.net/ -.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ -.. _StructuredTextNG: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG -.. _project history file: ../../../HISTORY.html -.. _PEP 287: ../../peps/pep-0287.html -.. _Docstring Processing System framework: ../../peps/pep-0256.html -.. _comp.lang.python: news:comp.lang.python -.. _Python-dev: http://mail.python.org/pipermail/python-dev/ -.. _Docstring Processing System: http://docstring.sourceforge.net/ -.. _master PEP repository: http://www.python.org/peps/ - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt deleted file mode 100644 index 1445619b3..000000000 --- a/docutils/docs/ref/rst/restructuredtext.txt +++ /dev/null @@ -1,2879 +0,0 @@ -======================================= - reStructuredText Markup Specification -======================================= -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. Note:: - - This document is a detailed technical specification; it is not a - tutorial or a primer. If this is your first exposure to - reStructuredText, please read `A ReStructuredText Primer`_ and the - `Quick reStructuredText`_ user reference first. - -.. _A ReStructuredText Primer: ../../user/rst/quickstart.html -.. _Quick reStructuredText: ../../user/rst/quickref.html - - -reStructuredText_ is plaintext that uses simple and intuitive -constructs to indicate the structure of a document. These constructs -are equally easy to read in raw and processed forms. This document is -itself an example of reStructuredText (raw, if you are reading the -text file, or processed, if you are reading an HTML document, for -example). The reStructuredText parser is a component of Docutils_. - -Simple, implicit markup is used to indicate special constructs, such -as section headings, bullet lists, and emphasis. The markup used is -as minimal and unobtrusive as possible. Less often-used constructs -and extensions to the basic reStructuredText syntax may have more -elaborate or explicit markup. - -reStructuredText is applicable to documents of any length, from the -very small (such as inline program documentation fragments, e.g. -Python docstrings) to the quite large (this document). - -The first section gives a quick overview of the syntax of the -reStructuredText markup by example. A complete specification is given -in the `Syntax Details`_ section. - -`Literal blocks`_ (in which no markup processing is done) are used for -examples throughout this document, to illustrate the plaintext markup. - - -.. contents:: - - ------------------------ - Quick Syntax Overview ------------------------ - -A reStructuredText document is made up of body or block-level -elements, and may be structured into sections. Sections_ are -indicated through title style (underlines & optional overlines). -Sections contain body elements and/or subsections. Some body elements -contain further elements, such as lists containing list items, which -in turn may contain paragraphs and other body elements. Others, such -as paragraphs, contain text and `inline markup`_ elements. - -Here are examples of `body elements`_: - -- Paragraphs_ (and `inline markup`_):: - - Paragraphs contain text and may contain inline markup: - *emphasis*, **strong emphasis**, `interpreted text`, ``inline - literals``, standalone hyperlinks (http://www.python.org), - external hyperlinks (Python_), internal cross-references - (example_), footnote references ([1]_), citation references - ([CIT2002]_), substitution references (|example|), and _`inline - internal targets`. - - Paragraphs are separated by blank lines and are left-aligned. - -- Five types of lists: - - 1. `Bullet lists`_:: - - - This is a bullet list. - - - Bullets can be "-", "*", or "+". - - 2. `Enumerated lists`_:: - - 1. This is an enumerated list. - - 2. Enumerators may be arabic numbers, letters, or roman - numerals. - - 3. `Definition lists`_:: - - what - Definition lists associate a term with a definition. - - how - The term is a one-line phrase, and the definition is one - or more paragraphs or body elements, indented relative to - the term. - - 4. `Field lists`_:: - - :what: Field lists map field names to field bodies, like - database records. They are often part of an extension - syntax. - - :how: The field marker is a colon, the field name, and a - colon. - - The field body may contain one or more body elements, - indented relative to the field marker. - - 5. `Option lists`_, for listing command-line options:: - - -a command-line option "a" - -b file options can have arguments - and long descriptions - --long options can be long also - --input=file long options can also have - arguments - /V DOS/VMS-style options too - - There must be at least two spaces between the option and the - description. - -- `Literal blocks`_:: - - Literal blocks are either indented or line-prefix-quoted blocks, - and indicated with a double-colon ("::") at the end of the - preceding paragraph (right here -->):: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -- `Block quotes`_:: - - Block quotes consist of indented body elements: - - This theory, that is mine, is mine. - - -- Anne Elk (Miss) - -- `Doctest blocks`_:: - - >>> print 'Python-specific usage examples; begun with ">>>"' - Python-specific usage examples; begun with ">>>" - >>> print '(cut and pasted from interactive Python sessions)' - (cut and pasted from interactive Python sessions) - -- Two syntaxes for tables_: - - 1. `Grid tables`_; complete, but complex and verbose:: - - +------------------------+------------+----------+ - | Header row, column 1 | Header 2 | Header 3 | - +========================+============+==========+ - | body row 1, column 1 | column 2 | column 3 | - +------------------------+------------+----------+ - | body row 2 | Cells may span | - +------------------------+-----------------------+ - - 2. `Simple tables`_; easy and compact, but limited:: - - ==================== ========== ========== - Header row, column 1 Header 2 Header 3 - ==================== ========== ========== - body row 1, column 1 column 2 column 3 - body row 2 Cells may span columns - ==================== ====================== - -- `Explicit markup blocks`_ all begin with an explicit block marker, - two periods and a space: - - - Footnotes_:: - - .. [1] A footnote contains body elements, consistently - indented by at least 3 spaces. - - - Citations_:: - - .. [CIT2002] Just like a footnote, except the label is - textual. - - - `Hyperlink targets`_:: - - .. _Python: http://www.python.org - - .. _example: - - The "_example" target above points to this paragraph. - - - Directives_:: - - .. image:: mylogo.png - - - `Substitution definitions`_:: - - .. |symbol here| image:: symbol.png - - - Comments_:: - - .. Comments begin with two dots and a space. Anything may - follow, except for the syntax of footnotes/citations, - hyperlink targets, directives, or substitution definitions. - - ----------------- - Syntax Details ----------------- - -Descriptions below list "doctree elements" (document tree element -names; XML DTD generic identifiers) corresponding to syntax -constructs. For details on the hierarchy of elements, please see `The -Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. - - -Whitespace -========== - -Spaces are recommended for indentation_, but tabs may also be used. -Tabs will be converted to spaces. Tab stops are at every 8th column. - -Other whitespace characters (form feeds [chr(12)] and vertical tabs -[chr(11)]) are converted to single spaces before processing. - - -Blank Lines ------------ - -Blank lines are used to separate paragraphs and other elements. -Multiple successive blank lines are equivalent to a single blank line, -except within literal blocks (where all whitespace is preserved). -Blank lines may be omitted when the markup makes element separation -unambiguous, in conjunction with indentation. The first line of a -document is treated as if it is preceded by a blank line, and the last -line of a document is treated as if it is followed by a blank line. - - -Indentation ------------ - -Indentation is used to indicate -- and is only significant in -indicating -- block quotes, definitions (in definition list items), -and local nested content: - -- list item content (multi-line contents of list items, and multiple - body elements within a list item, including nested lists), -- the content of literal blocks, and -- the content of explicit markup blocks. - -Any text whose indentation is less than that of the current level -(i.e., unindented text or "dedents") ends the current level of -indentation. - -Since all indentation is significant, the level of indentation must be -consistent. For example, indentation is the sole markup indicator for -`block quotes`_:: - - This is a top-level paragraph. - - This paragraph belongs to a first-level block quote. - - Paragraph 2 of the first-level block quote. - -Multiple levels of indentation within a block quote will result in -more complex structures:: - - This is a top-level paragraph. - - This paragraph belongs to a first-level block quote. - - This paragraph belongs to a second-level block quote. - - Another top-level paragraph. - - This paragraph belongs to a second-level block quote. - - This paragraph belongs to a first-level block quote. The - second-level block quote above is inside this first-level - block quote. - -When a paragraph or other construct consists of more than one line of -text, the lines must be left-aligned:: - - This is a paragraph. The lines of - this paragraph are aligned at the left. - - This paragraph has problems. The - lines are not left-aligned. In addition - to potential misinterpretation, warning - and/or error messages will be generated - by the parser. - -Several constructs begin with a marker, and the body of the construct -must be indented relative to the marker. For constructs using simple -markers (`bullet lists`_, `enumerated lists`_, footnotes_, citations_, -`hyperlink targets`_, directives_, and comments_), the level of -indentation of the body is determined by the position of the first -line of text, which begins on the same line as the marker. For -example, bullet list bodies must be indented by at least two columns -relative to the left edge of the bullet:: - - - This is the first line of a bullet list - item's paragraph. All lines must align - relative to the first line. [1]_ - - This indented paragraph is interpreted - as a block quote. - - Because it is not sufficiently indented, - this paragraph does not belong to the list - item. - - .. [1] Here's a footnote. The second line is aligned - with the beginning of the footnote label. The ".." - marker is what determines the indentation. - -For constructs using complex markers (`field lists`_ and `option -lists`_), where the marker may contain arbitrary text, the indentation -of the first line *after* the marker determines the left edge of the -body. For example, field lists may have very long markers (containing -the field names):: - - :Hello: This field has a short field name, so aligning the field - body with the first line is feasible. - - :Number-of-African-swallows-required-to-carry-a-coconut: It would - be very difficult to align the field body with the left edge - of the first line. It may even be preferable not to begin the - body on the same line as the marker. - - -Escaping Mechanism -================== - -The character set universally available to plaintext documents, 7-bit -ASCII, is limited. No matter what characters are used for markup, -they will already have multiple meanings in written text. Therefore -markup characters *will* sometimes appear in text **without being -intended as markup**. Any serious markup system requires an escaping -mechanism to override the default meaning of the characters used for -the markup. In reStructuredText we use the backslash, commonly used -as an escaping character in other domains. - -A backslash followed by any character (except whitespace characters) -escapes that character. The escaped character represents the -character itself, and is prevented from playing a role in any markup -interpretation. The backslash is removed from the output. A literal -backslash is represented by two backslashes in a row (the first -backslash "escapes" the second, preventing it being interpreted in an -"escaping" role). - -Backslash-escaped whitespace characters are removed from the document. -This allows for character-level `inline markup`_. - -There are two contexts in which backslashes have no special meaning: -literal blocks and inline literals. In these contexts, a single -backslash represents a literal backslash, without having to double up. - -Please note that the reStructuredText specification and parser do not -address the issue of the representation or extraction of text input -(how and in what form the text actually *reaches* the parser). -Backslashes and other characters may serve a character-escaping -purpose in certain contexts and must be dealt with appropriately. For -example, Python uses backslashes in strings to escape certain -characters, but not others. The simplest solution when backslashes -appear in Python docstrings is to use raw docstrings:: - - r"""This is a raw docstring. Backslashes (\) are not touched.""" - - -Reference Names -=============== - -Simple reference names are single words consisting of alphanumerics -plus isolated (no two adjacent) internal hyphens, underscores, and -periods; no whitespace or other characters are allowed. Footnote -labels (Footnotes_ & `Footnote References`_), citation labels -(Citations_ & `Citation References`_), `interpreted text`_ roles, and -some `hyperlink references`_ use the simple reference name syntax. - -Reference names using punctuation or whose names are phrases (two or -more space-separated words) are called "phrase-references". -Phrase-references are expressed by enclosing the phrase in backquotes -and treating the backquoted text as a reference name:: - - Want to learn about `my favorite programming language`_? - - .. _my favorite programming language: http://www.python.org - -Simple reference names may also optionally use backquotes. - -Reference names are whitespace-neutral and case-insensitive. When -resolving reference names internally: - -- whitespace is normalized (one or more spaces, horizontal or vertical - tabs, newlines, carriage returns, or form feeds, are interpreted as - a single space), and - -- case is normalized (all alphabetic characters are converted to - lowercase). - -For example, the following `hyperlink references`_ are equivalent:: - - - `A HYPERLINK`_ - - `a hyperlink`_ - - `A - Hyperlink`_ - -Hyperlinks_, footnotes_, and citations_ all share the same namespace -for reference names. The labels of citations (simple reference names) -and manually-numbered footnotes (numbers) are entered into the same -database as other hyperlink names. This means that a footnote -(defined as "``.. [1]``") which can be referred to by a footnote -reference (``[1]_``), can also be referred to by a plain hyperlink -reference (1_). Of course, each type of reference (hyperlink, -footnote, citation) may be processed and rendered differently. Some -care should be taken to avoid reference name conflicts. - - -Document Structure -================== - -Document --------- - -Doctree element: document. - -The top-level element of a parsed reStructuredText document is the -"document" element. After initial parsing, the document element is a -simple container for a document fragment, consisting of `body -elements`_, transitions_, and sections_, but lacking a document title -or other bibliographic elements. The code that calls the parser may -choose to run one or more optional post-parse transforms_, -rearranging the document fragment into a complete document with a -title and possibly other metadata elements (author, date, etc.; see -`Bibliographic Fields`_). - -Specifically, there is no way to indicate a document title and -subtitle explicitly in reStructuredText. Instead, a lone top-level -section title (see Sections_ below) can be treated as the document -title. Similarly, a lone second-level section title immediately after -the "document title" can become the document subtitle. The rest of -the sections are then lifted up a level or two. See the `DocTitle -transform`_ for details. - - -Sections --------- - -Doctree elements: section, title. - -Sections are identified through their titles, which are marked up with -adornment: "underlines" below the title text, or underlines and -matching "overlines" above the title. An underline/overline is a -single repeated punctuation character that begins in column 1 and -forms a line extending at least as far as the right edge of the title -text. Specifically, an underline/overline character may be any -non-alphanumeric printable 7-bit ASCII character [#]_. When an -overline is used, the length and character used must match the -underline. Underline-only adornment styles are distinct from -overline-and-underline styles that use the same character. There may -be any number of levels of section titles, although some output -formats may have limits (HTML has 6 levels). - -.. [#] The following are all valid section title adornment - characters:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - Some characters are more suitable than others. The following are - recommended:: - - = - ` : . ' " ~ ^ _ * + # - -Rather than imposing a fixed number and order of section title -adornment styles, the order enforced will be the order as encountered. -The first style encountered will be an outermost title (like HTML H1), -the second style will be a subtitle, the third will be a subsubtitle, -and so on. - -Below are examples of section title styles:: - - =============== - Section Title - =============== - - --------------- - Section Title - --------------- - - Section Title - ============= - - Section Title - ------------- - - Section Title - ````````````` - - Section Title - ''''''''''''' - - Section Title - ............. - - Section Title - ~~~~~~~~~~~~~ - - Section Title - ************* - - Section Title - +++++++++++++ - - Section Title - ^^^^^^^^^^^^^ - -When a title has both an underline and an overline, the title text may -be inset, as in the first two examples above. This is merely -aesthetic and not significant. Underline-only title text may *not* be -inset. - -A blank line after a title is optional. All text blocks up to the -next title of the same or higher level are included in a section (or -subsection, etc.). - -All section title styles need not be used, nor need any specific -section title style be used. However, a document must be consistent -in its use of section titles: once a hierarchy of title styles is -established, sections must use that hierarchy. - -Each section title automatically generates a hyperlink target pointing -to the section. The text of the hyperlink target (the "reference -name") is the same as that of the section title. See `Implicit -Hyperlink Targets`_ for a complete description. - -Sections may contain `body elements`_, transitions_, and nested -sections. - - -Transitions ------------ - -Doctree element: transition. - - Instead of subheads, extra space or a type ornament between - paragraphs may be used to mark text divisions or to signal - changes in subject or emphasis. - - (The Chicago Manual of Style, 14th edition, section 1.80) - -Transitions are commonly seen in novels and short fiction, as a gap -spanning one or more lines, with or without a type ornament such as a -row of asterisks. Transitions separate other body elements. A -transition should not begin or end a section or document, nor should -two transitions be immediately adjacent. - -The syntax for a transition marker is a horizontal line of 4 or more -repeated punctuation characters. The syntax is the same as section -title underlines without title text. Transition markers require blank -lines before and after:: - - Para. - - ---------- - - Para. - -Unlike section title underlines, no hierarchy of transition markers is -enforced, nor do differences in transition markers accomplish -anything. It is recommended that a single consistent style be used. - -The processing system is free to render transitions in output in any -way it likes. For example, horizontal rules (``<hr>``) in HTML output -would be an obvious choice. - - -Body Elements -============= - -Paragraphs ----------- - -Doctree element: paragraph. - -Paragraphs consist of blocks of left-aligned text with no markup -indicating any other body element. Blank lines separate paragraphs -from each other and from other body elements. Paragraphs may contain -`inline markup`_. - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | | - +------------------------------+ - - +------------------------------+ - | paragraph | - | | - +------------------------------+ - - -Bullet Lists ------------- - -Doctree elements: bullet_list, list_item. - -A text block which begins with a "-", "*", or "+", followed by -whitespace, is a bullet list item (a.k.a. "unordered" list item). -List item bodies must be left-aligned and indented relative to the -bullet; the text immediately after the bullet determines the -indentation. For example:: - - - This is the first bullet list item. The blank line above the - first list item is required; blank lines between list items - (such as below this paragraph) are optional. - - - This is the first paragraph in the second item in the list. - - This is the second paragraph in the second item in the list. - The blank line above this paragraph is required. The left edge - of this paragraph lines up with the paragraph above, both - indented relative to the bullet. - - - This is a sublist. The bullet lines up with the left edge of - the text blocks above. A sublist is a new list so requires a - blank line above and below. - - - This is the third item of the main list. - - This paragraph is not part of the list. - -Here are examples of **incorrectly** formatted bullet lists:: - - - This first line is fine. - A blank line is required between list items and paragraphs. - (Warning) - - - The following line appears to be a new sublist, but it is not: - - This is a paragraph continuation, not a sublist (since there's - no blank line). This line is also incorrectly indented. - - Warnings may be issued by the implementation. - -Syntax diagram:: - - +------+-----------------------+ - | "- " | list item | - +------| (body elements)+ | - +-----------------------+ - - -Enumerated Lists ----------------- - -Doctree elements: enumerated_list, list_item. - -Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, -but use enumerators instead of bullets. An enumerator consists of an -enumeration sequence member and formatting, followed by whitespace. -The following enumeration sequences are recognized: - -- arabic numerals: 1, 2, 3, ... (no upper limit). -- uppercase alphabet characters: A, B, C, ..., Z. -- lower-case alphabet characters: a, b, c, ..., z. -- uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999). -- lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999). - -In addition, the auto-enumerator, "#", may be used to automatically -enumerate a list. Auto-enumerated lists may begin with explicit -enumeration, which sets the sequence. Fully auto-enumerated lists use -arabic numerals and begin with 1. (Auto-enumerated lists are new in -Docutils 0.3.8.) - -The following formatting types are recognized: - -- suffixed with a period: "1.", "A.", "a.", "I.", "i.". -- surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)". -- suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)". - -While parsing an enumerated list, a new list will be started whenever: - -- An enumerator is encountered which does not have the same format and - sequence type as the current list (e.g. "1.", "(a)" produces two - separate lists). - -- The enumerators are not in sequence (e.g., "1.", "3." produces two - separate lists). - -It is recommended that the enumerator of the first list item be -ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values -will be recognized, they may not be supported by the output format. A -level-1 [info] system message will be generated for any list beginning -with a non-ordinal-1 enumerator. - -Lists using Roman numerals must begin with "I"/"i" or a -multi-character value, such as "II" or "XV". Any other -single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be -interpreted as a letter of the alphabet, not as a Roman numeral. -Likewise, lists using letters of the alphabet may not begin with -"I"/"i", since these are recognized as Roman numeral 1. - -The second line of each enumerated list item is checked for validity. -This is to prevent ordinary paragraphs from being mistakenly -interpreted as list items, when they happen to begin with text -identical to enumerators. For example, this text is parsed as an -ordinary paragraph:: - - A. Einstein was a really - smart dude. - -However, ambiguity cannot be avoided if the paragraph consists of only -one line. This text is parsed as an enumerated list item:: - - A. Einstein was a really smart dude. - -If a single-line paragraph begins with text identical to an enumerator -("A.", "1.", "(b)", "I)", etc.), the first character will have to be -escaped in order to have the line parsed as an ordinary paragraph:: - - \A. Einstein was a really smart dude. - -Examples of nested enumerated lists:: - - 1. Item 1 initial text. - - a) Item 1a. - b) Item 1b. - - 2. a) Item 2a. - b) Item 2b. - -Example syntax diagram:: - - +-------+----------------------+ - | "1. " | list item | - +-------| (body elements)+ | - +----------------------+ - - -Definition Lists ----------------- - -Doctree elements: definition_list, definition_list_item, term, -classifier, definition. - -Each definition list item contains a term, optional classifiers, and a -definition. A term is a simple one-line word or phrase. Optional -classifiers may follow the term on the same line, each after an inline -" : " (space, colon, space). A definition is a block indented -relative to the term, and may contain multiple paragraphs and other -body elements. There may be no blank line between a term line and a -definition block (this distinguishes definition lists from `block -quotes`_). Blank lines are required before the first and after the -last definition list item, but are optional in-between. For example:: - - term 1 - Definition 1. - - term 2 - Definition 2, paragraph 1. - - Definition 2, paragraph 2. - - term 3 : classifier - Definition 3. - - term 4 : classifier one : classifier two - Definition 4. - -Inline markup is parsed in the term line before the classifier -delimiter (" : ") is recognized. The delimiter will only be -recognized if it appears outside of any inline markup. - -A definition list may be used in various ways, including: - -- As a dictionary or glossary. The term is the word itself, a - classifier may be used to indicate the usage of the term (noun, - verb, etc.), and the definition follows. - -- To describe program variables. The term is the variable name, a - classifier may be used to indicate the type of the variable (string, - integer, etc.), and the definition describes the variable's use in - the program. This usage of definition lists supports the classifier - syntax of Grouch_, a system for describing and enforcing a Python - object schema. - -Syntax diagram:: - - +----------------------------+ - | term [ " : " classifier ]* | - +--+-------------------------+--+ - | definition | - | (body elements)+ | - +----------------------------+ - - -Field Lists ------------ - -Doctree elements: field_list, field, field_name, field_body. - -Field lists are used as part of an extension syntax, such as options -for directives_, or database-like records meant for further -processing. They may also be used for two-column table-like -structures resembling database records (label & data pairs). -Applications of reStructuredText may recognize field names and -transform fields or field bodies in certain contexts. For examples, -see `Bibliographic Fields`_ below, or the "image_" and "meta_" -directives in `reStructuredText Directives`_. - -Field lists are mappings from field names to field bodies, modeled on -RFC822_ headers. A field name may consist of any characters, but -colons (":") inside of field names must be escaped with a backslash. -Inline markup is parsed in field names. Field names are -case-insensitive when further processed or transformed. The field -name, along with a single colon prefix and suffix, together form the -field marker. The field marker is followed by whitespace and the -field body. The field body may contain multiple body elements, -indented relative to the field marker. The first line after the field -name marker determines the indentation of the field body. For -example:: - - :Date: 2001-08-16 - :Version: 1 - :Authors: - Me - - Myself - - I - :Indentation: Since the field marker may be quite long, the second - and subsequent lines of the field body do not have to line up - with the first line, but they must be indented relative to the - field name marker, and they must line up with each other. - :Parameter i: integer - -The interpretation of individual words in a multi-word field name is -up to the application. The application may specify a syntax for the -field name. For example, second and subsequent words may be treated -as "arguments", quoted phrases may be treated as a single argument, -and direct support for the "name=value" syntax may be added. - -Standard RFC822_ headers cannot be used for this construct because -they are ambiguous. A word followed by a colon at the beginning of a -line is common in written text. However, in well-defined contexts -such as when a field list invariably occurs at the beginning of a -document (PEPs and email messages), standard RFC822 headers could be -used. - -Syntax diagram (simplified):: - - +--------------------+----------------------+ - | ":" field name ":" | field body | - +-------+------------+ | - | (body elements)+ | - +-----------------------------------+ - - -Bibliographic Fields -```````````````````` - -Doctree elements: docinfo, author, authors, organization, contact, -version, status, date, copyright, field, topic. - -When a field list is the first non-comment element in a document -(after the document title, if there is one), it may have its fields -transformed to document bibliographic data. This bibliographic data -corresponds to the front matter of a book, such as the title page and -copyright page. - -Certain registered field names (listed below) are recognized and -transformed to the corresponding doctree elements, most becoming child -elements of the "docinfo" element. No ordering is required of these -fields, although they may be rearranged to fit the document structure, -as noted. Unless otherwise indicated below, each of the bibliographic -elements' field bodies may contain a single paragraph only. Field -bodies may be checked for `RCS keywords`_ and cleaned up. Any -unrecognized fields will remain as generic fields in the docinfo -element. - -The registered bibliographic field names and their corresponding -doctree elements are as follows: - -- Field name "Author": author element. -- "Authors": authors. -- "Organization": organization. -- "Contact": contact. -- "Address": address. -- "Version": version. -- "Status": status. -- "Date": date. -- "Copyright": copyright. -- "Dedication": topic. -- "Abstract": topic. - -The "Authors" field may contain either: a single paragraph consisting -of a list of authors, separated by ";" or ","; or a bullet list whose -elements each contain a single paragraph per author. ";" is checked -first, so "Doe, Jane; Doe, John" will work. In some languages -(e.g. Swedish), there is no singular/plural distinction between -"Author" and "Authors", so only an "Authors" field is provided, and a -single name is interpreted as an "Author". If a single name contains -a comma, end it with a semicolon to disambiguate: ":Authors: Doe, -Jane;". - -The "Address" field is for a multi-line surface mailing address. -Newlines and whitespace will be preserved. - -The "Dedication" and "Abstract" fields may contain arbitrary body -elements. Only one of each is allowed. They become topic elements -with "Dedication" or "Abstract" titles (or language equivalents) -immediately following the docinfo element. - -This field-name-to-element mapping can be replaced for other -languages. See the `DocInfo transform`_ implementation documentation -for details. - -Unregistered/generic fields may contain one or more paragraphs or -arbitrary body elements. - - -RCS Keywords -```````````` - -`Bibliographic fields`_ recognized by the parser are normally checked -for RCS [#]_ keywords and cleaned up [#]_. RCS keywords may be -entered into source files as "$keyword$", and once stored under RCS or -CVS [#]_, they are expanded to "$keyword: expansion text $". For -example, a "Status" field will be transformed to a "status" element:: - - :Status: $keyword: expansion text $ - -.. [#] Revision Control System. -.. [#] RCS keyword processing can be turned off (unimplemented). -.. [#] Concurrent Versions System. CVS uses the same keywords as RCS. - -Processed, the "status" element's text will become simply "expansion -text". The dollar sign delimiters and leading RCS keyword name are -removed. - -The RCS keyword processing only kicks in when the field list is in -bibliographic context (first non-comment construct in the document, -after a document title if there is one). - - -Option Lists ------------- - -Doctree elements: option_list, option_list_item, option_group, option, -option_string, option_argument, description. - -Option lists are two-column lists of command-line options and -descriptions, documenting a program's options. For example:: - - -a Output all. - -b Output both (this description is - quite long). - -c arg Output just arg. - --long Output all day long. - - -p This option has two paragraphs in the description. - This is the first. - - This is the second. Blank lines may be omitted between - options (as above) or left in (as here and below). - - --very-long-option A VMS-style option. Note the adjustment for - the required two spaces. - - --an-even-longer-option - The description can also start on the next line. - - -2, --two This option has two variants. - - -f FILE, --file=FILE These two options are synonyms; both have - arguments. - - /V A VMS/DOS-style option. - -There are several types of options recognized by reStructuredText: - -- Short POSIX options consist of one dash and an option letter. -- Long POSIX options consist of two dashes and an option word; some - systems use a single dash. -- Old GNU-style "plus" options consist of one plus and an option - letter ("plus" options are deprecated now, their use discouraged). -- DOS/VMS options consist of a slash and an option letter or word. - -Please note that both POSIX-style and DOS/VMS-style options may be -used by DOS or Windows software. These and other variations are -sometimes used mixed together. The names above have been chosen for -convenience only. - -The syntax for short and long POSIX options is based on the syntax -supported by Python's getopt.py_ module, which implements an option -parser similar to the `GNU libc getopt_long()`_ function but with some -restrictions. There are many variant option systems, and -reStructuredText option lists do not support all of them. - -Although long POSIX and DOS/VMS option words may be allowed to be -truncated by the operating system or the application when used on the -command line, reStructuredText option lists do not show or support -this with any special syntax. The complete option word should be -given, supported by notes about truncation if and when applicable. - -Options may be followed by an argument placeholder, whose role and -syntax should be explained in the description text. Either a space or -an equals sign may be used as a delimiter between options and option -argument placeholders; short options ("-" or "+" prefix only) may omit -the delimiter. Option arguments may take one of two forms: - -- Begins with a letter (``[a-zA-Z]``) and subsequently consists of - letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``). -- Begins with an open-angle-bracket (``<``) and ends with a - close-angle-bracket (``>``); any characters except angle brackets - are allowed internally. - -Multiple option "synonyms" may be listed, sharing a single -description. They must be separated by comma-space. - -There must be at least two spaces between the option(s) and the -description. The description may contain multiple body elements. The -first line after the option marker determines the indentation of the -description. As with other types of lists, blank lines are required -before the first option list item and after the last, but are optional -between option entries. - -Syntax diagram (simplified):: - - +----------------------------+-------------+ - | option [" " argument] " " | description | - +-------+--------------------+ | - | (body elements)+ | - +----------------------------------+ - - -Literal Blocks --------------- - -Doctree element: literal_block. - -A paragraph consisting of two colons ("::") signifies that the -following text block(s) comprise a literal block. The literal block -must either be indented or quoted (see below). No markup processing -is done within a literal block. It is left as-is, and is typically -rendered in a monospaced typeface:: - - This is a typical paragraph. An indented literal block follows. - - :: - - for a in [5,4,3,2,1]: # this is program code, shown as-is - print a - print "it's..." - # a literal block continues until the indentation ends - - This text has returned to the indentation of the first paragraph, - is outside of the literal block, and is therefore treated as an - ordinary paragraph. - -The paragraph containing only "::" will be completely removed from the -output; no empty paragraph will remain. - -As a convenience, the "::" is recognized at the end of any paragraph. -If immediately preceded by whitespace, both colons will be removed -from the output (this is the "partially minimized" form). When text -immediately precedes the "::", *one* colon will be removed from the -output, leaving only one colon visible (i.e., "::" will be replaced by -":"; this is the "fully minimized" form). - -In other words, these are all equivalent (please pay attention to the -colons after "Paragraph"): - -1. Expanded form:: - - Paragraph: - - :: - - Literal block - -2. Partially minimized form:: - - Paragraph: :: - - Literal block - -3. Fully minimized form:: - - Paragraph:: - - Literal block - -All whitespace (including line breaks, but excluding minimum -indentation for indented literal blocks) is preserved. Blank lines -are required before and after a literal block, but these blank lines -are not included as part of the literal block. - - -Indented Literal Blocks -``````````````````````` - -Indented literal blocks are indicated by indentation relative to the -surrounding text (leading whitespace on each line). The minimum -indentation will be removed from each line of an indented literal -block. The literal block need not be contiguous; blank lines are -allowed between sections of indented text. The literal block ends -with the end of the indentation. - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | (ends with "::") | - +------------------------------+ - +---------------------------+ - | indented literal block | - +---------------------------+ - - -Quoted Literal Blocks -````````````````````` - -Quoted literal blocks are unindented contiguous blocks of text where -each line begins with the same non-alphanumeric printable 7-bit ASCII -character [#]_. A blank line ends a quoted literal block. The -quoting characters are preserved in the processed document. - -.. [#] - The following are all valid quoting characters:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - Note that these are the same characters as are valid for title - adornment of sections_. - -Possible uses include literate programming in Haskell and email -quoting:: - - John Doe wrote:: - - >> Great idea! - > - > Why didn't I think of that? - - You just did! ;-) - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | (ends with "::") | - +------------------------------+ - +------------------------------+ - | ">" per-line-quoted | - | ">" contiguous literal block | - +------------------------------+ - - -Line Blocks ------------ - -Doctree elements: line_block, line. (New in Docutils 0.3.5.) - -Line blocks are useful for address blocks, verse (poetry, song -lyrics), and unadorned lists, where the structure of lines is -significant. Line blocks are groups of lines beginning with vertical -bar ("|") prefixes. Each vertical bar prefix indicates a new line, so -line breaks are preserved. Initial indents are also significant, -resulting in a nested structure. Inline markup is supported. -Continuation lines are wrapped portions of long lines; they begin with -a space in place of the vertical bar. The left edge of a continuation -line must be indented, but need not be aligned with the left edge of -the text above it. A line block ends with a blank line. - -This example illustrates continuation lines:: - - | Lend us a couple of bob till Thursday. - | I'm absolutely skint. - | But I'm expecting a postal order and I can pay you back - as soon as it comes. - | Love, Ewan. - -This example illustrates the nesting of line blocks, indicated by the -initial indentation of new lines:: - - Take it away, Eric the Orchestra Leader! - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -Syntax diagram:: - - +------+-----------------------+ - | "| " | line | - +------| continuation line | - +-----------------------+ - - -Block Quotes ------------- - -Doctree element: block_quote, attribution. - -A text block that is indented relative to the preceding text, without -markup indicating it to be a literal block, is a block quote. All -markup processing (for body elements and inline markup) continues -within the block quote:: - - This is an ordinary paragraph, introducing a block quote. - - "It is my business to know things. That is my trade." - - -- Sherlock Holmes - -If the final block of a block quote begins with "--", "---", or a true -em-dash (flush left within the block quote), it is interpreted as an -attribution. If the attribution consists of multiple lines, the left -edges of the second and subsequent lines must align. - -Blank lines are required before and after a block quote, but these -blank lines are not included as part of the block quote. - -Syntax diagram:: - - +------------------------------+ - | (current level of | - | indentation) | - +------------------------------+ - +---------------------------+ - | block quote | - | (body elements)+ | - | | - | -- attribution text | - | (optional) | - +---------------------------+ - - -Doctest Blocks --------------- - -Doctree element: doctest_block. - -Doctest blocks are interactive Python sessions cut-and-pasted into -docstrings. They are meant to illustrate usage by example, and -provide an elegant and powerful testing environment via the `doctest -module`_ in the Python standard library. - -Doctest blocks are text blocks which begin with ``">>> "``, the Python -interactive interpreter main prompt, and end with a blank line. -Doctest blocks are treated as a special case of literal blocks, -without requiring the literal block syntax. If both are present, the -literal block syntax takes priority over Doctest block syntax:: - - This is an ordinary paragraph. - - >>> print 'this is a Doctest block' - this is a Doctest block - - The following is a literal block:: - - >>> This is not recognized as a doctest block by - reStructuredText. It *will* be recognized by the doctest - module, though! - -Indentation is not required for doctest blocks. - - -Tables ------- - -Doctree elements: table, tgroup, colspec, thead, tbody, row, entry. - -ReStructuredText provides two syntaxes for delineating table cells: -`Grid Tables`_ and `Simple Tables`_. - -As with other body elements, blank lines are required before and after -tables. Tables' left edges should align with the left edge of -preceding text blocks; if indented, the table is considered to be part -of a block quote. - -Once isolated, each table cell is treated as a miniature document; the -top and bottom cell boundaries act as delimiting blank lines. Each -cell contains zero or more body elements. Cell contents may include -left and/or right margins, which are removed before processing. - - -Grid Tables -``````````` - -Grid tables provide a complete table representation via grid-like -"ASCII art". Grid tables allow arbitrary cell contents (body -elements), and both row and column spans. However, grid tables can be -cumbersome to produce, especially for simple data sets. The `Emacs -table mode`_ is a tool that allows easy editing of grid tables, in -Emacs. See `Simple Tables`_ for a simpler (but limited) -representation. - -Grid tables are described with a visual grid made up of the characters -"-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines -(row separators). The equals sign ("=") may be used to separate -optional header rows from the table body (not supported by the `Emacs -table mode`_). The vertical bar ("|") is used for vertical lines -(column separators). The plus sign ("+") is used for intersections of -horizontal and vertical lines. Example:: - - +------------------------+------------+----------+----------+ - | Header row, column 1 | Header 2 | Header 3 | Header 4 | - | (header rows optional) | | | | - +========================+============+==========+==========+ - | body row 1, column 1 | column 2 | column 3 | column 4 | - +------------------------+------------+----------+----------+ - | body row 2 | Cells may span columns. | - +------------------------+------------+---------------------+ - | body row 3 | Cells may | - Table cells | - +------------------------+ span rows. | - contain | - | body row 4 | | - body elements. | - +------------------------+------------+---------------------+ - -Some care must be taken with grid tables to avoid undesired -interactions with cell text in rare cases. For example, the following -table contains a cell in row 2 spanning from column 2 to column 4:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -If a vertical bar is used in the text of that cell, it could have -unintended effects if accidentally aligned with column boundaries:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -Several solutions are possible. All that is needed is to break the -continuity of the cell outline rectangle. One possibility is to shift -the text by adding an extra space before:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -Another possibility is to add an extra line to row 2:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - | | | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - - -Simple Tables -````````````` - -Simple tables provide a compact and easy to type but limited -row-oriented table representation for simple data sets. Cell contents -are typically single paragraphs, although arbitrary body elements may -be represented in most cells. Simple tables allow multi-line rows (in -all but the first column) and column spans, but not row spans. See -`Grid Tables`_ above for a complete table representation. - -Simple tables are described with horizontal borders made up of "=" and -"-" characters. The equals sign ("=") is used for top and bottom -table borders, and to separate optional header rows from the table -body. The hyphen ("-") is used to indicate column spans in a single -row by underlining the joined columns, and may optionally be used to -explicitly and/or visually separate rows. - -A simple table begins with a top border of equals signs with one or -more spaces at each column boundary (two or more spaces recommended). -Regardless of spans, the top border *must* fully describe all table -columns. There must be at least two columns in the table (to -differentiate it from section headers). The last of the optional -header rows is underlined with '=', again with spaces at column -boundaries. There may not be a blank line below the header row -separator; it would be interpreted as the bottom border of the table. -The bottom boundary of the table consists of '=' underlines, also with -spaces at column boundaries. For example, here is a truth table, a -three-column table with one header row and four body rows:: - - ===== ===== ======= - A B A and B - ===== ===== ======= - False False False - True False False - False True False - True True True - ===== ===== ======= - -Underlines of '-' may be used to indicate column spans by "filling in" -column margins to join adjacent columns. Column span underlines must -be complete (they must cover all columns) and align with established -column boundaries. Text lines containing column span underlines may -not contain any other text. A column span underline applies only to -one row immediately above it. For example, here is a table with a -column span in the header:: - - ===== ===== ====== - Inputs Output - ------------ ------ - A B A or B - ===== ===== ====== - False False False - True False True - False True True - True True True - ===== ===== ====== - -Each line of text must contain spaces at column boundaries, except -where cells have been joined by column spans. Each line of text -starts a new row, except when there is a blank cell in the first -column. In that case, that line of text is parsed as a continuation -line. For this reason, cells in the first column of new rows (*not* -continuation lines) *must* contain some text; blank cells would lead -to a misinterpretation. An empty comment ("..") is sufficient and -will be omitted from the processed output (see Comments_ below). -Also, this mechanism limits cells in the first column to only one line -of text. Use `grid tables`_ if this limitation is unacceptable. - -Underlines of '-' may also be used to visually separate rows, even if -there are no column spans. This is especially useful in long tables, -where rows are many lines long. - -Blank lines are permitted within simple tables. Their interpretation -depends on the context. Blank lines *between* rows are ignored. -Blank lines *within* multi-line rows may separate paragraphs or other -body elements within cells. - -The rightmost column is unbounded; text may continue past the edge of -the table (as indicated by the table borders). However, it is -recommended that borders be made long enough to contain the entire -text. - -The following example illustrates continuation lines (row 2 consists -of two lines of text, and four lines for row 3), a blank line -separating paragraphs (row 3, column 2), and text extending past the -right edge of the table:: - - ===== ===== - col 1 col 2 - ===== ===== - 1 Second column of row 1. - 2 Second column of row 2. - Second line of paragraph. - 3 - Second column of row 3. - - - Second item in bullet - list (row 3, column 2). - ===== ===== - - -Explicit Markup Blocks ----------------------- - -An explicit markup block is a text block: - -- whose first line begins with ".." followed by whitespace (the - "explicit markup start"), -- whose second and subsequent lines (if any) are indented relative to - the first, and -- which ends before an unindented line. - -Explicit markup blocks are analogous to bullet list items, with ".." -as the bullet. The text on the lines immediately after the explicit -markup start determines the indentation of the block body. The -maximum common indentation is always removed from the second and -subsequent lines of the block body. Therefore if the first construct -fits in one line, and the indentation of the first and second -constructs should differ, the first construct should not begin on the -same line as the explicit markup start. - -Blank lines are required between explicit markup blocks and other -elements, but are optional between explicit markup blocks where -unambiguous. - -The explicit markup syntax is used for footnotes, citations, hyperlink -targets, directives, substitution definitions, and comments. - - -Footnotes -````````` - -Doctree elements: footnote, label. - -Each footnote consists of an explicit markup start (".. "), a left -square bracket, the footnote label, a right square bracket, and -whitespace, followed by indented body elements. A footnote label can -be: - -- a whole decimal number consisting of one or more digits, - -- a single "#" (denoting `auto-numbered footnotes`_), - -- a "#" followed by a simple reference name (an `autonumber label`_), - or - -- a single "*" (denoting `auto-symbol footnotes`_). - -The footnote content (body elements) must be consistently indented (by -at least 3 spaces) and left-aligned. The first body element within a -footnote may often begin on the same line as the footnote label. -However, if the first element fits on one line and the indentation of -the remaining elements differ, the first element must begin on the -line after the footnote label. Otherwise, the difference in -indentation will not be detected. - -Footnotes may occur anywhere in the document, not only at the end. -Where and how they appear in the processed output depends on the -processing system. - -Here is a manually numbered footnote:: - - .. [1] Body elements go here. - -Each footnote automatically generates a hyperlink target pointing to -itself. The text of the hyperlink target name is the same as that of -the footnote label. `Auto-numbered footnotes`_ generate a number as -their footnote label and reference name. See `Implicit Hyperlink -Targets`_ for a complete description of the mechanism. - -Syntax diagram:: - - +-------+-------------------------+ - | ".. " | "[" label "]" footnote | - +-------+ | - | (body elements)+ | - +-------------------------+ - - -Auto-Numbered Footnotes -....................... - -A number sign ("#") may be used as the first character of a footnote -label to request automatic numbering of the footnote or footnote -reference. - -The first footnote to request automatic numbering is assigned the -label "1", the second is assigned the label "2", and so on (assuming -there are no manually numbered footnotes present; see `Mixed Manual -and Auto-Numbered Footnotes`_ below). A footnote which has -automatically received a label "1" generates an implicit hyperlink -target with name "1", just as if the label was explicitly specified. - -.. _autonumber label: `autonumber labels`_ - -A footnote may specify a label explicitly while at the same time -requesting automatic numbering: ``[#label]``. These labels are called -_`autonumber labels`. Autonumber labels do two things: - -- On the footnote itself, they generate a hyperlink target whose name - is the autonumber label (doesn't include the "#"). - -- They allow an automatically numbered footnote to be referred to more - than once, as a footnote reference or hyperlink reference. For - example:: - - If [#note]_ is the first footnote reference, it will show up as - "[1]". We can refer to it again as [#note]_ and again see - "[1]". We can also refer to it as note_ (an ordinary internal - hyperlink reference). - - .. [#note] This is the footnote labeled "note". - -The numbering is determined by the order of the footnotes, not by the -order of the references. For footnote references without autonumber -labels (``[#]_``), the footnotes and footnote references must be in -the same relative order but need not alternate in lock-step. For -example:: - - [#]_ is a reference to footnote 1, and [#]_ is a reference to - footnote 2. - - .. [#] This is footnote 1. - .. [#] This is footnote 2. - .. [#] This is footnote 3. - - [#]_ is a reference to footnote 3. - -Special care must be taken if footnotes themselves contain -auto-numbered footnote references, or if multiple references are made -in close proximity. Footnotes and references are noted in the order -they are encountered in the document, which is not necessarily the -same as the order in which a person would read them. - - -Auto-Symbol Footnotes -..................... - -An asterisk ("*") may be used for footnote labels to request automatic -symbol generation for footnotes and footnote references. The asterisk -may be the only character in the label. For example:: - - Here is a symbolic footnote reference: [*]_. - - .. [*] This is the footnote. - -A transform will insert symbols as labels into corresponding footnotes -and footnote references. The number of references must be equal to -the number of footnotes. One symbol footnote cannot have multiple -references. - -The standard Docutils system uses the following symbols for footnote -marks [#]_: - -- asterisk/star ("*") -- dagger (HTML character entity "†", Unicode U+02020) -- double dagger ("‡"/U+02021) -- section mark ("§"/U+000A7) -- pilcrow or paragraph mark ("¶"/U+000B6) -- number sign ("#") -- spade suit ("♠"/U+02660) -- heart suit ("♥"/U+02665) -- diamond suit ("♦"/U+02666) -- club suit ("♣"/U+02663) - -.. [#] This list was inspired by the list of symbols for "Note - Reference Marks" in The Chicago Manual of Style, 14th edition, - section 12.51. "Parallels" ("||") were given in CMoS instead of - the pilcrow. The last four symbols (the card suits) were added - arbitrarily. - -If more than ten symbols are required, the same sequence will be -reused, doubled and then tripled, and so on ("**" etc.). - -.. Note:: When using auto-symbol footnotes, the choice of output - encoding is important. Many of the symbols used are not encodable - in certain common text encodings such as Latin-1 (ISO 8859-1). The - use of UTF-8 for the output encoding is recommended. An - alternative for HTML and XML output is to use the - "xmlcharrefreplace" `output encoding error handler`__. - -__ ../../user/config.html#output-encoding-error-handler - - -Mixed Manual and Auto-Numbered Footnotes -........................................ - -Manual and automatic footnote numbering may both be used within a -single document, although the results may not be expected. Manual -numbering takes priority. Only unused footnote numbers are assigned -to auto-numbered footnotes. The following example should be -illustrative:: - - [2]_ will be "2" (manually numbered), - [#]_ will be "3" (anonymous auto-numbered), and - [#label]_ will be "1" (labeled auto-numbered). - - .. [2] This footnote is labeled manually, so its number is fixed. - - .. [#label] This autonumber-labeled footnote will be labeled "1". - It is the first auto-numbered footnote and no other footnote - with label "1" exists. The order of the footnotes is used to - determine numbering, not the order of the footnote references. - - .. [#] This footnote will be labeled "3". It is the second - auto-numbered footnote, but footnote label "2" is already used. - - -Citations -````````` - -Citations are identical to footnotes except that they use only -non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation -labels are simple `reference names`_ (case-insensitive single words -consisting of alphanumerics plus internal hyphens, underscores, and -periods; no whitespace). Citations may be rendered separately and -differently from footnotes. For example:: - - Here is a citation reference: [CIT2002]_. - - .. [CIT2002] This is the citation. It's just like a footnote, - except the label is textual. - - -.. _hyperlinks: - -Hyperlink Targets -````````````````` - -Doctree element: target. - -These are also called _`explicit hyperlink targets`, to differentiate -them from `implicit hyperlink targets`_ defined below. - -Hyperlink targets identify a location within or outside of a document, -which may be linked to by `hyperlink references`_. - -Hyperlink targets may be named or anonymous. Named hyperlink targets -consist of an explicit markup start (".. "), an underscore, the -reference name (no trailing underscore), a colon, whitespace, and a -link block:: - - .. _hyperlink-name: link-block - -Reference names are whitespace-neutral and case-insensitive. See -`Reference Names`_ for details and examples. - -Anonymous hyperlink targets consist of an explicit markup start -(".. "), two underscores, a colon, whitespace, and a link block; there -is no reference name:: - - .. __: anonymous-hyperlink-target-link-block - -An alternate syntax for anonymous hyperlinks consists of two -underscores, a space, and a link block:: - - __ anonymous-hyperlink-target-link-block - -See `Anonymous Hyperlinks`_ below. - -There are three types of hyperlink targets: internal, external, and -indirect. - -1. _`Internal hyperlink targets` have empty link blocks. They provide - an end point allowing a hyperlink to connect one place to another - within a document. An internal hyperlink target points to the - element following the target. For example:: - - Clicking on this internal hyperlink will take us to the target_ - below. - - .. _target: - - The hyperlink target above points to this paragraph. - - Internal hyperlink targets may be "chained". Multiple adjacent - internal hyperlink targets all point to the same element:: - - .. _target1: - .. _target2: - - The targets "target1" and "target2" are synonyms; they both - point to this paragraph. - - If the element "pointed to" is an external hyperlink target (with a - URI in its link block; see #2 below) the URI from the external - hyperlink target is propagated to the internal hyperlink targets; - they will all "point to" the same URI. There is no need to - duplicate a URI. For example, all three of the following hyperlink - targets refer to the same URI:: - - .. _Python DOC-SIG mailing list archive: - .. _archive: - .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ - - An inline form of internal hyperlink target is available; see - `Inline Internal Targets`_. - -2. _`External hyperlink targets` have an absolute or relative URI or - email address in their link blocks. For example, take the - following input:: - - See the Python_ home page for info. - - `Write to me`_ with your questions. - - .. _Python: http://www.python.org - .. _Write to me: jdoe@example.com - - After processing into HTML, the hyperlinks might be expressed as:: - - See the <a href="http://www.python.org">Python</a> home page - for info. - - <a href="mailto:jdoe@example.com">Write to me</a> with your - questions. - - An external hyperlink's URI may begin on the same line as the - explicit markup start and target name, or it may begin in an - indented text block immediately following, with no intervening - blank lines. If there are multiple lines in the link block, they - are concatenated. Any whitespace is removed (whitespace is - permitted to allow for line wrapping). The following external - hyperlink targets are equivalent:: - - .. _one-liner: http://docutils.sourceforge.net/rst.html - - .. _starts-on-this-line: http:// - docutils.sourceforge.net/rst.html - - .. _entirely-below: - http://docutils. - sourceforge.net/rst.html - - If an external hyperlink target's URI contains an underscore as its - last character, it must be escaped to avoid being mistaken for an - indirect hyperlink target:: - - This link_ refers to a file called ``underscore_``. - - .. _link: underscore\_ - - It is possible (although not generally recommended) to include URIs - directly within hyperlink references. See `Embedded URIs`_ below. - -3. _`Indirect hyperlink targets` have a hyperlink reference in their - link blocks. In the following example, target "one" indirectly - references whatever target "two" references, and target "two" - references target "three", an internal hyperlink target. In - effect, all three reference the same thing:: - - .. _one: two_ - .. _two: three_ - .. _three: - - Just as with `hyperlink references`_ anywhere else in a document, - if a phrase-reference is used in the link block it must be enclosed - in backquotes. As with `external hyperlink targets`_, the link - block of an indirect hyperlink target may begin on the same line as - the explicit markup start or the next line. It may also be split - over multiple lines, in which case the lines are joined with - whitespace before being normalized. - - For example, the following indirect hyperlink targets are - equivalent:: - - .. _one-liner: `A HYPERLINK`_ - .. _entirely-below: - `a hyperlink`_ - .. _split: `A - Hyperlink`_ - -If the reference name contains any colons, either: - -- the phrase must be enclosed in backquotes:: - - .. _`FAQTS: Computers: Programming: Languages: Python`: - http://python.faqts.com/ - -- or the colon(s) must be backslash-escaped in the link target:: - - .. _Chapter One\: "Tadpole Days": - - It's not easy being green... - -See `Implicit Hyperlink Targets`_ below for the resolution of -duplicate reference names. - -Syntax diagram:: - - +-------+----------------------+ - | ".. " | "_" name ":" link | - +-------+ block | - | | - +----------------------+ - - -Anonymous Hyperlinks -.................... - -The `World Wide Web Consortium`_ recommends in its `HTML Techniques -for Web Content Accessibility Guidelines`_ that authors should -"clearly identify the target of each link." Hyperlink references -should be as verbose as possible, but duplicating a verbose hyperlink -name in the target is onerous and error-prone. Anonymous hyperlinks -are designed to allow convenient verbose hyperlink references, and are -analogous to `Auto-Numbered Footnotes`_. They are particularly useful -in short or one-off documents. However, this feature is easily abused -and can result in unreadable plaintext and/or unmaintainable -documents. Caution is advised. - -Anonymous `hyperlink references`_ are specified with two underscores -instead of one:: - - See `the web site of my favorite programming language`__. - -Anonymous targets begin with ".. __:"; no reference name is required -or allowed:: - - .. __: http://www.python.org - -As a convenient alternative, anonymous targets may begin with "__" -only:: - - __ http://www.python.org - -The reference name of the reference is not used to match the reference -to its target. Instead, the order of anonymous hyperlink references -and targets within the document is significant: the first anonymous -reference will link to the first anonymous target. The number of -anonymous hyperlink references in a document must match the number of -anonymous targets. For readability, it is recommended that targets be -kept close to references. Take care when editing text containing -anonymous references; adding, removing, and rearranging references -require attention to the order of corresponding targets. - - -Directives -`````````` - -Doctree elements: depend on the directive. - -Directives are an extension mechanism for reStructuredText, a way of -adding support for new constructs without adding new primary syntax -(directives may support additional syntax locally). All standard -directives (those implemented and registered in the reference -reStructuredText parser) are described in the `reStructuredText -Directives`_ document, and are always available. Any other directives -are domain-specific, and may require special action to make them -available when processing the document. - -For example, here's how an image_ may be placed:: - - .. image:: mylogo.jpeg - -A figure_ (a graphic with a caption) may placed like this:: - - .. figure:: larch.png - - The larch. - -An admonition_ (note, caution, etc.) contains other body elements:: - - .. note:: This is a paragraph - - - Here is a bullet list. - -Directives are indicated by an explicit markup start (".. ") followed -by the directive type, two colons, and whitespace (together called the -"directive marker"). Directive types are case-insensitive single -words (alphanumerics plus internal hyphens, underscores, and periods; -no whitespace). Two colons are used after the directive type for -these reasons: - -- Two colons are distinctive, and unlikely to be used in common text. - -- Two colons avoids clashes with common comment text like:: - - .. Danger: modify at your own risk! - -- If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), a level-3 - (error) system message is generated, and the entire directive block - (including the directive itself) will be included as a literal - block. Thus "::" is a natural choice. - -The directive block is consists of any text on the first line of the -directive after the directive marker, and any subsequent indented -text. The interpretation of the directive block is up to the -directive code. There are three logical parts to the directive block: - -1. Directive arguments. -2. Directive options. -3. Directive content. - -Individual directives can employ any combination of these parts. -Directive arguments can be filesystem paths, URLs, title text, etc. -Directive options are indicated using `field lists`_; the field names -and contents are directive-specific. Arguments and options must form -a contiguous block beginning on the first or second line of the -directive; a blank line indicates the beginning of the directive -content block. If either arguments and/or options are employed by the -directive, a blank line must separate them from the directive content. -The "figure" directive employs all three parts:: - - .. figure:: larch.png - :scale: 50 - - The larch. - -Simple directives may not require any content. If a directive that -does not employ a content block is followed by indented text anyway, -it is an error. If a block quote should immediately follow a -directive, use an empty comment in-between (see Comments_ below). - -Actions taken in response to directives and the interpretation of text -in the directive content block or subsequent text block(s) are -directive-dependent. See `reStructuredText Directives`_ for details. - -Directives are meant for the arbitrary processing of their contents, -which can be transformed into something possibly unrelated to the -original text. It may also be possible for directives to be used as -pragmas, to modify the behavior of the parser, such as to experiment -with alternate syntax. There is no parser support for this -functionality at present; if a reasonable need for pragma directives -is found, they may be supported. - -Directives do not generate "directive" elements; they are a *parser -construct* only, and have no intrinsic meaning outside of -reStructuredText. Instead, the parser will transform recognized -directives into (possibly specialized) document elements. Unknown -directives will trigger level-3 (error) system messages. - -Syntax diagram:: - - +-------+-------------------------------+ - | ".. " | directive type "::" directive | - +-------+ block | - | | - +-------------------------------+ - - -Substitution Definitions -```````````````````````` - -Doctree element: substitution_definition. - -Substitution definitions are indicated by an explicit markup start -(".. ") followed by a vertical bar, the substitution text, another -vertical bar, whitespace, and the definition block. Substitution text -may not begin or end with whitespace. A substitution definition block -contains an embedded inline-compatible directive (without the leading -".. "), such as "image_" or "replace_". For example:: - - The |biohazard| symbol must be used on containers used to - dispose of medical waste. - - .. |biohazard| image:: biohazard.png - -It is an error for a substitution definition block to directly or -indirectly contain a circular substitution reference. - -`Substitution references`_ are replaced in-line by the processed -contents of the corresponding definition (linked by matching -substitution text). Matches are case-sensitive but forgiving; if no -exact match is found, a case-insensitive comparison is attempted. - -Substitution definitions allow the power and flexibility of -block-level directives_ to be shared by inline text. They are a way -to include arbitrarily complex inline structures within text, while -keeping the details out of the flow of text. They are the equivalent -of SGML/XML's named entities or programming language macros. - -Without the substitution mechanism, every time someone wants an -application-specific new inline structure, they would have to petition -for a syntax change. In combination with existing directive syntax, -any inline structure can be coded without new syntax (except possibly -a new directive). - -Syntax diagram:: - - +-------+-----------------------------------------------------+ - | ".. " | "|" substitution text "| " directive type "::" data | - +-------+ directive block | - | | - +-----------------------------------------------------+ - -Following are some use cases for the substitution mechanism. Please -note that most of the embedded directives shown are examples only and -have not been implemented. - -Objects - Substitution references may be used to associate ambiguous text - with a unique object identifier. - - For example, many sites may wish to implement an inline "user" - directive:: - - |Michael| and |Jon| are our widget-wranglers. - - .. |Michael| user:: mjones - .. |Jon| user:: jhl - - Depending on the needs of the site, this may be used to index the - document for later searching, to hyperlink the inline text in - various ways (mailto, homepage, mouseover Javascript with profile - and contact information, etc.), or to customize presentation of - the text (include username in the inline text, include an icon - image with a link next to the text, make the text bold or a - different color, etc.). - - The same approach can be used in documents which frequently refer - to a particular type of objects with unique identifiers but - ambiguous common names. Movies, albums, books, photos, court - cases, and laws are possible. For example:: - - |The Transparent Society| offers a fascinating alternate view - on privacy issues. - - .. |The Transparent Society| book:: isbn=0738201448 - - Classes or functions, in contexts where the module or class names - are unclear and/or interpreted text cannot be used, are another - possibility:: - - 4XSLT has the convenience method |runString|, so you don't - have to mess with DOM objects if all you want is the - transformed output. - - .. |runString| function:: module=xml.xslt class=Processor - -Images - Images are a common use for substitution references:: - - West led the |H| 3, covered by dummy's |H| Q, East's |H| K, - and trumped in hand with the |S| 2. - - .. |H| image:: /images/heart.png - :height: 11 - :width: 11 - .. |S| image:: /images/spade.png - :height: 11 - :width: 11 - - * |Red light| means stop. - * |Green light| means go. - * |Yellow light| means go really fast. - - .. |Red light| image:: red_light.png - .. |Green light| image:: green_light.png - .. |Yellow light| image:: yellow_light.png - - |-><-| is the official symbol of POEE_. - - .. |-><-| image:: discord.png - .. _POEE: http://www.poee.org/ - - The "image_" directive has been implemented. - -Styles [#]_ - Substitution references may be used to associate inline text with - an externally defined presentation style:: - - Even |the text in Texas| is big. - - .. |the text in Texas| style:: big - - The style name may be meaningful in the context of some particular - output format (CSS class name for HTML output, LaTeX style name - for LaTeX, etc), or may be ignored for other output formats (such - as plaintext). - - .. @@@ This needs to be rethought & rewritten or removed: - - Interpreted text is unsuitable for this purpose because the set - of style names cannot be predefined - it is the domain of the - content author, not the author of the parser and output - formatter - and there is no way to associate a style name - argument with an interpreted text style role. Also, it may be - desirable to use the same mechanism for styling blocks:: - - .. style:: motto - At Bob's Underwear Shop, we'll do anything to get in - your pants. - - .. style:: disclaimer - All rights reversed. Reprint what you like. - - .. [#] There may be sufficient need for a "style" mechanism to - warrant simpler syntax such as an extension to the interpreted - text role syntax. The substitution mechanism is cumbersome for - simple text styling. - -Templates - Inline markup may be used for later processing by a template - engine. For example, a Zope_ author might write:: - - Welcome back, |name|! - - .. |name| tal:: replace user/getUserName - - After processing, this ZPT output would result:: - - Welcome back, - <span tal:replace="user/getUserName">name</span>! - - Zope would then transform this to something like "Welcome back, - David!" during a session with an actual user. - -Replacement text - The substitution mechanism may be used for simple macro - substitution. This may be appropriate when the replacement text - is repeated many times throughout one or more documents, - especially if it may need to change later. A short example is - unavoidably contrived:: - - |RST| is a little annoying to type over and over, especially - when writing about |RST| itself, and spelling out the - bicapitalized word |RST| every time isn't really necessary for - |RST| source readability. - - .. |RST| replace:: reStructuredText_ - .. _reStructuredText: http://docutils.sourceforge.net/rst.html - - Substitution is also appropriate when the replacement text cannot - be represented using other inline constructs, or is obtrusively - long:: - - But still, that's nothing compared to a name like - |j2ee-cas|__. - - .. |j2ee-cas| replace:: - the Java `TM`:super: 2 Platform, Enterprise Edition Client - Access Services - __ http://developer.java.sun.com/developer/earlyAccess/ - j2eecas/ - - The "replace_" directive has been implemented. - - -Comments -```````` - -Doctree element: comment. - -Arbitrary indented text may follow the explicit markup start and will -be processed as a comment element. No further processing is done on -the comment block text; a comment contains a single "text blob". -Depending on the output formatter, comments may be removed from the -processed output. The only restriction on comments is that they not -use the same syntax as any of the other explicit markup constructs: -substitution definitions, directives, footnotes, citations, or -hyperlink targets. To ensure that none of the other explicit markup -constructs is recognized, leave the ".." on a line by itself:: - - .. This is a comment - .. - _so: is this! - .. - [and] this! - .. - this:: too! - .. - |even| this:: ! - -An explicit markup start followed by a blank line and nothing else -(apart from whitespace) is an "empty comment". It serves to terminate -a preceding construct, and does **not** consume any indented text -following. To have a block quote follow a list or any indented -construct, insert an unindented empty comment in-between. - -Syntax diagram:: - - +-------+----------------------+ - | ".. " | comment | - +-------+ block | - | | - +----------------------+ - - -Implicit Hyperlink Targets -========================== - -Implicit hyperlink targets are generated by section titles, footnotes, -and citations, and may also be generated by extension constructs. -Implicit hyperlink targets otherwise behave identically to explicit -`hyperlink targets`_. - -Problems of ambiguity due to conflicting duplicate implicit and -explicit reference names are avoided by following this procedure: - -1. `Explicit hyperlink targets`_ override any implicit targets having - the same reference name. The implicit hyperlink targets are - removed, and level-1 (info) system messages are inserted. - -2. Duplicate implicit hyperlink targets are removed, and level-1 - (info) system messages inserted. For example, if two or more - sections have the same title (such as "Introduction" subsections of - a rigidly-structured document), there will be duplicate implicit - hyperlink targets. - -3. Duplicate explicit hyperlink targets are removed, and level-2 - (warning) system messages are inserted. Exception: duplicate - `external hyperlink targets`_ (identical hyperlink names and - referenced URIs) do not conflict, and are not removed. - -System messages are inserted where target links have been removed. -See "Error Handling" in `PEP 258`_. - -The parser must return a set of *unique* hyperlink targets. The -calling software (such as the Docutils_) can warn of unresolvable -links, giving reasons for the messages. - - -Inline Markup -============= - -In reStructuredText, inline markup applies to words or phrases within -a text block. The same whitespace and punctuation that serves to -delimit words in written text is used to delimit the inline markup -syntax constructs. The text within inline markup may not begin or end -with whitespace. Arbitrary `character-level inline markup`_ is -supported although not encouraged. Inline markup cannot be nested. - -There are nine inline markup constructs. Five of the constructs use -identical start-strings and end-strings to indicate the markup: - -- emphasis_: "*" -- `strong emphasis`_: "**" -- `interpreted text`_: "`" -- `inline literals`_: "``" -- `substitution references`_: "|" - -Three constructs use different start-strings and end-strings: - -- `inline internal targets`_: "_`" and "`" -- `footnote references`_: "[" and "]_" -- `hyperlink references`_: "`" and "\`_" (phrases), or just a - trailing "_" (single words) - -`Standalone hyperlinks`_ are recognized implicitly, and use no extra -markup. - -The inline markup start-string and end-string recognition rules are as -follows. If any of the conditions are not met, the start-string or -end-string will not be recognized or processed. - -1. Inline markup start-strings must start a text block or be - immediately preceded by whitespace or one of:: - - ' " ( [ { < - / : - -2. Inline markup start-strings must be immediately followed by - non-whitespace. - -3. Inline markup end-strings must be immediately preceded by - non-whitespace. - -4. Inline markup end-strings must end a text block or be immediately - followed by whitespace or one of:: - - ' " ) ] } > - / : . , ; ! ? \ - -5. If an inline markup start-string is immediately preceded by a - single or double quote, "(", "[", "{", or "<", it must not be - immediately followed by the corresponding single or double quote, - ")", "]", "}", or ">". - -6. An inline markup end-string must be separated by at least one - character from the start-string. - -7. An unescaped backslash preceding a start-string or end-string will - disable markup recognition, except for the end-string of `inline - literals`_. See `Escaping Mechanism`_ above for details. - -For example, none of the following are recognized as containing inline -markup start-strings: - -- asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_* -- double asterisks: ** a**b O(N**2) etc. -- backquotes: ` `` etc. -- underscores: _ __ __init__ __init__() etc. -- vertical bars: | || etc. - -It may be desirable to use inline literals for some of these anyhow, -especially if they represent code snippets. It's a judgment call. - -These cases *do* require either literal-quoting or escaping to avoid -misinterpretation:: - - *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt - -The inline markup recognition rules were devised intentionally to -allow 90% of non-markup uses of "*", "`", "_", and "|" *without* -resorting to backslashes. For 9 of the remaining 10%, use inline -literals or literal blocks:: - - "``\*``" -> "\*" (possibly in another font or quoted) - -Only those who understand the escaping and inline markup rules should -attempt the remaining 1%. ;-) - -Inline markup delimiter characters are used for multiple constructs, -so to avoid ambiguity there must be a specific recognition order for -each character. The inline markup recognition order is as follows: - -- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_ - ("*"). - -- Backquotes: `Inline literals`_ ("``"), `inline internal targets`_ - (leading "_`", trailing "`"), are mutually independent, and are - recognized before phrase `hyperlink references`_ (leading "`", - trailing "\`_") and `interpreted text`_ ("`"). - -- Trailing underscores: Footnote references ("[" + label + "]_") and - simple `hyperlink references`_ (name + trailing "_") are mutually - independent. - -- Vertical bars: `Substitution references`_ ("|") are independently - recognized. - -- `Standalone hyperlinks`_ are the last to be recognized. - - -Character-Level Inline Markup ------------------------------ - -It is possible to mark up individual characters within a word with -backslash escapes (see `Escaping Mechanism`_ above). Backslash -escapes can be used to allow arbitrary text to immediately follow -inline markup:: - - Python ``list``\s use square bracket syntax. - -The backslash will disappear from the processed document. The word -"list" will appear as inline literal text, and the letter "s" will -immediately follow it as normal text, with no space in-between. - -Arbitrary text may immediately precede inline markup using -backslash-escaped whitespace:: - - Possible in *re*\ ``Structured``\ *Text*, though not encouraged. - -The backslashes and spaces separating "re", "Structured", and "Text" -above will disappear from the processed document. - -.. CAUTION:: - - The use of backslash-escapes for character-level inline markup is - not encouraged. Such use is ugly and detrimental to the - unprocessed document's readability. Please use this feature - sparingly and only where absolutely necessary. - - -Emphasis --------- - -Doctree element: emphasis. - -Start-string = end-string = "*". - -Text enclosed by single asterisk characters is emphasized:: - - This is *emphasized text*. - -Emphasized text is typically displayed in italics. - - -Strong Emphasis ---------------- - -Doctree element: strong. - -Start-string = end-string = "**". - -Text enclosed by double-asterisks is emphasized strongly:: - - This is **strong text**. - -Strongly emphasized text is typically displayed in boldface. - - -Interpreted Text ----------------- - -Doctree element: depends on the explicit or implicit role and -processing. - -Start-string = end-string = "`". - -Interpreted text is text that is meant to be related, indexed, linked, -summarized, or otherwise processed, but the text itself is typically -left alone. Interpreted text is enclosed by single backquote -characters:: - - This is `interpreted text`. - -The "role" of the interpreted text determines how the text is -interpreted. The role may be inferred implicitly (as above; the -"default role" is used) or indicated explicitly, using a role marker. -A role marker consists of a colon, the role name, and another colon. -A role name is a single word consisting of alphanumerics plus internal -hyphens, underscores, and periods; no whitespace or other characters -are allowed. A role marker is either a prefix or a suffix to the -interpreted text, whichever reads better; it's up to the author:: - - :role:`interpreted text` - - `interpreted text`:role: - -Interpreted text allows extensions to the available inline descriptive -markup constructs. To emphasis_, `strong emphasis`_, `inline -literals`_, and `hyperlink references`_, we can add "title reference", -"index entry", "acronym", "class", "red", "blinking" or anything else -we want. Only pre-determined roles are recognized; unknown roles will -generate errors. A core set of standard roles is implemented in the -reference parser; see `reStructuredText Interpreted Text Roles`_ for -individual descriptions. In addition, applications may support -specialized roles. - - -Inline Literals ---------------- - -Doctree element: literal. - -Start-string = end-string = "``". - -Text enclosed by double-backquotes is treated as inline literals:: - - This text is an example of ``inline literals``. - -Inline literals may contain any characters except two adjacent -backquotes in an end-string context (according to the recognition -rules above). No markup interpretation (including backslash-escape -interpretation) is done within inline literals. - -Line breaks are *not* preserved in inline literals. Although a -reStructuredText parser will preserve runs of spaces in its output, -the final representation of the processed document is dependent on the -output formatter, thus the preservation of whitespace cannot be -guaranteed. If the preservation of line breaks and/or other -whitespace is important, `literal blocks`_ should be used. - -Inline literals are useful for short code snippets. For example:: - - The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches - floating-point numbers (without exponents). - - -Hyperlink References --------------------- - -Doctree element: reference. - -- Named hyperlink references: - - - Start-string = "" (empty string), end-string = "_". - - Start-string = "`", end-string = "\`_". (Phrase references.) - -- Anonymous hyperlink references: - - - Start-string = "" (empty string), end-string = "__". - - Start-string = "`", end-string = "\`__". (Phrase references.) - -Hyperlink references are indicated by a trailing underscore, "_", -except for `standalone hyperlinks`_ which are recognized -independently. The underscore can be thought of as a right-pointing -arrow. The trailing underscores point away from hyperlink references, -and the leading underscores point toward `hyperlink targets`_. - -Hyperlinks consist of two parts. In the text body, there is a source -link, a reference name with a trailing underscore (or two underscores -for `anonymous hyperlinks`_):: - - See the Python_ home page for info. - -A target link with a matching reference name must exist somewhere else -in the document. See `Hyperlink Targets`_ for a full description). - -`Anonymous hyperlinks`_ (which see) do not use reference names to -match references to targets, but otherwise behave similarly to named -hyperlinks. - - -Embedded URIs -````````````` - -A hyperlink reference may directly embed a target URI inline, within -angle brackets ("<...>") as follows:: - - See the `Python home page <http://www.python.org>`_ for info. - -This is exactly equivalent to:: - - See the `Python home page`_ for info. - - .. _Python home page: http://www.python.org - -The bracketed URI must be preceded by whitespace and be the last text -before the end string. With a single trailing underscore, the -reference is named and the same target URI may be referred to again. - -With two trailing underscores, the reference and target are both -anonymous, and the target cannot be referred to again. These are -"one-off" hyperlinks. For example:: - - `RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC - 2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together - define the syntax of URIs. - -Equivalent to:: - - `RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs. - - __ http://www.rfc-editor.org/rfc/rfc2396.txt - __ http://www.rfc-editor.org/rfc/rfc2732.txt - -If reference text happens to end with angle-bracketed text that is -*not* a URI, the open-angle-bracket needs to be backslash-escaped. -For example, here is a reference to a title describing a tag:: - - See `HTML Element: \<a>`_ below. - -The reference text may also be omitted, in which case the URI will be -duplicated for use as the reference text. This is useful for relative -URIs where the address or file name is also the desired reference -text:: - - See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__ - for details. - -.. CAUTION:: - - This construct offers easy authoring and maintenance of hyperlinks - at the expense of general readability. Inline URIs, especially - long ones, inevitably interrupt the natural flow of text. For - documents meant to be read in source form, the use of independent - block-level `hyperlink targets`_ is **strongly recommended**. The - embedded URI construct is most suited to documents intended *only* - to be read in processed form. - - -Inline Internal Targets ------------------------- - -Doctree element: target. - -Start-string = "_`", end-string = "`". - -Inline internal targets are the equivalent of explicit `internal -hyperlink targets`_, but may appear within running text. The syntax -begins with an underscore and a backquote, is followed by a hyperlink -name or phrase, and ends with a backquote. Inline internal targets -may not be anonymous. - -For example, the following paragraph contains a hyperlink target named -"Norwegian Blue":: - - Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it? - -See `Implicit Hyperlink Targets`_ for the resolution of duplicate -reference names. - - -Footnote References -------------------- - -Doctree element: footnote_reference. - -Start-string = "[", end-string = "]_". - -Each footnote reference consists of a square-bracketed label followed -by a trailing underscore. Footnote labels are one of: - -- one or more digits (i.e., a number), - -- a single "#" (denoting `auto-numbered footnotes`_), - -- a "#" followed by a simple reference name (an `autonumber label`_), - or - -- a single "*" (denoting `auto-symbol footnotes`_). - -For example:: - - Please RTFM [1]_. - - .. [1] Read The Fine Manual - - -Citation References -------------------- - -Doctree element: citation_reference. - -Start-string = "[", end-string = "]_". - -Each citation reference consists of a square-bracketed label followed -by a trailing underscore. Citation labels are simple `reference -names`_ (case-insensitive single words, consisting of alphanumerics -plus internal hyphens, underscores, and periods; no whitespace). - -For example:: - - Here is a citation reference: [CIT2002]_. - -See Citations_ for the citation itself. - - -Substitution References ------------------------ - -Doctree element: substitution_reference, reference. - -Start-string = "|", end-string = "|" (optionally followed by "_" or -"__"). - -Vertical bars are used to bracket the substitution reference text. A -substitution reference may also be a hyperlink reference by appending -a "_" (named) or "__" (anonymous) suffix; the substitution text is -used for the reference text in the named case. - -The processing system replaces substitution references with the -processed contents of the corresponding `substitution definitions`_ -(which see for the definition of "correspond"). Substitution -definitions produce inline-compatible elements. - -Examples:: - - This is a simple |substitution reference|. It will be replaced by - the processing system. - - This is a combination |substitution and hyperlink reference|_. In - addition to being replaced, the replacement text or element will - refer to the "substitution and hyperlink reference" target. - - -Standalone Hyperlinks ---------------------- - -Doctree element: reference. - -Start-string = end-string = "" (empty string). - -A URI (absolute URI [#URI]_ or standalone email address) within a text -block is treated as a general external hyperlink with the URI itself -as the link's text. For example:: - - See http://www.python.org for info. - -would be marked up in HTML as:: - - See <a href="http://www.python.org">http://www.python.org</a> for - info. - -Two forms of URI are recognized: - -1. Absolute URIs. These consist of a scheme, a colon (":"), and a - scheme-specific part whose interpretation depends on the scheme. - - The scheme is the name of the protocol, such as "http", "ftp", - "mailto", or "telnet". The scheme consists of an initial letter, - followed by letters, numbers, and/or "+", "-", ".". Recognition is - limited to known schemes, per the `Official IANA Registry of URI - Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_. - - The scheme-specific part of the resource identifier may be either - hierarchical or opaque: - - - Hierarchical identifiers begin with one or two slashes and may - use slashes to separate hierarchical components of the path. - Examples are web pages and FTP sites:: - - http://www.python.org - - ftp://ftp.python.org/pub/python - - - Opaque identifiers do not begin with slashes. Examples are - email addresses and newsgroups:: - - mailto:someone@somewhere.com - - news:comp.lang.python - - With queries, fragments, and %-escape sequences, URIs can become - quite complicated. A reStructuredText parser must be able to - recognize any absolute URI, as defined in RFC2396_ and RFC2732_. - -2. Standalone email addresses, which are treated as if they were - absolute URIs with a "mailto:" scheme. Example:: - - someone@somewhere.com - -Punctuation at the end of a URI is not considered part of the URI, -unless the URI is terminated by a closing angle bracket (">"). -Backslashes may be used in URIs to escape markup characters, -specifically asterisks ("*") and underscores ("_") which are vaid URI -characters (see `Escaping Mechanism`_ above). - -.. [#URI] Uniform Resource Identifier. URIs are a general form of - URLs (Uniform Resource Locators). For the syntax of URIs see - RFC2396_ and RFC2732_. - - -Units -===== - -(New in Docutils 0.3.10.) - -All measures consist of a positive floating point number in standard -(non-scientific) notation and a unit, possibly separated by one or -more spaces. - -Units are only supported where explicitly mentioned in the reference -manuals. - - -Length Units ------------- - -The following length units are supported by the reStructuredText -parser: - -* em (ems, the height of the element's font) -* ex (x-height, the height of the letter "x") -* px (pixels, relative to the canvas resolution) -* in (inches; 1in=2.54cm) -* cm (centimeters; 1cm=10mm) -* mm (millimeters) -* pt (points; 1pt=1/72in) -* pc (picas; 1pc=12pt) - -(List and explanations taken from -http://www.htmlhelp.com/reference/css/units.html#length.) - -The following are all valid length values: "1.5em", "20 mm", ".5in". - - -Percentage Units ----------------- - -Percentage values have a percent sign ("%") as unit. Percentage -values are relative to other values, depending on the context in which -they occur. - - ----------------- - Error Handling ----------------- - -Doctree element: system_message, problematic. - -Markup errors are handled according to the specification in `PEP -258`_. - - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _transforms: - http://docutils.sourceforge.net/docutils/transforms/ -.. _Grouch: http://www.mems-exchange.org/software/grouch/ -.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt -.. _DocTitle transform: -.. _DocInfo transform: - http://docutils.sourceforge.net/docutils/transforms/frontmatter.py -.. _getopt.py: - http://www.python.org/doc/current/lib/module-getopt.html -.. _GNU libc getopt_long(): - http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html -.. _Emacs table mode: http://table.sourceforge.net/ -.. _Official IANA Registry of URI Schemes: - http://www.iana.org/assignments/uri-schemes -.. _Retired Index of WWW Addressing Schemes: - http://www.w3.org/Addressing/schemes.html -.. _World Wide Web Consortium: http://www.w3.org/ -.. _HTML Techniques for Web Content Accessibility Guidelines: - http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text -.. _image: directives.html#image -.. _replace: directives.html#replace -.. _meta: directives.html#meta -.. _figure: directives.html#figure -.. _admonition: directives.html#admonitions -.. _reStructuredText Directives: directives.html -.. _reStructuredText Interpreted Text Roles: roles.html -.. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt -.. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt -.. _Zope: http://www.zope.com/ -.. _PEP 258: ../../peps/pep-0258.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/roles.txt b/docutils/docs/ref/rst/roles.txt deleted file mode 100644 index 3b8b114bc..000000000 --- a/docutils/docs/ref/rst/roles.txt +++ /dev/null @@ -1,318 +0,0 @@ -========================================= - reStructuredText Interpreted Text Roles -========================================= - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -This document describes the interpreted text roles implemented in the -reference reStructuredText parser. - -Interpreted text uses backquotes (`) around the text. An explicit -role marker may optionally appear before or after the text, delimited -with colons. For example:: - - This is `interpreted text` using the default role. - - This is :title:`interpreted text` using an explicit role. - -A default role may be defined by applications of reStructuredText; it -is used if no explicit ``:role:`` prefix or suffix is given. The -"default default role" is `:title-reference:`_. It can be changed -using the default-role_ directive. - -See the `Interpreted Text`_ section in the `reStructuredText Markup -Specification`_ for syntax details. For details on the hierarchy of -elements, please see `The Docutils Document Tree`_ and the `Docutils -Generic DTD`_ XML document type definition. For interpreted text role -implementation details, see `Creating reStructuredText Interpreted -Text Roles`_. - -.. _"role" directive: directives.html#role -.. _default-role: directives.html#default-role -.. _Interpreted Text: restructuredtext.html#interpreted-text -.. _reStructuredText Markup Specification: restructuredtext.html -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Interpreted Text Roles: - ../../howto/rst-roles.html - - -.. contents:: - - ---------------- - Customization ---------------- - -Custom interpreted text roles may be defined in a document with the -`"role" directive`_. Customization details are listed with each role. - -.. _class: - -A ``class`` option is recognized by the "role" directive for most -interpreted text roles. A description__ is provided in the `"role" -directive`_ documentation. - -__ directives.html#role-class - - ----------------- - Standard Roles ----------------- - -``:emphasis:`` -============== - -:Aliases: None -:DTD Element: emphasis -:Customization: - :Options: class_. - :Content: None. - -Implements emphasis. These are equivalent:: - - *text* - :emphasis:`text` - - -``:literal:`` -============== - -:Aliases: None -:DTD Element: literal -:Customization: - :Options: class_. - :Content: None. - -Implements inline literal text. These are equivalent:: - - ``text`` - :literal:`text` - -Care must be taken with backslash-escapes though. These are *not* -equivalent:: - - ``text \ and \ backslashes`` - :literal:`text \ and \ backslashes` - -The backslashes in the first line are preserved (and do nothing), -whereas the backslashes in the second line escape the following -spaces. - - -``:pep-reference:`` -=================== - -:Aliases: ``:PEP:`` -:DTD Element: reference -:Customization: - :Options: class_. - :Content: None. - -The ``:pep-reference:`` role is used to create an HTTP reference to a -PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually -used. For example:: - - See :PEP:`287` for more information about reStructuredText. - -This is equivalent to:: - - See `PEP 287`__ for more information about reStructuredText. - - __ http://www.python.org/peps/pep-0287.html - - -``:rfc-reference:`` -=================== - -:Aliases: ``:RFC:`` -:DTD Element: reference -:Customization: - :Options: class_. - :Content: None. - -The ``:rfc-reference:`` role is used to create an HTTP reference to an -RFC (Internet Request for Comments). The ``:RFC:`` alias is usually -used. For example:: - - See :RFC:`2822` for information about email headers. - -This is equivalent to:: - - See `RFC 2822`__ for information about email headers. - - __ http://www.faqs.org/rfcs/rfc2822.html - - -``:strong:`` -============ - -:Aliases: None -:DTD Element: strong -:Customization: - :Options: class_. - :Content: None. - -Implements strong emphasis. These are equivalent:: - - **text** - :strong:`text` - - -``:subscript:`` -=============== - -:Aliases: ``:sub:`` -:DTD Element: subscript -:Customization: - :Options: class_. - :Content: None. - -Implements subscripts. - -.. Tip:: - - Whitespace or punctuation is required around interpreted text, but - often not desired with subscripts & superscripts. - Backslash-escaped whitespace can be used; the whitespace will be - removed from the processed document:: - - H\ :sub:`2`\ O - E = mc\ :sup:`2` - - In such cases, readability of the plain text can be greatly - improved with substitutions:: - - The chemical formula for pure water is |H2O|. - - .. |H2O| replace:: H\ :sub:`2`\ O - - See `the reStructuredText spec`__ for further information on - `character-level markup`__ and `the substitution mechanism`__. - - __ restructuredtext.html - __ restructuredtext.html#character-level-inline-markup - __ restructuredtext.html#substitution-references - - -``:superscript:`` -================= - -:Aliases: ``:sup:`` -:DTD Element: superscript -:Customization: - :Options: class_. - :Content: None. - -Implements superscripts. See the tip in `:subscript:`_ above. - - -``:title-reference:`` -===================== - -:Aliases: ``:title:``, ``:t:``. -:DTD Element: title_reference -:Customization: - :Options: class_. - :Content: None. - -The ``:title-reference:`` role is used to describe the titles of -books, periodicals, and other materials. It is the equivalent of the -HTML "cite" element, and it is expected that HTML writers will -typically render "title_reference" elements using "cite". - -Since title references are typically rendered with italics, they are -often marked up using ``*emphasis*``, which is misleading and vague. -The "title_reference" element provides accurate and unambiguous -descriptive markup. - -Let's assume ``:title-reference:`` is the default interpreted text -role (see below) for this example:: - - `Design Patterns` [GoF95]_ is an excellent read. - -The following document fragment (pseudo-XML_) will result from -processing:: - - <paragraph> - <title_reference> - Design Patterns - - <citation_reference refname="gof95"> - GoF95 - is an excellent read. - -``:title-reference:`` is the default interpreted text role in the -standard reStructuredText parser. This means that no explicit role is -required. Applications of reStructuredText may designate a different -default role, in which case the explicit ``:title-reference:`` role -must be used to obtain a ``title_reference`` element. - - -.. _pseudo-XML: ../doctree.html#pseudo-xml - - -------------------- - Specialized Roles -------------------- - -``raw`` -======= - -:Aliases: None -:DTD Element: raw -:Customization: - :Options: class_, format - :Content: None - -.. WARNING:: - - The "raw" role is a stop-gap measure allowing the author to bypass - reStructuredText's markup. It is a "power-user" feature that - should not be overused or abused. The use of "raw" ties documents - to specific output formats and makes them less portable. - - If you often need to use "raw"-derived interpreted text roles or - the "raw" directive, that is a sign either of overuse/abuse or that - functionality may be missing from reStructuredText. Please - describe your situation in a message to the Docutils-users_ mailing - list. - - .. _Docutils-users: ../../user/mailing-lists.html#docutils-user - -The "raw" role indicates non-reStructuredText data that is to be -passed untouched to the Writer. It is the inline equivalent of the -`"raw" directive`_; see its documentation for details on the -semantics. - -.. _"raw" directive: directives.html#raw - -The "raw" role cannot be used directly. The `"role" directive`_ must -first be used to build custom roles based on the "raw" role. One or -more formats (Writer names) must be provided in a "format" option. - -For example, the following creates an HTML-specific "raw-html" role:: - - .. role:: raw-html(raw) - :format: html - -This role can now be used directly to pass data untouched to the HTML -Writer. For example:: - - If there just *has* to be a line break here, - :raw-html:`<br />` - it can be accomplished with a "raw"-derived role. - But the line block syntax should be considered first. - -.. Tip:: Roles based on "raw" should clearly indicate their origin, so - they are not mistaken for reStructuredText markup. Using a "raw-" - prefix for role names is recommended. - -In addition to "class_", the following option is recognized: - -``format`` : text - One or more space-separated output format names (Writer names). diff --git a/docutils/docs/ref/soextblx.dtd b/docutils/docs/ref/soextblx.dtd deleted file mode 100644 index 56ba311ba..000000000 --- a/docutils/docs/ref/soextblx.dtd +++ /dev/null @@ -1,312 +0,0 @@ -<!-- -=========================================================================== - OASIS XML Exchange Table Model Declaration Module -=========================================================================== -:Date: 1999-03-15 ---> - -<!-- This set of declarations defines the XML version of the Exchange - Table Model as of the date shown in the Formal Public Identifier - (FPI) for this entity. - - This set of declarations may be referred to using a public external - entity declaration and reference as shown in the following three - lines: - - <!ENTITY % calstblx - PUBLIC "-//OASIS//DTD XML Exchange Table Model 19990315//EN"> - %calstblx; - - If various parameter entities used within this set of declarations - are to be given non-default values, the appropriate declarations - should be given before calling in this package (i.e., before the - "%calstblx;" reference). ---> - -<!-- The motivation for this XML version of the Exchange Table Model - is simply to create an XML version of the SGML Exchange Table - Model. By design, no effort has been made to "improve" the model. - - This XML version incorporates the logical bare minimum changes - necessary to make the Exchange Table Model a valid XML DTD. ---> - -<!-- The XML version of the Exchange Table Model differs from - the SGML version in the following ways: - - The following parameter entities have been removed: - - - tbl.table.excep, tbl.hdft.excep, tbl.row.excep, tbl.entry.excep - There are no exceptions in XML. The following normative statement - is made in lieu of exceptions: the exchange table model explicitly - forbids a table from occurring within another table. If the - content model of an entry includes a table element, then this - cannot be enforced by the DTD, but it is a deviation from the - exchange table model to include a table within a table. - - - tbl.hdft.name, tbl.hdft.mdl, tbl.hdft.excep, tbl.hdft.att - The motivation for these elements was to change the table - header/footer elements. Since XML does not allow element declarations - to contain name groups, and the exchange table model does not - allow a table to contain footers, the continued presence of these - attributes seems unnecessary. - - The following parameter entity has been added: - - - tbl.thead.att - This entity parameterizes the attributes on thead. It replaces - the tbl.hdft.att parameter entity. - - Other miscellaneous changes: - - - Tag ommission indicators have been removed - - Comments have been removed from declarations - - NUMBER attributes have been changed to NMTOKEN - - NUTOKEN attributes have been to changed to NMTOKEN - - Removed the grouping characters around the content model - parameter entry for the 'entry' element. This is necessary - so that an entry can contain #PCDATA and be defined as an - optional, repeatable OR group beginning with #PCDATA. ---> - -<!-- This entity includes a set of element and attribute declarations - that partially defines the Exchange table model. However, the model - is not well-defined without the accompanying natural language - description of the semantics (meanings) of these various elements, - attributes, and attribute values. The semantic writeup, also available - from SGML Open, should be used in conjunction with this entity. ---> - -<!-- In order to use the Exchange table model, various parameter entity - declarations are required. A brief description is as follows: - - ENTITY NAME WHERE USED WHAT IT IS - - %yesorno In ATTLIST of: An attribute declared value - almost all elements for a "boolean" attribute - - %paracon In content model of: The "text" (logical content) - <entry> of the model group for <entry> - - %titles In content model of: The "title" part of the model - table element group for the table element - - %tbl.table.name In declaration of: The name of the "table" - table element element - - %tbl.table-titles.mdl In content model of: The model group for the title - table elements part of the content model for - table element - - %tbl.table.mdl In content model of: The model group for the content - table elements model for table element, - often (and by default) defined - in terms of %tbl.table-titles.mdl - and tgroup - - %tbl.table.att In ATTLIST of: Additional attributes on the - table element table element - - %bodyatt In ATTLIST of: Additional attributes on the - table element table element (for backward - compatibility with the SGML - model) - - %tbl.tgroup.mdl In content model of: The model group for the content - <tgroup> model for <tgroup> - - %tbl.tgroup.att In ATTLIST of: Additional attributes on the -4 <tgroup> <tgroup> element - - %tbl.thead.att In ATTLIST of: Additional attributes on the - <thead> <thead> element - - %tbl.tbody.att In ATTLIST of: Additional attributes on the - <tbody> <tbody> element - - %tbl.colspec.att In ATTLIST of: Additional attributes on the - <colspec> <colspec> element - - %tbl.row.mdl In content model of: The model group for the content - <row> model for <row> - - %tbl.row.att In ATTLIST of: Additional attributes on the - <row> <row> element - - %tbl.entry.mdl In content model of: The model group for the content - <entry> model for <entry> - - %tbl.entry.att In ATTLIST of: Additional attributes on the - <entry> <entry> element - - This set of declarations will use the default definitions shown below - for any of these parameter entities that are not declared before this - set of declarations is referenced. ---> - -<!-- These definitions are not directly related to the table model, but are - used in the default CALS table model and may be defined elsewhere (and - prior to the inclusion of this table module) in the referencing DTD. --> - -<!ENTITY % yesorno 'NMTOKEN'> <!-- no if zero(s), yes if any other value --> -<!ENTITY % titles 'title?'> -<!ENTITY % paracon '#PCDATA'> <!-- default for use in entry content --> - -<!-- -The parameter entities as defined below change and simplify the CALS table -model as published (as part of the Example DTD) in MIL-HDBK-28001. The -resulting simplified DTD has support from the SGML Open vendors and is -therefore more interoperable among different systems. - -These following declarations provide the Exchange default definitions -for these entities. However, these entities can be redefined (by giving -the appropriate parameter entity declaration(s) prior to the reference -to this Table Model declaration set entity) to fit the needs of the -current application. - -Note, however, that changes may have significant effect on the ability to -interchange table information. These changes may manifest themselves -in useability, presentation, and possible structure information degradation. ---> - -<!ENTITY % tbl.table.name "table"> -<!ENTITY % tbl.table-titles.mdl "%titles;,"> -<!ENTITY % tbl.table-main.mdl "tgroup+"> -<!ENTITY % tbl.table.mdl "%tbl.table-titles.mdl; %tbl.table-main.mdl;"> -<!ENTITY % tbl.table.att " - pgwide %yesorno; #IMPLIED "> -<!ENTITY % bodyatt ""> -<!ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody"> -<!ENTITY % tbl.tgroup.att ""> -<!ENTITY % tbl.thead.att ""> -<!ENTITY % tbl.tbody.att ""> -<!ENTITY % tbl.colspec.att ""> -<!ENTITY % tbl.row.mdl "entry+"> -<!ENTITY % tbl.row.att ""> -<!ENTITY % tbl.entry.mdl "(%paracon;)*"> -<!ENTITY % tbl.entry.att ""> - -<!-- ===== Element and attribute declarations follow. ===== --> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.table.name "table" - ENTITY % tbl.table-titles.mdl "%titles;," - ENTITY % tbl.table.mdl "%tbl.table-titles; tgroup+" - ENTITY % tbl.table.att " - pgwide %yesorno; #IMPLIED " ---> - -<!ELEMENT %tbl.table.name; (%tbl.table.mdl;)> - -<!ATTLIST %tbl.table.name; - frame (top|bottom|topbot|all|sides|none) #IMPLIED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - %tbl.table.att; - %bodyatt; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody" - ENTITY % tbl.tgroup.att "" ---> - -<!ELEMENT tgroup (%tbl.tgroup.mdl;) > - -<!ATTLIST tgroup - cols NMTOKEN #REQUIRED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - align (left|right|center|justify|char) #IMPLIED - %tbl.tgroup.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.colspec.att "" ---> - -<!ELEMENT colspec EMPTY > - -<!ATTLIST colspec - colnum NMTOKEN #IMPLIED - colname NMTOKEN #IMPLIED - colwidth CDATA #IMPLIED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - align (left|right|center|justify|char) #IMPLIED - char CDATA #IMPLIED - charoff NMTOKEN #IMPLIED - %tbl.colspec.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.thead.att "" ---> - -<!ELEMENT thead (row+)> - -<!ATTLIST thead - valign (top|middle|bottom) #IMPLIED - %tbl.thead.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.tbody.att "" ---> - -<!ELEMENT tbody (row+)> - -<!ATTLIST tbody - valign (top|middle|bottom) #IMPLIED - %tbl.tbody.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.row.mdl "entry+" - ENTITY % tbl.row.att "" ---> - -<!ELEMENT row (%tbl.row.mdl;)> - -<!ATTLIST row - rowsep %yesorno; #IMPLIED - valign (top|middle|bottom) #IMPLIED - %tbl.row.att; -> - - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % paracon "#PCDATA" - ENTITY % tbl.entry.mdl "(%paracon;)*" - ENTITY % tbl.entry.att "" ---> - -<!ELEMENT entry %tbl.entry.mdl;> - -<!ATTLIST entry - colname NMTOKEN #IMPLIED - namest NMTOKEN #IMPLIED - nameend NMTOKEN #IMPLIED - morerows NMTOKEN #IMPLIED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - align (left|right|center|justify|char) #IMPLIED - char CDATA #IMPLIED - charoff NMTOKEN #IMPLIED - valign (top|middle|bottom) #IMPLIED - %tbl.entry.att; -> diff --git a/docutils/docs/ref/transforms.txt b/docutils/docs/ref/transforms.txt deleted file mode 100644 index 54446f8dd..000000000 --- a/docutils/docs/ref/transforms.txt +++ /dev/null @@ -1,116 +0,0 @@ -===================== - Docutils Transforms -===================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - - -.. contents:: - - -For background about transforms and the Transformer object, see `PEP -258`_. - -.. _PEP 258: ../peps/pep-0258.html#transformer - - -Transforms Listed in Priority Order -=================================== - -============================== ============================ ======== -Transform: module.Class Added By Priority -============================== ============================ ======== -misc.class "class" (d/p) 210 - -references.Substitutions standalone (r), pep (r) 220 - -references.PropagateTargets standalone (r), pep (r) 260 - -frontmatter.DocTitle standalone (r) 320 - -frontmatter.DocInfo standalone (r) 340 - -frontmatter.SectSubTitle standalone (r) 350 - -peps.Headers pep (r) 360 - -peps.Contents pep (r) 380 - -references.AnonymousHyperlinks standalone (r), pep (r) 440 - -references.IndirectHyperlinks standalone (r), pep (r) 460 - -peps.TargetNotes pep (r) 520 - -references.TargetNotes peps.TargetNotes (t/p) 0 - -misc.CallBack peps.TargetNotes (t/p) 1 - -references.TargetNotes "target-notes" (d/p) 540 - -references.Footnotes standalone (r), pep (r) 620 - -references.ExternalTargets standalone (r), pep (r) 640 - -references.InternalTargets standalone (r), pep (r) 660 - -parts.SectNum "sectnum" (d/p) 710 - -parts.Contents "contents" (d/p), 720 - peps.Contents (t/p) - -universal.StripComments Reader (r) 740 - -peps.PEPZero peps.Headers (t/p) 760 - -components.Filter "meta" (d/p) 780 - -writer_aux.Compound newlatex2e (w) 810 - -universal.Decorations Reader (r) 820 - -misc.Transitions standalone (r), pep (r) 830 - -universal.ExposeInternals Reader (r) 840 - -references.DanglingReferences standalone (r), pep (r) 850 - -universal.Messages Writer (w) 860 - -universal.FilterMessages Writer (w) 870 - -universal.TestMessages DocutilsTestSupport 880 - -misc.CallBack n/a 990 -============================== ============================ ======== - -Key: - -* (r): Reader -* (w): Writer -* (d): Directive -* (t): Transform -* (/p): Via a "pending" node - - -Transform Priority Range Categories -=================================== - -==== ==== ================================================ - Priority ----------- ------------------------------------------------ -From To Category -==== ==== ================================================ - 0 99 immediate execution (added by another transform) - 100 199 very early (non-standard) - 200 299 very early - 300 399 early - 400 699 main - 700 799 late - 800 899 very late - 900 999 very late (non-standard) -==== ==== ================================================ diff --git a/docutils/docs/user/Makefile.docutils-update b/docutils/docs/user/Makefile.docutils-update deleted file mode 100644 index 89097b5ff..000000000 --- a/docutils/docs/user/Makefile.docutils-update +++ /dev/null @@ -1,6 +0,0 @@ -slide-shows.s5.html: slide-shows.txt - rst2s5.py slide-shows.txt slide-shows.s5.html \ - --config ../../tools/docutils.conf \ - --overwrite-theme-files \ - --link-stylesheet \ - --no-generator --no-datestamp --no-source-link diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt deleted file mode 100644 index 0413dd5be..000000000 --- a/docutils/docs/user/config.txt +++ /dev/null @@ -1,1041 +0,0 @@ -============================== - Docutils Configuration Files -============================== - -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -.. Cross-reference command-line options with configuration file - settings? Make alphabetical indexes of both. - -Configuration files are used for persistent customization; they can be -set once and take effect every time you use a front-end tool. -Configuration file settings override the built-in defaults, and -command-line options override all. - -By default, Docutils checks the following places for configuration -files, in the following order: - -1. ``/etc/docutils.conf``: This is a system-wide configuration file, - applicable to all Docutils processing on the system. - -2. ``./docutils.conf``: This is a project-specific configuration file, - located in the current directory. The Docutils front end has to be - executed from the directory containing this configuration file for - it to take effect (note that this may have nothing to do with the - location of the source files). Settings in the project-specific - configuration file will override corresponding settings in the - system-wide file. - -3. ``~/.docutils``: This is a user-specific configuration file, - located in the user's home directory. Settings in this file will - override corresponding settings in both the system-wide and - project-specific configuration files. - -If more than one configuration file is found, all will be read but -later entries will override earlier ones. For example, a "stylesheet" -entry in a user-specific configuration file will override a -"stylesheet" entry in the system-wide file. - -The default implicit config file paths can be overridden by the -``DOCUTILSCONFIG`` environment variable. ``DOCUTILSCONFIG`` should -contain a colon-separated (semicolon-separated on Windows) sequence of -config file paths to search for; leave it empty to disable implicit -config files altogether. Tilde-expansion is performed on paths. -Paths are interpreted relative to the current working directory. -Empty path items are ignored. - -In addition, a configuration file may be explicitly specified with the -"--config" command-line option. This configuration file is read after -the three implicit ones listed above (or the ones defined by the -``DOCUTILSCONFIG`` environment variable), and its entries will have -priority. - - -------------------------- -Configuration File Syntax -------------------------- - -Configuration files use the standard ConfigParser.py_ Python_ module. -From its documentation: - - The configuration file consists of sections, lead by a "[section]" - header and followed by "name: value" entries, with continuations - in the style of `RFC 822`_; "name=value" is also accepted. Note - that leading whitespace is removed from values. ... Lines - beginning with "#" or ";" are ignored and may be used to provide - comments. - -.. Note:: No format string interpolation is done. - -Configuration file entry names correspond to internal runtime -settings. Underscores ("_") and hyphens ("-") can be used -interchangably in entry names; hyphens are automatically converted to -underscores. - -For on/off switch settings (booleans), the following values are -recognized: - -* On: "true", "yes", "on", "1" -* Off: "false", "no", "off", "0", "" (no value) - - -------------------------------------- -Configuration File Sections & Entries -------------------------------------- - -Below are the Docutils runtime settings, listed by config file -section. Any setting may be specified in any section, but only -settings from active sections will be used. Sections correspond to -Docutils components (module name or alias; section names are always in -lowercase letters). Each `Docutils application`_ uses a specific set -of components; corresponding configuration file sections are applied -when the application is used. Configuration sections are applied in -general-to-specific order, as follows: - -1. `[general]`_ - -2. `[parsers]`_, parser dependencies, and the section specific to the - Parser used ("[... parser]"). Currently, only `[restructuredtext - parser]`_ is applicable. - -3. `[readers]`_, reader dependencies, and the section specific to the - Reader used ("[... reader]"). For example, `[pep reader]`_ depends - on `[standalone reader]`_. - -4. `[writers]`_, writer dependencies, and the section specific to the - Writer used ("[... writer]"). For example, `[pep_html writer]`_ - depends on `[html4css1 writer]`_. - -5. `[applications]`_, application dependencies, and the section - specific to the Application (front-end tool) in use - ("[... application]"). - -Since any setting may be specified in any section, this ordering -allows component- or application-specific overrides of earlier -settings. For example, there may be Reader-specific overrides of -general settings; Writer-specific overrides of Parser settings; -Application-specific overrides of Writer settings; and so on. - -If multiple configuration files are applicable, the process is -completed (all sections are applied in the order given) for each one -before going on to the next. For example, a "[pep_html writer] -stylesheet" setting in an earlier configuration file would be -overridden by an "[html4css1 writer] stylesheet" setting in a later -file. - -Some knowledge of Python_ is assumed for some attributes. - -.. _ConfigParser.py: - http://www.python.org/doc/current/lib/module-ConfigParser.html -.. _Python: http://www.python.org/ -.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt -.. _Docutils application: tools.html - - -[general] -========= - -Settings in the "[general]" section are always applied. - -_`auto_id_prefix` - Prefix prepended to all auto-generated IDs generated within the - document, after id_prefix_. - - Default: "id". Options: ``--auto-id-prefix`` (hidden, intended - mainly for programmatic use). - -_`datestamp` - Include a time/datestamp in the document footer. Contains a - format string for Python's ``time.strftime``. See the `time - module documentation`__. - - Default: None. Options: ``--date, -d, --time, -t, - --no-datestamp``. - - Configuration file entry examples:: - - # Equivalent to --date command-line option, results in - # ISO 8601 extended format datestamp, e.g. "2001-12-21": - datestamp: %Y-%m-%d - - # Equivalent to --time command-line option, results in - # date/timestamp like "2001-12-21 18:43 UTC": - datestamp: %Y-%m-%d %H:%M UTC - - # Disables datestamp; equivalent to --no-datestamp: - datestamp: - - __ http://www.python.org/doc/current/lib/module-time.html - -_`debug` - Report debug-level system messages. - - Default: don't (None). Options: ``--debug, --no-debug``. - -_`dump_internals` - At the end of processing, write all internal attributes of the - document (``document.__dict__``) to stderr. - - Default: don't (None). Options: ``--dump-internals`` (hidden, for - development use only). - -_`dump_pseudo_xml` - At the end of processing, write the pseudo-XML representation of - the document to stderr. - - Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden, - for development use only). - -_`dump_settings` - At the end of processing, write all Docutils settings to stderr. - - Default: don't (None). Options: ``--dump-settings`` (hidden, for - development use only). - -_`dump_transforms` - At the end of processing, write a list of all transforms applied - to the document to stderr. - - Default: don't (None). Options: ``--dump-transforms`` (hidden, - for development use only). - -_`error_encoding` - The text encoding for error output. - - Default: "ascii". Options: ``--error-encoding, -e``. - -_`error_encoding_error_handler` - The error handler for unencodable characters in error output. See - output_encoding_error_handler_ for acceptable values. - - Default: "backslashreplace" for Python 2.3 and later; "replace" - otherwise. Options: ``--error-encoding-error-handler, - --error-encoding, -e``. - -_`exit_status_level` - A system message level threshold; non-halting system messages at - or above this level will produce a non-zero exit status at normal - exit. Exit status is the maximum system message level plus 10 (11 - for INFO, etc.). - - Default: disabled (5). Options: ``--exit-status``. - -_`expose_internals` - List of internal attribues to expose as external attributes (with - "internal:" namespace prefix). To specify multiple attributes in - configuration files, use colons to separate names; on the command - line, the option may be used more than once. - - Default: don't (None). Options: ``--expose-internal-attribute`` - (hidden, for development use only). - -_`footnote_backlinks` - Enable or disable backlinks from footnotes and citations to their - references. - - Default: enabled (1). Options: ``--footnote-backlinks, - --no-footnote-backlinks``. - -_`generator` - Include a "Generated by Docutils" credit and link in the document - footer. - - Default: off (None). Options: ``--generator, -g, - --no-generator``. - -_`halt_level` - The threshold at or above which system messages are converted to - exceptions, halting execution immediately. If `traceback`_ is - set, the exception will propagate; otherwise, Docutils will exit. - - Default: severe (4). Options: ``--halt, --strict``. - -_`id_prefix` - Prefix prepended to all IDs generated within the document. See - also auto_id_prefix_. - - Default: "" (empty). Options: ``--id-prefix`` (hidden, intended - mainly for programmatic use). - -_`input_encoding` - The text encoding for input. - - Default: auto-detect (None). Options: ``--input-encoding, -i``. - -_`input_encoding_error_handler` - The error handler for undecodable characters in the input. - Acceptable values include: - - strict - Raise an exception in case of an encoding error. - replace - Replace malformed data with the official Unicode replacement - character, U+FFFD. - ignore - Ignore malformed data and continue without further notice. - - Acceptable values are the same as for the "error" parameter of - Python's ``unicode`` function; other values may be defined in - applications or in future versions of Python. - - Default: "strict". Options: ``--input-encoding-error-handler, - --input-encoding, -i``. - -_`language_code` - `ISO 639`_ 2-letter language code (3-letter codes used only if no - 2-letter code exists). - - Default: English ("en"). Options: ``--language, -l``. - -_`output_encoding` - The text encoding for output. - - Default: "UTF-8". Options: ``--output-encoding, -o``. - -_`output_encoding_error_handler` - The error handler for unencodable characters in the output. - Acceptable values include: - - strict - Raise an exception in case of an encoding error. - replace - Replace malformed data with a suitable replacement marker, - such as "?". - ignore - Ignore malformed data and continue without further notice. - xmlcharrefreplace - Replace with the appropriate XML character reference, such as - "``†``". - backslashreplace - (Python 2.3+) Replace with backslashed escape sequences, such - as "``\u2020``". - - Acceptable values are the same as for the "error" parameter of - Python's ``encode`` string method; other values may be defined in - applications or in future versions of Python. - - Default: "strict". Options: ``--output-encoding-error-handler, - --output-encoding, -o``. - -_`record_dependencies` - Path to a file where Docutils will write a list of files that the - input and output depend on [#dependencies]_, e.g. due to file - inclusion. [#pwd]_ The format is one filename per line. This - option is particularly useful in conjunction with programs like - ``make``. - - Set to ``-`` in order to write dependencies to stdout. - - Default: None. Option: ``--record-dependencies``. - -_`report_level` - Verbosity threshold at or above which system messages are - reported. - - Default: warning (2). Options: ``--report, -r, --verbose, -v, - --quiet, -q``. - -_`sectnum_xform` - Enable or disable the section numbering transform - (docutils.transforms.parts.SectNum). - - Default: enabled (1). Options: ``--section-numbering``, - ``--no-section-numbering``. - -_`source_link` - Include a "View document source" link in the document footer. URL - will be relative to the destination. - - Default: don't (None). Options: ``--source-link, -s, - --no-source-link``. - -_`source_url` - An explicit URL for a "View document source" link, used verbatim. - - Default: compute if source_link (None). Options: ``--source-url, - --no-source-link``. - -_`strict_visitor` - When processing a document tree with the Visitor pattern, raise an - error if a writer does not support a node type listed as optional. - For transitional development use. - - Default: disabled (None). Option: ``--strict-visitor`` (hidden, - for development use only). - -_`strip_comments` - Enable the removal of comment elements from the document tree. - - Default: disabled (None). Options: ``--strip-comment``, - ``--leave-comments``. - -_`title` - The document title as metadata, which does not become part of the - document body. It overrides a document-supplied title. For - example, in HTML output the metadata document title appears in the - title bar of the browser window. - - Default: none. Option: ``--title``. - -_`toc_backlinks` - Enable backlinks from section titles to table of contents entries - ("entry"), to the top of the TOC ("top"), or disable ("none"). - - Default: "entry". Options: ``--toc-entry-backlinks, - --toc-top-backlinks, --no-toc-backlinks``. - -_`traceback` - Enable Python tracebacks when halt-level system messages and other - exceptions occur. Useful for debugging, and essential for issue - reports. Exceptions are allowed to propagate, instead of being - caught and reported (in a user-friendly way) by Docutils. - - Default: disabled (None) unless Docutils is run programmatically - using the `Publisher Interface`_. Options: ``--traceback, - --no-traceback``. - - .. _Publisher Interface: ../api/publisher.html - -_`warning_stream` - Path to a file for the output of system messages (warnings) - [#pwd]_. - - Default: stderr (None). Options: ``--warnings``. - - -[parsers] ---------- - -Docutils currently supports only one parser, for reStructuredText. - - -[restructuredtext parser] -````````````````````````` - -_`file_insertion_enabled` - Enable or disable directives that insert the contents of external - files, such as the "include_" & "raw_". A "warning" system - message (including the directive text) is inserted instead. (See - also raw_enabled_ for another security-relevant setting.) - - Default: enabled (1). Options: ``--file-insertion-enabled, - --no-file-insertion``. - - .. _include: ../ref/rst/directives.html#include - .. _raw: ../ref/rst/directives.html#raw - -_`pep_references` - Recognize and link to standalone PEP references (like "PEP 258"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--pep-references``. - -_`pep_base_url` - Base URL for PEP references. - - Default: "http://www.python.org/peps/". Option: - ``--pep-base-url``. - -_`raw_enabled` - Enable or disable the "raw_" directive. A "warning" system - message (including the directive text) is inserted instead. (See - also file_insertion_enabled_ for another security-relevant - setting.) - - Default: enabled (1). Options: ``--raw-enabled, --no-raw``. - -_`rfc_references` - Recognize and link to standalone RFC references (like "RFC 822"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--rfc-references``. - -_`rfc_base_url` - Base URL for RFC references. - - Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``. - -_`tab_width` - Number of spaces for hard tab expansion. - - Default: 8. Options: ``--tab-width``. - -_`trim_footnote_reference_space` - Remove spaces before footnote references. - - Default: don't (None); may be overriden by a writer-specific - footnote_references__ default though. Options: - ``--trim-footnote-reference-space, - --leave-footnote-reference-space``. - -__ `footnote_references [latex2e writer]`_ - - -[readers] ---------- - - -[standalone reader] -``````````````````` - -_`docinfo_xform` - Enable or disable the bibliographic field list transform - (docutils.transforms.frontmatter.DocInfo). - - Default: enabled (1). Options: ``--no-doc-info``. - -_`doctitle_xform` - Enable or disable the promotion of a lone top-level section title - to document title (and subsequent section title to document - subtitle promotion; docutils.transforms.frontmatter.DocTitle). - - Default: enabled (1). Options: ``--no-doc-title``. - -_`sectsubtitle_xform` - - Enable or disable the promotion of the title of a lone subsection - to a subtitle (docutils.transforms.frontmatter.SectSubTitle). - - Default: disabled (0). Options: ``--section-subtitles, - --no-section-subtitles``. - - -[pep reader] -```````````` - -The `pep_references`_ and `rfc_references`_ options -(`[restructuredtext parser]`_) are set on by default. - - -[python reader] -``````````````` - -Under construction. - - -[writers] ---------- - -[docutils_xml writer] -````````````````````` - -_`doctype_declaration` - Generate XML with a DOCTYPE declaration. - - Default: do (1). Options: ``--no-doctype``. - -_`indents` - Generate XML with indents and newlines. - - Default: don't (None). Options: ``--indents``. - -_`newlines` - Generate XML with newlines before and after tags. - - Default: don't (None). Options: ``--newlines``. - -.. _xml_declaration [docutils_xml writer]: - -xml_declaration - Generate XML with an XML declaration. Also defined for the - `HTML Writer`__. - - .. Caution:: The XML declaration carries text encoding - information, without which standard tools may be unable to read - the generated XML. - - Default: do (1). Options: ``--no-xml-declaration``. - - __ `xml_declaration [html4css1 writer]`_ - - -[html4css1 writer] -`````````````````` - -.. _attribution [html4css1 writer]: - -attribution - Format for block quote attributions: one of "dash" (em-dash - prefix), "parentheses"/"parens", or "none". Also defined for the - `LaTeX Writer`__. - - Default: "dash". Options: ``--attribution``. - - __ `attribution [latex2e writer]`_ - -_`cloak_email_addresses` - Scramble email addresses to confuse harvesters. In the reference - URI, the "@" will be replaced by %-escapes (as of RFC 1738). In - the visible text (link text) of an email reference, the "@" and - all periods (".") will be surrounded by ``<span>`` tags. - Furthermore, HTML entities are used to encode these characters in - order to further complicate decoding the email address. For - example, "abc@example.org" will be output as:: - - <a class="reference" href="mailto:abc%40example.org"> - abc<span>@</span>example<span>.</span>org</a> - - .. Note:: While cloaking email addresses will have little to no - impact on the rendering and usability of email links in most - browsers, some browsers (e.g. the ``links`` browser) may decode - cloaked email addresses incorrectly. - - Default: don't cloak (None). Option: ``--cloak-email-addresses``. - -_`compact_lists` - Remove extra vertical whitespace between items of bullet lists and - enumerated lists, when list items are all "simple" (i.e., items - each contain one paragraph and/or one "simple" sublist only). The - behaviour can be specified directly via "class" attributes (values - "compact" and "open") in the document. - - Default: enabled (1). Options: ``--compact-lists, - --no-compact-lists``. - -_`compact_field_lists` - Remove extra vertical whitespace between items of field lists that - are "simple" (i.e., all field bodies each contain at most one - paragraph). The behaviour can be specified directly via "class" - attributes (values "compact" and "open") in the document. - - Default: enabled (1). Options: ``--compact-field-lists, - --no-compact-field-lists``. - -_`embed_stylesheet` - Embed the stylesheet in the output HTML file. The stylesheet file - must be accessible during processing. - - Default: enabled. Options: ``--embed-stylesheet, - --link-stylesheet``. - -_`field_name_limit` - The maximum width (in characters) for one-column field names. - Longer field names will span an entire row of the table used to - render the field list. 0 indicates "no limit". See also - option_limit_. - - Default: 14 characters. Option: ``--field-name-limit``. - -.. _footnote_references [html4css1 writer]: - -footnote_references - Format for footnote references, one of "superscript" or - "brackets". Also defined for the `LaTeX Writer`__. - - Overrides [#override]_ trim_footnote_reference_space_, if - applicable. [#footnote_space]_ - - Default: "brackets". Option: ``--footnote-references``. - - __ `footnote_references [latex2e writer]`_ - -_`initial_header_level` - The initial level for header elements. This does not affect the - document title & subtitle; see doctitle_xform_. - - Default: 1 (for "<h1>"). Option: ``--initial-header-level``. - -_`option_limit` - The maximum width (in characters) for options in option lists. - Longer options will span an entire row of the table used to render - the option list. 0 indicates "no limit". See also - field_name_limit_. - - Default: 14 characters. Option: ``--option-limit``. - -.. _stylesheet [html4css1 writer]: - -stylesheet - CSS stylesheet URL, used verbatim. Overrides the - "stylesheet_path" setting [#override]_. Pass an empty string to - deactivate stylesheet inclusion. - - Default: None. Options: ``--stylesheet``. - - (Setting also defined for the `LaTeX Writer`__.) - - __ `stylesheet [latex2e writer]`_ - -.. _stylesheet_path [html4css1 writer]: - -stylesheet_path - Path to CSS stylesheet [#pwd]_. Overrides the "stylesheet" URL - setting [#override]_. Path is adjusted relative to the output - HTML file. Also defined for the `LaTeX Writer`__. - - Default: "html4css1.css" in the docutils/writers/html4css1/ - directory (installed automatically; for the exact machine-specific - path, use the ``--help`` option). Options: ``--stylesheet-path``. - - __ `stylesheet_path [latex2e writer]`_ - -.. _xml_declaration [html4css1 writer]: - -xml_declaration - Generate XML with an XML declaration. Also defined for the - `Docutils XML Writer`__. - - .. Caution:: The XML declaration carries text encoding - information, without which standard tools may be unable to read - the generated XML. - - Default: do (1). Options: ``--no-xml-declaration``. - - __ `xml_declaration [docutils_xml writer]`_ - - -[pep_html writer] -................. - -The PEP/HTML Writer derives from the standard HTML Writer, and shares -all settings defined in the `[html4css1 writer]`_ section. The -"[html4css1 writer]" section of configuration files is processed -before the "[pep_html writer]" section. - -The PEP/HTML Writer's default for the ``stylesheet_path`` setting -differs from that of the standard HTML Writer: -``docutils/writers/pep_html/pep.css`` in the installation directory is -used. For the exact machine-specific path, use the ``--help`` option. - -_`no_random` - Do not use a random banner image. Mainly used to get predictable - results when testing. - - Default: random enabled (None). Options: ``--no-random`` - (hidden). - -_`pep_home` - Home URL prefix for PEPs. - - Default: current directory ("."). Options: ``--pep-home``. - -_`template` - Path to PEP template file [#pwd]_. - - Default: "pep-html-template" (in current directory). Options: - ``--template``. - -_`python_home` - Python's home URL. - - Default: parent directory (".."). Options: ``--python-home``. - - -[s5_html writer] -................. - -The S5/HTML Writer derives from the standard HTML Writer, and shares -all settings defined in the `[html4css1 writer]`_ section. The -"[html4css1 writer]" section of configuration files is processed -before the "[s5_html writer]" section. - -The S5/HTML Writer's default for the ``compact_lists`` setting differs -from that of the standard HTML Writer: the default here is to disable -compact lists. - -_`current_slide` - - Enable or disable the current slide indicator ("1/15"). - - Default: disabled (None). Options: ``--current-slide``, - ``--no-current-slide``. - -_`overwrite_theme_files` - Allow or prevent the overwriting of existing theme files in the - ``ui/<theme>`` directory. This has no effect if "theme_url_" is - used. - - Default: keep existing theme files (None). Options: - ``--keep-theme-files``, ``--overwrite-theme-files``. - -_`theme` - Name of an installed S5 theme, to be copied into a ``ui/<theme>`` - subdirectory, beside the destination file (output HTML). Note - that existing theme files will not be overwritten; the existing - theme directory you must be deleted manually. Overrides the - "theme_url_" setting [#override]_. - - Default: "default". Option: ``--theme``. - -_`theme_url` - The URL of an S5 theme directory. The destination file (output - HTML) will link to this theme; nothing will be copied. Overrides - the "theme_" setting [#override]_. - - Default: None. Option: ``--theme-url``. - - -[latex2e writer] -```````````````` - -_`use_latex_toc` - To get pagenumbers in the table of contents the table of contents - must be generated by latex. Usually latex must be run twice to get - numbers correct. - - *Note:* LaTeX will number the sections, which might be a bug in - this case. - - Default: off. Option: ``--use-latex-toc``. - -.. XXX Missing: use_latex_docinfo - -_`use_latex_footnotes` - Use LaTeX-footnotes not a figure simulation. This might give no - Hyperrefs on /to footnotes, but should be able to handle an - unlimited number of footnotes. - - Default: off. Option: ``--use-latex-footnotes``. - -_`hyperlink_color` - Color of any hyperlinks embedded in text. Use "0" to disable - coloring of links. - - Default: "blue". Option: ``--hyperlink-color``. - -_`documentclass` - Specify latex documentclass, *but* beaware that books have chapters - articles not. - - Default: "article". Option: ``--documentclass``. - -_`documentoptions` - Specify document options. Multiple options can be given, separated by - commas. - - Default: "10pt,a4paper". Option: ``--documentoptions``. - -.. _stylesheet [latex2e writer]: - -stylesheet - Specify a stylesheet file. Overrides stylesheet_path - [#override]_. The file will be ``\input`` by latex in the - document header. Also defined for the `HTML Writer`__. - - Default: no stylesheet (""). Option: ``--stylesheet``. - - __ `stylesheet [html4css1 writer]`_ - -.. _stylesheet_path [latex2e writer]: - -stylesheet_path - Path to stylesheet [#pwd]_. Overrides "stylesheet" setting - (``--stylesheet``) [#override]_. - - Please note that you will have to run ``latex`` from the directory - containing the output file; otherwise the stylesheet reference - will be invalid. - - This setting is also defined for the `HTML Writer`__. - - Default: None. Option: ``--stylesheet-path``. - - __ `stylesheet_path [html4css1 writer]`_ - -.. XXX Missing: embed_stylesheet - -.. _footnote_references [latex2e writer]: - -footnote_references - Format for footnote references: one of "superscript" or - "brackets". Also defined for the `HTML Writer`__. - - Overrides [#override]_ trim_footnote_reference_space_, if - applicable. [#footnote_space]_ - - Default: "superscript". Option: ``--footnote-references``. - - __ `footnote_references [html4css1 writer]`_ - -.. _attribution [latex2e writer]: - -attribution - Format for block quote attributions, the same as for the - html-writer: one of "dash" (em-dash prefix), - "parentheses"/"parens" or "none". Also defined for the `HTML - Writer`__. - - Default: "dash". Option: ``--attribution``. - - __ `attribution [html4css1 writer]`_ - -_`compound_enumerators` - Enable or disable compound enumerators for nested enumerated lists - (e.g. "1.2.a.ii"). - - Default: disabled (None). Options: ``--compound-enumerators``, - ``--no-compound-enumerators``. - -_`section_prefix_for_enumerators` - Enable or disable section ("." subsection ...) prefixes for - compound enumerators. This has no effect unless - `compound_enumerators`_ are enabled. - - Default: disabled (None). Options: - ``--section-prefix-for-enumerators``, - ``--no-section-prefix-for-enumerators``. - -_`section_enumerator_separator` - The separator between section number prefix and enumerator for - compound enumerated lists (see `compound_enumerators`_). - - Generally it isn't recommended to use both sub-sections and nested - enumerated lists with compound enumerators. This setting avoids - ambiguity in the situation where a section "1" has a list item - enumerated "1.1", and subsection "1.1" has list item "1". With a - separator of ".", these both would translate into a final compound - enumerator of "1.1.1". With a separator of "-", we get the - unambiguous "1-1.1" and "1.1-1". - - Default: "-". Option: ``--section-enumerator-separator``. - -_`table_style` - Specify the drawing of separation lines. - - - "standard" lines around and between cells. - - "booktabs" a line above and below the table and one after the - head. - - "nolines". - - Default: "standard". Option: ``--table-style``. - - -[pseudoxml writer] -`````````````````` - -No settings are defined for this Writer. - - -[applications] --------------- - -[buildhtml application] -``````````````````````` - -_`prune` - List of directories not to process. To specify multiple - directories in configuration files, use colon-separated paths; on - the command line, the option may be used more than once. - - Default: none ([]). Options: ``--prune``. - -_`recurse` - Recursively scan subdirectories, or ignore subdirectories. - - Default: recurse (1). Options: ``--recurse, --local``. - -_`silent` - Work silently (no progress messages). Independent of - "report_level". - - Default: show progress (None). Options: ``--silent``. - - -[docfactory application] -```````````````````````` - -(To be completed.) - - -Other Settings -============== - -These settings are only effective as command-line options, positional -arguments, or for internal use; setting them in configuration files -has no effect. - -_`config` - Path to a configuration file to read (if it exists) [#pwd]_. - Settings may override defaults and earlier settings. The config - file is processed immediately. Multiple ``--config`` options may - be specified; each will be processed in turn. - - Filesystem path settings contained within the config file will be - interpreted relative to the config file's location (*not* relative - to the current working directory). - - Default: None. Options: ``--config``. - -_`_directories` - (``buildhtml.py`` front end.) List of paths to source - directories, set from positional arguments. - - Default: current working directory (None). No command-line - options. - -_`_disable_config` - Prevent standard configuration files from being read. For - programmatic use only. - - Default: config files enabled (None). No command-line options. - -_`_destination` - Path to output destination, set from positional arguments. - - Default: stdout (None). No command-line options. - -_`_source` - Path to input source, set from positional arguments. - - Default: stdin (None). No command-line options. - -.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html - -.. [#pwd] Path relative to the working directory of the process at - launch. - -.. [#override] The overridden setting will automatically be set to - ``None`` for command-line options and config file settings. Client - programs which specify defaults that override other settings must - do the overriding explicitly, by assigning ``None`` to the other - settings. - -.. [#dependencies] Some notes on the dependency recorder: - - * Images are only added to the dependency list if the - reStructuredText parser extracted image dimensions from the file. - - * Stylesheets are only added if they are embedded. - - * For practical reasons, the output of the LaTeX writer is - considered merely an *intermediate* processing stage. The - dependency recorder records all files the *rendered* file - (e.g. in PDF or DVI format) depends on. Thus, images and - stylesheets are both unconditionally recorded as dependencies - when using the LaTeX writer. - -.. [#footnote_space] The footnote space is trimmed if the reference - style is "superscript", and it is left if the reference style is - "brackets". - - The overriding only happens if the parser supports the - trim_footnote_reference_space option. - - ------------------------------- -Old-Format Configuration Files ------------------------------- - -Formerly, Docutils configuration files contained a single "[options]" -section only. This was found to be inflexible, and in August 2003 -Docutils adopted the current component-based configuration file -sections as described above. Docutils will still recognize the old -"[options]" section, but complains with a deprecation warning. - -To convert existing config files, the easiest way is to change the -section title: change "[options]" to "[general]". Most settings -haven't changed. The only ones to watch out for are these: - -===================== ===================================== -Old-Format Setting New Section & Setting -===================== ===================================== -pep_stylesheet [pep_html writer] stylesheet -pep_stylesheet_path [pep_html writer] stylesheet_path -pep_template [pep_html writer] template -===================== ===================================== diff --git a/docutils/docs/user/emacs.txt b/docutils/docs/user/emacs.txt deleted file mode 100644 index 49687f599..000000000 --- a/docutils/docs/user/emacs.txt +++ /dev/null @@ -1,497 +0,0 @@ -.. -*- coding: utf-8 -*- - -======================================== - Emacs Support for reStructuredText -======================================== - -:Author: Martin Blais <blais@furius.ca> -:Date: $Date$ -:Abstract: - - High-level description of the existing emacs support for editing - reStructuredText text documents. Suggested setup code and usage - instructions are provided. - -.. contents:: - - -Introduction -============ - -reStructuredText_ is a series of conventions that allows a -toolset--docutils--to extract generic document structure from simple -text files. For people who use Emacs_, there is a package that adds -some support for the conventions that reStructuredText_ specifies: -``rst.el``. - -This document describes the most important features that it provides, -how to setup your emacs to use them and how to invoke them. - - -Basic Setup -=========== - -The emacs support is completely provided by the ``rst.el`` emacs -package. In order to use these features, you need to put the file in -your emacs load-path, and to load it with:: - - (require 'rst) ;; or (load "rst") - -Additional configuration variables can be customized and can be found -by browsing the source code for ``rst.el``. - -Then you will want to bind keys to the most common commands it -provides. A standard text-mode hook function is maintained and -provided by the package for this use, set it up like this:: - - (add-hook 'text-mode-hook 'rst-text-mode-bindings) - -A prefix map is defined for all the ``rst.el`` commands. By default, -it is bound to the mode-specific-map and ``p``, e.g. ``C-c p ...``. - - -Section Decoration Adjustment -============================= - -The rst package does not completely parse all the reStructuredText_ -constructs, but it contains the ability to recognize the section -decorations and to build the hierarchy of the document. What we call -section decorations or adornments are the underlines or under- and -overlines used to mark a section title. - -There is a function that helps a great deal to maintain these -decorations: ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or -``C-=`` by default). This function is a Swiss army knife that can be -invoked repeatedly and whose behaviour depends on context: - -#. If there is an incomplete underline, e.g.:: - - My Section Title - ^^ - - Invocation will complete the section title. You can simply enter a - few characters of the title and invoke the function to complete it. - It can also be used to adjust the length of the existing decoration - when you need to edit the title. - -#. If there is no section decoration, a decoration one level under the - last encountered section level is added; - -#. If there is already a section decoration, it is promoted to the - next level. You can invoke it like this repeatedly to cycle the - title through the hierarchy of existing decorations. - -Invoking the function with a negative prefix argument, e.g. ``C-- -C-=``, will effectively reverse the direction of decoration cycling. -To alternate between underline-only and over-and-under styles, you can -use a regular prefix argument, e.g. ``C-u C-=``. See the -documentation of ``rst-adjust`` for more description of the prefix -arguments to alter the behaviour of the function. - - -Promoting and Demoting Many Sections ------------------------------------- - -When you are re-organizing the structure of a document, it can be -useful to change the level of a number of section titles. The same -key binding can be used to do that: if the region is active when the -binding is invoked, all the section titles that are within the region -are promoted accordingly (or demoted, with negative prefix arg). - - -Customizations --------------- - -You can set the variable ``rst-preferred-decorations`` to a list of -the decorations that you like to use for documents. Everyone has -their preference. ``rst-default-indent`` can be set to the number of -indent spaces preferred for the over-and-under decoration style. - - -Viewing the Hierarchy of Section Decorations -============================================ - -You can visualize the hierarchy of the section decorations in the -current buffer by invoking ``rst-display-decorations-hierarchy``, -bound on ``C-c p h``. A temporary buffer will appear with fake -section titles rendered in the style of the current document. This -can be useful when editing other people's documents to find out which -section decorations correspond to which levels. - - -Table of Contents -================= - -When you are editing long documents, it can be a bit difficult to -orient yourself in the structure of your text. To that effect, a -function is provided that quickly parses the document and presents a -hierarchically indented table of contents of the document in a -temporary buffer, in which you can navigate and press ``Return`` to go -to a specific section. - -Invoke this function (``rst-toc``) with ``C-c p t``. It should -present a temporary buffer that looks something like this:: - - Table of Contents: - Debugging Meta-Techniques - Introduction - Debugging Solution Patterns - Recognize That a Bug Exists - Subdivide and Isolate - Identify and Verify Assumptions - Use a Tool for Introspection - Change one thing at a time - Learn about the System - Understanding a bug - The Basic Steps in Debugging - Attitude - Bad Feelings - Good Feelings - References - -When you select a section title, the temporary buffer disappears and -you are left with the cursor positioned at the chosen section. - - -Inserting a Table of Contents ------------------------------ - -Oftentimes in long text documents that are meant to be read directly, -a Table of Contents is inserted at the beginning of the text. This is -the case for most internet FAQs, for example. In reStructuredText_ -documents, since the table of contents is automatically generated by -the parser with the ``.. contents::`` directive, people generally have -not been adding a text table of contents to their source documents, -and partly because it is too much trouble to edit and maintain. - -The emacs support for reStructuredText_ provides a function to insert -such a table of contents in your document. Since it is not meant to -be part of the document text, you should place such a table of -contents within a comment, so that it is ignored by the parser. This -is the favoured usage:: - - .. contents:: - .. - 1 Introduction - 2 Debugging Solution Patterns - 2.1 Recognize That a Bug Exists - 2.2 Subdivide and Isolate - 2.3 Identify and Verify Assumptions - 2.4 Use a Tool for Introspection - 2.5 Change one thing at a time - 2.6 Learn about the System - 3 Understanding a bug - 4 The Basic Steps in Debugging - 5 Attitude - 5.1 Bad Feelings - 5.2 Good Feelings - 6 References - -Just place the cursor at the top-left corner where you want to insert -the TOC and invoke the function with ``C-c p i``. The table of -contents will display all the section titles that are under the -location where the insertion occurs. This way you can insert local -table of contents by placing them in the appropriate location. - -If you have deep nesting of sections, you can use a numeric prefix -argument to limit the depth of rendering of the TOC. - -You can also customize the look of the TOC by setting the values of -the following variables:: ``rst-toc-indent``, -``rst-toc-insert-style``, ``rst-toc-insert-max-level``. - - -Maintaining the Table of Contents Up-to-date --------------------------------------------- - -One issue is that you will probably want to maintain the inserted -table of contents up-to-date. There is a function that will -automatically look for the inserted TOC (``rst-toc-insert-update``) -and it can be added to a hook on the section decoration adjustment -function, so that every time you adjust a section title, the TOC is -updated. Add this functionality with the following emacs -configuration:: - - (add-hook 'rst-adjust-hook 'rst-toc-insert-update) - -You can invoke the update on the current buffer with ``C-c p u``. - - -Navigating Between the Section Titles -===================================== - -You can move the cursor between the different sections by using the -``rst-backward-section`` and ``rst-forward-section`` functions, by -default bound to the ``C-c p p`` and ``C-c p n`` keys (also ``C-c -C-p`` and ``C-c C-n``). - - -Shifting Bullet List Levels -=========================== - -Due to the nature of reStructuredText_, bullet lists are always -indented by two characters (unless they are part of a blockquote), -e.g. :: - - - Fruits - - - Bananas - - Apples - - Oranges - - - Veggies - - - Zucchini - - Chick Peas - -To this effect, when re-organizing bullet lists, it can be useful to -shift regions of text by indents of two characters. You can use the -``C-c C-r`` and ``C-c C-l`` to shift the current region. These -bindings are similar to the ones provided by python-mode for editing -python code and behave similarly. - - -Major Mode for Editing reStructuredText Documents -================================================= - -There is a major mode available for editing and syntax highlighting -reStructuredText_ constructs. This mode was written by Stefan Merten -[#]_. It mostly provides lazy syntax coloring for many of the -constructs that reStructuredText_ prescribes. - -To enable this mode, type ``M-x rst-mode`` or you can set up an -``auto-mode-alist`` to automatically turn it on whenever you visit -reStructuredText_ documents:: - - (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) ) - -If have local variables enabled (see ``enable-local-variables`` in the -Emacs manual), you can also add the following at the top of your -documents to trigger rst-mode:: - - .. -*- mode: rst -*- - -Or add this at the end of your documents:: - - .. - Local Variables: - mode: rst - End: - -By default, the font-lock colouring is performed lazily. If you don't -like this, you can turn this off by setting the value of -``rst-mode-lazy``. You can also change the various colours (see the -source file for the whole list of customizable faces). - -.. [#] This mode used to be provided by the file ``rst-mode.el`` and - has now been integrated with the rest of the emacs code. - - -Converting Documents from Emacs -=============================== - -At the moment there is minimal support for calling the conversion -tools from within Emacs. You can add a key binding like this to -invoke it:: - - (local-set-key [(control c)(?9)] 'rst-compile) - -This function basically creates a compilation command with the correct -output name for the current buffer and then invokes Emacs' compile -function. It also looks for the presence of a ``docutils.conf`` -configuration file in the parent directories and adds it to the -cmdline options. You can customize which tool is used to perform the -conversion and some standard options to always be added as well. - -Invocation uses the toolset indicated by -``rst-compile-primary-toolset`` (default is ``'html``). Invocation -with a prefix argument uses ``rst-compile-secondary-toolset`` (default -is ``'latex``). - -.. note:: - - In general it is preferred to use a Makefile to automate the - conversion of many documents or a hierarchy of documents. The - functionality presented above is meant to be convenient for use on - single files. - - -Other / External Useful Emacs Settings -====================================== - -This section covers general emacs text-mode settings that are useful -in the context of reStructuredText_ conventions. These are not -provided by ``rst.el`` but you may find them useful specifically for -reStructuredText_ documents. - - -Settings for Filling Lists --------------------------- - -One problem with the default text-mode settings is that *filling* long -lines in bullet and enumerated lists that do not have an empty line -between them merges them together, e.g.:: - - - Bananas; - - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay; - - Oranges; - -Becomes:: - - - Bananas; One Apple a day keeps the doctor away, and eating more - - keeps the pirates at bay; Oranges; - -This is usually not what you want. What you want is this:: - - - Bananas; - - One Apple a day keeps the doctor away, and eating more keeps - the pirates at bay; - - Oranges; - -The problem is that emacs does not recognize the various consecutive -items as forming paragraph boundaries. You can fix this easily by -changing the global value of the parapraph boundary detection to -recognize such lists, using the ``rst-set-paragraph-separation`` -function:: - - (add-hook 'text-mode-hook 'rst-set-paragraph-separation) - - -``text-mode`` Settings ----------------------- - -Consult the Emacs manual for more text-mode customizations. In -particular, you may be interested in setting the following variables, -functions and modes that pertain somewhat to text-mode: - -- indent-tabs-mode -- colon-double-space -- auto-fill-mode -- auto-mode-alist -- fill-region - - -Editing Tables: Emacs table mode --------------------------------- - -You may want to check out `Emacs table mode`_ to create an edit -tables, it allows creating ascii tables compatible with -reStructuredText_. - -.. _Emacs table mode: http://table.sourceforge.net/ - - -Character Processing --------------------- - -Since reStructuredText punts on the issue of character processing, -here are some useful resources for Emacs users in the Unicode world: - -* `xmlunicode.el and unichars.el from Norman Walsh - <http://nwalsh.com/emacs/xmlchars/index.html>`__ - -* `An essay by Tim Bray, with example code - <http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__ - -* For Emacs users on Mac OS X, here are some useful useful additions - to your .emacs file. - - - To get direct keyboard input of non-ASCII characters (like - "option-e e" resulting in "é" [eacute]), first enable the option - key by setting the command key as your meta key:: - - (setq mac-command-key-is-meta t) ;; nil for option key - - Next, use one of these lines:: - - (set-keyboard-coding-system 'mac-roman) - (setq mac-keyboard-text-encoding kTextEncodingISOLatin1) - - I prefer the first line, because it enables non-Latin-1 characters - as well (em-dash, curly quotes, etc.). - - - To enable the display of all characters in the Mac-Roman charset, - first create a fontset listing the fonts to use for each range of - characters using charsets that Emacs understands:: - - (create-fontset-from-fontset-spec - "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco, - ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman, - latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman, - mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman") - - Latin-1 doesn't cover characters like em-dash and curly quotes, so - "mule-unicode-0100-24ff" is needed. - - Next, use that fontset:: - - (set-frame-font "fontset-monaco") - - - To enable cooperation between the system clipboard and the Emacs - kill ring, add this line:: - - (set-clipboard-coding-system 'mac-roman) - - Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X - FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__. - -No matter what platform (or editor) you're using, I recommend the -ProFont__ programmer's font. It's monospaced, small but readable, -similar characters are visually distinctive (like "I1l|", "0O", "ao", -and ".,:;"), and free. - -__ http://www.tobias-jung.de/seekingprofont/ - - -Credits -======= - -- The automatic section adjustment and table of contents features were - written by Martin Blais; -- ``rst-mode`` and its syntax highlighting was implemented by Stefan - Merten; -- Various other functions were implemented by David Goodger. - - -Obsolete Files -============== - -On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and -``rst-mode.el`` were merged to form the new ``rst.el``. You can -consider the old files obsolete and remove them. - - -Future Work -=========== - -Here are some features and ideas that will be worked on in the future, -in those frenzied mornings of excitement over the virtues of the -one-true-way kitchen sink of editors: - -- It would be nice to differentiate between text files using - reStructuredText_ and other general text files. If we had a - function to automatically guess whether a .txt file is following the - reStructuredText_ conventions, we could trigger rst-mode without - having to hard-code this in every text file, nor forcing the user to - add a local mode variable at the top of the file. - - We could perform this guessing by searching for a valid decoration - at the top of the document or searching for reStructuredText_ - directives further on. - -- The suggested decorations when adjusting should not have to cycle - below one below the last section decoration level preceding the - cursor. We need to fix that. - - -.. _Emacs: http://www.gnu.org/software/emacs/emacs.html -.. _reStructuredText: http://docutils.sf.net/rst.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/user/images/big-black.png b/docutils/docs/user/images/big-black.png Binary files differdeleted file mode 100644 index 869a0cf9f..000000000 --- a/docutils/docs/user/images/big-black.png +++ /dev/null diff --git a/docutils/docs/user/images/big-white.png b/docutils/docs/user/images/big-white.png Binary files differdeleted file mode 100644 index 1ce6d7d7d..000000000 --- a/docutils/docs/user/images/big-white.png +++ /dev/null diff --git a/docutils/docs/user/images/default.png b/docutils/docs/user/images/default.png Binary files differdeleted file mode 100644 index 509eeddad..000000000 --- a/docutils/docs/user/images/default.png +++ /dev/null diff --git a/docutils/docs/user/images/happy_monkey.png b/docutils/docs/user/images/happy_monkey.png Binary files differdeleted file mode 100644 index 2164c06dd..000000000 --- a/docutils/docs/user/images/happy_monkey.png +++ /dev/null diff --git a/docutils/docs/user/images/medium-black.png b/docutils/docs/user/images/medium-black.png Binary files differdeleted file mode 100644 index f851e679e..000000000 --- a/docutils/docs/user/images/medium-black.png +++ /dev/null diff --git a/docutils/docs/user/images/medium-white.png b/docutils/docs/user/images/medium-white.png Binary files differdeleted file mode 100644 index e5a465a56..000000000 --- a/docutils/docs/user/images/medium-white.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-all.png b/docutils/docs/user/images/rsp-all.png Binary files differdeleted file mode 100644 index 3e5f5ede3..000000000 --- a/docutils/docs/user/images/rsp-all.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-breaks.png b/docutils/docs/user/images/rsp-breaks.png Binary files differdeleted file mode 100644 index f2a31b098..000000000 --- a/docutils/docs/user/images/rsp-breaks.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-covers.png b/docutils/docs/user/images/rsp-covers.png Binary files differdeleted file mode 100644 index 597c2c2a8..000000000 --- a/docutils/docs/user/images/rsp-covers.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-cuts.png b/docutils/docs/user/images/rsp-cuts.png Binary files differdeleted file mode 100644 index aa46b3876..000000000 --- a/docutils/docs/user/images/rsp-cuts.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-empty.png b/docutils/docs/user/images/rsp-empty.png Binary files differdeleted file mode 100644 index f6b93c38b..000000000 --- a/docutils/docs/user/images/rsp-empty.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-objects.png b/docutils/docs/user/images/rsp-objects.png Binary files differdeleted file mode 100644 index 43ce276f1..000000000 --- a/docutils/docs/user/images/rsp-objects.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp.svg b/docutils/docs/user/images/rsp.svg deleted file mode 100644 index 03445d3bc..000000000 --- a/docutils/docs/user/images/rsp.svg +++ /dev/null @@ -1,636 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="1224.0000pt" - height="792.00000pt" - id="svg16130" - sodipodi:version="0.32" - inkscape:version="0.42" - sodipodi:docbase="/Users/david/projects/docutils/s5-branch/docs/user/images" - sodipodi:docname="rsp.svg" - inkscape:export-filename="/Users/david/projects/docutils/s5-branch/docs/user/images/rsp-empty.png" - inkscape:export-xdpi="90.000000" - inkscape:export-ydpi="90.000000"> - <defs - id="defs16132"> - <radialGradient - cx="64.960804" - cy="86.732626" - fx="64.394720" - fy="89.843742" - id="radialGradient1157" - r="4.6795605" - xlink:href="#linearGradient1125" - gradientTransform="scale(1.232968,0.811051)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1147" - x1="30.807715" - x2="9.1659926" - xlink:href="#linearGradient1129" - y1="134.41771" - y2="128.61883" - gradientTransform="scale(2.035443,0.491293)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1146" - x1="23.109005" - x2="23.655650" - xlink:href="#linearGradient1129" - y1="86.372661" - y2="75.530011" - gradientTransform="scale(1.564854,0.639037)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1150" - x1="7.1055503" - x2="37.417715" - xlink:href="#linearGradient1152" - y1="148.97907" - y2="149.31015" - gradientTransform="scale(1.328405,0.752782)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1152"> - <stop - id="stop1153" - offset="0.00000000" - style="stop-color:#ffffff;stop-opacity:0.00000000;" /> - <stop - id="stop1155" - offset="0.44302326" - style="stop-color:#ffffff;stop-opacity:0.46274510;" /> - <stop - id="stop1154" - offset="1.0000000" - style="stop-color:#ffffff;stop-opacity:0.00000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1151" - x1="29.180973" - x2="12.077421" - xlink:href="#linearGradient1152" - y1="176.88234" - y2="176.49016" - gradientTransform="scale(1.503932,0.664924)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1135" - x1="5.6004575" - x2="57.337623" - xlink:href="#linearGradient1136" - y1="125.70108" - y2="125.70108" - gradientTransform="scale(1.240748,0.805966)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1129"> - <stop - id="stop1130" - offset="0.00000000" - style="stop-color:#ffffff;stop-opacity:0.00000000;" /> - <stop - id="stop1131" - offset="1.0000000" - style="stop-color:#ffffff;stop-opacity:0.64583331;" /> - </linearGradient> - <linearGradient - id="linearGradient1128" - x1="76.620649" - x2="89.927438" - xlink:href="#linearGradient1129" - y1="79.202017" - y2="132.51965" - gradientTransform="scale(1.342210,0.745040)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1133" - x1="95.959445" - x2="95.959445" - xlink:href="#linearGradient1125" - y1="96.280971" - y2="6.0312801" - gradientTransform="scale(1.356086,0.737416)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1136"> - <stop - id="stop1137" - offset="0.00000000" - style="stop-color:#000000;stop-opacity:1.0000000;" /> - <stop - id="stop1138" - offset="1.0000000" - style="stop-color:#454545;stop-opacity:1.0000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1145" - x1="26.716417" - x2="57.535761" - xlink:href="#linearGradient1136" - y1="72.512797" - y2="104.12337" - gradientTransform="scale(1.435519,0.696612)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1125"> - <stop - id="stop1126" - offset="0.00000000" - style="stop-color:#979797;stop-opacity:1.0000000;" /> - <stop - id="stop1163" - offset="0.35050300" - style="stop-color:#fafafa;stop-opacity:1.0000000;" /> - <stop - id="stop1164" - offset="0.36050299" - style="stop-color:#9f9f9f;stop-opacity:1.0000000;" /> - <stop - id="stop1127" - offset="1.0000000" - style="stop-color:#ffffff;stop-opacity:1.0000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1134" - x1="66.560545" - x2="26.091148" - xlink:href="#linearGradient1125" - y1="135.98955" - y2="85.436682" - gradientTransform="scale(1.892867,0.528299)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1243"> - <stop - id="stop1244" - offset="0.00000000" - style="stop-color:#000000;stop-opacity:0.19791667;" /> - <stop - id="stop1245" - offset="1.0000000" - style="stop-color:#000000;stop-opacity:0.00000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1149" - x1="508.22840" - x2="505.28565" - xlink:href="#linearGradient1243" - y1="556.37391" - y2="107.87502" - gradientTransform="scale(1.347706,0.742001)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16217" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16219" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16221" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16223" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="0.52132701" - inkscape:cx="650.00000" - inkscape:cy="497.00000" - inkscape:document-units="px" - inkscape:current-layer="layer7" - showgrid="true" - inkscape:grid-bbox="false" - inkscape:grid-points="false" - gridspacingx="5.0000000px" - gridspacingy="5.0000000px" - gridtolerance="2.5000000px" - inkscape:window-width="920" - inkscape:window-height="603" - inkscape:window-x="20" - inkscape:window-y="73" /> - <metadata - id="metadata16135"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="base" - inkscape:groupmode="layer" - id="layer1" - style="display:inline"> - <g - id="g17404" - transform="translate(100.0000,-75.00000)" - style="stroke:none;stroke-opacity:1.0000000"> - <rect - ry="38.000000" - rx="38.000000" - style="fill:#ffffff;fill-opacity:0.14999999;stroke:none;stroke-opacity:1.0000000" - id="rrect19" - width="1100.0000" - height="844.00000" - x="0.0000000" - y="146.00000" /> - <rect - ry="36.000000" - rx="36.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect18" - width="1096.0000" - height="840.00000" - x="2.0000000" - y="148.00000" /> - <rect - ry="34.000000" - rx="34.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect17" - width="1092.0000" - height="836.00000" - x="4.0000000" - y="150.00000" /> - <rect - ry="32.000000" - rx="32.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect16" - width="1088.0000" - height="832.00000" - x="6.0000000" - y="152.00000" /> - <rect - ry="30.000000" - rx="30.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect15" - width="1084.0000" - height="828.00000" - x="8.0000000" - y="154.00000" /> - <rect - ry="28.000000" - rx="28.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect14" - width="1080.0000" - height="824.00000" - x="10.000000" - y="156.00000" /> - <rect - ry="26.000000" - rx="26.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect13" - width="1076.0000" - height="820.00000" - x="12.000000" - y="158.00000" /> - <rect - ry="24.000000" - rx="24.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect12" - width="1072.0000" - height="816.00000" - x="14.000000" - y="160.00000" /> - <rect - ry="22.000000" - rx="22.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect11" - width="1068.0000" - height="812.00000" - x="16.000000" - y="162.00000" /> - <rect - ry="20.000000" - rx="20.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect10" - width="1064.0000" - height="808.00000" - x="18.000000" - y="164.00000" /> - <rect - ry="18.000000" - rx="18.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect9" - width="1060.0000" - height="804.00000" - x="20.000000" - y="166.00000" /> - <rect - ry="16.000000" - rx="16.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect8" - width="1056.0000" - height="800.00000" - x="22.000000" - y="168.00000" /> - <rect - ry="14.000000" - rx="14.000000" - style="fill:#ffffff;fill-opacity:0.11999995;stroke:none;stroke-opacity:1.0000000" - id="rrect7" - width="1052.0000" - height="796.00000" - x="24.000000" - y="170.00000" /> - <rect - ry="12.000000" - rx="12.000000" - style="fill:#ffffff;fill-opacity:0.14000000;stroke:none;stroke-opacity:1.0000000" - id="rrect6" - width="1048.0000" - height="792.00000" - x="26.000000" - y="172.00000" /> - <rect - ry="10.000000" - rx="10.000000" - style="fill:#ffffff;fill-opacity:0.15999998;stroke:none;stroke-opacity:1.0000000" - id="rrect5" - width="1044.0000" - height="788.00000" - x="28.000000" - y="174.00000" /> - <rect - ry="8.0000000" - rx="8.0000000" - style="fill:#ffffff;fill-opacity:0.17999996;stroke:none;stroke-opacity:1.0000000" - id="rrect4" - width="1040.0000" - height="784.00000" - x="30.000000" - y="176.00000" /> - <rect - ry="6.0000000" - rx="6.0000000" - style="fill:#ffffff;fill-opacity:0.20000000;stroke:none;stroke-opacity:1.0000000" - id="rrect3" - width="1036.0000" - height="780.00000" - x="32.000000" - y="178.00000" /> - <rect - ry="4.0000000" - rx="4.0000000" - style="fill:#ffffff;fill-opacity:0.21999998;stroke:none;stroke-opacity:1.0000000" - id="rrect2" - width="1032.0000" - height="776.00000" - x="34.000000" - y="180.00000" /> - <rect - ry="2.0000000" - rx="2.0000000" - style="fill:#ffffff;fill-opacity:0.49999997;stroke:none;stroke-opacity:1.0000000" - id="rrect1" - width="1028.0000" - height="772.00000" - x="36.000000" - y="182.00000" /> - <rect - style="fill:#ffffff;fill-opacity:1.0000000;stroke:none;stroke-width:2.0000000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="rect7529" - width="1024.0000" - height="768.00000" - x="38.000000" - y="184.00000" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer6" - inkscape:label="cuts" - style="display:inline"> - <g - style="display:inline" - id="g17268" - transform="matrix(3.955288,0.000000,0.000000,3.955288,-1133.851,-788.5280)"> - <g - transform="matrix(-1.028194e-2,1.033891e-2,-1.033891e-2,-1.028194e-2,587.3686,366.0048)" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - id="g17126"> - <path - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - sodipodi:nodetypes="ccccc" - id="path17128" - d="M 7602.2995,10592.638 L 6351.2995,11841.638 L 7603.2995,9842.6385 L 8851.2995,11843.638 L 7602.2995,10592.638 z " /> - </g> - <path - id="text17130" - d="M 346.56856,325.28003 C 346.01656,325.52003 345.34456,325.66403 344.48056,325.66403 C 342.70456,325.66403 341.26456,324.51203 341.26456,322.35203 C 341.24056,320.43204 342.48856,319.06403 344.40856,319.06403 C 345.36856,319.06403 346.01656,319.23203 346.44856,319.42403 L 347.02456,316.71203 C 346.25656,316.42403 345.20056,316.25603 344.24056,316.25603 C 339.87256,316.25603 337.52056,319.06404 337.52056,322.49603 C 337.52056,326.19203 339.94456,328.52003 343.73656,328.52003 C 345.12856,328.52003 346.35256,328.28003 347.00056,327.96803 L 346.56856,325.28003 M 360.08468,316.52003 L 356.43668,316.52003 L 356.43668,323.50403 C 356.43668,323.81603 356.38868,324.08003 356.29268,324.29603 C 356.07668,324.87203 355.47668,325.56803 354.46868,325.56803 C 353.17269,325.56803 352.62068,324.53603 352.62068,322.83203 L 352.62068,316.52003 L 348.97268,316.52003 L 348.97268,323.40803 C 348.97268,327.03203 350.70069,328.52003 353.10068,328.52003 C 355.21268,328.52003 356.31669,327.32003 356.77268,326.60003 L 356.84468,326.60003 L 357.01268,328.25603 L 360.18068,328.25603 C 360.13268,327.27204 360.08468,326.02403 360.08468,324.48803 L 360.08468,316.52003 M 363.54031,314.31203 L 363.54031,316.52003 L 361.98031,316.52003 L 361.98031,319.20803 L 363.54031,319.20803 L 363.54031,324.03203 C 363.54031,325.68803 363.87631,326.81603 364.54831,327.51203 C 365.14831,328.11203 366.13231,328.52003 367.30831,328.52003 C 368.31631,328.52003 369.20431,328.37603 369.66031,328.20803 L 369.63631,325.44803 C 369.30031,325.52003 369.06031,325.54403 368.55631,325.54403 C 367.47631,325.54403 367.11631,324.89603 367.11631,323.48003 L 367.11631,319.20803 L 369.73231,319.20803 L 369.73231,316.52003 L 367.11631,316.52003 L 367.11631,313.32803 L 363.54031,314.31203 M 371.17681,327.68003 C 372.06481,328.16003 373.43281,328.52003 374.96881,328.52003 C 378.32881,328.52003 380.03281,326.91203 380.03281,324.70403 C 380.00881,323.00004 379.09681,321.84803 376.86481,321.10403 C 375.42481,320.60003 374.96881,320.31203 374.96881,319.73603 C 374.96881,319.16003 375.47281,318.80003 376.36081,318.80003 C 377.34481,318.80003 378.37681,319.18403 378.90481,319.44803 L 379.52881,316.95203 C 378.80881,316.59203 377.60881,316.25603 376.24081,316.25603 C 373.33681,316.25603 371.46481,317.91204 371.46481,320.12003 C 371.44081,321.48803 372.37681,322.83203 374.82481,323.62403 C 376.16881,324.08003 376.52881,324.36803 376.52881,324.99203 C 376.52881,325.59203 376.07281,325.95203 374.96881,325.95203 C 373.88881,325.95203 372.49681,325.49603 371.82481,325.08803 L 371.17681,327.68003" - style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer5" - inkscape:label="scissors" - style="display:inline"> - <g - style="display:inline" - transform="matrix(-0.261242,0.531875,-0.531875,-0.261243,609.4123,269.4384)" - id="g834"> - <path - transform="matrix(-0.974540,0.224211,0.224211,0.974540,434.7533,-39.90828)" - style="font-size:12.000000px;fill:#dadadb;fill-rule:evenodd;stroke:#000000;stroke-width:10.000006;stroke-linejoin:round;stroke-dasharray:none" - id="path693" - d="M 130.58000,19.228100 C 131.42800,19.228100 283.20600,268.51700 283.20600,268.51700 C 283.20600,268.51700 237.41800,294.80300 238.26600,294.80300 C 239.11400,294.80300 112.77400,100.62900 130.58000,19.228100 z " /> - <path - style="font-size:12.000000px;fill:#1f1f61;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:10.000000;stroke-linejoin:bevel;stroke-dasharray:none" - id="path596" - d="M 267.36640,300.28500 C 267.36640,300.28500 221.96450,419.33820 230.36720,437.01870 C 230.00410,447.80450 196.57070,496.47240 174.95750,496.94460 C 156.32120,498.11630 95.023300,483.45520 104.85110,423.19450 C 116.53670,361.19710 166.80670,382.68650 186.68190,380.35660 C 206.55780,378.02600 240.34010,301.17560 216.89540,284.78780 C 243.06010,291.66780 266.70660,302.06270 267.36640,300.28500 z M 178.01080,388.46270 C 110.22310,370.58330 97.043850,476.92290 157.42350,483.15570 C 225.11850,486.03500 224.54920,396.02940 178.01080,388.46270 z " /> - <path - transform="matrix(0.984591,0.174877,-0.174877,0.984591,41.27270,-35.37063)" - style="font-size:12.000000px;fill:#dadadb;fill-rule:evenodd;stroke:#000000;stroke-width:9.9999933;stroke-linejoin:bevel;stroke-dasharray:none" - id="path674" - d="M 130.58000,19.228100 C 131.42800,19.228100 283.20600,268.51700 283.20600,268.51700 C 283.20600,268.51700 237.41800,294.80300 238.26600,294.80300 C 239.11400,294.80300 112.77400,100.62900 130.58000,19.228100 z " /> - <path - transform="translate(161.5948,57.16911)" - style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none" - sodipodi:nodetypes="ccc" - id="path710" - d="M 81.400500,200.68300 C 66.137900,201.53100 63.594200,225.27300 81.400500,226.12100 C 98.359000,225.27300 98.359200,200.68300 81.400500,200.68300 z " /> - <path - transform="translate(161.5948,57.16911)" - style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none" - id="path711" - d="M 69.529600,209.16300 C 71.225500,209.16300 86.488100,224.42500 86.488100,224.42500" /> - <path - transform="translate(161.5948,57.16911)" - style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none" - sodipodi:nodetypes="cc" - id="path712" - d="M 76.313000,203.22700 C 77.160900,203.22700 92.423500,218.49000 92.423500,218.49000" /> - <path - style="font-size:12.000000px;fill:#e6ffff;fill-opacity:0.75000000;fill-rule:evenodd;stroke-width:1.0000000pt" - sodipodi:nodetypes="cccc" - id="path717" - d="M 311.59912,21.282200 C 312.44712,21.282200 250.54912,207.82500 250.54912,207.82500 C 250.54912,207.82500 257.17737,220.62188 259.72037,219.77388 C 262.26437,218.92588 318.38312,30.609400 311.59912,21.282200 z " /> - <path - transform="translate(-3.750000,3.750000)" - style="font-size:12.000000px;fill-opacity:0.31851897;fill-rule:evenodd;stroke-width:1.0000000pt" - sodipodi:nodetypes="ccccc" - id="path718" - d="M 236.85900,262.03100 L 240.39000,257.08300 L 256.63200,272.60800 L 252.68100,276.70800 L 236.85900,262.03100 z " /> - <path - style="font-size:12.000000px;fill:#1f1f61;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:10.000000;stroke-linejoin:bevel;stroke-dasharray:none" - id="path590" - d="M 319.25070,379.53570 C 386.05280,358.26700 404.56760,463.80860 344.57810,473.07250 C 277.11370,479.35530 273.15220,389.43500 319.25070,379.53570 z M 225.57020,295.96700 C 225.57020,295.96700 276.90680,412.58430 269.40450,430.66530 C 270.31010,441.41910 306.15060,488.34270 327.76030,487.72650 C 346.43190,487.95870 406.91430,470.23100 394.06590,410.54120 C 379.27480,349.21050 330.15000,373.20280 310.18270,371.87620 C 290.21460,370.54890 252.60710,295.49620 275.19730,277.94910 C 249.41200,286.13730 226.31860,297.70920 225.57020,295.96700 z " /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer4" - inkscape:label="breaks" - style="display:inline"> - <g - style="display:inline" - id="g17263" - transform="matrix(3.955288,0.000000,0.000000,3.955288,-654.3060,-855.6644)"> - <g - transform="matrix(0.000000,1.458120e-2,1.458120e-2,0.000000,167.9907,189.6206)" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - id="g2604"> - <path - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - sodipodi:nodetypes="ccccc" - id="path2606" - d="M 7601.0000,11063.000 L 6350.0000,12312.000 L 7602.0000,10313.000 L 8850.0000,12314.000 L 7601.0000,11063.000 z " /> - </g> - <path - id="text17114" - d="M 299.55643,273.07213 C 299.55643,274.39213 299.50843,275.80813 299.46043,276.57613 L 302.55643,276.57613 L 302.70043,274.94413 L 302.74843,274.94413 C 303.56443,276.33613 304.90843,276.84013 306.27643,276.84013 C 308.96443,276.84013 311.62843,274.72813 311.62843,270.50413 C 311.65243,266.90413 309.61243,264.57613 306.80443,264.57613 C 305.17243,264.57613 303.94843,265.22413 303.25243,266.23213 L 303.20443,266.23213 L 303.20443,259.53613 L 299.55643,259.53613 L 299.55643,273.07213 M 303.20443,269.85613 C 303.20443,269.61613 303.22843,269.40013 303.27643,269.18413 C 303.51643,268.12813 304.42843,267.38413 305.41243,267.38413 C 307.11643,267.38413 307.93243,268.82413 307.93243,270.64813 C 307.93243,272.76013 306.97243,273.96013 305.41243,273.96013 C 304.35643,273.96013 303.51643,273.19213 303.27643,272.23213 C 303.22843,272.04013 303.20443,271.82413 303.20443,271.58413 L 303.20443,269.85613 M 313.90018,276.57613 L 317.54818,276.57613 L 317.54818,270.64813 C 317.54818,270.33613 317.57218,270.07213 317.62018,269.83213 C 317.86018,268.68013 318.77218,267.98413 320.11618,267.98413 C 320.52418,267.98413 320.81218,268.03213 321.12418,268.08013 L 321.12418,264.64813 C 320.86018,264.60013 320.69218,264.57613 320.35618,264.57613 C 319.20418,264.57613 317.78818,265.29613 317.18818,267.02413 L 317.09218,267.02413 L 316.94818,264.84013 L 313.82818,264.84013 C 313.90018,265.84813 313.92418,266.97613 313.92418,268.70413 L 313.90018,276.57613 M 333.40881,271.87213 C 333.45681,271.58413 333.52881,271.03213 333.52881,270.40813 C 333.52881,267.50413 332.08880,264.55213 328.29681,264.55213 C 324.24081,264.55213 322.36881,267.84013 322.36881,270.81613 C 322.36881,274.51213 324.64881,276.81613 328.63281,276.81613 C 330.21681,276.81613 331.68081,276.57613 332.88081,276.07213 L 332.40081,273.60013 C 331.41681,273.93613 330.40881,274.10413 329.16081,274.10413 C 327.45681,274.10413 325.96881,273.38413 325.84881,271.84813 L 333.40881,271.87213 M 325.82481,269.35213 C 325.92081,268.39213 326.54481,266.97613 328.10481,266.97613 C 329.76081,266.97613 330.14481,268.48813 330.14481,269.35213 L 325.82481,269.35213 M 345.46506,269.64013 C 345.46506,266.88013 344.24105,264.57613 340.32906,264.57613 C 338.19306,264.57613 336.58506,265.17613 335.76906,265.63213 L 336.44106,267.96013 C 337.20906,267.50413 338.48106,267.09613 339.68106,267.09613 C 341.48106,267.09613 341.81706,267.98413 341.81706,268.60813 L 341.81706,268.75213 C 337.66506,268.75213 334.92906,270.19213 334.92906,273.24013 C 334.92906,275.11213 336.34506,276.84013 338.72106,276.84013 C 340.11306,276.84013 341.31306,276.33613 342.08106,275.40013 L 342.15306,275.40013 L 342.36906,276.57613 L 345.65706,276.57613 C 345.51306,275.92813 345.46506,274.84813 345.46506,273.74413 L 345.46506,269.64013 M 341.93706,272.30413 C 341.93706,272.52013 341.91306,272.73613 341.86506,272.92813 C 341.62506,273.67213 340.85706,274.27213 339.96906,274.27213 C 339.15306,274.27213 338.52906,273.81613 338.52906,272.88013 C 338.52906,271.48813 340.01706,271.03213 341.93706,271.03213 L 341.93706,272.30413 M 352.00131,259.53613 L 348.35331,259.53613 L 348.35331,276.57613 L 352.00131,276.57613 L 352.00131,272.92813 L 352.91331,271.75213 L 355.76931,276.57613 L 360.25731,276.57613 L 355.45731,269.59213 L 359.65731,264.84013 L 355.26531,264.84013 L 352.88931,268.39213 C 352.60131,268.82413 352.31331,269.30413 352.04931,269.80813 L 352.00131,269.80813 L 352.00131,259.53613 M 360.71256,276.00013 C 361.60056,276.48013 362.96856,276.84013 364.50456,276.84013 C 367.86455,276.84013 369.56856,275.23213 369.56856,273.02413 C 369.54456,271.32013 368.63256,270.16813 366.40056,269.42413 C 364.96056,268.92013 364.50456,268.63213 364.50456,268.05613 C 364.50456,267.48013 365.00856,267.12013 365.89656,267.12013 C 366.88056,267.12013 367.91256,267.50413 368.44056,267.76813 L 369.06456,265.27213 C 368.34456,264.91213 367.14456,264.57613 365.77656,264.57613 C 362.87256,264.57613 361.00056,266.23213 361.00056,268.44013 C 360.97656,269.80813 361.91256,271.15213 364.36056,271.94413 C 365.70456,272.40013 366.06456,272.68813 366.06456,273.31213 C 366.06456,273.91213 365.60856,274.27213 364.50456,274.27213 C 363.42456,274.27213 362.03256,273.81613 361.36056,273.40813 L 360.71256,276.00013" - style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer3" - inkscape:label="rock" - style="display:inline"> - <g - style="display:inline" - transform="matrix(0.708388,0.000000,0.000000,0.708388,768.4189,171.0555)" - id="g2067"> - <path - sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" - id="path10" - d="M 149.15160,130.25073 L 138.01458,125.99417 L 132.85423,131.15452 L 127.69388,137.17493 L 120.81341,144.91545 L 113.07289,154.37609 L 105.33236,163.83673 L 97.591837,173.29738 L 89.851312,183.61808 L 82.970845,194.79883 L 76.090379,205.11953 L 70.069971,215.44023 L 64.909621,224.04082 L 61.469388,232.64140 L 58.889213,240.38192 L 58.889213,246.40233 L 60.609329,250.70262 L 66.629738,257.58309 L 73.510204,263.60350 L 82.110787,269.62391 L 90.711370,275.64431 L 100.17201,280.80466 L 108.77259,285.96501 L 117.37318,291.98542 L 124.25364,296.28571 L 129.41399,300.58601 L 132.85423,304.02624 L 135.43440,306.60641 L 138.01458,308.32653 L 140.59475,310.04665 L 144.03499,311.76676 L 150.05539,314.34694 L 156.93586,316.92711 L 165.53644,319.50729 L 195.63848,318.64723 L 201.65889,318.64723 L 208.53936,318.64723 L 216.27988,319.50729 L 224.02041,320.36735 L 230.90087,321.22741 L 236.06122,323.80758 L 241.22157,325.52770 L 248.10204,325.52770 L 254.98251,325.52770 L 261.86297,324.66764 L 268.74344,322.94752 L 275.62391,321.22741 L 281.64431,318.64723 L 286.80466,316.92711 L 291.10496,314.34694 L 295.40525,310.90671 L 298.84548,306.60641 L 303.14577,302.30612 L 306.58601,298.00583 L 310.02624,293.70554 L 312.60641,291.12536 L 315.18659,290.26531 L 318.62682,290.26531 L 322.92711,289.40525 L 328.94752,287.68513 L 334.96793,285.10496 L 340.98834,283.38484 L 346.14869,280.80466 L 349.58892,279.08455 L 351.30904,277.36443 L 356.78718,268.76385 L 364.48397,254.32361 L 363.12536,245.36152 L 359.04956,237.80175 L 362.48980,236.94169 L 365.93003,234.36152 L 368.51020,230.92128 L 371.09038,225.76093 L 373.67055,221.46064 L 375.39067,218.02041 L 376.25073,215.44023 L 377.11079,214.58017 L 365.93003,182.75802 L 364.20991,181.03790 L 361.62974,176.73761 L 357.32945,171.57726 L 352.16910,164.69679 L 347.00875,158.67638 L 342.70845,153.51603 L 333.79008,153.06414 L 329.62682,149.89505 L 322.92711,148.35569 L 320.03207,145.27697 L 315.64140,143.64723 L 312.97085,142.01749 L 308.94169,139.52769 L 304.14285,137.62682 L 299.34403,135.63557 L 295.22449,130.56560 L 290.24490,127.71429 L 286.80466,123.41399 L 284.22449,119.97376 L 282.50437,117.39359 L 281.64431,116.53353 L 239.50146,101.91254 L 238.64140,101.91254 L 236.06122,101.05248 L 231.76093,100.19242 L 227.46064,99.332362 L 222.30029,98.472303 L 218.00000,98.472303 L 213.69971,98.472303 L 211.11953,98.472303 L 181.51020,124.82216 L 149.15160,130.25073 z " - style="fill:#b5abab;fill-opacity:1.0000000" /> - <path - sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" - id="path1333" - d="M 272.27930,110.03646 L 278.00000,110.00000 L 281.00000,109.00000 L 285.00000,109.00000 L 288.00000,109.00000 L 290.00000,113.00000 L 293.00000,116.00000 L 295.00000,119.00000 L 298.00000,123.00000 L 300.00000,126.00000 L 302.00000,130.00000 L 303.00000,134.00000 L 303.00000,138.00000 L 302.00000,139.00000 L 302.00000,139.00000 L 301.00000,140.00000 L 301.00000,140.00000 L 297.00000,137.00000 L 293.00000,135.00000 L 290.00000,132.00000 L 287.00000,129.00000 L 284.00000,128.00000 L 280.00000,127.00000 L 277.00000,126.00000 L 273.00000,126.00000 L 270.00000,125.00000 L 266.00000,125.00000 L 262.00000,125.00000 L 259.00000,125.00000 L 254.00000,122.00000 L 249.00000,119.00000 L 245.00000,116.00000 L 240.00000,112.00000 L 235.00000,110.00000 L 230.00000,108.00000 L 225.00000,109.00000 L 219.00000,111.00000 L 214.00000,113.00000 L 209.00000,116.00000 L 204.00000,119.00000 L 199.00000,122.00000 L 194.00000,125.00000 L 190.00000,129.00000 L 186.00000,134.00000 L 183.00000,139.00000 L 177.00000,141.00000 L 171.00000,143.00000 L 164.00000,143.00000 L 157.00000,143.00000 L 150.00000,144.00000 L 143.00000,145.00000 L 137.00000,147.00000 L 131.00000,151.00000 L 129.00000,153.00000 L 127.00000,155.00000 L 125.00000,158.00000 L 124.00000,161.00000 L 117.00000,167.00000 L 111.00000,174.00000 L 106.00000,181.00000 L 101.00000,188.00000 L 96.000000,195.00000 L 92.000000,203.00000 L 87.000000,211.00000 L 81.000000,218.00000 L 78.000000,225.00000 L 74.000000,231.00000 L 70.000000,238.00000 L 69.000000,246.00000 L 74.000000,250.00000 L 79.000000,254.00000 L 83.000000,259.00000 L 88.000000,263.00000 L 93.000000,267.00000 L 97.000000,272.00000 L 102.00000,276.00000 L 107.00000,280.00000 L 111.00000,284.00000 L 116.00000,287.00000 L 121.00000,291.00000 L 126.00000,294.00000 L 132.00000,296.00000 L 138.00000,299.00000 L 144.00000,301.00000 L 150.00000,302.00000 L 155.00000,302.00000 L 159.00000,302.00000 L 164.00000,302.00000 L 168.00000,302.00000 L 172.00000,302.00000 L 176.00000,301.00000 L 180.00000,300.00000 L 184.00000,297.00000 L 188.00000,296.00000 L 191.00000,296.00000 L 193.00000,297.00000 L 196.00000,300.00000 L 198.00000,302.00000 L 201.00000,304.00000 L 204.00000,306.00000 L 207.00000,306.00000 L 211.00000,308.00000 L 214.00000,309.00000 L 218.00000,310.00000 L 222.00000,311.00000 L 226.00000,312.00000 L 230.00000,312.00000 L 233.00000,313.00000 L 237.00000,314.00000 L 240.00000,314.00000 L 244.00000,314.00000 L 246.00000,314.00000 L 249.00000,313.00000 L 252.00000,312.00000 L 255.00000,311.00000 L 258.00000,311.00000 L 261.00000,311.00000 L 267.00000,308.00000 L 273.00000,305.00000 L 279.00000,301.00000 L 285.00000,296.00000 L 290.00000,291.00000 L 296.00000,287.00000 L 302.00000,282.00000 L 308.00000,278.00000 L 312.00000,277.00000 L 316.00000,276.00000 L 321.00000,276.00000 L 325.00000,275.00000 L 329.00000,275.00000 L 334.00000,275.00000 L 338.00000,274.00000 L 343.00000,274.00000 L 344.00000,272.00000 L 346.00000,270.00000 L 349.00000,268.00000 L 351.00000,265.00000 L 354.00000,263.00000 L 356.00000,259.00000 L 357.00000,256.00000 L 359.00000,253.00000 L 357.00000,248.00000 L 355.00000,244.00000 L 353.00000,239.00000 L 352.00000,234.00000 L 355.00000,231.00000 L 359.00000,228.00000 L 363.00000,226.00000 L 366.00000,222.00000 L 363.00000,217.00000 L 359.00000,212.00000 L 355.00000,206.00000 L 354.00000,200.00000 L 356.00000,192.00000 L 358.00000,183.00000 L 358.00000,175.00000 L 354.00000,167.00000 L 352.00000,165.00000 L 349.00000,163.00000 L 347.00000,161.00000 L 344.00000,160.00000 L 341.00000,159.00000 L 338.00000,158.00000 L 335.00000,158.00000 L 332.00000,158.00000 L 330.00000,156.00000 L 328.00000,154.00000 L 327.00000,153.00000 L 327.00000,150.00000 L 329.00000,149.00000 L 335.00000,150.00000 L 342.00000,151.00000 L 349.00000,152.00000 L 355.00000,154.00000 L 361.00000,156.00000 L 367.00000,160.00000 L 371.00000,164.00000 L 374.00000,171.00000 L 374.00000,178.00000 L 373.00000,186.00000 L 372.00000,193.00000 L 375.00000,200.00000 L 379.00000,204.00000 L 382.00000,208.00000 L 386.00000,212.00000 L 388.00000,216.00000 L 389.00000,216.00000 L 389.00000,217.00000 L 389.00000,218.00000 L 389.00000,219.00000 L 389.00000,219.00000 L 391.00000,219.00000 L 391.00000,224.00000 L 390.00000,227.00000 L 388.00000,230.00000 L 385.00000,233.00000 L 382.00000,235.00000 L 378.00000,238.00000 L 375.00000,240.00000 L 373.00000,243.00000 L 372.00000,249.00000 L 372.00000,254.00000 L 370.00000,259.00000 L 367.00000,264.00000 L 365.00000,269.00000 L 362.00000,274.00000 L 358.00000,279.00000 L 353.00000,283.00000 L 348.00000,286.00000 L 343.00000,289.00000 L 338.00000,292.00000 L 332.00000,293.00000 L 328.00000,293.00000 L 325.00000,294.00000 L 321.00000,296.00000 L 319.00000,298.00000 L 317.00000,302.00000 L 315.00000,305.00000 L 313.00000,308.00000 L 311.00000,312.00000 L 308.00000,315.00000 L 306.00000,318.00000 L 302.00000,321.00000 L 299.00000,322.00000 L 295.00000,324.00000 L 291.00000,325.00000 L 288.00000,327.00000 L 284.00000,329.00000 L 276.00000,330.00000 L 267.00000,332.00000 L 259.00000,333.00000 L 250.00000,333.00000 L 242.00000,333.00000 L 233.00000,333.00000 L 225.00000,332.00000 L 217.00000,329.00000 L 212.00000,328.00000 L 207.00000,327.00000 L 202.00000,325.00000 L 197.00000,324.00000 L 192.00000,323.00000 L 187.00000,323.00000 L 182.00000,324.00000 L 178.00000,326.00000 L 168.00000,325.00000 L 158.00000,322.00000 L 149.00000,317.00000 L 140.00000,312.00000 L 131.00000,306.00000 L 123.00000,301.00000 L 115.00000,295.00000 L 108.00000,291.00000 L 105.00000,289.00000 L 102.00000,286.00000 L 98.000000,284.00000 L 94.000000,283.00000 L 90.000000,281.00000 L 86.000000,279.00000 L 83.000000,277.00000 L 79.000000,275.00000 L 75.000000,272.00000 L 71.000000,269.00000 L 66.000000,266.00000 L 62.000000,263.00000 L 58.000000,260.00000 L 54.000000,256.00000 L 51.000000,251.00000 L 49.000000,247.00000 L 51.000000,238.00000 L 54.000000,229.00000 L 58.000000,221.00000 L 63.000000,213.00000 L 85.000000,179.00000 L 89.000000,173.00000 L 94.000000,167.00000 L 99.000000,162.00000 L 104.00000,156.00000 L 108.00000,151.00000 L 113.00000,146.00000 L 117.00000,141.00000 L 121.00000,135.00000 L 125.00000,132.00000 L 128.00000,129.00000 L 132.00000,126.00000 L 135.00000,123.00000 L 139.00000,121.00000 L 143.00000,119.00000 L 148.00000,118.00000 L 152.00000,117.00000 L 157.00000,117.00000 L 162.00000,117.00000 L 167.00000,117.00000 L 172.00000,117.00000 L 176.00000,117.00000 L 181.00000,115.00000 L 185.00000,113.00000 L 189.00000,110.00000 L 192.00000,107.00000 L 196.00000,105.00000 L 200.00000,102.00000 L 203.00000,99.000000 L 207.00000,96.000000 L 210.00000,94.000000 L 214.00000,92.000000 L 219.00000,91.000000 L 221.00000,89.000000 L 223.00000,88.000000 L 227.00000,89.000000 L 230.00000,89.000000 L 234.00000,89.000000 L 237.00000,91.000000 L 241.00000,92.000000 L 244.00000,95.000000 L 247.00000,97.000000 L 250.00000,100.00000 L 253.00000,103.00000 L 257.03646,105.51823 L 262.08918,108.23892" - style="fill:#000000" /> - <path - sodipodi:nodetypes="ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" - style="fill:#645858;fill-opacity:1.0000000" - d="M 289.76968,176.61808 L 294.76968,177.61808 L 298.76968,178.61808 L 303.76968,179.61808 L 308.76968,180.61808 L 312.76968,182.61808 L 316.76968,184.61808 L 320.76968,186.61808 L 322.88387,187.07485 L 323.76968,189.55120 L 325.24603,192.02754 L 322.76968,193.61808 L 320.88387,193.01571 L 319.76968,193.61808 L 316.76968,193.61808 L 313.58860,194.38970 L 311.00000,195.69680 L 307.54519,197.77551 L 303.00583,200.85423 L 298.46647,201.08455 L 293.92711,197.23616 L 287.84840,196.69680 L 283.30904,197.46648 L 279.53936,196.46648 L 275.76968,193.69680 L 269.32070,193.78135 L 264.55102,194.01167 L 259.78134,194.70263 L 256.55102,193.85423 L 252.62974,193.46648 L 245.24198,195.69680 L 240.70262,196.38776 L 235.62391,196.84840 L 230.31487,199.61808 L 225.77551,203.69680 L 218.92711,207.23616 L 213.16327,211.85423 L 206.31487,213.16327 L 201.23615,211.93295 L 193.84840,210.70263 L 187.99806,205.86607 L 181.57290,203.02154 L 174.66149,202.84239 L 166.45481,204.08455 L 159.37609,206.62391 L 151.06495,208.38970 L 147.76968,206.79916 L 144.29333,204.91335 L 142.58860,202.02754 L 141.58860,199.14173 L 142.47441,196.07485 L 146.76968,196.61808 L 151.76968,194.61808 L 156.76968,191.61808 L 161.76968,189.61808 L 165.76968,187.61808 L 170.76968,185.61808 L 175.76968,182.61808 L 180.76968,180.61808 L 183.76968,180.61808 L 187.76968,179.61808 L 190.76968,180.61808 L 193.76968,181.61808 L 196.76968,182.61808 L 198.76968,183.61808 L 201.76968,185.61808 L 204.76968,188.61808 L 208.76968,187.61808 L 212.76968,184.61808 L 215.76968,180.61808 L 217.76968,176.61808 L 221.76968,174.61808 L 225.76968,172.61808 L 229.76968,169.61808 L 233.76968,167.61808 L 237.76968,165.61808 L 242.76968,163.61808 L 246.76968,161.61808 L 250.76968,159.61808 L 256.76968,160.61808 L 261.76968,162.61808 L 265.76968,165.61808 L 269.76968,169.61808 L 274.76968,173.61808 L 278.76968,175.61808 L 283.76968,177.61808 L 289.76968,176.61808 z " - id="path2065" /> - <path - id="path16" - d="M 289.00000,172.00000 L 294.00000,173.00000 L 298.00000,174.00000 L 303.00000,175.00000 L 308.00000,176.00000 L 312.00000,178.00000 L 316.00000,180.00000 L 320.00000,182.00000 L 323.00000,186.00000 L 323.00000,187.00000 L 323.00000,188.00000 L 322.00000,189.00000 L 321.00000,190.00000 L 319.00000,189.00000 L 316.00000,189.00000 L 314.00000,188.00000 L 311.00000,188.00000 L 308.00000,188.00000 L 305.00000,188.00000 L 303.00000,188.00000 L 300.00000,188.00000 L 296.00000,187.00000 L 293.00000,187.00000 L 290.00000,188.00000 L 287.00000,188.00000 L 284.00000,189.00000 L 281.00000,189.00000 L 278.00000,188.00000 L 275.00000,186.00000 L 272.00000,184.00000 L 268.00000,181.00000 L 264.00000,178.00000 L 260.00000,176.00000 L 256.00000,174.00000 L 252.00000,173.00000 L 247.00000,173.00000 L 243.00000,174.00000 L 239.00000,177.00000 L 235.00000,180.00000 L 232.00000,183.00000 L 229.00000,186.00000 L 228.00000,185.00000 L 226.00000,188.00000 L 223.00000,191.00000 L 221.00000,193.00000 L 218.00000,195.00000 L 215.00000,196.00000 L 212.00000,198.00000 L 210.00000,200.00000 L 207.00000,202.00000 L 204.00000,201.00000 L 202.00000,200.00000 L 199.00000,200.00000 L 197.00000,198.00000 L 194.00000,197.00000 L 192.00000,195.00000 L 190.00000,193.00000 L 189.00000,191.00000 L 185.00000,190.00000 L 182.00000,190.00000 L 178.00000,191.00000 L 174.00000,192.00000 L 150.00000,202.00000 L 147.00000,201.00000 L 145.00000,200.00000 L 143.00000,198.00000 L 142.00000,196.00000 L 142.00000,195.00000 L 146.00000,192.00000 L 151.00000,190.00000 L 156.00000,187.00000 L 161.00000,185.00000 L 165.00000,183.00000 L 170.00000,181.00000 L 175.00000,178.00000 L 180.00000,176.00000 L 183.00000,176.00000 L 187.00000,175.00000 L 190.00000,176.00000 L 193.00000,177.00000 L 196.00000,178.00000 L 198.00000,179.00000 L 201.00000,181.00000 L 204.00000,184.00000 L 208.00000,183.00000 L 212.00000,180.00000 L 215.00000,176.00000 L 217.00000,172.00000 L 221.00000,170.00000 L 225.00000,168.00000 L 229.00000,165.00000 L 233.00000,163.00000 L 237.00000,161.00000 L 242.00000,159.00000 L 246.00000,157.00000 L 250.00000,155.00000 L 256.00000,156.00000 L 261.00000,158.00000 L 265.00000,161.00000 L 269.00000,165.00000 L 274.00000,169.00000 L 278.00000,171.00000 L 283.00000,173.00000 L 289.00000,172.00000 z " - style="fill:#000000" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer8" - inkscape:label="covers" - style="display:inline"> - <g - id="g17273" - transform="matrix(3.955288,0.000000,0.000000,3.955288,155.1671,-915.1278)"> - <g - id="g17118" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - transform="matrix(1.274278e-2,7.087528e-3,-7.087528e-3,1.274278e-2,147.7444,148.5166)"> - <path - d="M 7601.0000,11063.000 L 6350.0000,12312.000 L 7602.0000,10313.000 L 8850.0000,12314.000 L 7601.0000,11063.000 z " - id="path17120" - sodipodi:nodetypes="ccccc" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" /> - </g> - <path - id="text17122" - d="M 187.95573,356.23294 C 187.40374,356.47294 186.73173,356.61694 185.86773,356.61694 C 184.09174,356.61694 182.65173,355.46494 182.65173,353.30494 C 182.62773,351.38494 183.87574,350.01694 185.79573,350.01694 C 186.75573,350.01694 187.40374,350.18494 187.83573,350.37694 L 188.41173,347.66494 C 187.64374,347.37694 186.58773,347.20894 185.62773,347.20894 C 181.25974,347.20894 178.90773,350.01694 178.90773,353.44894 C 178.90773,357.14493 181.33174,359.47294 185.12373,359.47294 C 186.51573,359.47294 187.73974,359.23294 188.38773,358.92094 L 187.95573,356.23294 M 195.83186,359.47294 C 198.95186,359.47294 201.99986,357.50493 201.99986,353.23294 C 201.99986,349.68094 199.59986,347.20894 196.02386,347.20894 C 192.23186,347.20894 189.73586,349.63294 189.73586,353.42494 C 189.73586,357.21693 192.37586,359.47294 195.80786,359.47294 L 195.83186,359.47294 M 195.85586,356.85694 C 194.31986,356.85694 193.47986,355.34494 193.47986,353.35294 C 193.47986,351.60094 194.15186,349.82494 195.87986,349.82494 C 197.53586,349.82494 198.20786,351.60094 198.20786,353.32894 C 198.20786,355.44094 197.31986,356.85694 195.87986,356.85694 L 195.85586,356.85694 M 202.98798,347.47294 L 207.25998,359.20894 L 210.90798,359.20894 L 215.27598,347.47294 L 211.43598,347.47294 L 209.92398,352.92094 C 209.65999,353.92894 209.46798,354.81694 209.27598,355.77694 L 209.20398,355.77694 C 209.01199,354.84094 208.81998,353.90494 208.53198,352.92094 L 206.94798,347.47294 L 202.98798,347.47294 M 227.30711,354.50494 C 227.35511,354.21694 227.42711,353.66494 227.42711,353.04094 C 227.42711,350.13694 225.98711,347.18494 222.19511,347.18494 C 218.13911,347.18494 216.26711,350.47294 216.26711,353.44894 C 216.26711,357.14493 218.54711,359.44894 222.53111,359.44894 C 224.11511,359.44894 225.57911,359.20894 226.77911,358.70494 L 226.29911,356.23294 C 225.31511,356.56894 224.30711,356.73694 223.05911,356.73694 C 221.35511,356.73694 219.86711,356.01694 219.74711,354.48094 L 227.30711,354.50494 M 219.72311,351.98494 C 219.81911,351.02494 220.44311,349.60894 222.00311,349.60894 C 223.65911,349.60894 224.04311,351.12094 224.04311,351.98494 L 219.72311,351.98494 M 229.59536,359.20894 L 233.24336,359.20894 L 233.24336,353.28094 C 233.24336,352.96894 233.26736,352.70494 233.31536,352.46494 C 233.55536,351.31294 234.46736,350.61694 235.81136,350.61694 C 236.21936,350.61694 236.50736,350.66494 236.81936,350.71294 L 236.81936,347.28094 C 236.55536,347.23294 236.38736,347.20894 236.05136,347.20894 C 234.89936,347.20894 233.48336,347.92894 232.88336,349.65694 L 232.78736,349.65694 L 232.64336,347.47294 L 229.52336,347.47294 C 229.59536,348.48094 229.61936,349.60894 229.61936,351.33694 L 229.59536,359.20894 M 238.06398,358.63294 C 238.95198,359.11294 240.31999,359.47294 241.85598,359.47294 C 245.21598,359.47294 246.91998,357.86494 246.91998,355.65694 C 246.89598,353.95294 245.98398,352.80094 243.75198,352.05694 C 242.31199,351.55294 241.85598,351.26494 241.85598,350.68894 C 241.85598,350.11294 242.35999,349.75294 243.24798,349.75294 C 244.23198,349.75294 245.26399,350.13694 245.79198,350.40094 L 246.41598,347.90494 C 245.69599,347.54494 244.49598,347.20894 243.12798,347.20894 C 240.22399,347.20894 238.35198,348.86494 238.35198,351.07294 C 238.32798,352.44094 239.26399,353.78494 241.71198,354.57694 C 243.05598,355.03294 243.41598,355.32094 243.41598,355.94494 C 243.41598,356.54494 242.95998,356.90494 241.85598,356.90494 C 240.77599,356.90494 239.38398,356.44894 238.71198,356.04094 L 238.06398,358.63294" - style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer7" - inkscape:label="paper" - style="display:inline"> - <g - style="display:inline" - id="g17136" - transform="matrix(3.955288,0.000000,0.000000,3.955288,-708.3488,-857.6103)"> - <path - sodipodi:nodetypes="cccccccc" - d="M 390.34708,372.49332 L 332.34539,427.86139 L 272.20460,392.33038 L 341.37790,339.74173 L 378.06120,351.10999 C 379.20468,351.78631 380.06344,352.64698 380.62363,353.61296 L 390.84522,371.30530 C 391.02046,371.60027 390.83244,372.00903 390.34708,372.49332 z " - style="fill:#ffff19;fill-opacity:1.0000000;stroke:#000000;stroke-width:1.6000000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12105" /> - <path - id="path12107" - style="fill:#bebe12;fill-opacity:1.0000000;stroke:#000000;stroke-width:1.6000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 390.84798,371.31968 C 390.67230,371.01421 390.16897,370.87309 389.44281,370.86931 L 380.40026,370.92353 L 380.40026,370.92353 L 381.40039,356.76032 C 381.45531,355.66353 381.19370,354.58394 380.62363,353.61296 L 390.84798,371.31968 z " - sodipodi:nodetypes="ccccccc" /> - </g> - </g> -</svg> diff --git a/docutils/docs/user/images/s5-files.png b/docutils/docs/user/images/s5-files.png Binary files differdeleted file mode 100644 index 53cbbf250..000000000 --- a/docutils/docs/user/images/s5-files.png +++ /dev/null diff --git a/docutils/docs/user/images/s5-files.svg b/docutils/docs/user/images/s5-files.svg deleted file mode 100644 index a3e644a22..000000000 --- a/docutils/docs/user/images/s5-files.svg +++ /dev/null @@ -1,639 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="595.27559pt" - height="841.88976pt" - id="svg5904" - sodipodi:version="0.32" - inkscape:version="0.42" - sodipodi:docbase="/Users/david/projects/docutils/s5-branch/docs/user/images" - sodipodi:docname="s5-files.svg" - inkscape:export-filename="/Users/david/projects/docutils/s5-branch/docs/user/images/s5-files.png" - inkscape:export-xdpi="100.00000" - inkscape:export-ydpi="100.00000"> - <defs - id="defs5906"> - <marker - inkscape:stockid="Arrow1Mstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="ccccc" - id="path10526" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.4)" /> - </marker> - <marker - inkscape:stockid="Arrow1Lstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Lstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="ccccc" - id="path10529" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.8)" /> - </marker> - <marker - inkscape:stockid="Arrow2Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Mend" - style="overflow:visible;"> - <path - sodipodi:nodetypes="cccc" - id="path10518" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(0.6) rotate(180) translate(-5,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Mstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Mstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="cccc" - id="path10509" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(0.6) translate(-5,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Lend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Lend" - style="overflow:visible;"> - <path - sodipodi:nodetypes="cccc" - id="path10521" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(1.1) rotate(180) translate(-5,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Lstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Lstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="cccc" - id="path10512" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(1.1) translate(-5,0)" /> - </marker> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="1.0050485" - inkscape:cx="359.99999" - inkscape:cy="345.00000" - inkscape:document-units="px" - inkscape:current-layer="layer1" - inkscape:window-width="1161" - inkscape:window-height="810" - inkscape:window-x="51" - inkscape:window-y="22" - showgrid="true" - inkscape:grid-bbox="true" - inkscape:grid-points="true" - gridspacingx="5.0000000px" - gridspacingy="5.0000000px" - gridtolerance="2.0000000px" /> - <metadata - id="metadata5909"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1" - style="display:inline"> - <g - id="g15792"> - <g - transform="translate(-5.000000,-55.00000)" - id="g13828" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <g - id="g13761" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <path - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" - d="M 451.84175,542.36220 L 490.47866,542.36220" - id="path13719" /> - <path - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" - d="M 515.00000,597.36220 L 491.83836,597.36220" - id="path13721" /> - <path - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" - d="M 515.00000,487.36218 L 491.83836,487.36218" - id="path13723" /> - <path - id="path13725" - d="M 491.83836,487.36218 L 491.83836,597.36220 L 491.83836,707.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13757" - d="M 515.00000,707.36218 L 491.83836,707.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - </g> - <g - id="g13695" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <path - id="path10755" - d="M 451.84175,982.36220 L 490.47866,982.36220" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13691" - d="M 515.00000,1037.3622 L 491.83836,1037.3622" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13689" - d="M 515.00000,927.36218 L 491.83836,927.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13687" - d="M 491.83836,1037.3622 L 491.83836,927.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - </g> - <g - id="g13174" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <path - id="path9672" - d="M 205.00000,762.36217 L 275.47323,762.36217" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13150" - d="M 325.12023,762.36218 L 276.91055,762.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13148" - d="M 325.12023,872.36218 L 276.91055,872.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13146" - d="M 325.12023,982.36218 L 276.91055,982.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13156" - d="M 325.12023,542.36218 L 276.91055,542.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13154" - d="M 276.91055,982.36218 L 276.91055,542.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:none;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13144" - d="M 325.12023,652.36218 L 276.91055,652.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - </g> - </g> - <g - transform="translate(-5.000000,-55.00000)" - id="g13805" - style="stroke:#000000;stroke-opacity:1.0000000"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13533" - transform="translate(-160.0000,215.0000)"> - <g - id="g13262" - transform="translate(522.7639,-102.4046)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path13264" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path13266" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9098" - y="266.27817" - x="748.73212" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="266.27817" - x="748.73212" - id="tspan9100" - sodipodi:role="line">s5-core</tspan><tspan - id="tspan9102" - y="290.27818" - x="748.73212" - sodipodi:role="line">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13541" - transform="translate(-160.0000,215.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(522.7639,7.595400)" - id="g13276"> - <path - id="path13278" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path13280" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9104" - y="377.05817" - x="749.49524" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="377.05817" - x="749.49524" - id="tspan9106" - sodipodi:role="line">framing</tspan><tspan - id="tspan9108" - y="401.05818" - x="749.49524" - sodipodi:role="line">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13549" - transform="translate(-160.0000,215.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(522.7639,117.5954)" - id="g13290"> - <path - id="path13292" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path13294" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - transform="scale(1.075185,0.930073)" - sodipodi:linespacing="100.00000%" - id="text9110" - y="522.89044" - x="696.86365" - style="font-size:25.804459px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="522.89044" - x="696.86365" - id="tspan9112" - sodipodi:role="line">pretty</tspan><tspan - id="tspan9114" - y="548.69490" - x="696.86365" - sodipodi:role="line">.css</tspan></text> - </g> - </g> - <g - transform="translate(-5.000000,-55.00000)" - id="g13701" - style="stroke:#000000;stroke-opacity:1.0000000"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13617" - transform="translate(-150.0000,240.0000)"> - <g - id="g13322" - transform="translate(512.7639,312.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path13324" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path13326" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9122" - y="682.05817" - x="740.27032" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="682.05817" - x="740.27033" - id="tspan9124" - sodipodi:role="line">iepngfix</tspan><tspan - id="tspan9126" - y="706.05818" - x="740.27032" - sodipodi:role="line">.htc</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13609" - transform="translate(-150.0000,240.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(512.7639,422.5954)" - id="g13336"> - <path - id="path13338" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path13340" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9116" - y="790.57019" - x="739.14758" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="790.57019" - x="739.14758" - id="tspan9118" - sodipodi:role="line">blank</tspan><tspan - id="tspan9120" - y="814.57020" - x="739.14758" - sodipodi:role="line">.gif</tspan></text> - </g> - </g> - <g - transform="translate(-5.000000,-55.00000)" - id="g13768" - style="stroke:#000000;stroke-opacity:1.0000000"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g12998" - transform="translate(140.0000,160.0000)"> - <g - id="g12960" - transform="translate(32.76392,117.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12962" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path12964" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9080" - y="486.96219" - x="259.42813" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="486.96219" - x="259.42813" - id="tspan9082" - sodipodi:role="line">outline</tspan><tspan - id="tspan9084" - y="510.96220" - x="259.42813" - sodipodi:role="line">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13006" - transform="translate(140.0000,160.0000)"> - <g - id="g12972" - transform="translate(32.76392,227.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12974" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path12976" /> - </g> - <text - xml:space="preserve" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - x="259.34225" - y="596.96216" - id="text9284" - sodipodi:linespacing="100.00000%"><tspan - sodipodi:role="line" - id="tspan9290" - x="259.34226" - y="596.96216">print</tspan><tspan - sodipodi:role="line" - id="tspan9292" - x="259.34225" - y="620.96217">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13014" - transform="translate(140.0000,160.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(32.76392,337.5954)" - id="g12978"> - <path - id="path12980" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path12982" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - xml:space="preserve" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - x="259.56012" - y="706.32617" - id="text12043" - sodipodi:linespacing="100.00000%"><tspan - sodipodi:role="line" - id="tspan12045" - x="259.56012" - y="706.32617">opera</tspan><tspan - sodipodi:role="line" - x="259.56012" - y="730.32618" - id="tspan12047">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13022" - transform="translate(140.0000,160.0000)"> - <g - id="g12984" - transform="translate(32.76392,447.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12986" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path12988" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9092" - y="816.30219" - x="259.32312" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="816.30219" - x="259.32312" - id="tspan9094" - sodipodi:role="line">slides</tspan><tspan - id="tspan9096" - y="840.30220" - x="259.32312" - sodipodi:role="line">.js</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g12990" - transform="translate(140.0000,160.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(32.76392,7.595403)" - id="g12886"> - <path - id="path2125" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path2168" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - transform="scale(1.003177,0.996833)" - sodipodi:linespacing="100.00000%" - id="text9074" - y="378.15045" - x="258.4964" - style="font-size:24.117754px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="378.15045" - x="258.49640" - id="tspan9076" - sodipodi:role="line">slides</tspan><tspan - id="tspan9078" - y="402.26821" - x="258.49640" - sodipodi:role="line">.css</tspan></text> - </g> - </g> - <g - id="g14176"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13130" - transform="translate(0.000000,-54.99999)"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 209.99815,696.86669 L 210.00000,852.36217 L 75.000000,852.36217 L 75.000000,672.36217 L 75.000000,672.36217 L 161.90250,672.36347 C 164.47041,672.36479 166.91132,672.97771 169.09117,674.07931 L 208.96319,694.29521 C 209.63463,694.62733 209.96767,695.52913 209.99815,696.86669 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12105" /> - <path - id="path12107" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 208.98791,694.31734 C 208.30060,693.96748 207.39771,694.23853 206.38536,694.97620 L 193.92602,704.33788 L 193.92602,704.33788 L 174.73992,678.74312 C 173.22293,676.78417 171.29202,675.17947 169.09117,674.07931 L 208.98791,694.31734 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - xml:space="preserve" - style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - x="146.13911" - y="695.62231" - id="text9058" - sodipodi:linespacing="100.00000%" - transform="scale(0.997872,1.002133)"><tspan - sodipodi:role="line" - x="146.13911" - y="695.62231" - id="tspan9128"><tspan - id="tspan14172" - style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:99.999976%;writing-mode:lr-tb;text-anchor:middle;stroke:#000000;stroke-width:0.0000000;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000;font-family:Myriad" />*.html</tspan><tspan - sodipodi:role="line" - x="146.13912" - y="732.43680" - id="tspan14174">output</tspan></text> - </g> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer2" - inkscape:label="2" - style="display:inline" /> -</svg> diff --git a/docutils/docs/user/images/small-black.png b/docutils/docs/user/images/small-black.png Binary files differdeleted file mode 100644 index f8d80d387..000000000 --- a/docutils/docs/user/images/small-black.png +++ /dev/null diff --git a/docutils/docs/user/images/small-white.png b/docutils/docs/user/images/small-white.png Binary files differdeleted file mode 100644 index 65f96895d..000000000 --- a/docutils/docs/user/images/small-white.png +++ /dev/null diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt deleted file mode 100644 index ce8447692..000000000 --- a/docutils/docs/user/latex.txt +++ /dev/null @@ -1,388 +0,0 @@ -================================ - Generating LaTeX with Docutils -================================ - -:Author: Engelbert Gruber -:Contact: grubert@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Introduction -============ - -Producing LaTeX code from reST input could be done in at least two ways: - -a. Transform the internal markup into corresponding LaTeX markup e.g. - a section title would be written as ```\section{this section ...}``. -b. Using LaTeX as a typesetting system to produce desired paperwork - without caring about loosing document structure information. - -The former might be preferable, but limits to LaTeXs capabilities, so -in reality it is a mix. The reality is that LaTeX has a titlepage with -title, author and date, by default only title is used. Author and date -are shown in the docutils docinfo table and set to blank for LaTeX. -To get author and date set by LaTeX specify option "use-LaTeX-docinfo". - -Options -======= - -Configuration can be done in two ways (again): - -1. Options to the docutils tool: e.g. language selection. -2. Options to LaTeX via the stylesheet file. - -The generated LaTeX documents should be kept processable by a standard -LaTeX installation (if such a thing exists), therefore the document -contains default settings. To allow *overwriting defaults* the stylesheet -is included at last. - -Run ``rst2latex.py --help`` to see the command-line options, or have look in -config documentytion. - - -===================== ================================================ -Configuration Issue Description -===================== ================================================ -papersize Default: a4paper. Paper geometry can be changed - using ``\geometry{xxx}`` entries. - - Some possibilities: - - * a4paper, b3paper, letterpaper, executivepaper, - legalpaper - * landscape, portrait, twoside. - - and a ton of other option setting margins. - - An example:: - - \geometry{a5paper,landscape} ---------------------- ------------------------------------------------ -paragraph indent By default LaTeX indents the forst line in a - paragraph. The following lines set indentation - to zero but add a vertical space between - paragraphs.:: - - \setlength{\parindent}{0pt} - \setlength{\parskip}{6pt plus 2pt minus 1pt} ---------------------- ------------------------------------------------ -admonitionwidth The width for admonitions. - Default: 0.9*textwidth, this can be changed - e.g.:: - - \setlength{\admonitionwidth}{0.7\textwidth} ---------------------- ------------------------------------------------ -docinfowidth The width for the docinfo table. - Default: 0.9*textwidth, changed to e.g.:: - - \setlength{\docinfowidth}{0.7\textwidth} ---------------------- ------------------------------------------------ -rubric style The header contains the definition of a new - LaTeX command rubric. Inserting:: - - \renewcommand{\rubric}[1]{\subsection*{ - ~\hfill {\color{red} #1} \hfill ~}} - - sets rubric to subsection style in red. - - Default: subsection style italic. ---------------------- ------------------------------------------------ -line spacing Is done with package *setspace*, which gives - singlespace, onehalfspace and doublespace - commands. To get documentwide double spacing, - add this to your stylesheet :: - - \usepackage{setspace} - \doublespacing - - Another way :: - - \linespread{1.55} - - And yet another, add ``doublesp`` to the - documentoptions and e.g. :: - - \setstretch{1.7} - - for bigger linespacing. ---------------------- ------------------------------------------------ -font selection see below -===================== ================================================ - - -Font selection --------------- - -When generating pdf-files from LaTeX, use the pdflatex command, the files -are a lot smaller if postscript fonts are used. This *was* fixed by putting -``\usepackage{times}`` into the stylesheet. - -It is said that the typewriter font in computer modern font, the default -LaTeX font package, is too heavy compared to the others. There is a package -or some commands too fix this, which i currently cannot find. - -Some people diagnose a similar unbalance for the postscript fonts, the -package to fix this is ``\usepackage{pslatex}``. -pslatex in contrast to the standard LaTeX fonts has a bold typewriter font. - -As ``times`` does not use the appropriate mathematical fonts and ``pslatex`` -does not work with T1 encodings one should use:: - - \usepackage{mathptmx} - \usepackage[scaled=.90]{helvet} - \usepackage{courier} - -*font encoding* can be selected with option "font-encoding". Default -uses package "ae" for old style font encoding use "OT1". - -Hyphenation ------------ - -The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to -10000 almost prevents hyphenation. As this produces lines with more spcea -between words one should increase LaTeX's ``\tolerance`` for this. - -E.g. try :: - - \hyphenpenalty=5000 - \tolerance=1000 - -Unicode -------- - -The generated LaTeX documents are in latin1 encoding per default, if unicode -characters are required one must set ``--output-encoding=utf-8`` install -`LaTeX unicode`_ support and add:: - - \usepackage{ucs} - \usepackage[utf8]{inputenc} - -to the stylesheet. If LaTeX issues a Warning about unloaded/known characters -adding :: - - \PreloadUnicodePage{n} - -where *n* is the unicode pagenumber, might help. - -.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/ - -Table of figures ----------------- - -A table of figures can be generated by a command directly to LaTeX:: - - .. raw:: LaTeX - - \listoffigures - -LaTeX also has a command ``\listoftables``. - -Section numbering ------------------ - -If section numbering and LaTeX table of contents is used LaTeX and -docutils will number sections. To switch off displaying of LaTeX's -numbers one has to add following lines to the stylesheet :: - - % no section number display - \makeatletter - \def\@seccntformat#1{} - \makeatother - % no numbers in toc - \renewcommand{\numberline}[1]{} - - -Number pages by chapter ------------------------ - -This can be accomplished with :: - - \usepackage{chappg} - -From the documentation - - Basic operation of the package is to redefine ``\thepage`` to be - ``\thechapter-\arabic{page}``, and to cause the page number to be reset - (to 1) at the start of each chapter. So the pages of chapter 3 will - be numbered 3-1, 3-2, ..., and the pages of appendix B will be - numbered B-1, B-2, ... - -See documentation for details and other possibilities. - -Images ------- - -Images are included in LaTeX by the graphicx package. The supported -image formats depend on the used driver (dvi, dvips, pdftex, ...). - -If pdf-image inclusion in pdf files fails, specify -``--graphicx-option=pdftex`` or ``--graphicx-option=auto``. - - -Commands directly to LaTeX -========================== - -By means of the reST-raw directive one can give commands directly to -LaTeX, e.g. forcing a page break:: - - .. raw:: LaTeX - - \newpage - - -Or setting formulas in LaTeX:: - - .. raw:: LaTeX - - $$x^3 + 3x^2a + 3xa^2 + a^3,$$ - - -Or making a colorbox: If someone wants to get a red background for a textblock, -she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in -reStructuredText do something like this:: - - |begincolorbox| - Nobody expects the spanish inquisition. - |endcolorbox| - - .. |begincolorbox| raw:: LaTeX - - \\begin{center} - \\colorbox{bg}{ - \\parbox{0.985\\linewidth}{ - - .. |endcolorbox| raw:: LaTeX - - }} - \\end{center} - - -Custom title page ------------------ - -Currently maketitle only shows the title and subtitle, date and author are shown -in the docinfo table. - -To change the titlepage layout, e.g. see fancyhdr, one must redefine the -maketitle command in the stylesheet:: - - \renewcommand{\maketitle}{ - \begin{titlepage} - \begin{center} - \textsf{TITLE \@title} \\ - Date: \today - \end{center} - \end{titlepage} - } - -``\@title`` contains the title. - -Problems -======== - -Open to be fixed or open to discussion. - -footnotes and citations ------------------------ - -Initially both were implemented using figures, because hyperlinking back -and forth seemed to be impossible. Later images were put into figures. - -This results in footnotes images and figures possibly being mixed at page -foot. - -* Use LaTeX footnotes and citations for printing or more complex layout. -* Footnotes and citations done with figures might excell in hyperlink - support. - -If ``use-latex-citations`` is used a bibliography is inserted right at -the end of the document. *This should be customizable*. - -Tables ------- - -:Tablewidth: reST-documents line length is assumed to be 80 characters. The - tablewidth is set relative to this value. If someone produces - documents with line length of 132 this will fail. - - Table width is tried to fit in page even if it is wider than - the assumed linewidth, still assumed linewidth is a hook. - -* In tools.txt the option tables right column, there should be some more spacing - between the description and the next paragraph "Default:". - - Paragraph separation in tables is hairy. - see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab - - - The strut solution did not work. - - setting extrarowheight added ad top of row not between paragraphs in - a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline. - - baselineskip/stretch does not help. -* Should there be two hlines after table head and on table end ? -* Table: multicol cells are always {l}. -* The contents of a rowspan cell do not influence table height. - (Maybe if we put a tabular inside ?) -* Table heads and footer for longtable (firstpage lastpage ..). -* Table cells with multirow and multicolumn -* literal-blocks in table cells: - - - If verbatim or flushleft is used one gets vertical space above and below. - - This is bad for the topmost paragraph in a cell, therefore the writer - uses raggedright. - - Ragged right fails on followup paragraphs as the vertical space would be - missing. - -Notes -~~~~~ - -* table-style booktabs: booktabs.sty 1.00 does not work with longtable. - -Miscellaneous -------------- - -* Selection of LaTeX fontsize configurable. -* Assumed reST linelength for table width setting configurable. -* literal-block indentation configurable. -* recongize LaTeX and replace by ``\LaTeX``. -* Support embed-stylesheet. -* Sidebar handling. -* Maybe add end of line after term in definition list. see - http://roundup.sf.net/doc-0.5/features.pdf -* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH). -* center subsection{Abstract} gives a LaTeX error here. - ``! LaTeX Error: Something's wrong--perhaps a missing \item.`` - Committed a HACK: centering by hfill. -* Document errors are also too silent. -* Use optionlist for docinfo, the table does only work for single page. -* Consider peter funk's hooks for TeXpert: - - * Define his own document preamble (including the choice to - choose his own documentclass. That would make the ``--documentclass`` - option superfluous). I suggest to call this option ``--preamble`` - * Use two additional hooks to put additional stuff just behind the - ``\begin{document}`` and just before the ``\end{document}`` macros. - Typical uses would be ``\tableofcontents``, ``\listoffigures`` and - ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such - for larger documents. - -* The indentional problematic error in docs/user/rst/demo.txt is not - referring anywhere. -* Footnotes are not all on the same page (as in - docs/user/rst/demo.txt) and do not link back and forth. -* No link to system errors. -* Hyperlinks are not hyphenated; this leads to bad spacing. See - docs/user/rst/demo.txt 2.14 directives. -* Meta keywords into pdf ? -* Pagestyle headings does not work, when sections are starred. -* For additional docinfo items: the field_body is inserted as text, i.e. no - markup is done. -* Multiple author entries in docinfo (same thing as in html). -* keep literal-blocks together on a page, avoid pagebreaks. - - failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before - the block. - diff --git a/docutils/docs/user/links.txt b/docutils/docs/user/links.txt deleted file mode 100644 index 3bb2aaa70..000000000 --- a/docutils/docs/user/links.txt +++ /dev/null @@ -1,137 +0,0 @@ -===================== - Docutils_ Link List -===================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. title:: Docutils Links - -.. contents:: - -This document contains links users of Docutils and reStructuredText -may find useful, listed in no particular order. Many of the project -listed here are hosted in the `Docutils Sandbox`_. If you have -something to publish, you can get write access, too! - -The most current version of this link list can always be found at -http://docutils.sourceforge.net/docs/user/links.html. - - -Users ------ - -This section contains links which are interesting for all users of -Docutils. All projects listed here are usable by end users in some -way, however please do not expect all of them to run straight out of -the box. - -* For Wikis, please see the `FAQ entry about Wikis`_. - -* For Blogs (Weblogs), please see the `FAQ entry about Blogs`_. - -* Alberto Berti is developing an `OpenDocument writer`_. - -* xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML - dumps of the document tree (e.g. created with rst2xml.py) back to - reStructuredText. - -* xhtml2rest_, written by Antonios Christofides, is a simple utility - to convert XHTML to reStructuredText. - -* rst2ht_, by Oliver Rutherfurd, converts reStructuredText to an .ht - template, for use with ht2html_. - -* htmlnav_, by Gunnar Schwant, is an HTML writer which supports - navigation bars. - -* rst2chm_, written by Oliver Rutherfurd, generates Microsoft HTML - Help files from reStructuredText files. - -* rest2web_, by Michael Foord, is a tool for creating web sites with - reStructuredText. - -* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope" - application that is complete and ready to install. - -* The Docutils interface to PythonPoint_, also by Richard Jones, - produces PDF presentations using ReportLabs. - -* Engelbert Gruber has begun a `ManPage Writer`_. - -* Oliver Rutherfurd has begun a `DocBook Writer`_. - -* Gunnar Schwant's DocFactory_ is a wxPython GUI application for - Docutils. - -* Patrick O'Brien has taken over the `OpenOffice.org Writer`_. - -* Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely - on CSS (stylesheets). - -* Beni Cherniavsky has written a generic `preprocessing module`_ for - roles and/or directives and built preprocessors for TeX math for - both LaTeX and HTML output on top of it. - -* Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping - to handle everything one might do with Docutils. - - -API Developers --------------- - -This section contains links which are primarily interesting for -developers who use the Docutils API from within their own -applications. - -* Nabu_, written by Martin Blais, is a publishing system which - extracts information from reStructuredText documents and stores it - in a database. Python knowledge is required to write extractor - functions (see `Writing an Extractor`_) and to retrieve the data - from the database again. - -* There is a `pickle writer`_, written by Martin Blais. - - -Core Developers ---------------- - -Links primarily interesting for developers who work with the Docutils -code base. - -* PySource_, by Tony Ibbs, is an experimental Python source Reader. - There is some related code in David Goodger's sandbox - (pysource_reader_) and a `Python Source Reader`_ document. - - -.. _Docutils: http://docutils.sourceforge.net/ -.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax -.. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax -.. _OpenDocument writer: http://thread.gmane.org/gmane.text.docutils.devel/3388 -.. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html -.. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html -.. _ht2html: http://ht2html.sourceforge.net/ -.. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/ -.. _xhtml2rest: http://docutils.sf.net/sandbox/fwiemann/xhtml2rest/ -.. _rst2chm: http://www.rutherfurd.net/software/rst2chm/ -.. _rest2web: http://www.voidspace.org.uk/python/rest2web/ -.. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html -.. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/ -.. _PySource: http://docutils.sf.net/sandbox/tibs/pysource/ -.. _pysource_reader: http://docutils.sf.net/sandbox/davidg/pysource_reader/ -.. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html -.. _PythonPoint: http://docutils.sf.net/sandbox/richard/pythonpoint/ -.. _Manpage Writer: http://docutils.sf.net/sandbox/grubert/man/ -.. _ReportLabs/PDF Writer: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/ -.. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/ -.. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/ -.. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/pobrien/OpenOffice/ -.. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/ -.. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/ -.. _Makefile: http://docutils.sf.net/sandbox/cben/make/ -.. _Nabu: http://furius.ca/nabu/ -.. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html -.. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/ diff --git a/docutils/docs/user/mailing-lists.txt b/docutils/docs/user/mailing-lists.txt deleted file mode 100644 index 8137e29e7..000000000 --- a/docutils/docs/user/mailing-lists.txt +++ /dev/null @@ -1,111 +0,0 @@ -========================= - Docutils_ Mailing Lists -========================= - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - - -All discussion about Docutils takes place on mailing lists. - -There are four different lists with traffic related to Docutils. If -unsure, use the **Docutils-users** mailing list: - - -Docutils-users --------------- - -The Docutils-users mailing list is a place to discuss any issues -related to the usage of Docutils and reStructuredText. (Please be -sure to check the FAQ_ first.) - -There are three possibilities to **read and post** messages on the -mailing lists; use the one you feel most comfortable with. - -* Using an `email subscription`__. This is the traditional way; you - will receive all messages sent to the mailing list via email. - - __ http://lists.sourceforge.net/lists/listinfo/docutils-users - -* Using Gmane's `web interface`__. To post a message, click "post" or - "followup" in the drop-down menu on the right. - - __ http://news.gmane.org/gmane.text.docutils.user - -* If you prefer using a newsreader, you can also use Gmane's `NNTP - interface`__ (gmane.text.docutils.user on news.gmane.org). - - __ nntp://news.gmane.org/gmane.text.docutils.user. - -**If you do not wish to subscribe,** you can also just send an email -message to Docutils-users@lists.sourceforge.net. Please note in your -message that you are not subscribed (to make sure that you receive -copies [CCs] of any replies). - -The first time you post a message without being subscribed (also when -posting via Gmane), you will receive an automatic response with the -subject "Your message to Docutils-users awaits moderator approval"; -this is done to prevent spam to the mailing lists. Your message will -usually be approved within a few hours. To avoid duplicates, please -do not resend your message using a different email address. After -your first message has been approved, your email address will be added -to the whitelist and future messages will be posted to the mailing -list without moderation. - - -Doc-SIG -------- - -The "Python Documentation Special Interest Group" (Doc-SIG) mailing -list is occasionally used to discuss the usage of Docutils for Python -documentation. - -This mailing list can be accessed via `email subscription`__, web__ or -news__ (gmane.comp.python.documentation) as well. You must be -subscribed in order to post messages to this mailing list. - -__ http://mail.python.org/mailman/listinfo/doc-sig -__ http://news.gmane.org/gmane.comp.python.documentation -__ nntp://news.gmane.org/gmane.comp.python.documentation - - -Docutils-develop ----------------- - -Discussions about developing and extending Docutils take place on the -Docutils-develop mailing list. - -You can access this list via `email subscription`__, web__ or news__ -(gmane.text.docutils.devel); the posting address is -Docutils-develop@lists.sourceforge.net. - -__ http://lists.sourceforge.net/lists/listinfo/docutils-develop -__ http://news.gmane.org/gmane.text.docutils.devel -__ nntp://news.gmane.org/gmane.text.docutils.devel - - -Docutils-checkins ------------------ - -All check-ins to the `Subversion repository`_ cause a "check-in email" -to the Docutils-checkins list. In order to stay informed about -current development, developers are advised to monitor this mailing -list. - -This mailing list is for reading only; please direct any discussion -about the check-ins to Docutils-develop. (For your convenience, the -Reply-To header of all check-in emails points to Docutils-develop.) - -This mailing list is accessible via `email subscription`__, web__ or -news__ (gmane.text.docutils.cvs) as well. - -__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins -__ http://news.gmane.org/gmane.text.docutils.cvs -__ nntp://news.gmane.org/gmane.text.docutils.cvs - -.. _Subversion repository: http://docutils.sf.net/docs/dev/repository.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _FAQ: http://docutils.sourceforge.net/FAQ.html diff --git a/docutils/docs/user/rst/cheatsheet.txt b/docutils/docs/user/rst/cheatsheet.txt deleted file mode 100644 index dfea5bcb7..000000000 --- a/docutils/docs/user/rst/cheatsheet.txt +++ /dev/null @@ -1,125 +0,0 @@ -===================================================== - The reStructuredText_ Cheat Sheet: Syntax Reminders -===================================================== -:Info: See <http://docutils.sf.net/rst.html> for introductory docs. -:Author: David Goodger <goodger@python.org> -:Date: $Date$ -:Revision: $Revision$ -:Description: This is a "docinfo block", or bibliographic field list - -Section Structure -================= -Section titles are underlined or overlined & underlined. - -Body Elements -============= -Grid table: - -+--------------------------------+-----------------------------------+ -| Paragraphs are flush-left, | Literal block, preceded by "::":: | -| separated by blank lines. | | -| | Indented | -| Block quotes are indented. | | -+--------------------------------+ or:: | -| >>> print 'Doctest block' | | -| Doctest block | > Quoted | -+--------------------------------+-----------------------------------+ -| | Line blocks preserve line breaks & indents. [new in 0.3.6] | -| | Useful for addresses, verse, and adornment-free lists; long | -| lines can be wrapped with continuation lines. | -+--------------------------------------------------------------------+ - -Simple tables: - -================ ============================================================ -List Type Examples -================ ============================================================ -Bullet list * items begin with "-", "+", or "*" -Enumerated list 1. items use any variation of "1.", "A)", and "(i)" - #. also auto-enumerated -Definition list Term is flush-left : optional classifier - Definition is indented, no blank line between -Field list :field name: field body -Option list -o at least 2 spaces between option & description -================ ============================================================ - -================ ============================================================ -Explicit Markup Examples (visible in the `text source <cheatsheet.txt>`_) -================ ============================================================ -Footnote .. [1] Manually numbered or [#] auto-numbered - (even [#labelled]) or [*] auto-symbol -Citation .. [CIT2002] A citation. -Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html - .. _indirect target: reStructuredText_ - .. _internal target: -Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html -Directive ("::") .. image:: images/biohazard.png -Substitution Def .. |substitution| replace:: like an inline directive -Comment .. is anything else -================ ============================================================ - -Inline Markup -============= -*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text -with role`:emphasis:; ``inline literal text``; standalone hyperlink, -http://docutils.sourceforge.net; named reference, reStructuredText_; -`anonymous reference`__; footnote reference, [1]_; citation reference, -[CIT2002]_; |substitution|; _`inline internal target`. - -Directive Quick Reference -========================= -See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info. - -================ ============================================================ -Directive Name Description (Docutils version added to, in [brackets]) -================ ============================================================ -attention Specific admonition; also "caution", "danger", - "error", "hint", "important", "note", "tip", "warning" -admonition Generic titled admonition: ``.. admonition:: By The Way`` -image ``.. image:: picture.png``; many options possible -figure Like "image", but with optional caption and legend -topic ``.. topic:: Title``; like a mini section -sidebar ``.. sidebar:: Title``; like a mini parallel document -parsed-literal A literal block with parsed inline markup -rubric ``.. rubric:: Informal Heading`` -epigraph Block quote with class="epigraph" -highlights Block quote with class="highlights" -pull-quote Block quote with class="pull-quote" -compound Compound paragraphs [0.3.6] -container Generic block-level container element [0.3.10] -table Create a titled table [0.3.1] -list-table Create a table from a uniform two-level bullet list [0.3.8] -csv-table Create a table from CSV data (requires Python 2.3+) [0.3.4] -contents Generate a table of contents -sectnum Automatically number sections, subsections, etc. -header, footer Create document decorations [0.3.8] -target-notes Create an explicit footnote for each external target -meta HTML-specific metadata -include Read an external reST file as if it were inline -raw Non-reST data passed untouched to the Writer -replace Replacement text for substitution definitions -unicode Unicode character code conversion for substitution defs -date Generates today's date; for substitution defs -class Set a "class" attribute on the next element -role Create a custom interpreted text role [0.3.2] -default-role Set the default interpreted text role [0.3.10] -title Set the metadata document title [0.3.10] -================ ============================================================ - -Interpreted Text Role Quick Reference -===================================== -See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info. - -================ ============================================================ -Role Name Description -================ ============================================================ -emphasis Equivalent to *emphasis* -literal Equivalent to ``literal`` but processes backslash escapes -PEP Reference to a numbered Python Enhancement Proposal -RFC Reference to a numbered Internet Request For Comments -raw For non-reST data; cannot be used directly (see docs) [0.3.6] -strong Equivalent to **strong** -sub Subscript -sup Superscript -title Title reference (book, etc.); standard default role -================ ============================================================ diff --git a/docutils/docs/user/rst/demo.txt b/docutils/docs/user/rst/demo.txt deleted file mode 100644 index 7a0abd033..000000000 --- a/docutils/docs/user/rst/demo.txt +++ /dev/null @@ -1,552 +0,0 @@ -.. This is a comment. Note how any initial comments are moved by - transforms to after the document title, subtitle, and docinfo. - -================================ - reStructuredText Demonstration -================================ - -.. Above is the document title, and below is the subtitle. - They are transformed from section titles after parsing. - --------------------------------- - Examples of Syntax Constructs --------------------------------- - -.. bibliographic fields (which also require a transform): - -:Author: David Goodger -:Address: 123 Example Street - Example, EX Canada - A1B 2C3 -:Contact: goodger@users.sourceforge.net -:Authors: Me; Myself; I -:organization: humankind -:date: $Date$ -:status: This is a "work in progress" -:revision: $Revision$ -:version: 1 -:copyright: This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. -:field name: This is a generic bibliographic field. -:field name 2: - Generic bibliographic fields may contain multiple body elements. - - Like this. - -:Dedication: - - For Docutils users & co-developers. - -:abstract: - - This document is a demonstration of the reStructuredText markup - language, containing examples of all basic reStructuredText - constructs and many advanced constructs. - -.. meta:: - :keywords: reStructuredText, demonstration, demo, parser - :description lang=en: A demonstration of the reStructuredText - markup language, containing examples of all basic - constructs and many advanced constructs. - -.. contents:: Table of Contents -.. section-numbering:: - - -Structural Elements -=================== - -Section Title -------------- - -That's it, the text just above this line. - -Transitions ------------ - -Here's a transition: - ---------- - -It divides the section. - -Body Elements -============= - -Paragraphs ----------- - -A paragraph. - -Inline Markup -````````````` - -Paragraphs contain text and may contain inline markup: *emphasis*, -**strong emphasis**, ``inline literals``, standalone hyperlinks -(http://www.python.org), external hyperlinks (Python_), internal -cross-references (example_), external hyperlinks with embedded URIs -(`Python web site <http://www.python.org>`__), footnote references -(manually numbered [1]_, anonymous auto-numbered [#]_, labeled -auto-numbered [#label]_, or symbolic [*]_), citation references -([CIT2002]_), substitution references (|example|), and _`inline -hyperlink targets` (see Targets_ below for a reference back to here). -Character-level inline markup is also possible (although exceedingly -ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by -|problematic| text (generated by processing errors; this one is -intentional). - -The default role for interpreted text is `Title Reference`. Here are -some explicit interpreted text roles: a PEP reference (:PEP:`287`); an -RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; -and explicit roles for :emphasis:`standard` :strong:`inline` -:literal:`markup`. - -.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! - -Let's test wrapping and whitespace significance in inline literals: -``This is an example of --inline-literal --text, --including some-- -strangely--hyphenated-words. Adjust-the-width-of-your-browser-window -to see how the text is wrapped. -- ---- -------- Now note the -spacing between the words of this sentence (words -should be grouped in pairs).`` - -If the ``--pep-references`` option was supplied, there should be a -live link to PEP 258 here. - -Bullet Lists ------------- - -- A bullet list - - + Nested bullet list. - + Nested item 2. - -- Item 2. - - Paragraph 2 of item 2. - - * Nested bullet list. - * Nested item 2. - - - Third level. - - Item 2. - - * Nested item 3. - -Enumerated Lists ----------------- - -1. Arabic numerals. - - a) lower alpha) - - (i) (lower roman) - - A. upper alpha. - - I) upper roman) - -2. Lists that don't start at 1: - - 3. Three - - 4. Four - - C. C - - D. D - - iii. iii - - iv. iv - -#. List items may also be auto-enumerated. - -Definition Lists ----------------- - -Term - Definition -Term : classifier - Definition paragraph 1. - - Definition paragraph 2. -Term - Definition - -Field Lists ------------ - -:what: Field lists map field names to field bodies, like database - records. They are often part of an extension syntax. They are - an unambiguous variant of RFC 2822 fields. - -:how arg1 arg2: - - The field marker is a colon, the field name, and a colon. - - The field body may contain one or more body elements, indented - relative to the field marker. - -Option Lists ------------- - -For listing command-line options: - --a command-line option "a" --b file options can have arguments - and long descriptions ---long options can be long also ---input=file long options can also have - arguments - ---very-long-option - The description can also start on the next line. - - The description may contain multiple body elements, - regardless of where it starts. - --x, -y, -z Multiple options are an "option group". --v, --verbose Commonly-seen: short & long options. --1 file, --one=file, --two file - Multiple options with arguments. -/V DOS/VMS-style options too - -There must be at least two spaces between the option and the -description. - -Literal Blocks --------------- - -Literal blocks are indicated with a double-colon ("::") at the end of -the preceding paragraph (over there ``-->``). They can be indented:: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -Or they can be quoted without indentation:: - ->> Great idea! -> -> Why didn't I think of that? - -Line Blocks ------------ - -| This is a line block. It ends with a blank line. -| Each new line begins with a vertical bar ("|"). -| Line breaks and initial indents are preserved. -| Continuation lines are wrapped portions of long lines; - they begin with a space in place of the vertical bar. -| The left edge of a continuation line need not be aligned with - the left edge of the text above it. - -| This is a second line block. -| -| Blank lines are permitted internally, but they must begin with a "|". - -Take it away, Eric the Orchestra Leader! - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -Block Quotes ------------- - -Block quotes consist of indented body elements: - - My theory by A. Elk. Brackets Miss, brackets. This theory goes - as follows and begins now. All brontosauruses are thin at one - end, much much thicker in the middle and then thin again at the - far end. That is my theory, it is mine, and belongs to me and I - own it, and what it is too. - - -- Anne Elk (Miss) - -Doctest Blocks --------------- - ->>> print 'Python-specific usage examples; begun with ">>>"' -Python-specific usage examples; begun with ">>>" ->>> print '(cut and pasted from interactive Python sessions)' -(cut and pasted from interactive Python sessions) - -Tables ------- - -Here's a grid table followed by a simple table: - -+------------------------+------------+----------+----------+ -| Header row, column 1 | Header 2 | Header 3 | Header 4 | -| (header rows optional) | | | | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | Cells may span columns. | -+------------------------+------------+---------------------+ -| body row 3 | Cells may | - Table cells | -+------------------------+ span rows. | - contain | -| body row 4 | | - body elements. | -+------------------------+------------+----------+----------+ -| body row 5 | Cells may also be | | -| | empty: ``-->`` | | -+------------------------+-----------------------+----------+ - -===== ===== ====== - Inputs Output ------------- ------ - A B A or B -===== ===== ====== -False False False -True False True -False True True -True True True -===== ===== ====== - -Footnotes ---------- - -.. [1] A footnote contains body elements, consistently indented by at - least 3 spaces. - - This is the footnote's second paragraph. - -.. [#label] Footnotes may be numbered, either manually (as in [1]_) or - automatically using a "#"-prefixed label. This footnote has a - label so it can be referred to from multiple places, both as a - footnote reference ([#label]_) and as a hyperlink reference - (label_). - -.. [#] This footnote is numbered automatically and anonymously using a - label of "#" only. - -.. [*] Footnotes may also use symbols, specified with a "*" label. - Here's a reference to the next footnote: [*]_. - -.. [*] This footnote shows the next symbol in the sequence. - -.. [4] Here's an unreferenced footnote, with a reference to a - nonexistent footnote: [5]_. - -Citations ---------- - -.. [CIT2002] Citations are text-labeled footnotes. They may be - rendered separately and differently from footnotes. - -Here's a reference to the above, [CIT2002]_, and a [nonexistent]_ -citation. - -Targets -------- - -.. _example: - -This paragraph is pointed to by the explicit "example" target. A -reference can be found under `Inline Markup`_, above. `Inline -hyperlink targets`_ are also possible. - -Section headers are implicit targets, referred to by name. See -Targets_, which is a subsection of `Body Elements`_. - -Explicit external targets are interpolated into references such as -"Python_". - -.. _Python: http://www.python.org/ - -Targets may be indirect and anonymous. Thus `this phrase`__ may also -refer to the Targets_ section. - -__ Targets_ - -Here's a `hyperlink reference without a target`_, which generates an -error. - -Duplicate Target Names -`````````````````````` - -Duplicate names in section headers or other implicit targets will -generate "info" (level-1) system messages. Duplicate names in -explicit targets will generate "warning" (level-2) system messages. - -Duplicate Target Names -`````````````````````` - -Since there are two "Duplicate Target Names" section headers, we -cannot uniquely refer to either of them by name. If we try to (like -this: `Duplicate Target Names`_), an error is generated. - -Directives ----------- - -.. contents:: :local: - -These are just a sample of the many reStructuredText Directives. For -others, please see -http://docutils.sourceforge.net/docs/ref/rst/directives.html. - -Document Parts -`````````````` - -An example of the "contents" directive can be seen above this section -(a local, untitled table of contents_) and at the beginning of the -document (a document-wide `table of contents`_). - -Images -`````` - -An image directive (also clickable -- a hyperlink reference): - -.. image:: images/title.png - :target: directives_ - -A figure directive: - -.. figure:: images/title.png - :alt: reStructuredText, the markup syntax - - A figure is an image with a caption and/or a legend: - - +------------+-----------------------------------------------+ - | re | Revised, revisited, based on 're' module. | - +------------+-----------------------------------------------+ - | Structured | Structure-enhanced text, structuredtext. | - +------------+-----------------------------------------------+ - | Text | Well it is, isn't it? | - +------------+-----------------------------------------------+ - - This paragraph is also part of the legend. - -Admonitions -``````````` - -.. Attention:: Directives at large. - -.. Caution:: - - Don't take any wooden nickels. - -.. DANGER:: Mad scientist at work! - -.. Error:: Does not compute. - -.. Hint:: It's bigger than a bread box. - -.. Important:: - - Wash behind your ears. - - Clean up your room. - - Call your mother. - - Back up your data. - -.. Note:: This is a note. - -.. Tip:: 15% if the service is good. - -.. WARNING:: Strong prose may provoke extreme mental exertion. - Reader discretion is strongly advised. - -.. admonition:: And, by the way... - - You can make up your own admonition too. - -Topics, Sidebars, and Rubrics -````````````````````````````` - -.. sidebar:: Sidebar Title - :subtitle: Optional Subtitle - - This is a sidebar. It is for text outside the flow of the main - text. - - .. rubric:: This is a rubric inside a sidebar - - Sidebars often appears beside the main text with a border and - background color. - -.. topic:: Topic Title - - This is a topic. - -.. rubric:: This is a rubric - -Target Footnotes -```````````````` - -.. target-notes:: - -Replacement Text -```````````````` - -I recommend you try |Python|_. - -.. |Python| replace:: Python, *the* best language around - -Compound Paragraph -`````````````````` - -.. compound:: - - This paragraph contains a literal block:: - - Connecting... OK - Transmitting data... OK - Disconnecting... OK - - and thus consists of a simple paragraph, a literal block, and - another simple paragraph. Nonetheless it is semantically *one* - paragraph. - -This construct is called a *compound paragraph* and can be produced -with the "compound" directive. - -Substitution Definitions ------------------------- - -An inline image (|example|) example: - -.. |EXAMPLE| image:: images/biohazard.png - -(Substitution definitions are not visible in the HTML source.) - -Comments --------- - -Here's one: - -.. Comments begin with two dots and a space. Anything may - follow, except for the syntax of footnotes, hyperlink - targets, directives, or substitution definitions. - - Double-dashes -- "--" -- must be escaped somehow in HTML output. - -(View the HTML source to see the comment.) - -Error Handling -============== - -Any errors caught during processing will generate system messages. - -|*** Expect 6 errors (including this one). ***| - -There should be six messages in the following, auto-generated -section, "Docutils System Messages": - -.. section should be added by Docutils automatically diff --git a/docutils/docs/user/rst/images/ball1.gif b/docutils/docs/user/rst/images/ball1.gif Binary files differdeleted file mode 100644 index 3e14441d9..000000000 --- a/docutils/docs/user/rst/images/ball1.gif +++ /dev/null diff --git a/docutils/docs/user/rst/images/biohazard.png b/docutils/docs/user/rst/images/biohazard.png Binary files differdeleted file mode 100644 index ae4629d8b..000000000 --- a/docutils/docs/user/rst/images/biohazard.png +++ /dev/null diff --git a/docutils/docs/user/rst/images/title.png b/docutils/docs/user/rst/images/title.png Binary files differdeleted file mode 100644 index cc6218efe..000000000 --- a/docutils/docs/user/rst/images/title.png +++ /dev/null diff --git a/docutils/docs/user/rst/quickref.html b/docutils/docs/user/rst/quickref.html deleted file mode 100644 index 604cfe6bc..000000000 --- a/docutils/docs/user/rst/quickref.html +++ /dev/null @@ -1,1352 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" - "http://www.w3.org/TR/html4/loose.dtd"> - -<html> - <head> - <title>Quick reStructuredText</title> - <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> - - <style type="text/css"><!-- - a.backref { text-decoration: none ; color: black } - div.line-block { display: block } - div.line-block div.line-block { margin-left: 1.5em } - --></style> - - </head> - - <body> - <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1> - - <!-- Caveat: if you're reading the HTML for the examples, --> - <!-- beware that it was hand-generated, not by Docutils/ReST. --> - - <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" - >http://docutils.sourceforge.net/docs/user/rst/quickref.html</a></em> - <br><em>Being a cheat-sheet for reStructuredText</em> - <br><em>Updated $Date$</em> - - <blockquote> - <p>Copyright: This document has been placed in the public domain. - </blockquote> - - - <p>The full details of the markup may be found on the - <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> - page. This document is just intended as a reminder. - - <p>Links that look like "(<a href="#details">details</a>)" point - into the HTML version of the full <a - href="../../ref/rst/restructuredtext.html">reStructuredText - specification</a> document. These are relative links; if they - don't work, please use the <a - href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" - >master "Quick reStructuredText"</a> document. - - <h2><a name="contents">Contents</a></h2> - - <ul> - <li><a href="#inline-markup">Inline Markup</a></li> - <li><a href="#escaping">Escaping with Backslashes</a></li> - <li><a href="#section-structure">Section Structure</a></li> - <li><a href="#paragraphs">Paragraphs</a></li> - <li><a href="#bullet-lists">Bullet Lists</a></li> - <li><a href="#enumerated-lists">Enumerated Lists</a></li> - <li><a href="#definition-lists">Definition Lists</a></li> - <li><a href="#field-lists">Field Lists</a></li> - <li><a href="#option-lists">Option Lists</a></li> - <li><a href="#literal-blocks">Literal Blocks</a></li> - <li><a href="#line-blocks">Line Blocks</a></li> - <li><a href="#block-quotes">Block Quotes</a></li> - <li><a href="#doctest-blocks">Doctest Blocks</a></li> - <li><a href="#tables">Tables</a></li> - <li><a href="#transitions">Transitions</a></li> - <li><a href="#explicit-markup">Explicit Markup</a> - <ul> - <li><a href="#footnotes">Footnotes</a></li> - <li><a href="#citations">Citations</a></li> - <li><a href="#hyperlink-targets">Hyperlink Targets</a> - <ul> - <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li> - <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li> - <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li> - <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li> - </ul></li> - <li><a href="#directives">Directives</a></li> - <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> - <li><a href="#comments">Comments</a></li> - </ul></li> - <li><a href="#getting-help">Getting Help</a></li> - </ul> - - <h2><a href="#contents" name="inline-markup" class="backref" - >Inline Markup</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#inline-markup">details</a>) - - <p>Inline markup allows words and phrases within text to have - character styles (like italics and boldface) and functionality - (like hyperlinks). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th>Plain text - <th>Typical result - <th>Notes - </thead> - <tbody> - <tr valign="top"> - <td nowrap><samp>*emphasis*</samp> - <td><em>emphasis</em> - <td>Normally rendered as italics. - - <tr valign="top"> - <td nowrap><samp>**strong emphasis**</samp> - <td><strong>strong emphasis</strong> - <td>Normally rendered as boldface. - - <tr valign="top"> - <td nowrap><samp>`interpreted text`</samp> - <td>(see note at right) - <td>The rendering and <em>meaning</em> of interpreted text is - domain- or application-dependent. It can be used for things - like index entries or explicit descriptive markup (like program - identifiers). - - <tr valign="top"> - <td nowrap><samp>``inline literal``</samp> - <td><code>inline literal</code> - <td>Normally rendered as monospaced text. Spaces should be - preserved, but line breaks will not be. - - <tr valign="top"> - <td nowrap><samp>reference_</samp> - <td><a href="#hyperlink-targets">reference</a> - <td>A simple, one-word hyperlink reference. See <a - href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>`phrase reference`_</samp> - <td><a href="#hyperlink-targets">phrase reference</a> - <td>A hyperlink reference with spaces or punctuation needs to be - quoted with backquotes. See <a - href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>anonymous__</samp> - <td><a href="#hyperlink-targets">anonymous</a> - <td>With two underscores instead of one, both simple and phrase - references may be anonymous (the reference text is not repeated - at the target). See <a - href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>_`inline internal target`</samp> - <td><a name="inline-internal-target">inline internal target</a> - <td>A crossreference target within text. - See <a href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>|substitution reference|</samp> - <td>(see note at right) - <td>The result is substituted in from the <a - href="#substitution-references-and-definitions">substitution - definition</a>. It could be text, an image, a hyperlink, or a - combination of these and others. - - <tr valign="top"> - <td nowrap><samp>footnote reference [1]_</samp> - <td>footnote reference <sup><a href="#footnotes">1</a></sup> - <td>See <a href="#footnotes">Footnotes</a>. - - <tr valign="top"> - <td nowrap><samp>citation reference [CIT2002]_</samp> - <td>citation reference <a href="#citations">[CIT2002]</a> - <td>See <a href="#citations">Citations</a>. - - <tr valign="top"> - <td nowrap><samp>http://docutils.sf.net/</samp> - <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> - <td>A standalone hyperlink. - - </table> - - <p>Asterisk, backquote, vertical bar, and underscore are inline - delimiter characters. Asterisk, backquote, and vertical bar act - like quote marks; matching characters surround the marked-up word - or phrase, whitespace or other quoting is required outside them, - and there can't be whitespace just inside them. If you want to use - inline delimiter characters literally, <a href="#escaping">escape - (with backslash)</a> or quote them (with double backquotes; i.e. - use inline literals). - - <p>In detail, the reStructuredText specification says that in - inline markup, the following rules apply to start-strings and - end-strings (inline markup delimiters): - - <ol> - <li>The start-string must start a text block or be - immediately preceded by whitespace or any of - <samp>' " ( [ {</samp> or <samp><</samp>. - <li>The start-string must be immediately followed by non-whitespace. - <li>The end-string must be immediately preceded by non-whitespace. - <li>The end-string must end a text block (end of document or - followed by a blank line) or be immediately followed by whitespace - or any of <samp>' " . , : ; ! ? - ) ] } / \</samp> - or <samp>></samp>. - <li>If a start-string is immediately preceded by one of - <samp>' " ( [ {</samp> or <samp><</samp>, it must not be - immediately followed by the corresponding character from - <samp>' " ) ] }</samp> or <samp>></samp>. - <li>An end-string must be separated by at least one - character from the start-string. - <li>An <a href="#escaping">unescaped</a> backslash preceding a - start-string or end-string will disable markup recognition, except - for the end-string of inline literals. - </ol> - - <p>Also remember that inline markup may not be nested (well, - except that inline literals can contain any of the other inline - markup delimiter characters, but that doesn't count because - nothing is processed). - - <h2><a href="#contents" name="escaping" class="backref" - >Escaping with Backslashes</a></h2> - - <p>(<a - href="../../ref/rst/restructuredtext.html#escaping-mechanism">details</a>) - - <p>reStructuredText uses backslashes ("\") to override the special - meaning given to markup characters and get the literal characters - themselves. To get a literal backslash, use an escaped backslash - ("\\"). For example: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Raw reStructuredText - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"><td> - <samp>*escape* ``with`` "\"</samp> - <td><em>escape</em> <samp>with</samp> "" - <tr valign="top"><td> - <samp>\*escape* \``with`` "\\"</samp> - <td>*escape* ``with`` "\" - </table> - - <p>In Python strings it will, of course, be necessary - to escape any backslash characters so that they actually - <em>reach</em> reStructuredText. - The simplest way to do this is to use raw strings: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Python string - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"><td> - <samp>r"""\*escape* \`with` "\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\\*escape* \\`with` "\\\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\*escape* \`with` "\\""""</samp> - <td><em>escape</em> with "" - </table> - - <h2><a href="#contents" name="section-structure" class="backref" - >Section Structure</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#sections">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>=====</samp> -<br><samp>Title</samp> -<br><samp>=====</samp> -<br><samp>Subtitle</samp> -<br><samp>--------</samp> -<br><samp>Titles are underlined (or over-</samp> -<br><samp>and underlined) with a printing</samp> -<br><samp>nonalphanumeric 7-bit ASCII</samp> -<br><samp>character. Recommended choices</samp> -<br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> -<br><samp>The underline/overline must be at</samp> -<br><samp>least as long as the title text.</samp> -<br><samp></samp> -<br><samp>A lone top-level (sub)section</samp> -<br><samp>is lifted up to be the document's</samp> -<br><samp>(sub)title.</samp> - - <td> - <font size="+2"><strong>Title</strong></font> - <p><font size="+1"><strong>Subtitle</strong></font> - <p>Titles are underlined (or over- - and underlined) with a printing - nonalphanumeric 7-bit ASCII - character. Recommended choices - are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". - The underline/overline must be at - least as long as the title text. - <p>A lone top-level (sub)section is - lifted up to be the document's - (sub)title. - </table> - - <h2><a href="#contents" name="paragraphs" class="backref" - >Paragraphs</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#paragraphs">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>This is a paragraph.</samp> - -<p><samp>Paragraphs line up at their left</samp> -<br><samp>edges, and are normally separated</samp> -<br><samp>by blank lines.</samp> - - <td> - <p>This is a paragraph. - - <p>Paragraphs line up at their left edges, and are normally - separated by blank lines. - - </table> - - <h2><a href="#contents" name="bullet-lists" class="backref" - >Bullet Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#bullet-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Bullet lists:</samp> - -<p><samp>- This is item 1</samp> -<br><samp>- This is item 2</samp> - -<p><samp>- Bullets are "-", "*" or "+".</samp> -<br><samp> Continuing text must be aligned</samp> -<br><samp> after the bullet and whitespace.</samp> - -<p><samp>Note that a blank line is required</samp> -<br><samp>before the first item and after the</samp> -<br><samp>last, but is optional between items.</samp> - <td>Bullet lists: - <ul> - <li>This is item 1 - <li>This is item 2 - <li>Bullets are "-", "*" or "+". - Continuing text must be aligned - after the bullet and whitespace. - </ul> - <p>Note that a blank line is required before the first - item and after the last, but is optional between items. - </table> - - <h2><a href="#contents" name="enumerated-lists" class="backref" - >Enumerated Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#enumerated-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Enumerated lists:</samp> - -<p><samp>3. This is the first item</samp> -<br><samp>4. This is the second item</samp> -<br><samp>5. Enumerators are arabic numbers,</samp> -<br><samp> single letters, or roman numerals</samp> -<br><samp>6. List items should be sequentially</samp> -<br><samp> numbered, but need not start at 1</samp> -<br><samp> (although not all formatters will</samp> -<br><samp> honour the first index).</samp> -<br><samp>#. This item is auto-enumerated</samp> - <td>Enumerated lists: - <ol type="1"> - <li value="3">This is the first item - <li>This is the second item - <li>Enumerators are arabic numbers, single letters, - or roman numerals - <li>List items should be sequentially numbered, - but need not start at 1 (although not all - formatters will honour the first index). - <li>This item is auto-enumerated - </ol> - </table> - - <h2><a href="#contents" name="definition-lists" class="backref" - >Definition Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#definition-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Definition lists:</samp> -<br> -<br><samp>what</samp> -<br><samp> Definition lists associate a term with</samp> -<br><samp> a definition.</samp> -<br> -<br><samp>how</samp> -<br><samp> The term is a one-line phrase, and the</samp> -<br><samp> definition is one or more paragraphs or</samp> -<br><samp> body elements, indented relative to the</samp> -<br><samp> term. Blank lines are not allowed</samp> -<br><samp> between term and definition.</samp> - <td>Definition lists: - <dl> - <dt><strong>what</strong> - <dd>Definition lists associate a term with - a definition. - - <dt><strong>how</strong> - <dd>The term is a one-line phrase, and the - definition is one or more paragraphs or - body elements, indented relative to the - term. Blank lines are not allowed - between term and definition. - </dl> - </table> - - <h2><a href="#contents" name="field-lists" class="backref" - >Field Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#field-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>:Authors:</samp> -<br><samp> Tony J. (Tibs) Ibbs,</samp> -<br><samp> David Goodger</samp> - -<p><samp> (and sundry other good-natured folks)</samp> - -<p><samp>:Version: 1.0 of 2001/08/08</samp> -<br><samp>:Dedication: To my father.</samp> - <td> - <table> - <tr valign="top"> - <td><strong>Authors:</strong> - <td>Tony J. (Tibs) Ibbs, - David Goodger - <tr><td><td>(and sundry other good-natured folks) - <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 - <tr><td><strong>Dedication:</strong><td>To my father. - </table> - </table> - - <p>Field lists are used as part of an extension syntax, such as - options for <a href="#directives">directives</a>, or database-like - records meant for further processing. Field lists may also be - used as generic two-column table constructs in documents. - - <h2><a href="#contents" name="option-lists" class="backref" - >Option Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#option-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> --a command-line option "a" -<br>-b file options can have arguments -<br> and long descriptions -<br>--long options can be long also -<br>--input=file long options can also have -<br> arguments -<br>/V DOS/VMS-style options too -</samp> - - <td> - <table border="0" width="100%"> - <tbody valign="top"> - <tr> - <td width="30%"><samp>-a</samp> - <td>command-line option "a" - <tr> - <td><samp>-b <i>file</i></samp> - <td>options can have arguments and long descriptions - <tr> - <td><samp>--long</samp> - <td>options can be long also - <tr> - <td><samp>--input=<i>file</i></samp> - <td>long options can also have arguments - <tr> - <td><samp>/V</samp> - <td>DOS/VMS-style options too - </table> - </table> - - <p>There must be at least two spaces between the option and the - description. - - <h2><a href="#contents" name="literal-blocks" class="backref" - >Literal Blocks</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#literal-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>A paragraph containing only two colons</samp> -<br><samp>indicates that the following indented</samp> -<br><samp>or quoted text is a literal block.</samp> -<br> -<br><samp>::</samp> -<br> -<br><samp> Whitespace, newlines, blank lines, and</samp> -<br><samp> all kinds of markup (like *this* or</samp> -<br><samp> \this) is preserved by literal blocks.</samp> -<br> -<br><samp> The paragraph containing only '::'</samp> -<br><samp> will be omitted from the result.</samp> -<br> -<br><samp>The ``::`` may be tacked onto the very</samp> -<br><samp>end of any paragraph. The ``::`` will be</samp> -<br><samp>omitted if it is preceded by whitespace.</samp> -<br><samp>The ``::`` will be converted to a single</samp> -<br><samp>colon if preceded by text, like this::</samp> -<br> -<br><samp> It's very convenient to use this form.</samp> -<br> -<br><samp>Literal blocks end when text returns to</samp> -<br><samp>the preceding paragraph's indentation.</samp> -<br><samp>This means that something like this</samp> -<br><samp>is possible::</samp> -<br> -<br><samp> We start here</samp> -<br><samp> and continue here</samp> -<br><samp> and end here.</samp> -<br> -<br><samp>Per-line quoting can also be used on</samp> -<br><samp>unindented literal blocks:</samp> -<br> -<br><samp>> Useful for quotes from email and</samp> -<br><samp>> for Haskell literate programming.</samp> - - <td> - <p>A paragraph containing only two colons -indicates that the following indented or quoted -text is a literal block. - - <pre> - Whitespace, newlines, blank lines, and - all kinds of markup (like *this* or - \this) is preserved by literal blocks. - - The paragraph containing only '::' - will be omitted from the result.</pre> - - <p>The <samp>::</samp> may be tacked onto the very -end of any paragraph. The <samp>::</samp> will be -omitted if it is preceded by whitespace. -The <samp>::</samp> will be converted to a single -colon if preceded by text, like this: - - <pre> - It's very convenient to use this form.</pre> - - <p>Literal blocks end when text returns to -the preceding paragraph's indentation. -This means that something like this is possible: - - <pre> - We start here - and continue here - and end here.</pre> - - <p>Per-line quoting can also be used on -unindented literal blocks: - - <pre> - > Useful for quotes from email and - > for Haskell literate programming.</pre> - </table> - - <h2><a href="#contents" name="line-blocks" class="backref" - >Line Blocks</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#line-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>| Line blocks are useful for addresses,</samp> -<br><samp>| verse, and adornment-free lists.</samp> -<br><samp>|</samp> -<br><samp>| Each new line begins with a</samp> -<br><samp>| vertical bar ("|").</samp> -<br><samp>| Line breaks and initial indents</samp> -<br><samp>| are preserved.</samp> -<br><samp>| Continuation lines are wrapped</samp> -<br><samp> portions of long lines; they begin</samp> -<br><samp> with spaces in place of vertical bars.</samp> - - <td> - <div class="line-block"> - <div class="line">Line blocks are useful for addresses,</div> - <div class="line">verse, and adornment-free lists.</div> - <div class="line"><br /></div> - <div class="line">Each new line begins with a</div> - <div class="line">vertical bar ("|").</div> - <div class="line-block"> - <div class="line">Line breaks and initial indents</div> - <div class="line">are preserved.</div> - </div> - <div class="line">Continuation lines are wrapped portions - of long lines; they begin - with spaces in place of vertical bars.</div> - </div> - </table> - - <h2><a href="#contents" name="block-quotes" class="backref" - >Block Quotes</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#block-quotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Block quotes are just:</samp> - -<p><samp> Indented paragraphs,</samp> - -<p><samp> and they may nest.</samp> - <td> - Block quotes are just: - <blockquote> - <p>Indented paragraphs, - <blockquote> - <p>and they may nest. - </blockquote> - </blockquote> - </table> - - <h2><a href="#contents" name="doctest-blocks" class="backref" - >Doctest Blocks</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp>Doctest blocks are interactive -<br>Python sessions. They begin with -<br>"``>>>``" and end with a blank line.</samp> - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> - - <td> - <p>Doctest blocks are interactive - Python sessions. They begin with - "<samp>>>></samp>" and end with a blank line. - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> - </table> - - <p>"The <a - href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a> - module searches a module's docstrings for text that looks like an - interactive Python session, then executes all such sessions to - verify they still work exactly as shown." (From the doctest docs.) - - <h2><a href="#contents" name="tables" class="backref" - >Tables</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>) - - <p>There are two syntaxes for tables in reStructuredText. Grid - tables are complete but cumbersome to create. Simple tables are - easy to create but limited (no row spans, etc.).</p> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>Grid table:</samp></p> - -<p><samp>+------------+------------+-----------+</samp> -<br><samp>| Header 1 | Header 2 | Header 3 |</samp> -<br><samp>+============+============+===========+</samp> -<br><samp>| body row 1 | column 2 | column 3 |</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 2 | Cells may span columns.|</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 3 | Cells may | - Cells |</samp> -<br><samp>+------------+ span rows. | - contain |</samp> -<br><samp>| body row 4 | | - blocks. |</samp> -<br><samp>+------------+------------+-----------+</samp></p> - <td> - <p>Grid table:</p> - <table border="1"> - <thead valign="bottom"> - <tr> - <th>Header 1 - <th>Header 2 - <th>Header 3 - </tr> - </thead> - <tbody valign="top"> - <tr> - <td>body row 1 - <td>column 2 - <td>column 3 - </tr> - <tr> - <td>body row 2 - <td colspan="2">Cells may span columns. - </tr> - <tr> - <td>body row 3 - <td rowspan="2">Cells may<br>span rows. - <td rowspan="2"> - <ul> - <li>Cells - <li>contain - <li>blocks. - </ul> - </tr> - <tr> - <td>body row 4 - </tr> - </table> - <tr valign="top"> - <td> -<p><samp>Simple table:</samp></p> - -<p><samp>===== ===== ======</samp> -<br><samp> Inputs Output</samp> -<br><samp>------------ ------</samp> -<br><samp> A B A or B</samp> -<br><samp>===== ===== ======</samp> -<br><samp>False False False</samp> -<br><samp>True False True</samp> -<br><samp>False True True</samp> -<br><samp>True True True</samp> -<br><samp>===== ===== ======</samp></p> - - <td> - <p>Simple table:</p> - <table border="1"> - <colgroup> - <col width="31%"> - <col width="31%"> - <col width="38%"> - </colgroup> - <thead valign="bottom"> - <tr> - <th colspan="2">Inputs - <th>Output - <tr> - <th>A - <th>B - <th>A or B - <tbody valign="top"> - <tr> - <td>False - <td>False - <td>False - <tr> - <td>True - <td>False - <td>True - <tr> - <td>False - <td>True - <td>True - <tr> - <td>True - <td>True - <td>True - </table> - - </table> - - <h2><a href="#contents" name="transitions" class="backref" - >Transitions</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> -A transition marker is a horizontal line -<br>of 4 or more repeated punctuation -<br>characters.</samp> - - <p><samp>------------</samp> - - <p><samp>A transition should not begin or end a -<br>section or document, nor should two -<br>transitions be immediately adjacent.</samp> - - <td> - <p>A transition marker is a horizontal line - of 4 or more repeated punctuation - characters.</p> - - <hr> - - <p>A transition should not begin or end a - section or document, nor should two - transitions be immediately adjacent. - </table> - - <p>Transitions are commonly seen in novels and short fiction, as a - gap spanning one or more lines, marking text divisions or - signaling changes in subject, time, point of view, or emphasis. - - <h2><a href="#contents" name="explicit-markup" class="backref" - >Explicit Markup</a></h2> - - <p>Explicit markup blocks are used for constructs which float - (footnotes), have no direct paper-document representation - (hyperlink targets, comments), or require specialized processing - (directives). They all begin with two periods and whitespace, the - "explicit markup start". - - <h3><a href="#contents" name="footnotes" class="backref" - >Footnotes</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Footnote references, like [5]_.</samp> - <br><samp>Note that footnotes may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [5] A numerical footnote. Note</samp> - <br><samp> there's no colon after the ``]``.</samp> - - <td> - Footnote references, like <sup><a href="#5">5</a></sup>. - Note that footnotes may get rearranged, e.g., to the bottom of - the "page". - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. - Note there's no colon after the <samp>]</samp>. - </table> - - <tr valign="top"> - <td> - <samp>Autonumbered footnotes are</samp> - <br><samp>possible, like using [#]_ and [#]_.</samp> - <p><samp>.. [#] This is the first one.</samp> - <br><samp>.. [#] This is the second one.</samp> - - <p><samp>They may be assigned 'autonumber</samp> - <br><samp>labels' - for instance, - <br>[#fourth]_ and [#third]_.</samp> - - <p><samp>.. [#third] a.k.a. third_</samp> - <p><samp>.. [#fourth] a.k.a. fourth_</samp> - <td> - Autonumbered footnotes are possible, like using <sup><a - href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. - - <p>They may be assigned 'autonumber labels' - for instance, - <sup><a href="#fourth">4</a></sup> and <sup><a - href="#third">3</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. - <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. - <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> - <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> - </table> - - <tr valign="top"> - <td> - <samp>Auto-symbol footnotes are also</samp> - <br><samp>possible, like this: [*]_ and [*]_.</samp> - <p><samp>.. [*] This is the first one.</samp> - <br><samp>.. [*] This is the second one.</samp> - - <td> - Auto-symbol footnotes are also - possible, like this: <sup><a href="#symbol1">*</a></sup> - and <sup><a href="#symbol2">†</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote - <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. - </table> - - </table> - - <p>The numbering of auto-numbered footnotes is determined by the - order of the footnotes, not of the references. For auto-numbered - footnote references without autonumber labels - ("<samp>[#]_</samp>"), the references and footnotes must be in the - same relative order. Similarly for auto-symbol footnotes - ("<samp>[*]_</samp>"). - - <h3><a href="#contents" name="citations" class="backref" - >Citations</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Citation references, like [CIT2002]_.</samp> - <br><samp>Note that citations may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [CIT2002] A citation</samp> - <br><samp> (as often used in journals).</samp> - - <p><samp>Citation labels contain alphanumerics,</samp> - <br><samp>underlines, hyphens and fullstops.</samp> - <br><samp>Case is not significant.</samp> - - <p><samp>Given a citation like [this]_, one</samp> - <br><samp>can also refer to it like this_.</samp> - - <p><samp>.. [this] here.</samp> - - <td> - Citation references, like <a href="#cit2002">[CIT2002]</a>. - Note that citations may get rearranged, e.g., to the bottom of - the "page". - - <p>Citation labels contain alphanumerics, underlines, hyphens - and fullstops. Case is not significant. - - <p>Given a citation like <a href="#this">[this]</a>, one - can also refer to it like <a href="#this">this</a>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Citations: --> - <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation - (as often used in journals). - <tr><td><a name="this"><strong>[this]</strong></a><td> here. - </table> - - </table> - - <h3><a href="#contents" name="hyperlink-targets" class="backref" - >Hyperlink Targets</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>) - - <h4><a href="#contents" name="external-hyperlink-targets" class="backref" - >External Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td rowspan="2"> - <samp>External hyperlinks, like Python_.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <tr><td>External hyperlinks, like - <a href="http://www.python.org/">Python</a>. - </table> - <tr valign="top"> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Call-out form</em> - <tr><td>External hyperlinks, like - <a href="#labPython"><i>Python</i></a>. - - <p><table> - <tr><td colspan="2"><hr> - <tr><td><a name="labPython"><i>Python:</i></a> - <td> <a href="http://www.python.org/">http://www.python.org/</a> - </table> - </table> - </table> - - <p>"<em>Fold-in</em>" is the representation typically used in HTML - documents (think of the indirect hyperlink being "folded in" like - ingredients into a cake), and "<em>call-out</em>" is more suitable for - printed documents, where the link needs to be presented explicitly, for - example as a footnote. You can force usage of the call-out form by - using the - "<a href="../../ref/rst/directives.html#target-notes">target-notes</a>" - directive. - - <p>reStructuredText also provides for <b>embedded URIs</b> (<a - href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>), - a convenience at the expense of readability. A hyperlink - reference may directly embed a target URI inline, within angle - brackets. The following is exactly equivalent to the example above: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td rowspan="2"> - <samp>External hyperlinks, like `Python -<br><http://www.python.org/>`_.</samp> - <td>External hyperlinks, like - <a href="http://www.python.org/">Python</a>. - </table> - - <h4><a href="#contents" name="internal-hyperlink-targets" class="backref" - >Internal Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td rowspan="2"><samp>Internal crossreferences, like example_.</samp> - - <p><samp>.. _example:</samp> - - <p><samp>This is an example crossreference target.</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <!-- Note that some browsers may not like an "a" tag that --> - <!-- does not have any content, so we could arbitrarily --> - <!-- use the first word as content - *or* just trust to --> - <!-- luck! --> - <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> - <p><a name="example-foldin">This</a> is an example - crossreference target. - </table> - <tr valign="top"> - <td> - <table width="100%"> - <tr><td bgcolor="#99CCFF"><em>Call-out form</em> - <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> - - <p><a name="example-callout"><i>example:</i></a> - <br>This is an example crossreference target. - </table> - - </table> - - <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" - >Indirect Hyperlink Targets</a></h4> - - <p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Python_ is `my favourite -<br>programming language`__.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - - <p><samp>__ Python_</samp> - - <td> - <p><a href="http://www.python.org/">Python</a> is - <a href="http://www.python.org/">my favourite - programming language</a>. - - </table> - - <p>The second hyperlink target (the line beginning with - "<samp>__</samp>") is both an indirect hyperlink target - (<i>indirectly</i> pointing at the Python website via the - "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink - target</b>. In the text, a double-underscore suffix is used to - indicate an <b>anonymous hyperlink reference</b>. In an anonymous - hyperlink target, the reference text is not repeated. This is - useful for references with long text or throw-away references, but - the target should be kept close to the reference to prevent them - going out of sync. - - <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" - >Implicit Hyperlink Targets</a></h4> - - <p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>) - - <p>Section titles, footnotes, and citations automatically generate - hyperlink targets (the title text or footnote/citation label is - used as the hyperlink name). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead><tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Titles are targets, too</samp> - <br><samp>=======================</samp> - <br><samp>Implict references, like `Titles are</samp> - <br><samp>targets, too`_.</samp> - <td> - <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> - <p>Implict references, like <a href="#title">Titles are - targets, too</a>. - </table> - - <h3><a href="#contents" name="directives" class="backref" - >Directives</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>) - - <p>Directives are a general-purpose extension mechanism, a way of - adding support for new constructs without adding new syntax. For - a description of all standard directives, see <a - href="../../ref/rst/directives.html" >reStructuredText - Directives</a>. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp>For instance:</samp> - - <p><samp>.. image:: images/ball1.gif</samp> - - <td> - For instance: - <p><img src="images/ball1.gif" alt="ball1"> - </table> - - <h3><a href="#contents" name="substitution-references-and-definitions" - class="backref" >Substitution References and Definitions</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>) - - <p>Substitutions are like inline directives, allowing graphics and - arbitrary constructs within text. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp> -The |biohazard| symbol must be -used on containers used to -dispose of medical waste.</samp> - - <p><samp> -.. |biohazard| image:: biohazard.png</samp> - - <td> - - <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol - must be used on containers used to dispose of medical waste. - - </table> - - <h3><a href="#contents" name="comments" class="backref" - >Comments</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>) - - <p>Any text which begins with an explicit markup start but doesn't - use the syntax of any of the constructs above, is a comment. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp>.. This text will not be shown</samp> - <br><samp> (but, for instance, in HTML might be</samp> - <br><samp> rendered as an HTML comment)</samp> - - <td> - <!-- This text will not be shown --> - <!-- (but, for instance in HTML might be --> - <!-- rendered as an HTML comment) --> - - <tr valign="top"> - <td> - <samp>An empty "comment" does not</samp> - <br><samp>"consume" following blocks.</samp> - <p><samp>..</samp> - <p><samp> So this block is not "lost",</samp> - <br><samp> despite its indentation.</samp> - <td> - An empty "comment" does not - "consume" following blocks. - <blockquote> - So this block is not "lost", - despite its indentation. - </blockquote> - </table> - - <h2><a href="#contents" name="getting-help" class="backref" - >Getting Help</a></h2> - - <p>Users who have questions or need assistance with Docutils or - reStructuredText should <a - href="mailto:docutils-users@lists.sourceforge.net" >post a - message</a> to the <a - href="http://lists.sourceforge.net/lists/listinfo/docutils-users" - >Docutils-Users mailing list</a>. The <a - href="http://docutils.sourceforge.net/" >Docutils project web - site</a> has more information. - - <p><hr> - <address> - <p>Authors: - <a href="http://www.tibsnjoan.co.uk/">Tibs</a> - (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) - and David Goodger - (<a href="mailto:goodger@python.org">goodger@python.org</a>) - </address> - <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> - </body> -</html> diff --git a/docutils/docs/user/rst/quickstart.txt b/docutils/docs/user/rst/quickstart.txt deleted file mode 100644 index 735dcf512..000000000 --- a/docutils/docs/user/rst/quickstart.txt +++ /dev/null @@ -1,387 +0,0 @@ -A ReStructuredText Primer -========================= - -:Author: Richard Jones -:Version: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -The text below contains links that look like "(quickref__)". These -are relative links that point to the `Quick reStructuredText`_ user -reference. If these links don't work, please refer to the `master -quick reference`_ document. - -__ -.. _Quick reStructuredText: quickref.html -.. _master quick reference: - http://docutils.sourceforge.net/docs/user/rst/quickref.html - - -Structure ---------- - -From the outset, let me say that "Structured Text" is probably a bit -of a misnomer. It's more like "Relaxed Text" that uses certain -consistent patterns. These patterns are interpreted by a HTML -converter to produce "Very Structured Text" that can be used by a web -browser. - -The most basic pattern recognised is a **paragraph** (quickref__). -That's a chunk of text that is separated by blank lines (one is -enough). Paragraphs must have the same indentation -- that is, line -up at their left edge. Paragraphs that start indented will result in -indented quote paragraphs. For example:: - - This is a paragraph. It's quite - short. - - This paragraph will result in an indented block of - text, typically used for quoting other text. - - This is another one. - -Results in: - - This is a paragraph. It's quite - short. - - This paragraph will result in an indented block of - text, typically used for quoting other text. - - This is another one. - -__ quickref.html#paragraphs - -Text styles ------------ - -(quickref__) - -__ quickref.html#inline-markup - -Inside paragraphs and other bodies of text, you may additionally mark -text for *italics* with "``*italics*``" or **bold** with -"``**bold**``". - -If you want something to appear as a fixed-space literal, use -"````double back-quotes````". Note that no further fiddling is done -inside the double back-quotes -- so asterisks "``*``" etc. are left -alone. - -If you find that you want to use one of the "special" characters in -text, it will generally be OK -- reStructuredText is pretty smart. -For example, this * asterisk is handled just fine. If you actually -want text \*surrounded by asterisks* to **not** be italicised, then -you need to indicate that the asterisk is not special. You do this by -placing a backslash just before it, like so "``\*``" (quickref__), or -by enclosing it in double back-quotes (inline literals), like this:: - - ``\*`` - -__ quickref.html#escaping - -Lists ------ - -Lists of items come in three main flavours: **enumerated**, -**bulleted** and **definitions**. In all list cases, you may have as -many paragraphs, sublists, etc. as you want, as long as the left-hand -side of the paragraph or whatever aligns with the first line of text -in the list item. - -Lists must always start a new paragraph -- that is, they must appear -after a blank line. - -**enumerated** lists (numbers, letters or roman numerals; quickref__) - __ quickref.html#enumerated-lists - - Start a line off with a number or letter followed by a period ".", - right bracket ")" or surrounded by brackets "( )" -- whatever you're - comfortable with. All of the following forms are recognised:: - - 1. numbers - - A. upper-case letters - and it goes over many lines - - with two paragraphs and all! - - a. lower-case letters - - 3. with a sub-list starting at a different number - 4. make sure the numbers are in the correct sequence though! - - I. upper-case roman numerals - - i. lower-case roman numerals - - (1) numbers again - - 1) and again - - Results in (note: the different enumerated list styles are not - always supported by every web browser, so you may not get the full - effect here): - - 1. numbers - - A. upper-case letters - and it goes over many lines - - with two paragraphs and all! - - a. lower-case letters - - 3. with a sub-list starting at a different number - 4. make sure the numbers are in the correct sequence though! - - I. upper-case roman numerals - - i. lower-case roman numerals - - (1) numbers again - - 1) and again - -**bulleted** lists (quickref__) - __ quickref.html#bullet-lists - - Just like enumerated lists, start the line off with a bullet point - character - either "-", "+" or "*":: - - * a bullet point using "*" - - - a sub-list using "-" - - + yet another sub-list - - - another item - - Results in: - - * a bullet point using "*" - - - a sub-list using "-" - - + yet another sub-list - - - another item - -**definition** lists (quickref__) - __ quickref.html#definition-lists - - Unlike the other two, the definition lists consist of a term, and - the definition of that term. The format of a definition list is:: - - what - Definition lists associate a term with a definition. - - *how* - The term is a one-line phrase, and the definition is one or more - paragraphs or body elements, indented relative to the term. - Blank lines are not allowed between term and definition. - - Results in: - - what - Definition lists associate a term with a definition. - - *how* - The term is a one-line phrase, and the definition is one or more - paragraphs or body elements, indented relative to the term. - Blank lines are not allowed between term and definition. - -Preformatting (code samples) ----------------------------- -(quickref__) - -__ quickref.html#literal-blocks - -To just include a chunk of preformatted, never-to-be-fiddled-with -text, finish the prior paragraph with "``::``". The preformatted -block is finished when the text falls back to the same indentation -level as a paragraph prior to the preformatted block. For example:: - - An example:: - - Whitespace, newlines, blank lines, and all kinds of markup - (like *this* or \this) is preserved by literal blocks. - Lookie here, I've dropped an indentation level - (but not far enough) - - no more example - -Results in: - - An example:: - - Whitespace, newlines, blank lines, and all kinds of markup - (like *this* or \this) is preserved by literal blocks. - Lookie here, I've dropped an indentation level - (but not far enough) - - no more example - -Note that if a paragraph consists only of "``::``", then it's removed -from the output:: - - :: - - This is preformatted text, and the - last "::" paragraph is removed - -Results in: - -:: - - This is preformatted text, and the - last "::" paragraph is removed - -Sections --------- - -(quickref__) - -__ quickref.html#section-structure - -To break longer text up into sections, you use **section headers**. -These are a single line of text (one or more words) with adornment: an -underline alone, or an underline and an overline together, in dashes -"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the -non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you -feel comfortable with. An underline-only adornment is distinct from -an overline-and-underline adornment using the same character. The -underline/overline must be at least as long as the title text. Be -consistent, since all sections marked with the same adornment style -are deemed to be at the same level:: - - Chapter 1 Title - =============== - - Section 1.1 Title - ----------------- - - Subsection 1.1.1 Title - ~~~~~~~~~~~~~~~~~~~~~~ - - Section 1.2 Title - ----------------- - - Chapter 2 Title - =============== - -This results in the following structure, illustrated by simplified -pseudo-XML:: - - <section> - <title> - Chapter 1 Title - <section> - <title> - Section 1.1 Title - <section> - <title> - Subsection 1.1.1 Title - <section> - <title> - Section 1.2 Title - <section> - <title> - Chapter 2 Title - -(Pseudo-XML uses indentation for nesting and has no end-tags. It's -not possible to show actual processed output, as in the other -examples, because sections cannot exist inside block quotes. For a -concrete example, compare the section structure of this document's -source text and processed output.) - -Note that section headers are available as link targets, just using -their name. To link to the Lists_ heading, I write "``Lists_``". If -the heading has a space in it like `text styles`_, we need to quote -the heading "```text styles`_``". - - -Document Title / Subtitle -````````````````````````` - -The title of the whole document is distinct from section titles and -may be formatted somewhat differently (e.g. the HTML writer by default -shows it as a centered heading). - -To indicate the document title in reStructuredText, use a unique adornment -style at the beginning of the document. To indicate the document subtitle, -use another unique adornment style immediately after the document title. For -example:: - - ================ - Document Title - ================ - ---------- - Subtitle - ---------- - - Section Title - ============= - - ... - -Note that "Document Title" and "Section Title" above both use equals -signs, but are distict and unrelated styles. The text of -overline-and-underlined titles (but not underlined-only) may be inset -for aesthetics. - - -Images ------- - -(quickref__) - -__ quickref.html#directives - -To include an image in your document, you use the the ``image`` directive__. -For example:: - - .. image:: images/biohazard.png - -results in: - -.. image:: images/biohazard.png - -The ``images/biohazard.png`` part indicates the filename of the image -you wish to appear in the document. There's no restriction placed on -the image (format, size etc). If the image is to appear in HTML and -you wish to supply additional information, you may:: - - .. image:: images/biohazard.png - :height: 100 - :width: 200 - :scale: 50 - :alt: alternate text - -See the full `image directive documentation`__ for more info. - -__ ../../ref/rst/directives.html -__ ../../ref/rst/directives.html#images - - -What Next? ----------- - -This primer introduces the most common features of reStructuredText, -but there are a lot more to explore. The `Quick reStructuredText`_ -user reference is a good place to go next. For complete details, the -`reStructuredText Markup Specification`_ is the place to go [#]_. - -Users who have questions or need assistance with Docutils or -reStructuredText should post a message to the Docutils-users_ mailing -list. - -.. [#] If that relative link doesn't work, try the master document: - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. - -.. _reStructuredText Markup Specification: - ../../ref/rst/restructuredtext.html -.. _Docutils-users: ../mailing-lists.html#docutils-users -.. _Docutils project web site: http://docutils.sourceforge.net/ diff --git a/docutils/docs/user/slide-shows.txt b/docutils/docs/user/slide-shows.txt deleted file mode 100644 index 6732f4f44..000000000 --- a/docutils/docs/user/slide-shows.txt +++ /dev/null @@ -1,1004 +0,0 @@ -.. include:: <s5defs.txt> - -================================= - Easy Slide Shows With reST & S5 -================================= - -:Authors: David Goodger & Chris Liechti -:Date: $Date$ - -.. This document has been placed in the public domain. - -.. container:: handout - - How to create quick, good-looking presentation slide shows with - Docutils_/reStructuredText_ and S5_. - - This document serves both as a user manual and as a usage example - of the s5_html.py writer and the rst2s5.py front end. - - To view this document as a slide show see - http://docutils.sf.net/docs/user/slide-shows.s5.html (or `your - local copy <slide-shows.s5.html>`__). - -.. contents:: - :class: handout - -.. class:: tiny - -* S5 themes are designed for full-screen display areas with a 4:3 - aspect ratio. If the slide text doesn't fit in your browser window, - try decreasing the text size. - -* Use the space bar to advance, Page Up/Down & arrow keys to navigate. - -* Best viewed in Firefox_, Safari, and Konqueror. Click the "|mode|" - button to switch between presentation & handout/outline modes. Hit - the "C" key to display the navigation controls, or mouse over the - lower right-hand corner. - -* Functionality is limited in Opera. Switch to full-screen mode (F11 - key) to activate Opera Show. - -* S5 works in Internet Explorer, but it may look ugly. - -.. container:: handout - - The first slide of a presentation consists of all visible text up - to the first section title. The document title is also added to - the footer of all slides. - - The "footer" directive is used to specify part of the slide footer - text. It is currently limited to one short line (one paragraph). - - There is no support for the "header" directive in the themes - included with Docutils. - -.. _Docutils: http://docutils.sourceforge.net/ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _S5: http://meyerweb.com/eric/tools/s5/ -.. _Firefox: http://www.mozilla.com/firefox/ -.. |bullet| unicode:: U+02022 -.. |mode| unicode:: U+00D8 .. capital o with stroke - -.. footer:: Location |bullet| Date - - -Introduction -============ - -.. class:: handout - - ``rst2s5.py`` is a Docutils_ front end that outputs HTML for use - with S5_, a "Simple Standards-based Slide Show System" by Eric - Meyer. - -.. topic:: Installation - :class: handout - - Prerequisites: Python and the Docutils_ package have to be - installed. See the `Docutils README`__ file for installation - instructions. - - __ http://docutils.sourceforge.net/README.html - -* reStructuredText - - .. class:: handout - - Uses normal reStructuredText as input. - -* One section per slide - - .. class:: handout - - Each first-level section is converted into a single slide. - -* XHTML output - - .. container:: handout - - Presentations can be viewed using most modern graphical web - browsers. The browser must support CSS, JavaScript, and XHTML. - S5 even works with IE! - - S5 was designed to add the functionality of the `Opera Show`_ - standard (without Opera Show's limitations) to non-Opera - browsers. Unfortunately, most of S5's CSS and JavaScript - extensions don't function in the Opera browser. - - .. _Opera Show: http://www.opera.com/support/tutorials/operashow/ - -* Themes - - .. class:: handout - - A variety of themes are available. See `Example Themes`_, below. - -* ``rst2s5.py`` - - .. class:: handout - - The front-end tool to generate S5 slide shows. - -.. topic:: Keyboard Controls - :class: handout - - The following apply in any supporting browser besides Opera, which - uses the default Opera Show controls instead. - - .. list-table:: - :header-rows: 1 - - * - Action - - Key(s) - * - Go to the next slide - - * [Space bar] - * [Return] - * [Enter] - * [Right arrow] - * [Down arrow] - * [Page down] - * Click the left mouse button outside of the control area, - Flash object, or movie - * - Go to the previous slide - - * [Left arrow] - * [Up arrow] - * [Page up] - * - Go to the title (first) slide - - [Home] - * - Go to the last slide - - [End] - * - Jump directly to a slide - - Type the slide number, then hit [Return] or [Enter] - * - Skip forward *n* slides - - Type the number of slides to skip, then hit any "go to next" - key (except [Return] or [Enter]) - * - Skip backward *n* slides - - Type the number of slides to skip, then hit any "go to - previous" key - * - Switch between slideshow and outline view - - * [T] - * Click the |mode| button - * - Show/hide slide controls - - * [C] - * Move the mouse pointer over the control area - - Further details of the S5 user interface can be found at `Eric - Meyer's S5 page`__. - - __ S5_ - - -Features (1) -============ - -.. container:: handout - - The S5/HTML Writer supports all the standard Docutils HTML - features. S5 has been released to the Public Domain. - -S5-specific features: - -.. class:: incremental - -* The document title is duplicated on each slide in the S5 footer. - -* The ``footer`` directive may be used to define additional text in - the S5 footer. - - .. container:: handout - - But it is limited to one line of text. - - This is useful for information such as the date of the - presentation and/or the location. The field in the footer is - left blank if no ``footer`` directive is used. - - Example:: - - .. footer:: Location - Date - - There is also a progress indicator (slide counter) in the footer - that can be enabled. It's disabled by default. - -* Incremental display. - - .. class:: handout - - An "incremental" class can be assigned to lists and other elements - to get one-item-at-a-time behavior (like this list). Incremental - display does not work in the Opera browser. - -* Text auto-scaling. - - .. class:: handout - - The text size adjusts relative to the size of your browser window - automatically. You may need to reload the document after resizing - the window. The browser and platform affect the font used; be sure - to test the slide show on the presentation system. - - -Features (2): Handouts -====================== - -.. container:: handout - - The contents of any element with a "class" attribute value of - "handout" are hidden in the slide presentation, and are only - visible when the presentation is printed, or viewed in outline - mode. "Handout"-class elements can appear anywhere in the text, as - often as needed. - - This means that the slides and extra handout material can be - combined in one document. The handout can be printed directly from - the browser, and it will contain more than just silly framed - slides. This can be used to provide more detailed information, or - for speaker's notes. - -.. class:: incremental - -* Use the "class" directive:: - - .. class:: handout - - .. container:: handout - - The ``.. class:: handout`` directive can be used to tag - individual paragraphs and other elements. The "class" directive - applies to the first element immediately following:: - - .. class:: handout - - This paragraph will get a - ``class="handout"`` attribute. - - This paragraph will not be affected. - - It also applies to multiple elements in the directive content:: - - .. class:: handout - - These paragraphs are the content - of the "class" directive. And as such... - - Both paragraphs will *individually* receive - ``class="handout"`` attributes. - -* Use the "container" directive:: - - .. container:: handout - - .. container:: handout - - Arbitrary handout blocks can be created using the ``container`` - directive. The content is treated as one. - -* Use the "class" option of directives that support it:: - - .. topic:: Extra Material For Handouts - :class: handout - -.. container:: handout - - The following directives support "class" options: - - * all admonition directives ("admonition", "note", "hint", etc.) - * "image" & "figure" - * "topic" - * "sidebar" - * "line-block" - * "parsed-literal" - * "rubric" - * "compound" - * "table", "csv-table", & "list-table" - * "target-notes" (more about that below) - * "role" (pre-defined; more below) - - Handout contents are also visible on the screen if the S5 view mode - is toggled from "slide show" to "outline" mode. - - -Caveats -======= - -.. class:: incremental - -1. Some Docutils features are not supported by some themes. - - .. container:: handout - - For example, header rendering is not supported by the themes - supplied with Docutils. - - The "header" directive is used to set header text. S5 - automatically inserts section/slide titles into the "header" - area of a slide. If both Docutils headers and S5 headers (slide - titles) exist simultaneously, they interfere with each other. - -2. Care must be taken with the "contents" directive. - - .. container:: handout - - The ``--no-toc-backlinks`` option is the default for the S5/HTML - writer (``toc_backlinks=0`` setting). Other values for this - setting will change the CSS class of headings such that they - won't show up correctly in the slide show. - - Use the ``:class: handout`` option on the "contents" directive - to limit the table of contents to the handout/outline mode - only:: - - .. contents:: - :class: handout - - -.. class:: incremental - -3. Subsections ... ------------------- - -... may be used, sparingly. - -.. container:: handout - - Only first-level sections become slides. Not many levels of - subsections can fit on a slide. - - Subsections (of any level) work normally in handouts though. Add - "``.. class:: handout``" before a subsection (or sub-subsection, or - ...), and the entire subsection will only appear in the handout. - - -Generating a Slide Show (1) -=========================== - -.. class:: incremental - -1. Open a console (terminal, command shell) and go to the folder - containing your file, ``slides.txt``. - -2. Run the command:: - - rst2s5.py slides.txt slides.html - -3. Specify an S5 theme with the ``--theme`` option. - - .. class:: handout - - Docutils will copy the S5 theme files into a ``ui/<theme>`` folder - beside the output HTML file. A slide show can also link to an - existing theme using the ``--theme-url`` option. - - -Generating a Slide Show (2) -=========================== - -.. class:: incremental - -4. Include a copy of any linked stylesheet. - - .. class:: handout - - The default Docutils stylesheet, ``html4css1.css``, will normally - be embedded in the output HTML. If you choose to link to a - stylesheet instead of embedding, you must include a copy (suggested - location: in the ``ui/`` directory). - -5. Open ``slides.html`` in a web browser. - -6. Expand the browser window to full-screen mode, and speak. - - .. class:: handout - - The `Web Developer`__ extension for Firefox is very useful. With - it, you can resize your browser window to the exact dimensions of - the projector you'll be using, so you can test beforehand. There - are many other useful features as well. - - __ http://chrispederick.com/work/webdeveloper/ - -7. Profit! - - -Examples (1) -============ - -.. sidebar:: Hint - - Admonitions, tables, sidebars, and other elements can be used in - on-screen presentations in handouts. Images too! - - .. image:: images/happy_monkey.png - :alt: sample image - -===== ===== ====== - A B A or B -===== ===== ====== -False False False -True False True -False True True -True True True -===== ===== ====== - - -Examples (2): Incremental Text -============================== - -.. class:: incremental - - Paragraphs can be displayed one at a time... - - .. container:: - - ... or a bunch at a time. - - This second paragraph is displayed together with the previous - one by grouping them with the "container" directive. - -`We can also display` `one` `word` `at` `a` `time,` -`or a phrase` `at a time,` -`or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!` - -`(But the markup ain't pretty.)` - - -Examples (3): Incr. Graphics -============================ - -Let's play... Rock, Scissors, Paper - -.. container:: animation - - .. image:: images/rsp-empty.png - :class: hidden slide-display - - .. class:: incremental hidden slide-display - - .. image:: images/rsp-objects.png - .. image:: images/rsp-cuts.png - .. image:: images/rsp-covers.png - .. image:: images/rsp-breaks.png - - .. image:: images/rsp-all.png - :class: incremental - - -Themes -====== - -.. class:: incremental - -* Several themes are available, and they're easy to adapt. - - .. container:: handout - - Themes from the `S5 tutorial`__ can be used. These themes are in - the public domain and may be redistributed freely. - - __ http://meyerweb.com/eric/tools/s5/s5blank.zip - - Sites with other S5 themes: - - * http://meyerweb.com/eric/tools/s5/themes/ - * http://mozilla.wikicities.com/wiki/Firefox_S5:Designs - * http://lachy.id.au/dev/mozilla/firefox/s5/ - - S5 is becoming more popular every day. Do a web search for "S5 - theme" and you're bound to find plenty of choices. - -* "``--theme``" option. - - .. container:: handout - - The theme can be specified with the "``--theme``" command-line - option. - - Example:: - - rst2s5 --theme big-black slides.txt slides.html - - The default theme is "default". - -* "``theme``" setting. - - .. class:: handout - - You can set the theme with the "``theme``" configuration file - setting. - -* Copied to ``./ui/<theme>/``. - - .. class:: handout - - Themes are copied into a ``ui/<theme>`` folder inside the folder - containing the presentation. - -* Link with "``--theme-url``" option. - - .. class:: handout - - Link to a theme on the same or another web site, using the - "``--theme-url``" option or "``theme_url``" configuration file - setting. - - -Example Themes -============== - -.. class:: handout - - The default theme, "default", is a simplified version of S5's - default theme. It accommodates up to 13 lines of text. - -.. class:: center - - "default" - - .. image:: images/default.png - :align: center - - -Example Themes: Small Text -========================== - -.. class:: handout - - The "small-white" and "small-black" themes are simplifications of - the default theme (**small** black text on a **white** background, - and **small** black text on a **white** background, respectively). - They each accommodate up to 15 lines of text. - -.. list-table:: - :class: borderless - - * - "small-white" - - .. image:: images/small-white.png - - - "small-black" - - .. image:: images/small-black.png - - -Example Themes: Large Text -========================== - -.. class:: handout - - The "big-white" and "big-black" themes feature very large, bold - text, with no footers. Only five short lines fit in a slide. - -.. list-table:: - :class: borderless - - * - "big-white" - - .. image:: images/big-white.png - - - "big-black" - - .. image:: images/big-black.png - - -Example Themes: Medium Text -=========================== - -.. class:: handout - - The "medium-white" and "medium-black" themes feature medium-sized - text. Up to 8 lines of text are accommodated. - -.. list-table:: - :class: borderless - - * - "medium-white" - - .. image:: images/medium-white.png - - - "medium-black" - - .. image:: images/medium-black.png - - -S5 Theme Files -============== - -An S5 theme consists of a directory containing several files -- -stylesheets, JavaScript, and graphics: - -.. image:: images/s5-files.png - :align: center - -.. container:: handout - - The generated HTML contains the entire slide show text. It also - contains links to the following files: - - * slides.css simply contains import links to: - - - s5-core.css: Default styles critical to the proper functioning - of the slide show; don't touch this! - - - framing.css: Sets the basic layout of slide components (header, - footer, controls, etc. This file is the often edited. - - - pretty.css: Presentation styles that give the slide show a - unique look and feel. This is the file that you're most likely - to edit for a custom theme. You can make a whole new theme - just by editing this file, and not touching the others. - - * outline.css: Styles for outline mode. - - * print.css: Styles for printing; hides most layout elements, and - may display others. - - * opera.css: Styles necessary for the proper functioning of S5 in - Opera Show. - - * slides.js: the JavaScript that drives the dynamic side of the - slide show (actions and navigation controls). It automatically - IDs the slides when the document loads, builds the navigation - menu, handles the hiding and showing of slides, and so on. The - code also manages the fallback to Opera Show if you're using - the Opera web browser. - - Two files are included to support PNG transparency (alpha - channels) in Internet Explorer: - - - iepngfix.htc - - blank.gif - - -Making a Custom Theme -===================== - -.. class:: incremental - -1. Run "``rst2s5.py --theme <base-theme> <doc>.txt <doc>.html``". - - .. class:: handout - - This initializes the ``ui`` directory with the base theme files. - -2. Copy ``ui/<base-theme>`` to ``ui/<new-theme>``. - -3. Edit the styles. - - .. class:: handout - - Start with ``pretty.css``; edit ``framing.css`` if you need to make - layout changes. - -4. Run "``rst2s5.py --theme <new-theme> <doc>.txt <doc>.html``". - - .. class:: handout - - Open your ``<doc>.html`` in a browser to test the new theme. - -5. Rinse & repeat. - - .. class:: handout - - Repeat from step 3 until you're satisfied. - -.. TODO: What to do next: - - * add a ``__base__`` file - * create a personal reusable theme (plugin) - * submit the new theme to Docutils - - ``docutils/writers/s5_html/themes/<theme>`` - -.. container:: handout - - Resources: - - * W3C's `Learning CSS <http://www.w3.org/Style/CSS/learning>`__ - - * `Creating An S5 Theme <http://home.cogeco.ca/~ve3ll/s5themes.htm>`__ - - * A short tutorial on how to create themes (in German): - `Eigenes Theme erstellen <http://yatil.de/s5/dokumentation/9/>`__ - - -Classes: Incremental (1) -======================== - -.. class:: handout - - Several "class" attribute values have built-in support in the - themes supplied with Docutils. - -.. class:: incremental - - As described earlier, - - * ``.. class:: incremental`` - - * ``.. container:: incremental`` - - * :: - - .. sidebar:: title - :class: incremental - - -Classes: Incremental (2) -======================== - -The "incremental" interpreted text role is also supported: - -.. class:: incremental - - :: - - :incremental:`This will appear first,` `and - this will appear second.`:incremental: - - Requires "``.. include:: <s5defs.txt>``". - -.. container:: handout - - As you can see, this markup is not very convenient. - -.. class:: incremental - - | But ``s5defs.txt`` includes this useful definition: - | "``.. default-role:: incremental``". So: - - :: - - `This` `is` `all` `we` `need` - -`This` `is` `all` `we` `need` `to mark up incremental text.` - - -Classes: Incremental (3) -======================== - -.. class:: small - -:: - - .. container:: animation - - .. image:: images/empty.png - :class: hidden slide-display - - .. class:: incremental hidden slide-display - - .. image:: images/1.png - .. image:: images/2.png - - .. image:: images/3.png - :class: incremental - -.. container:: handout - - This is how the example works. - - The animation effects are caused by placing successive images at - the same location, laying each image over the last. For best - results, all images should be the same size, and the positions of - image elements should be consistent. Use image transparency (alpha - channels) to get overlay effects. - - Absolute positioning is used, which means that the images take up - no space in the flow. If you want text to follow the images, you - have to specify the total size of the container via a style. - Otherwise, the images and any following text will overlap. - - These class values do the work: - - animation - This wraps the container with styles that position the images - absolutely, overlaying them over each other. Only useful on a - container. - - hidden - Unless overridden (by "slide-display", for example), these - elements will not be displayed. Only the last image will be - displayed in handout mode, when print, or when processed to - ordinary HTML, because it does *not* carry a "hidden" class. - - slide-display - In conjunction with "hidden", these elements will only appear - on the slide, preventing clutter in the handout. - - incremental - The second and subsequent images will appear one at a time. - The first image will already be present when the slide is - displayed, because it does *not* carry an "incremental" class. - - -Classes: Text Size -================== - -.. class:: incremental - - * :tiny:`tiny` (class & role name: "tiny", e.g. "``:tiny:`text```") - * :small:`small` ("small") - * normal (unstyled) - * :big:`big` ("big") - * :huge:`huge` ("huge") - - Requires "``.. include:: <s5defs.txt>``". - - -Classes: Alignment -================== - -.. class:: incremental - - .. class:: left - - Left (class name: "left") - - .. class:: center - - Center ("center" & "centre") - - .. class:: right - - Right ("right") - -.. class:: handout - - These classes apply to block-level elements only. They cannot be - used for inline text (i.e., they're not interpreted text roles). - -.. class:: incremental - - Example:: - - .. class:: center - - Text to be centered. - - -Classes: Text Colours -===================== - -:black:`black` [black], :gray:`gray`, :silver:`silver`, :white:`white` -[white], :maroon:`maroon`, :red:`red`, :magenta:`magenta`, -:fuchsia:`fuchsia`, :pink:`pink`, :orange:`orange`, :yellow:`yellow`, -:lime:`lime`, :green:`green`, :olive:`olive`, :teal:`teal`, -:cyan:`cyan`, :aqua:`aqua`, :blue:`blue`, :navy:`navy`, -:purple:`purple` - -The class names and role names are the same as the colour names. For -example, "``:orange:`text```" produces ":orange:`text`". - -.. class:: incremental - -Requires "``.. include:: <s5defs.txt>``". - - -Classes: Borderless Tables -========================== - -.. class:: handout - - Here's an ordinary, unstyled table: - -.. class:: incremental - - ========= ======= - Sometimes borders - --------- ------- - are useful. - ========= ======= - - And after applying "``.. class:: borderless``": - - .. class:: borderless - - ======= ========== ======= - But sometimes, borders - ------- ---------- ------- - are **not** wanted. - ======= ========== ======= - - -Classes: Print-Only -=================== - -.. class:: handout - - Elements with ``class="print"`` attributes display their contents - when printed, overriding ``class="hidden"``. - -.. class:: incremental - - Example: the "target-notes" directive:: - - .. topic:: Links - :class: hidden print - - .. target-notes:: - :class: hidden print - -.. container:: handout - - One good example, used in this document, is the "target-notes" - directive. For each external target (hyperlink) in the text, this - directive generates a footnote containing the visible URL as - content. Footnote references are placed after each hyperlink - reference. - - The "topic" directive is given a "class" attribute with values - "hidden" and "print", so the entire topic will only be displayed - when printed. The "target-notes" directive also assigns a "class" - attributes with values "hidden" and "print" to each of the footnote - references it inserts throughout the text; they will only show up - when printed. - -.. class:: incremental - - Other uses may require "``.. include:: <s5defs.txt>``". - - -Useful Extensions For Firefox -============================= - -* `Autohide`__ - - .. class:: handout - - Automatically hides toolbars in full-screen mode. - - __ http://www.krickelkrackel.de/autohide/autohide.htm - -* `Web Developer`__ - - .. class:: handout - - Adds a context submenu and a toolbar with a lot of useful - functionality, including the viewing and live editing of - stylesheets, and sizing the browser window. - - __ http://chrispederick.com/work/webdeveloper/ - - -To Do -===== - -.. class:: incremental - - * Multi-display support: - - - speaker's notes on the laptop screen - - slides on the projector - - two views stay in sync - - presentation controlled from either display - - * Add timeout to incremental style. - - .. class:: handout - - I.e., incremental-specific style should go away (revert to - normal) after a certain interval. - - These will require some serious JavaScript-fu! - - -That's All, Folks! -================== - -.. class:: huge - - Further information: - http://docutils.sf.net - - Docutils users' mailing list: - docutils-users@lists.sf.net - - `Any questions?` - - -.. topic:: Links - :class: hidden print - - .. target-notes:: :class: hidden print diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt deleted file mode 100644 index 20f5a3b2f..000000000 --- a/docutils/docs/user/tools.txt +++ /dev/null @@ -1,389 +0,0 @@ -========================== - Docutils Front-End Tools -========================== - -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - --------------- - Introduction --------------- - -Once the Docutils package is unpacked, you will discover a "``tools``" -directory containing several front ends for common Docutils -processing. Rather than a single all-purpose program, Docutils has -many small front ends, each specialized for a specific "Reader" (which -knows how to interpret a file in context), a "Parser" (which -understands the syntax of the text), and a "Writer" (which knows how -to generate a specific data format). - -Most front ends have common options and the same command-line usage -pattern:: - - toolname [options] [<source> [<destination]] - -(The exceptions are buildhtml.py_ and rstpep2html.py_.) See -rst2html.py_ for concrete examples. Each tool has a "``--help``" -option which lists the `command-line options`_ and arguments it -supports. Processing can also be customized with `configuration -files`_. - -The two arguments, "source" and "destination", are optional. If only -one argument (source) is specified, the standard output (stdout) is -used for the destination. If no arguments are specified, the standard -input (stdin) is used for the source as well. - - -Getting Help -============ - -First, try the "``--help``" option each front-end tool has. - -Users who have questions or need assistance with Docutils or -reStructuredText should post a message to the Docutils-users_ mailing -list. - -.. _Docutils-users: mailing-lists.html#docutils-users - - ------------ - The Tools ------------ - -HTML-Generating Tools -===================== - -buildhtml.py ------------- - -:Readers: Standalone, PEP -:Parser: reStructuredText -:Writers: HTML, PEP/HTML - -Use ``buildhtml.py`` to generate .html from all the .txt files -(including PEPs) in each <directory> given, and their subdirectories -too. (Use the ``--local`` option to skip subdirectories.) - -Usage:: - - buildhtml.py [options] [<directory> ...] - -After unpacking the Docutils package, the following shell commands -will generate HTML for all included documentation:: - - cd docutils/tools - buildhtml.py .. - -For official releases, the directory may be called "docutils-X.Y", -where "X.Y" is the release version. Alternatively:: - - cd docutils - tools/buildhtml.py --config=tools/docutils.conf - -The current directory (and all subdirectories) is chosen by default if -no directory is named. Some files may generate system messages -(docs/user/rst/demo.txt contains intentional errors); use the -``--quiet`` option to suppress all warnings. The ``--config`` option -ensures that the correct settings are in place (a ``docutils.conf`` -`configuration file`_ in the current directory is picked up -automatically). Command-line options may be used to override config -file settings or replace them altogether. - - -rst2html.py ------------ - -:Reader: Standalone -:Parser: reStructuredText -:Writer: HTML - -The ``rst2html.py`` front end reads standalone reStructuredText source -files and produces HTML 4 (XHTML 1) output compatible with modern -browsers that support cascading stylesheets (CSS). A stylesheet is -required for proper rendering; a simple but complete stylesheet is -installed and used by default (see Stylesheets_ below). - -For example, to process a reStructuredText file "``test.txt``" into -HTML:: - - rst2html.py test.txt test.html - -Now open the "``test.html``" file in your favorite browser to see the -results. To get a footer with a link to the source file, date & time -of processing, and links to the Docutils project, add some options:: - - rst2html.py -stg test.txt test.html - - -Stylesheets -``````````` - -``rst2html.py`` inserts into the generated HTML a cascading stylesheet -(or a link to a stylesheet, when passing the "``--link-stylesheet``" -option). A stylesheet is required for proper rendering. The default -stylesheet (``docutils/writers/html4css1/html4css1.css``, located in -the installation directory) is provided for basic use. To use a -different stylesheet, you must specify the stylesheet's location with -a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a -local file) command-line option, or with `configuration file`_ -settings (e.g. ``./docutils.conf`` or ``~/.docutils``). To experiment -with styles, please see the `guide to writing HTML (CSS) stylesheets -for Docutils`__. - -__ ../howto/html-stylesheets.html - - -rstpep2html.py --------------- - -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML - -``rstpep2html.py`` reads a new-style PEP (marked up with -reStructuredText) and produces HTML. It requires a template file and -a stylesheet. By default, it makes use of a "``pep-html-template``" -file and the "``pep.css``" stylesheet (both in the -``docutils/writers/pep_html/`` directory), but these can be overridden -by command-line options or configuration files. - -For example, to process a PEP into HTML:: - - cd <path-to-docutils>/docs/peps - rstpep2html.py pep-0287.txt pep-0287.html - - -rst2s5.py ---------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: S5/HTML - -The ``rst2s5.py`` front end reads standalone reStructuredText source -files and produces (X)HTML output compatible with S5_, the "Simple -Standards-based Slide Show System" by Eric Meyer. A theme is required -for proper rendering; several are distributed with Docutils and others -are available; see Themes_ below. - -For example, to process a reStructuredText file "``slides.txt``" into -S5/HTML:: - - rst2s5.py slides.txt slides.html - -Now open the "``slides.html``" file in your favorite browser, switch -to full-screen mode, and enjoy the results. - -.. _S5: http://meyerweb.com/eric/tools/s5/ - - -Themes -`````` - -Each S5 theme consists of a directory containing several files: -stylesheets, JavaScript, and graphics. These are copied into a -``ui/<theme>`` directory beside the generated HTML. A theme is chosen -using the "``--theme``" option (for themes that come with Docutils) or -the "``--theme-url``" option (for themes anywhere). For example, the -"medium-black" theme can be specified as follows:: - - rst2s5.py --theme medium-black slides.txt slides.html - -The theme will be copied to the ``ui/medium-black`` directory. - -Several themes are included with Docutils: - -``default`` - This is a simplified version of S5's default theme. - - :Main content: black serif text on a white background - :Text capacity: about 13 lines - :Headers: light blue, bold sans-serif text on a dark blue - background; titles are limited to one line - :Footers: small, gray, bold sans-serif text on a dark blue - background - -``small-white`` - (Small text on a white background.) - - :Main content: black serif text on a white background - :Text capacity: about 15 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: small, dark gray, bold sans-serif text on a white - background - -``small-black`` - :Main content: white serif text on a black background - :Text capacity: about 15 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: small, light gray, bold sans-serif text on a black - background - -``medium-white`` - :Main content: black serif text on a white background - :Text capacity: about 9 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: small, dark gray, bold sans-serif text on a white - background - -``medium-black`` - :Main content: white serif text on a black background - :Text capacity: about 9 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: small, light gray, bold sans-serif text on a black - background - -``big-white`` - :Main content: black, bold sans-serif text on a white background - :Text capacity: about 5 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: not displayed - -``big-black`` - :Main content: white, bold sans-serif text on a black background - :Text capacity: about 5 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: not displayed - -If a theme directory contains a file named ``__base__``, the name of -the theme's base theme will be read from it. Files are accumulated -from the named theme, any base themes, and the "default" theme (which -is the implicit base of all themes). - -For details, please see `Easy Slide Shows With reStructuredText & -S5 <slide-shows.html>`_. - - -LaTeX-Generating Tools -====================== - -rst2latex.py ------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: LaTeX2e - -The ``rst2latex.py`` front end reads standalone reStructuredText -source files and produces LaTeX2e output. For example, to process a -reStructuredText file "``test.txt``" into LaTeX:: - - rst2latex.py test.txt test.tex - -The output file "``test.tex``" should then be processed with ``latex`` -or ``pdflatex`` to get a typeset document. - -Some limitations and difference apply: - -- GIF, JPG and PNG images are not handled, when processed with - ``latex``; use ``pdflatex`` instead. -- Only the Latin-1 output encoding has been tested up to now (Latin-1 - has been made the default output encoding for LaTeX). -- The optional stylesheet file allows the inclusion of special packages - or overwriting default settings for LaTeX. -- Not all constructs are possible, see `Generating LaTeX with Docutils`_. - - -XML-Generating Tools -==================== - -rst2xml.py ----------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: XML (Docutils native) - -The ``rst2xml.py`` front end produces Docutils-native XML output. -This can be transformed with standard XML tools such as XSLT -processors into arbitrary final forms. - - -Testing/Debugging Tools -======================= - -rst2pseudoxml.py ----------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: Pseudo-XML - -``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to -Transform to Writer" pipeline. It produces a compact pretty-printed -"pseudo-XML", where nesting is indicated by indentation (no end-tags). -External attributes for all elements are output, and internal -attributes for any leftover "pending" elements are also given. - - -quicktest.py ------------- - -:Reader: N/A -:Parser: reStructuredText -:Writer: N/A - -The ``quicktest.py`` tool is used for testing the reStructuredText -parser. It does not use a Docutils Reader or Writer or the standard -Docutils command-line options. Rather, it does its own I/O and calls -the parser directly. No transforms are applied to the parsed -document. Various forms output are possible: - -- Pretty-printed pseudo-XML (default) -- Test data (Python list of input and pseudo-XML output strings; - useful for creating new test cases) -- Pretty-printed native XML -- Raw native XML (with or without a stylesheet reference) - - - ---------------- - Customization ---------------- - -Command-Line Options -==================== - -Each front-end tool supports command-line options for one-off -customization. For persistent customization, use `configuration -files`_. Command-line options take priority over configuration file -settings. - -Use the "--help" option on each of the front ends to list the -command-line options it supports. Command-line options and their -corresponding configuration file entry names are listed in the -`Docutils Configuration Files`_ document. - - -.. _configuration file: - -Configuration Files -=================== - -Configuration files are used for persistent customization; they can be -set once and take effect every time you use a front-end tool. - -For details, see `Docutils Configuration Files`_. - -.. _Docutils Configuration Files: config.html -.. _Generating LaTeX with Docutils: latex.html - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docutils/docutils.conf b/docutils/docutils.conf index cdce8d629..cdce8d629 100644 --- a/docutils/docutils/docutils.conf +++ b/docutils/docutils.conf diff --git a/docutils/docutils/examples.py b/docutils/examples.py index 96f6a0522..96f6a0522 100644 --- a/docutils/docutils/examples.py +++ b/docutils/examples.py diff --git a/docutils/extras/optparse.py b/docutils/extras/optparse.py deleted file mode 100644 index c21663c55..000000000 --- a/docutils/extras/optparse.py +++ /dev/null @@ -1,1417 +0,0 @@ -"""optparse - a powerful, extensible, and easy-to-use option parser. - -By Greg Ward <gward@python.net> - -Originally distributed as Optik; see http://optik.sourceforge.net/ . - -If you have problems with this module, please do not file bugs, -patches, or feature requests with Python; instead, use Optik's -SourceForge project page: - http://sourceforge.net/projects/optik - -For support, use the optik-users@lists.sourceforge.net mailing list -(http://lists.sourceforge.net/lists/listinfo/optik-users). -""" - -# Python developers: please do not make changes to this file, since -# it is automatically generated from the Optik source code. - -__version__ = "1.4.1+" - -__all__ = ['Option', - 'SUPPRESS_HELP', - 'SUPPRESS_USAGE', - 'Values', - 'OptionContainer', - 'OptionGroup', - 'OptionParser', - 'HelpFormatter', - 'IndentedHelpFormatter', - 'TitledHelpFormatter', - 'OptParseError', - 'OptionError', - 'OptionConflictError', - 'OptionValueError', - 'BadOptionError'] - -__copyright__ = """ -Copyright (c) 2001-2003 Gregory P. Ward. All rights reserved. -Copyright (c) 2002-2003 Python Software Foundation. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - - * Neither the name of the author nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS -IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED -TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A -PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR -CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -""" - -import sys, os -import types -import textwrap - -# This file was generated from: -# Id: option_parser.py,v 1.57 2003/08/27 02:35:41 goodger Exp -# Id: option.py,v 1.26 2003/05/08 01:20:36 gward Exp -# Id: help.py,v 1.6 2003/08/27 02:35:41 goodger Exp -# Id: errors.py,v 1.7 2003/04/21 01:53:28 gward Exp - -class OptParseError (Exception): - def __init__ (self, msg): - self.msg = msg - - def __str__ (self): - return self.msg - - -class OptionError (OptParseError): - """ - Raised if an Option instance is created with invalid or - inconsistent arguments. - """ - - def __init__ (self, msg, option): - self.msg = msg - self.option_id = str(option) - - def __str__ (self): - if self.option_id: - return "option %s: %s" % (self.option_id, self.msg) - else: - return self.msg - -class OptionConflictError (OptionError): - """ - Raised if conflicting options are added to an OptionParser. - """ - -class OptionValueError (OptParseError): - """ - Raised if an invalid option value is encountered on the command - line. - """ - -class BadOptionError (OptParseError): - """ - Raised if an invalid or ambiguous option is seen on the command-line. - """ - - -class HelpFormatter: - - """ - Abstract base class for formatting option help. OptionParser - instances should use one of the HelpFormatter subclasses for - formatting help; by default IndentedHelpFormatter is used. - - Instance attributes: - indent_increment : int - the number of columns to indent per nesting level - max_help_position : int - the maximum starting column for option help text - help_position : int - the calculated starting column for option help text; - initially the same as the maximum - width : int - total number of columns for output - level : int - current indentation level - current_indent : int - current indentation level (in columns) - help_width : int - number of columns available for option help text (calculated) - """ - - def __init__ (self, - indent_increment, - max_help_position, - width, - short_first): - self.indent_increment = indent_increment - self.help_position = self.max_help_position = max_help_position - self.width = width - self.current_indent = 0 - self.level = 0 - self.help_width = width - max_help_position - self.short_first = short_first - - def indent (self): - self.current_indent += self.indent_increment - self.level += 1 - - def dedent (self): - self.current_indent -= self.indent_increment - assert self.current_indent >= 0, "Indent decreased below 0." - self.level -= 1 - - def format_usage (self, usage): - raise NotImplementedError, "subclasses must implement" - - def format_heading (self, heading): - raise NotImplementedError, "subclasses must implement" - - def format_description (self, description): - desc_width = self.width - self.current_indent - indent = " "*self.current_indent - return textwrap.fill(description, desc_width, - initial_indent=indent, - subsequent_indent=indent) + "\n" - - def format_option (self, option): - # The help for each option consists of two parts: - # * the opt strings and metavars - # eg. ("-x", or "-fFILENAME, --file=FILENAME") - # * the user-supplied help string - # eg. ("turn on expert mode", "read data from FILENAME") - # - # If possible, we write both of these on the same line: - # -x turn on expert mode - # - # But if the opt string list is too long, we put the help - # string on a second line, indented to the same column it would - # start in if it fit on the first line. - # -fFILENAME, --file=FILENAME - # read data from FILENAME - result = [] - opts = option.option_strings - opt_width = self.help_position - self.current_indent - 2 - if len(opts) > opt_width: - opts = "%*s%s\n" % (self.current_indent, "", opts) - indent_first = self.help_position - else: # start help on same line as opts - opts = "%*s%-*s " % (self.current_indent, "", opt_width, opts) - indent_first = 0 - result.append(opts) - if option.help: - help_lines = textwrap.wrap(option.help, self.help_width) - result.append("%*s%s\n" % (indent_first, "", help_lines[0])) - result.extend(["%*s%s\n" % (self.help_position, "", line) - for line in help_lines[1:]]) - elif opts[-1] != "\n": - result.append("\n") - return "".join(result) - - def store_option_strings (self, parser): - self.indent() - max_len = 0 - for opt in parser.option_list: - strings = self.format_option_strings(opt) - opt.option_strings = strings - max_len = max(max_len, len(strings) + self.current_indent) - self.indent() - for group in parser.option_groups: - for opt in group.option_list: - strings = self.format_option_strings(opt) - opt.option_strings = strings - max_len = max(max_len, len(strings) + self.current_indent) - self.dedent() - self.dedent() - self.help_position = min(max_len + 2, self.max_help_position) - - def format_option_strings (self, option): - """Return a comma-separated list of option strings & metavariables.""" - if option.takes_value(): - metavar = option.metavar or option.dest.upper() - short_opts = [sopt + metavar for sopt in option._short_opts] - long_opts = [lopt + "=" + metavar for lopt in option._long_opts] - else: - short_opts = option._short_opts - long_opts = option._long_opts - - if self.short_first: - opts = short_opts + long_opts - else: - opts = long_opts + short_opts - - return ", ".join(opts) - -class IndentedHelpFormatter (HelpFormatter): - """Format help with indented section bodies. - """ - - def __init__ (self, - indent_increment=2, - max_help_position=24, - width=78, - short_first=1): - HelpFormatter.__init__( - self, indent_increment, max_help_position, width, short_first) - - def format_usage (self, usage): - return "usage: %s\n" % usage - - def format_heading (self, heading): - return "%*s%s:\n" % (self.current_indent, "", heading) - - -class TitledHelpFormatter (HelpFormatter): - """Format help with underlined section headers. - """ - - def __init__ (self, - indent_increment=0, - max_help_position=24, - width=78, - short_first=0): - HelpFormatter.__init__ ( - self, indent_increment, max_help_position, width, short_first) - - def format_usage (self, usage): - return "%s %s\n" % (self.format_heading("Usage"), usage) - - def format_heading (self, heading): - return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading)) - - -# Do the right thing with boolean values for all known Python versions. -try: - True, False -except NameError: - (True, False) = (1, 0) - -_builtin_cvt = { "int" : (int, "integer"), - "long" : (long, "long integer"), - "float" : (float, "floating-point"), - "complex" : (complex, "complex") } - -def check_builtin (option, opt, value): - (cvt, what) = _builtin_cvt[option.type] - try: - return cvt(value) - except ValueError: - raise OptionValueError( - #"%s: invalid %s argument %r" % (opt, what, value)) - "option %s: invalid %s value: %r" % (opt, what, value)) - -def check_choice(option, opt, value): - if value in option.choices: - return value - else: - choices = ", ".join(map(repr, option.choices)) - raise OptionValueError( - "option %s: invalid choice: %r (choose from %s)" - % (opt, value, choices)) - -# Not supplying a default is different from a default of None, -# so we need an explicit "not supplied" value. -NO_DEFAULT = "NO"+"DEFAULT" - - -class Option: - """ - Instance attributes: - _short_opts : [string] - _long_opts : [string] - - action : string - type : string - dest : string - default : any - nargs : int - const : any - choices : [string] - callback : function - callback_args : (any*) - callback_kwargs : { string : any } - help : string - metavar : string - """ - - # The list of instance attributes that may be set through - # keyword args to the constructor. - ATTRS = ['action', - 'type', - 'dest', - 'default', - 'nargs', - 'const', - 'choices', - 'callback', - 'callback_args', - 'callback_kwargs', - 'help', - 'metavar'] - - # The set of actions allowed by option parsers. Explicitly listed - # here so the constructor can validate its arguments. - ACTIONS = ("store", - "store_const", - "store_true", - "store_false", - "append", - "count", - "callback", - "help", - "version") - - # The set of actions that involve storing a value somewhere; - # also listed just for constructor argument validation. (If - # the action is one of these, there must be a destination.) - STORE_ACTIONS = ("store", - "store_const", - "store_true", - "store_false", - "append", - "count") - - # The set of actions for which it makes sense to supply a value - # type, ie. where we expect an argument to this option. - TYPED_ACTIONS = ("store", - "append", - "callback") - - # The set of known types for option parsers. Again, listed here for - # constructor argument validation. - TYPES = ("string", "int", "long", "float", "complex", "choice") - - # Dictionary of argument checking functions, which convert and - # validate option arguments according to the option type. - # - # Signature of checking functions is: - # check(option : Option, opt : string, value : string) -> any - # where - # option is the Option instance calling the checker - # opt is the actual option seen on the command-line - # (eg. "-a", "--file") - # value is the option argument seen on the command-line - # - # The return value should be in the appropriate Python type - # for option.type -- eg. an integer if option.type == "int". - # - # If no checker is defined for a type, arguments will be - # unchecked and remain strings. - TYPE_CHECKER = { "int" : check_builtin, - "long" : check_builtin, - "float" : check_builtin, - "complex" : check_builtin, - "choice" : check_choice, - } - - - # CHECK_METHODS is a list of unbound method objects; they are called - # by the constructor, in order, after all attributes are - # initialized. The list is created and filled in later, after all - # the methods are actually defined. (I just put it here because I - # like to define and document all class attributes in the same - # place.) Subclasses that add another _check_*() method should - # define their own CHECK_METHODS list that adds their check method - # to those from this class. - CHECK_METHODS = None - - - # -- Constructor/initialization methods ---------------------------- - - def __init__ (self, *opts, **attrs): - # Set _short_opts, _long_opts attrs from 'opts' tuple. - # Have to be set now, in case no option strings are supplied. - self._short_opts = [] - self._long_opts = [] - opts = self._check_opt_strings(opts) - self._set_opt_strings(opts) - - # Set all other attrs (action, type, etc.) from 'attrs' dict - self._set_attrs(attrs) - - # Check all the attributes we just set. There are lots of - # complicated interdependencies, but luckily they can be farmed - # out to the _check_*() methods listed in CHECK_METHODS -- which - # could be handy for subclasses! The one thing these all share - # is that they raise OptionError if they discover a problem. - for checker in self.CHECK_METHODS: - checker(self) - - def _check_opt_strings (self, opts): - # Filter out None because early versions of Optik had exactly - # one short option and one long option, either of which - # could be None. - opts = filter(None, opts) - if not opts: - raise TypeError("at least one option string must be supplied") - return opts - - def _set_opt_strings (self, opts): - for opt in opts: - if len(opt) < 2: - raise OptionError( - "invalid option string %r: " - "must be at least two characters long" % opt, self) - elif len(opt) == 2: - if not (opt[0] == "-" and opt[1] != "-"): - raise OptionError( - "invalid short option string %r: " - "must be of the form -x, (x any non-dash char)" % opt, - self) - self._short_opts.append(opt) - else: - if not (opt[0:2] == "--" and opt[2] != "-"): - raise OptionError( - "invalid long option string %r: " - "must start with --, followed by non-dash" % opt, - self) - self._long_opts.append(opt) - - def _set_attrs (self, attrs): - for attr in self.ATTRS: - if attrs.has_key(attr): - setattr(self, attr, attrs[attr]) - del attrs[attr] - else: - if attr == 'default': - setattr(self, attr, NO_DEFAULT) - else: - setattr(self, attr, None) - if attrs: - raise OptionError( - "invalid keyword arguments: %s" % ", ".join(attrs.keys()), - self) - - - # -- Constructor validation methods -------------------------------- - - def _check_action (self): - if self.action is None: - self.action = "store" - elif self.action not in self.ACTIONS: - raise OptionError("invalid action: %r" % self.action, self) - - def _check_type (self): - if self.type is None: - # XXX should factor out another class attr here: list of - # actions that *require* a type - if self.action in ("store", "append"): - if self.choices is not None: - # The "choices" attribute implies "choice" type. - self.type = "choice" - else: - # No type given? "string" is the most sensible default. - self.type = "string" - else: - if self.type not in self.TYPES: - raise OptionError("invalid option type: %r" % self.type, self) - if self.action not in self.TYPED_ACTIONS: - raise OptionError( - "must not supply a type for action %r" % self.action, self) - - def _check_choice(self): - if self.type == "choice": - if self.choices is None: - raise OptionError( - "must supply a list of choices for type 'choice'", self) - elif type(self.choices) not in (types.TupleType, types.ListType): - raise OptionError( - "choices must be a list of strings ('%s' supplied)" - % str(type(self.choices)).split("'")[1], self) - elif self.choices is not None: - raise OptionError( - "must not supply choices for type %r" % self.type, self) - - def _check_dest (self): - if self.action in self.STORE_ACTIONS and self.dest is None: - # No destination given, and we need one for this action. - # Glean a destination from the first long option string, - # or from the first short option string if no long options. - if self._long_opts: - # eg. "--foo-bar" -> "foo_bar" - self.dest = self._long_opts[0][2:].replace('-', '_') - else: - self.dest = self._short_opts[0][1] - - def _check_const (self): - if self.action != "store_const" and self.const is not None: - raise OptionError( - "'const' must not be supplied for action %r" % self.action, - self) - - def _check_nargs (self): - if self.action in self.TYPED_ACTIONS: - if self.nargs is None: - self.nargs = 1 - elif self.nargs is not None: - raise OptionError( - "'nargs' must not be supplied for action %r" % self.action, - self) - - def _check_callback (self): - if self.action == "callback": - if not callable(self.callback): - raise OptionError( - "callback not callable: %r" % self.callback, self) - if (self.callback_args is not None and - type(self.callback_args) is not types.TupleType): - raise OptionError( - "callback_args, if supplied, must be a tuple: not %r" - % self.callback_args, self) - if (self.callback_kwargs is not None and - type(self.callback_kwargs) is not types.DictType): - raise OptionError( - "callback_kwargs, if supplied, must be a dict: not %r" - % self.callback_kwargs, self) - else: - if self.callback is not None: - raise OptionError( - "callback supplied (%r) for non-callback option" - % self.callback, self) - if self.callback_args is not None: - raise OptionError( - "callback_args supplied for non-callback option", self) - if self.callback_kwargs is not None: - raise OptionError( - "callback_kwargs supplied for non-callback option", self) - - - CHECK_METHODS = [_check_action, - _check_type, - _check_choice, - _check_dest, - _check_const, - _check_nargs, - _check_callback] - - - # -- Miscellaneous methods ----------------------------------------- - - def __str__ (self): - return "/".join(self._short_opts + self._long_opts) - - def takes_value (self): - return self.type is not None - - - # -- Processing methods -------------------------------------------- - - def check_value (self, opt, value): - checker = self.TYPE_CHECKER.get(self.type) - if checker is None: - return value - else: - return checker(self, opt, value) - - def process (self, opt, value, values, parser): - - # First, convert the value(s) to the right type. Howl if any - # value(s) are bogus. - if value is not None: - if self.nargs == 1: - value = self.check_value(opt, value) - else: - value = tuple([self.check_value(opt, v) for v in value]) - - # And then take whatever action is expected of us. - # This is a separate method to make life easier for - # subclasses to add new actions. - return self.take_action( - self.action, self.dest, opt, value, values, parser) - - def take_action (self, action, dest, opt, value, values, parser): - if action == "store": - setattr(values, dest, value) - elif action == "store_const": - setattr(values, dest, self.const) - elif action == "store_true": - setattr(values, dest, True) - elif action == "store_false": - setattr(values, dest, False) - elif action == "append": - values.ensure_value(dest, []).append(value) - elif action == "count": - setattr(values, dest, values.ensure_value(dest, 0) + 1) - elif action == "callback": - args = self.callback_args or () - kwargs = self.callback_kwargs or {} - self.callback(self, opt, value, parser, *args, **kwargs) - elif action == "help": - parser.print_help() - sys.exit(0) - elif action == "version": - parser.print_version() - sys.exit(0) - else: - raise RuntimeError, "unknown action %r" % self.action - - return 1 - -# class Option - - -SUPPRESS_HELP = "SUPPRESS"+"HELP" -SUPPRESS_USAGE = "SUPPRESS"+"USAGE" - - -class Values: - - def __init__ (self, defaults=None): - if defaults: - for (attr, val) in defaults.items(): - setattr(self, attr, val) - - def __repr__ (self): - return ("<%s at 0x%x: %r>" - % (self.__class__.__name__, id(self), self.__dict__)) - - def _update_careful (self, dict): - """ - Update the option values from an arbitrary dictionary, but only - use keys from dict that already have a corresponding attribute - in self. Any keys in dict without a corresponding attribute - are silently ignored. - """ - for attr in dir(self): - if dict.has_key(attr): - dval = dict[attr] - if dval is not None: - setattr(self, attr, dval) - - def _update_loose (self, dict): - """ - Update the option values from an arbitrary dictionary, - using all keys from the dictionary regardless of whether - they have a corresponding attribute in self or not. - """ - self.__dict__.update(dict) - - def _update (self, dict, mode): - if mode == "careful": - self._update_careful(dict) - elif mode == "loose": - self._update_loose(dict) - else: - raise ValueError, "invalid update mode: %r" % mode - - def read_module (self, modname, mode="careful"): - __import__(modname) - mod = sys.modules[modname] - self._update(vars(mod), mode) - - def read_file (self, filename, mode="careful"): - vars = {} - execfile(filename, vars) - self._update(vars, mode) - - def ensure_value (self, attr, value): - if not hasattr(self, attr) or getattr(self, attr) is None: - setattr(self, attr, value) - return getattr(self, attr) - - -class OptionContainer: - - """ - Abstract base class. - - Class attributes: - standard_option_list : [Option] - list of standard options that will be accepted by all instances - of this parser class (intended to be overridden by subclasses). - - Instance attributes: - option_list : [Option] - the list of Option objects contained by this OptionContainer - _short_opt : { string : Option } - dictionary mapping short option strings, eg. "-f" or "-X", - to the Option instances that implement them. If an Option - has multiple short option strings, it will appears in this - dictionary multiple times. [1] - _long_opt : { string : Option } - dictionary mapping long option strings, eg. "--file" or - "--exclude", to the Option instances that implement them. - Again, a given Option can occur multiple times in this - dictionary. [1] - defaults : { string : any } - dictionary mapping option destination names to default - values for each destination [1] - - [1] These mappings are common to (shared by) all components of the - controlling OptionParser, where they are initially created. - - """ - - def __init__ (self, option_class, conflict_handler, description): - # Initialize the option list and related data structures. - # This method must be provided by subclasses, and it must - # initialize at least the following instance attributes: - # option_list, _short_opt, _long_opt, defaults. - self._create_option_list() - - self.option_class = option_class - self.set_conflict_handler(conflict_handler) - self.set_description(description) - - def _create_option_mappings (self): - # For use by OptionParser constructor -- create the master - # option mappings used by this OptionParser and all - # OptionGroups that it owns. - self._short_opt = {} # single letter -> Option instance - self._long_opt = {} # long option -> Option instance - self.defaults = {} # maps option dest -> default value - - - def _share_option_mappings (self, parser): - # For use by OptionGroup constructor -- use shared option - # mappings from the OptionParser that owns this OptionGroup. - self._short_opt = parser._short_opt - self._long_opt = parser._long_opt - self.defaults = parser.defaults - - def set_conflict_handler (self, handler): - if handler not in ("ignore", "error", "resolve"): - raise ValueError, "invalid conflict_resolution value %r" % handler - self.conflict_handler = handler - - def set_description (self, description): - self.description = description - - - # -- Option-adding methods ----------------------------------------- - - def _check_conflict (self, option): - conflict_opts = [] - for opt in option._short_opts: - if self._short_opt.has_key(opt): - conflict_opts.append((opt, self._short_opt[opt])) - for opt in option._long_opts: - if self._long_opt.has_key(opt): - conflict_opts.append((opt, self._long_opt[opt])) - - if conflict_opts: - handler = self.conflict_handler - if handler == "ignore": # behaviour for Optik 1.0, 1.1 - pass - elif handler == "error": # new in 1.2 - raise OptionConflictError( - "conflicting option string(s): %s" - % ", ".join([co[0] for co in conflict_opts]), - option) - elif handler == "resolve": # new in 1.2 - for (opt, c_option) in conflict_opts: - if opt.startswith("--"): - c_option._long_opts.remove(opt) - del self._long_opt[opt] - else: - c_option._short_opts.remove(opt) - del self._short_opt[opt] - if not (c_option._short_opts or c_option._long_opts): - c_option.container.option_list.remove(c_option) - - def add_option (self, *args, **kwargs): - """add_option(Option) - add_option(opt_str, ..., kwarg=val, ...) - """ - if type(args[0]) is types.StringType: - option = self.option_class(*args, **kwargs) - elif len(args) == 1 and not kwargs: - option = args[0] - if not isinstance(option, Option): - raise TypeError, "not an Option instance: %r" % option - else: - raise TypeError, "invalid arguments" - - self._check_conflict(option) - - self.option_list.append(option) - option.container = self - for opt in option._short_opts: - self._short_opt[opt] = option - for opt in option._long_opts: - self._long_opt[opt] = option - - if option.dest is not None: # option has a dest, we need a default - if option.default is not NO_DEFAULT: - self.defaults[option.dest] = option.default - elif not self.defaults.has_key(option.dest): - self.defaults[option.dest] = None - - return option - - def add_options (self, option_list): - for option in option_list: - self.add_option(option) - - # -- Option query/removal methods ---------------------------------- - - def get_option (self, opt_str): - return (self._short_opt.get(opt_str) or - self._long_opt.get(opt_str)) - - def has_option (self, opt_str): - return (self._short_opt.has_key(opt_str) or - self._long_opt.has_key(opt_str)) - - def remove_option (self, opt_str): - option = self._short_opt.get(opt_str) - if option is None: - option = self._long_opt.get(opt_str) - if option is None: - raise ValueError("no such option %r" % opt_str) - - for opt in option._short_opts: - del self._short_opt[opt] - for opt in option._long_opts: - del self._long_opt[opt] - option.container.option_list.remove(option) - - - # -- Help-formatting methods --------------------------------------- - - def format_option_help (self, formatter): - if not self.option_list: - return "" - result = [] - for option in self.option_list: - if not option.help is SUPPRESS_HELP: - result.append(formatter.format_option(option)) - return "".join(result) - - def format_description (self, formatter): - if self.description: - return formatter.format_description(self.description) - else: - return "" - - def format_help (self, formatter): - result = [] - if self.description: - result.append(self.format_description(formatter)) - if self.option_list: - result.append(self.format_option_help(formatter)) - return "\n".join(result) - - -class OptionGroup (OptionContainer): - - def __init__ (self, parser, title, description=None): - self.parser = parser - OptionContainer.__init__( - self, parser.option_class, parser.conflict_handler, description) - self.title = title - - def _create_option_list (self): - self.option_list = [] - self._share_option_mappings(self.parser) - - def set_title (self, title): - self.title = title - - # -- Help-formatting methods --------------------------------------- - - def format_help (self, formatter): - result = formatter.format_heading(self.title) - formatter.indent() - result += OptionContainer.format_help(self, formatter) - formatter.dedent() - return result - - -class OptionParser (OptionContainer): - - """ - Class attributes: - standard_option_list : [Option] - list of standard options that will be accepted by all instances - of this parser class (intended to be overridden by subclasses). - - Instance attributes: - usage : string - a usage string for your program. Before it is displayed - to the user, "%prog" will be expanded to the name of - your program (self.prog or os.path.basename(sys.argv[0])). - prog : string - the name of the current program (to override - os.path.basename(sys.argv[0])). - - allow_interspersed_args : boolean = true - if true, positional arguments may be interspersed with options. - Assuming -a and -b each take a single argument, the command-line - -ablah foo bar -bboo baz - will be interpreted the same as - -ablah -bboo -- foo bar baz - If this flag were false, that command line would be interpreted as - -ablah -- foo bar -bboo baz - -- ie. we stop processing options as soon as we see the first - non-option argument. (This is the tradition followed by - Python's getopt module, Perl's Getopt::Std, and other argument- - parsing libraries, but it is generally annoying to users.) - - rargs : [string] - the argument list currently being parsed. Only set when - parse_args() is active, and continually trimmed down as - we consume arguments. Mainly there for the benefit of - callback options. - largs : [string] - the list of leftover arguments that we have skipped while - parsing options. If allow_interspersed_args is false, this - list is always empty. - values : Values - the set of option values currently being accumulated. Only - set when parse_args() is active. Also mainly for callbacks. - - Because of the 'rargs', 'largs', and 'values' attributes, - OptionParser is not thread-safe. If, for some perverse reason, you - need to parse command-line arguments simultaneously in different - threads, use different OptionParser instances. - - """ - - standard_option_list = [] - - def __init__ (self, - usage=None, - option_list=None, - option_class=Option, - version=None, - conflict_handler="error", - description=None, - formatter=None, - add_help_option=1, - prog=None): - OptionContainer.__init__( - self, option_class, conflict_handler, description) - self.set_usage(usage) - self.prog = prog - self.version = version - self.allow_interspersed_args = 1 - if formatter is None: - formatter = IndentedHelpFormatter() - self.formatter = formatter - - # Populate the option list; initial sources are the - # standard_option_list class attribute, the 'option_list' - # argument, and (if applicable) the _add_version_option() and - # _add_help_option() methods. - self._populate_option_list(option_list, - add_help=add_help_option) - - self._init_parsing_state() - - # -- Private methods ----------------------------------------------- - # (used by our or OptionContainer's constructor) - - def _create_option_list (self): - self.option_list = [] - self.option_groups = [] - self._create_option_mappings() - - def _add_help_option (self): - self.add_option("-h", "--help", - action="help", - help="show this help message and exit") - - def _add_version_option (self): - self.add_option("--version", - action="version", - help="show program's version number and exit") - - def _populate_option_list (self, option_list, add_help=1): - if self.standard_option_list: - self.add_options(self.standard_option_list) - if option_list: - self.add_options(option_list) - if self.version: - self._add_version_option() - if add_help: - self._add_help_option() - - def _init_parsing_state (self): - # These are set in parse_args() for the convenience of callbacks. - self.rargs = None - self.largs = None - self.values = None - - - # -- Simple modifier methods --------------------------------------- - - def set_usage (self, usage): - if usage is None: - self.usage = "%prog [options]" - elif usage is SUPPRESS_USAGE: - self.usage = None - elif usage.startswith("usage: "): - # for backwards compatibility with Optik 1.3 and earlier - self.usage = usage[7:] - else: - self.usage = usage - - def enable_interspersed_args (self): - self.allow_interspersed_args = 1 - - def disable_interspersed_args (self): - self.allow_interspersed_args = 0 - - def set_default (self, dest, value): - self.defaults[dest] = value - - def set_defaults (self, **kwargs): - self.defaults.update(kwargs) - - def get_default_values (self): - return Values(self.defaults) - - - # -- OptionGroup methods ------------------------------------------- - - def add_option_group (self, *args, **kwargs): - # XXX lots of overlap with OptionContainer.add_option() - if type(args[0]) is types.StringType: - group = OptionGroup(self, *args, **kwargs) - elif len(args) == 1 and not kwargs: - group = args[0] - if not isinstance(group, OptionGroup): - raise TypeError, "not an OptionGroup instance: %r" % group - if group.parser is not self: - raise ValueError, "invalid OptionGroup (wrong parser)" - else: - raise TypeError, "invalid arguments" - - self.option_groups.append(group) - return group - - def get_option_group (self, opt_str): - option = (self._short_opt.get(opt_str) or - self._long_opt.get(opt_str)) - if option and option.container is not self: - return option.container - return None - - - # -- Option-parsing methods ---------------------------------------- - - def _get_args (self, args): - if args is None: - return sys.argv[1:] - else: - return args[:] # don't modify caller's list - - def parse_args (self, args=None, values=None): - """ - parse_args(args : [string] = sys.argv[1:], - values : Values = None) - -> (values : Values, args : [string]) - - Parse the command-line options found in 'args' (default: - sys.argv[1:]). Any errors result in a call to 'error()', which - by default prints the usage message to stderr and calls - sys.exit() with an error message. On success returns a pair - (values, args) where 'values' is an Values instance (with all - your option values) and 'args' is the list of arguments left - over after parsing options. - """ - rargs = self._get_args(args) - if values is None: - values = self.get_default_values() - - # Store the halves of the argument list as attributes for the - # convenience of callbacks: - # rargs - # the rest of the command-line (the "r" stands for - # "remaining" or "right-hand") - # largs - # the leftover arguments -- ie. what's left after removing - # options and their arguments (the "l" stands for "leftover" - # or "left-hand") - self.rargs = rargs - self.largs = largs = [] - self.values = values - - try: - stop = self._process_args(largs, rargs, values) - except (BadOptionError, OptionValueError), err: - self.error(err.msg) - - args = largs + rargs - return self.check_values(values, args) - - def check_values (self, values, args): - """ - check_values(values : Values, args : [string]) - -> (values : Values, args : [string]) - - Check that the supplied option values and leftover arguments are - valid. Returns the option values and leftover arguments - (possibly adjusted, possibly completely new -- whatever you - like). Default implementation just returns the passed-in - values; subclasses may override as desired. - """ - return (values, args) - - def _process_args (self, largs, rargs, values): - """_process_args(largs : [string], - rargs : [string], - values : Values) - - Process command-line arguments and populate 'values', consuming - options and arguments from 'rargs'. If 'allow_interspersed_args' is - false, stop at the first non-option argument. If true, accumulate any - interspersed non-option arguments in 'largs'. - """ - while rargs: - arg = rargs[0] - # We handle bare "--" explicitly, and bare "-" is handled by the - # standard arg handler since the short arg case ensures that the - # len of the opt string is greater than 1. - if arg == "--": - del rargs[0] - return - elif arg[0:2] == "--": - # process a single long option (possibly with value(s)) - self._process_long_opt(rargs, values) - elif arg[:1] == "-" and len(arg) > 1: - # process a cluster of short options (possibly with - # value(s) for the last one only) - self._process_short_opts(rargs, values) - elif self.allow_interspersed_args: - largs.append(arg) - del rargs[0] - else: - return # stop now, leave this arg in rargs - - # Say this is the original argument list: - # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)] - # ^ - # (we are about to process arg(i)). - # - # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of - # [arg0, ..., arg(i-1)] (any options and their arguments will have - # been removed from largs). - # - # The while loop will usually consume 1 or more arguments per pass. - # If it consumes 1 (eg. arg is an option that takes no arguments), - # then after _process_arg() is done the situation is: - # - # largs = subset of [arg0, ..., arg(i)] - # rargs = [arg(i+1), ..., arg(N-1)] - # - # If allow_interspersed_args is false, largs will always be - # *empty* -- still a subset of [arg0, ..., arg(i-1)], but - # not a very interesting subset! - - def _match_long_opt (self, opt): - """_match_long_opt(opt : string) -> string - - Determine which long option string 'opt' matches, ie. which one - it is an unambiguous abbrevation for. Raises BadOptionError if - 'opt' doesn't unambiguously match any long option string. - """ - return _match_abbrev(opt, self._long_opt) - - def _process_long_opt (self, rargs, values): - arg = rargs.pop(0) - - # Value explicitly attached to arg? Pretend it's the next - # argument. - if "=" in arg: - (opt, next_arg) = arg.split("=", 1) - rargs.insert(0, next_arg) - had_explicit_value = 1 - else: - opt = arg - had_explicit_value = 0 - - opt = self._match_long_opt(opt) - option = self._long_opt[opt] - if option.takes_value(): - nargs = option.nargs - if len(rargs) < nargs: - if nargs == 1: - self.error("%s option requires a value" % opt) - else: - self.error("%s option requires %d values" - % (opt, nargs)) - elif nargs == 1: - value = rargs.pop(0) - else: - value = tuple(rargs[0:nargs]) - del rargs[0:nargs] - - elif had_explicit_value: - self.error("%s option does not take a value" % opt) - - else: - value = None - - option.process(opt, value, values, self) - - def _process_short_opts (self, rargs, values): - arg = rargs.pop(0) - stop = 0 - i = 1 - for ch in arg[1:]: - opt = "-" + ch - option = self._short_opt.get(opt) - i += 1 # we have consumed a character - - if not option: - self.error("no such option: %s" % opt) - if option.takes_value(): - # Any characters left in arg? Pretend they're the - # next arg, and stop consuming characters of arg. - if i < len(arg): - rargs.insert(0, arg[i:]) - stop = 1 - - nargs = option.nargs - if len(rargs) < nargs: - if nargs == 1: - self.error("%s option requires a value" % opt) - else: - self.error("%s option requires %s values" - % (opt, nargs)) - elif nargs == 1: - value = rargs.pop(0) - else: - value = tuple(rargs[0:nargs]) - del rargs[0:nargs] - - else: # option doesn't take a value - value = None - - option.process(opt, value, values, self) - - if stop: - break - - - # -- Feedback methods ---------------------------------------------- - - def get_prog_name (self): - if self.prog is None: - return os.path.basename(sys.argv[0]) - else: - return self.prog - - def error (self, msg): - """error(msg : string) - - Print a usage message incorporating 'msg' to stderr and exit. - If you override this in a subclass, it should not return -- it - should either exit or raise an exception. - """ - self.print_usage(sys.stderr) - sys.stderr.write("%s: error: %s\n" % (self.get_prog_name(), msg)) - sys.exit(2) # command-line usage error - - def get_usage (self): - if self.usage: - return self.formatter.format_usage( - self.usage.replace("%prog", self.get_prog_name())) - else: - return "" - - def print_usage (self, file=None): - """print_usage(file : file = stdout) - - Print the usage message for the current program (self.usage) to - 'file' (default stdout). Any occurence of the string "%prog" in - self.usage is replaced with the name of the current program - (basename of sys.argv[0]). Does nothing if self.usage is empty - or not defined. - """ - if self.usage: - print >>file, self.get_usage() - - def get_version (self): - if self.version: - return self.version.replace("%prog", self.get_prog_name()) - else: - return "" - - def print_version (self, file=None): - """print_version(file : file = stdout) - - Print the version message for this program (self.version) to - 'file' (default stdout). As with print_usage(), any occurence - of "%prog" in self.version is replaced by the current program's - name. Does nothing if self.version is empty or undefined. - """ - if self.version: - print >>file, self.get_version() - - def format_option_help (self, formatter=None): - if formatter is None: - formatter = self.formatter - formatter.store_option_strings(self) - result = [] - result.append(formatter.format_heading("Options")) - formatter.indent() - if self.option_list: - result.append(OptionContainer.format_option_help(self, formatter)) - result.append("\n") - for group in self.option_groups: - result.append(group.format_help(formatter)) - result.append("\n") - formatter.dedent() - # Drop the last "\n", or the header if no options or option groups: - return "".join(result[:-1]) - - def format_help (self, formatter=None): - if formatter is None: - formatter = self.formatter - result = [] - if self.usage: - result.append(self.get_usage() + "\n") - if self.description: - result.append(self.format_description(formatter) + "\n") - result.append(self.format_option_help(formatter)) - return "".join(result) - - def print_help (self, file=None): - """print_help(file : file = stdout) - - Print an extended help message, listing all options and any - help text provided with them, to 'file' (default stdout). - """ - if file is None: - file = sys.stdout - file.write(self.format_help()) - -# class OptionParser - - -def _match_abbrev (s, wordmap): - """_match_abbrev(s : string, wordmap : {string : Option}) -> string - - Return the string key in 'wordmap' for which 's' is an unambiguous - abbreviation. If 's' is found to be ambiguous or doesn't match any of - 'words', raise BadOptionError. - """ - # Is there an exact match? - if wordmap.has_key(s): - return s - else: - # Isolate all words with s as a prefix. - possibilities = [word for word in wordmap.keys() - if word.startswith(s)] - # No exact match, so there had better be just one possibility. - if len(possibilities) == 1: - return possibilities[0] - elif not possibilities: - raise BadOptionError("no such option: %s" % s) - else: - # More than one possible completion: ambiguous prefix. - raise BadOptionError("ambiguous option: %s (%s?)" - % (s, ", ".join(possibilities))) - - -# Some day, there might be many Option classes. As of Optik 1.3, the -# preferred way to instantiate Options is indirectly, via make_option(), -# which will become a factory function when there are many Option -# classes. -make_option = Option diff --git a/docutils/extras/roman.py b/docutils/extras/roman.py deleted file mode 100644 index ebe088308..000000000 --- a/docutils/extras/roman.py +++ /dev/null @@ -1,81 +0,0 @@ -"""Convert to and from Roman numerals""" - -__author__ = "Mark Pilgrim (f8dy@diveintopython.org)" -__version__ = "1.4" -__date__ = "8 August 2001" -__copyright__ = """Copyright (c) 2001 Mark Pilgrim - -This program is part of "Dive Into Python", a free Python tutorial for -experienced programmers. Visit http://diveintopython.org/ for the -latest version. - -This program is free software; you can redistribute it and/or modify -it under the terms of the Python 2.1.1 license, available at -http://www.python.org/2.1.1/license.html -""" - -import re - -#Define exceptions -class RomanError(Exception): pass -class OutOfRangeError(RomanError): pass -class NotIntegerError(RomanError): pass -class InvalidRomanNumeralError(RomanError): pass - -#Define digit mapping -romanNumeralMap = (('M', 1000), - ('CM', 900), - ('D', 500), - ('CD', 400), - ('C', 100), - ('XC', 90), - ('L', 50), - ('XL', 40), - ('X', 10), - ('IX', 9), - ('V', 5), - ('IV', 4), - ('I', 1)) - -def toRoman(n): - """convert integer to Roman numeral""" - if not (0 < n < 5000): - raise OutOfRangeError, "number out of range (must be 1..4999)" - if int(n) <> n: - raise NotIntegerError, "decimals can not be converted" - - result = "" - for numeral, integer in romanNumeralMap: - while n >= integer: - result += numeral - n -= integer - return result - -#Define pattern to detect valid Roman numerals -romanNumeralPattern = re.compile(""" - ^ # beginning of string - M{0,4} # thousands - 0 to 4 M's - (CM|CD|D?C{0,3}) # hundreds - 900 (CM), 400 (CD), 0-300 (0 to 3 C's), - # or 500-800 (D, followed by 0 to 3 C's) - (XC|XL|L?X{0,3}) # tens - 90 (XC), 40 (XL), 0-30 (0 to 3 X's), - # or 50-80 (L, followed by 0 to 3 X's) - (IX|IV|V?I{0,3}) # ones - 9 (IX), 4 (IV), 0-3 (0 to 3 I's), - # or 5-8 (V, followed by 0 to 3 I's) - $ # end of string - """ ,re.VERBOSE) - -def fromRoman(s): - """convert Roman numeral to integer""" - if not s: - raise InvalidRomanNumeralError, 'Input can not be blank' - if not romanNumeralPattern.search(s): - raise InvalidRomanNumeralError, 'Invalid Roman numeral: %s' % s - - result = 0 - index = 0 - for numeral, integer in romanNumeralMap: - while s[index:index+len(numeral)] == numeral: - result += integer - index += len(numeral) - return result - diff --git a/docutils/extras/textwrap.py b/docutils/extras/textwrap.py deleted file mode 100644 index 6bafc8ffc..000000000 --- a/docutils/extras/textwrap.py +++ /dev/null @@ -1,356 +0,0 @@ -"""Text wrapping and filling. -""" - -# Copyright (C) 1999-2001 Gregory P. Ward. -# Copyright (C) 2002, 2003 Python Software Foundation. -# Written by Greg Ward <gward@python.net> - -__revision__ = "$Id$" - -import string, re -import types - -# Do the right thing with boolean values for all known Python versions -# (so this module can be copied to projects that don't depend on Python -# 2.3, e.g. Optik and Docutils). -try: - True, False -except NameError: - (True, False) = (1, 0) - -__all__ = ['TextWrapper', 'wrap', 'fill'] - -# Hardcode the recognized whitespace characters to the US-ASCII -# whitespace characters. The main reason for doing this is that in -# ISO-8859-1, 0xa0 is non-breaking whitespace, so in certain locales -# that character winds up in string.whitespace. Respecting -# string.whitespace in those cases would 1) make textwrap treat 0xa0 the -# same as any other whitespace char, which is clearly wrong (it's a -# *non-breaking* space), 2) possibly cause problems with Unicode, -# since 0xa0 is not in range(128). -_whitespace = '\t\n\x0b\x0c\r ' - -class TextWrapper: - """ - Object for wrapping/filling text. The public interface consists of - the wrap() and fill() methods; the other methods are just there for - subclasses to override in order to tweak the default behaviour. - If you want to completely replace the main wrapping algorithm, - you'll probably have to override _wrap_chunks(). - - Several instance attributes control various aspects of wrapping: - width (default: 70) - the maximum width of wrapped lines (unless break_long_words - is false) - initial_indent (default: "") - string that will be prepended to the first line of wrapped - output. Counts towards the line's width. - subsequent_indent (default: "") - string that will be prepended to all lines save the first - of wrapped output; also counts towards each line's width. - expand_tabs (default: true) - Expand tabs in input text to spaces before further processing. - Each tab will become 1 .. 8 spaces, depending on its position in - its line. If false, each tab is treated as a single character. - replace_whitespace (default: true) - Replace all whitespace characters in the input text by spaces - after tab expansion. Note that if expand_tabs is false and - replace_whitespace is true, every tab will be converted to a - single space! - fix_sentence_endings (default: false) - Ensure that sentence-ending punctuation is always followed - by two spaces. Off by default because the algorithm is - (unavoidably) imperfect. - break_long_words (default: true) - Break words longer than 'width'. If false, those words will not - be broken, and some lines might be longer than 'width'. - """ - - whitespace_trans = string.maketrans(_whitespace, ' ' * len(_whitespace)) - - unicode_whitespace_trans = {} - uspace = ord(u' ') - for x in map(ord, _whitespace): - unicode_whitespace_trans[x] = uspace - - # This funky little regex is just the trick for splitting - # text up into word-wrappable chunks. E.g. - # "Hello there -- you goof-ball, use the -b option!" - # splits into - # Hello/ /there/ /--/ /you/ /goof-/ball,/ /use/ /the/ /-b/ /option! - # (after stripping out empty strings). - wordsep_re = re.compile(r'(\s+|' # any whitespace - r'-*\w{2,}-(?=\w{2,})|' # hyphenated words - r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))') # em-dash - - # XXX will there be a locale-or-charset-aware version of - # string.lowercase in 2.3? - sentence_end_re = re.compile(r'[%s]' # lowercase letter - r'[\.\!\?]' # sentence-ending punct. - r'[\"\']?' # optional end-of-quote - % string.lowercase) - - - def __init__ (self, - width=70, - initial_indent="", - subsequent_indent="", - expand_tabs=True, - replace_whitespace=True, - fix_sentence_endings=False, - break_long_words=True): - self.width = width - self.initial_indent = initial_indent - self.subsequent_indent = subsequent_indent - self.expand_tabs = expand_tabs - self.replace_whitespace = replace_whitespace - self.fix_sentence_endings = fix_sentence_endings - self.break_long_words = break_long_words - - - # -- Private methods ----------------------------------------------- - # (possibly useful for subclasses to override) - - def _munge_whitespace(self, text): - """_munge_whitespace(text : string) -> string - - Munge whitespace in text: expand tabs and convert all other - whitespace characters to spaces. Eg. " foo\tbar\n\nbaz" - becomes " foo bar baz". - """ - if self.expand_tabs: - text = text.expandtabs() - if self.replace_whitespace: - if isinstance(text, types.StringType): - text = text.translate(self.whitespace_trans) - elif isinstance(text, types.UnicodeType): - text = text.translate(self.unicode_whitespace_trans) - return text - - - def _split(self, text): - """_split(text : string) -> [string] - - Split the text to wrap into indivisible chunks. Chunks are - not quite the same as words; see wrap_chunks() for full - details. As an example, the text - Look, goof-ball -- use the -b option! - breaks into the following chunks: - 'Look,', ' ', 'goof-', 'ball', ' ', '--', ' ', - 'use', ' ', 'the', ' ', '-b', ' ', 'option!' - """ - chunks = self.wordsep_re.split(text) - chunks = filter(None, chunks) - return chunks - - def _fix_sentence_endings(self, chunks): - """_fix_sentence_endings(chunks : [string]) - - Correct for sentence endings buried in 'chunks'. Eg. when the - original text contains "... foo.\nBar ...", munge_whitespace() - and split() will convert that to [..., "foo.", " ", "Bar", ...] - which has one too few spaces; this method simply changes the one - space to two. - """ - i = 0 - pat = self.sentence_end_re - while i < len(chunks)-1: - if chunks[i+1] == " " and pat.search(chunks[i]): - chunks[i+1] = " " - i += 2 - else: - i += 1 - - def _handle_long_word(self, chunks, cur_line, cur_len, width): - """_handle_long_word(chunks : [string], - cur_line : [string], - cur_len : int, width : int) - - Handle a chunk of text (most likely a word, not whitespace) that - is too long to fit in any line. - """ - space_left = width - cur_len - - # If we're allowed to break long words, then do so: put as much - # of the next chunk onto the current line as will fit. - if self.break_long_words: - cur_line.append(chunks[0][0:space_left]) - chunks[0] = chunks[0][space_left:] - - # Otherwise, we have to preserve the long word intact. Only add - # it to the current line if there's nothing already there -- - # that minimizes how much we violate the width constraint. - elif not cur_line: - cur_line.append(chunks.pop(0)) - - # If we're not allowed to break long words, and there's already - # text on the current line, do nothing. Next time through the - # main loop of _wrap_chunks(), we'll wind up here again, but - # cur_len will be zero, so the next line will be entirely - # devoted to the long word that we can't handle right now. - - def _wrap_chunks(self, chunks): - """_wrap_chunks(chunks : [string]) -> [string] - - Wrap a sequence of text chunks and return a list of lines of - length 'self.width' or less. (If 'break_long_words' is false, - some lines may be longer than this.) Chunks correspond roughly - to words and the whitespace between them: each chunk is - indivisible (modulo 'break_long_words'), but a line break can - come between any two chunks. Chunks should not have internal - whitespace; ie. a chunk is either all whitespace or a "word". - Whitespace chunks will be removed from the beginning and end of - lines, but apart from that whitespace is preserved. - """ - lines = [] - if self.width <= 0: - raise ValueError("invalid width %r (must be > 0)" % self.width) - - while chunks: - - # Start the list of chunks that will make up the current line. - # cur_len is just the length of all the chunks in cur_line. - cur_line = [] - cur_len = 0 - - # Figure out which static string will prefix this line. - if lines: - indent = self.subsequent_indent - else: - indent = self.initial_indent - - # Maximum width for this line. - width = self.width - len(indent) - - # First chunk on line is whitespace -- drop it, unless this - # is the very beginning of the text (ie. no lines started yet). - if chunks[0].strip() == '' and lines: - del chunks[0] - - while chunks: - l = len(chunks[0]) - - # Can at least squeeze this chunk onto the current line. - if cur_len + l <= width: - cur_line.append(chunks.pop(0)) - cur_len += l - - # Nope, this line is full. - else: - break - - # The current line is full, and the next chunk is too big to - # fit on *any* line (not just this one). - if chunks and len(chunks[0]) > width: - self._handle_long_word(chunks, cur_line, cur_len, width) - - # If the last chunk on this line is all whitespace, drop it. - if cur_line and cur_line[-1].strip() == '': - del cur_line[-1] - - # Convert current line back to a string and store it in list - # of all lines (return value). - if cur_line: - lines.append(indent + ''.join(cur_line)) - - return lines - - - # -- Public interface ---------------------------------------------- - - def wrap(self, text): - """wrap(text : string) -> [string] - - Reformat the single paragraph in 'text' so it fits in lines of - no more than 'self.width' columns, and return a list of wrapped - lines. Tabs in 'text' are expanded with string.expandtabs(), - and all other whitespace characters (including newline) are - converted to space. - """ - text = self._munge_whitespace(text) - indent = self.initial_indent - if len(text) + len(indent) <= self.width: - return [indent + text] - chunks = self._split(text) - if self.fix_sentence_endings: - self._fix_sentence_endings(chunks) - return self._wrap_chunks(chunks) - - def fill(self, text): - """fill(text : string) -> string - - Reformat the single paragraph in 'text' to fit in lines of no - more than 'self.width' columns, and return a new string - containing the entire wrapped paragraph. - """ - return "\n".join(self.wrap(text)) - - -# -- Convenience interface --------------------------------------------- - -def wrap(text, width=70, **kwargs): - """Wrap a single paragraph of text, returning a list of wrapped lines. - - Reformat the single paragraph in 'text' so it fits in lines of no - more than 'width' columns, and return a list of wrapped lines. By - default, tabs in 'text' are expanded with string.expandtabs(), and - all other whitespace characters (including newline) are converted to - space. See TextWrapper class for available keyword args to customize - wrapping behaviour. - """ - w = TextWrapper(width=width, **kwargs) - return w.wrap(text) - -def fill(text, width=70, **kwargs): - """Fill a single paragraph of text, returning a new string. - - Reformat the single paragraph in 'text' to fit in lines of no more - than 'width' columns, and return a new string containing the entire - wrapped paragraph. As with wrap(), tabs are expanded and other - whitespace characters converted to space. See TextWrapper class for - available keyword args to customize wrapping behaviour. - """ - w = TextWrapper(width=width, **kwargs) - return w.fill(text) - - -# -- Loosely related functionality ------------------------------------- - -def dedent(text): - """dedent(text : string) -> string - - Remove any whitespace than can be uniformly removed from the left - of every line in `text`. - - This can be used e.g. to make triple-quoted strings line up with - the left edge of screen/whatever, while still presenting it in the - source code in indented form. - - For example: - - def test(): - # end first line with \ to avoid the empty line! - s = '''\ - hello - world - ''' - print repr(s) # prints ' hello\n world\n ' - print repr(dedent(s)) # prints 'hello\n world\n' - """ - lines = text.expandtabs().split('\n') - margin = None - for line in lines: - content = line.lstrip() - if not content: - continue - indent = len(line) - len(content) - if margin is None: - margin = indent - else: - margin = min(margin, indent) - - if margin is not None and margin > 0: - for i in range(len(lines)): - lines[i] = lines[i][margin:] - - return '\n'.join(lines) diff --git a/docutils/docutils/frontend.py b/docutils/frontend.py index 46fcaab89..46fcaab89 100644 --- a/docutils/docutils/frontend.py +++ b/docutils/frontend.py diff --git a/docutils/install.py b/docutils/install.py deleted file mode 100755 index 1a71e433f..000000000 --- a/docutils/install.py +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env python -# $Id$ -# Copyright: This file has been placed in the public domain. - -""" -This is a quick & dirty installation shortcut. It is equivalent to the -command:: - - python setup.py install - -However, the shortcut lacks error checking and command-line option -processing. If you need any kind of customization or help, please use -one of:: - - python setup.py install --help - python setup.py --help -""" - -from distutils import core -from setup import do_setup - -if __name__ == '__main__' : - print __doc__ - core._setup_stop_after = 'config' - dist = do_setup() - dist.commands = ['install'] - dist.run_commands() diff --git a/docutils/docutils/io.py b/docutils/io.py index 5a6672e15..5a6672e15 100644 --- a/docutils/docutils/io.py +++ b/docutils/io.py diff --git a/docutils/docutils/languages/__init__.py b/docutils/languages/__init__.py index 018c880c4..018c880c4 100644 --- a/docutils/docutils/languages/__init__.py +++ b/docutils/languages/__init__.py diff --git a/docutils/docutils/languages/af.py b/docutils/languages/af.py index 1071b4469..1071b4469 100644 --- a/docutils/docutils/languages/af.py +++ b/docutils/languages/af.py diff --git a/docutils/docutils/languages/ca.py b/docutils/languages/ca.py index 069a853b3..069a853b3 100644 --- a/docutils/docutils/languages/ca.py +++ b/docutils/languages/ca.py diff --git a/docutils/docutils/languages/cs.py b/docutils/languages/cs.py index 94d4b70a1..94d4b70a1 100644 --- a/docutils/docutils/languages/cs.py +++ b/docutils/languages/cs.py diff --git a/docutils/docutils/languages/de.py b/docutils/languages/de.py index 3a829dd34..3a829dd34 100644 --- a/docutils/docutils/languages/de.py +++ b/docutils/languages/de.py diff --git a/docutils/docutils/languages/en.py b/docutils/languages/en.py index 3b39c486f..3b39c486f 100644 --- a/docutils/docutils/languages/en.py +++ b/docutils/languages/en.py diff --git a/docutils/docutils/languages/eo.py b/docutils/languages/eo.py index 32a1be4b1..32a1be4b1 100644 --- a/docutils/docutils/languages/eo.py +++ b/docutils/languages/eo.py diff --git a/docutils/docutils/languages/es.py b/docutils/languages/es.py index 7e3eb9b75..7e3eb9b75 100644 --- a/docutils/docutils/languages/es.py +++ b/docutils/languages/es.py diff --git a/docutils/docutils/languages/fi.py b/docutils/languages/fi.py index 340b33acb..340b33acb 100644 --- a/docutils/docutils/languages/fi.py +++ b/docutils/languages/fi.py diff --git a/docutils/docutils/languages/fr.py b/docutils/languages/fr.py index 33723befa..33723befa 100644 --- a/docutils/docutils/languages/fr.py +++ b/docutils/languages/fr.py diff --git a/docutils/docutils/languages/it.py b/docutils/languages/it.py index fa40afa83..fa40afa83 100644 --- a/docutils/docutils/languages/it.py +++ b/docutils/languages/it.py diff --git a/docutils/docutils/languages/ja.py b/docutils/languages/ja.py index dfa5ca076..dfa5ca076 100644 --- a/docutils/docutils/languages/ja.py +++ b/docutils/languages/ja.py diff --git a/docutils/docutils/languages/nl.py b/docutils/languages/nl.py index ca96d78d9..ca96d78d9 100644 --- a/docutils/docutils/languages/nl.py +++ b/docutils/languages/nl.py diff --git a/docutils/docutils/languages/pt_br.py b/docutils/languages/pt_br.py index 5d2df0e82..5d2df0e82 100644 --- a/docutils/docutils/languages/pt_br.py +++ b/docutils/languages/pt_br.py diff --git a/docutils/docutils/languages/ru.py b/docutils/languages/ru.py index 369d2febd..369d2febd 100644 --- a/docutils/docutils/languages/ru.py +++ b/docutils/languages/ru.py diff --git a/docutils/docutils/languages/sk.py b/docutils/languages/sk.py index bb5cf089a..bb5cf089a 100644 --- a/docutils/docutils/languages/sk.py +++ b/docutils/languages/sk.py diff --git a/docutils/docutils/languages/sv.py b/docutils/languages/sv.py index 275b3569a..275b3569a 100644 --- a/docutils/docutils/languages/sv.py +++ b/docutils/languages/sv.py diff --git a/docutils/docutils/languages/zh_cn.py b/docutils/languages/zh_cn.py index 4f8e06ee8..4f8e06ee8 100644 --- a/docutils/docutils/languages/zh_cn.py +++ b/docutils/languages/zh_cn.py diff --git a/docutils/docutils/languages/zh_tw.py b/docutils/languages/zh_tw.py index 12570cfba..12570cfba 100644 --- a/docutils/docutils/languages/zh_tw.py +++ b/docutils/languages/zh_tw.py diff --git a/docutils/licenses/docutils.conf b/docutils/licenses/docutils.conf deleted file mode 100644 index cdce8d629..000000000 --- a/docutils/licenses/docutils.conf +++ /dev/null @@ -1,5 +0,0 @@ -# This configuration file is to prevent tools/buildhtml.py from -# processing text files in and below this directory. - -[buildhtml application] -prune: . diff --git a/docutils/licenses/gpl.txt b/docutils/licenses/gpl.txt deleted file mode 100644 index 5b6e7c66c..000000000 --- a/docutils/licenses/gpl.txt +++ /dev/null @@ -1,340 +0,0 @@ - GNU GENERAL PUBLIC LICENSE - Version 2, June 1991 - - Copyright (C) 1989, 1991 Free Software Foundation, Inc. - 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software--to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - - GNU GENERAL PUBLIC LICENSE - TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION - - 0. This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The "Program", below, -refers to any such program or work, and a "work based on the Program" -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term "modification".) Each licensee is addressed as "you". - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - - 1. You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - - 2. You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - - a) You must cause the modified files to carry prominent notices - stating that you changed the files and the date of any change. - - b) You must cause any work that you distribute or publish, that in - whole or in part contains or is derived from the Program or any - part thereof, to be licensed as a whole at no charge to all third - parties under the terms of this License. - - c) If the modified program normally reads commands interactively - when run, you must cause it, when started running for such - interactive use in the most ordinary way, to print or display an - announcement including an appropriate copyright notice and a - notice that there is no warranty (or else, saying that you provide - a warranty) and that users may redistribute the program under - these conditions, and telling the user how to view a copy of this - License. (Exception: if the Program itself is interactive but - does not normally print such an announcement, your work based on - the Program is not required to print an announcement.) - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - - 3. You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - - a) Accompany it with the complete corresponding machine-readable - source code, which must be distributed under the terms of Sections - 1 and 2 above on a medium customarily used for software interchange; or, - - b) Accompany it with a written offer, valid for at least three - years, to give any third party, for a charge no more than your - cost of physically performing source distribution, a complete - machine-readable copy of the corresponding source code, to be - distributed under the terms of Sections 1 and 2 above on a medium - customarily used for software interchange; or, - - c) Accompany it with the information you received as to the offer - to distribute corresponding source code. (This alternative is - allowed only for noncommercial distribution and only if you - received the program in object code or executable form with such - an offer, in accord with Subsection b above.) - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - - 4. You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - - 5. You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - - 6. Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - - 7. If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - - 8. If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - - 9. The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and "any -later version", you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - - 10. If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - - NO WARRANTY - - 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - - 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - <one line to give the program's name and a brief idea of what it does.> - Copyright (C) <year> <name of author> - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - - Gnomovision version 69, Copyright (C) year name of author - Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, the commands you use may -be called something other than `show w' and `show c'; they could even be -mouse-clicks or menu items--whatever suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a "copyright disclaimer" for the program, if -necessary. Here is a sample; alter the names: - - Yoyodyne, Inc., hereby disclaims all copyright interest in the program - `Gnomovision' (which makes passes at compilers) written by James Hacker. - - <signature of Ty Coon>, 1 April 1989 - Ty Coon, President of Vice - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. diff --git a/docutils/licenses/python-2-1-1.txt b/docutils/licenses/python-2-1-1.txt deleted file mode 100644 index 7664787d1..000000000 --- a/docutils/licenses/python-2-1-1.txt +++ /dev/null @@ -1,232 +0,0 @@ -A. HISTORY OF THE SOFTWARE -========================== - -Python was created in the early 1990s by Guido van Rossum at Stichting -Mathematisch Centrum (CWI) in the Netherlands as a successor of a -language called ABC. Guido is Python's principal author, although it -includes many contributions from others. The last version released -from CWI was Python 1.2. In 1995, Guido continued his work on Python -at the Corporation for National Research Initiatives (CNRI) in Reston, -Virginia where he released several versions of the software. Python -1.6 was the last of the versions released by CNRI. In 2000, Guido and -the Python core development team moved to BeOpen.com to form the -BeOpen PythonLabs team. Python 2.0 was the first and only release -from BeOpen.com. - -Following the release of Python 1.6, and after Guido van Rossum left -CNRI to work with commercial software developers, it became clear that -the ability to use Python with software available under the GNU Public -License (GPL) was very desirable. CNRI and the Free Software -Foundation (FSF) interacted to develop enabling wording changes to the -Python license. Python 1.6.1 is essentially the same as Python 1.6, -with a few minor bug fixes, and with a different license that enables -later versions to be GPL-compatible. Python 2.1 is a derivative work -of Python 1.6.1, as well as of Python 2.0. - -After Python 2.0 was released by BeOpen.com, Guido van Rossum and the -other PythonLabs developers joined Digital Creations. All -intellectual property added from this point on, starting with Python -2.1 and its alpha and beta releases, is owned by the Python Software -Foundation (PSF), a non-profit modeled after the Apache Software -Foundation. See http://www.python.org/psf/ for more information about -the PSF. - -Thanks to the many outside volunteers who have worked under Guido's -direction to make these releases possible. - - -B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON -=============================================================== - -PSF LICENSE AGREEMENT ---------------------- - -1. This LICENSE AGREEMENT is between the Python Software Foundation -("PSF"), and the Individual or Organization ("Licensee") accessing and -otherwise using Python 2.1.1 software in source or binary form and its -associated documentation. - -2. Subject to the terms and conditions of this License Agreement, PSF -hereby grants Licensee a nonexclusive, royalty-free, world-wide -license to reproduce, analyze, test, perform and/or display publicly, -prepare derivative works, distribute, and otherwise use Python 2.1.1 -alone or in any derivative version, provided, however, that PSF's -License Agreement and PSF's notice of copyright, i.e., "Copyright (c) -2001 Python Software Foundation; All Rights Reserved" are retained in -Python 2.1.1 alone or in any derivative version prepared by Licensee. - -3. In the event Licensee prepares a derivative work that is based on -or incorporates Python 2.1.1 or any part thereof, and wants to make -the derivative work available to others as provided herein, then -Licensee hereby agrees to include in any such work a brief summary of -the changes made to Python 2.1.1. - -4. PSF is making Python 2.1.1 available to Licensee on an "AS IS" -basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.1.1 WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON -2.1.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS -A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.1.1, -OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -7. Nothing in this License Agreement shall be deemed to create any -relationship of agency, partnership, or joint venture between PSF and -Licensee. This License Agreement does not grant permission to use PSF -trademarks or trade name in a trademark sense to endorse or promote -products or services of Licensee, or any third party. - -8. By copying, installing or otherwise using Python 2.1.1, Licensee -agrees to be bound by the terms and conditions of this License -Agreement. - - -BEOPEN.COM TERMS AND CONDITIONS FOR PYTHON 2.0 ----------------------------------------------- - -BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 - -1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an -office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the -Individual or Organization ("Licensee") accessing and otherwise using -this software in source or binary form and its associated -documentation ("the Software"). - -2. Subject to the terms and conditions of this BeOpen Python License -Agreement, BeOpen hereby grants Licensee a non-exclusive, -royalty-free, world-wide license to reproduce, analyze, test, perform -and/or display publicly, prepare derivative works, distribute, and -otherwise use the Software alone or in any derivative version, -provided, however, that the BeOpen Python License is retained in the -Software, alone or in any derivative version prepared by Licensee. - -3. BeOpen is making the Software available to Licensee on an "AS IS" -basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE -SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS -AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY -DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -5. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -6. This License Agreement shall be governed by and interpreted in all -respects by the law of the State of California, excluding conflict of -law provisions. Nothing in this License Agreement shall be deemed to -create any relationship of agency, partnership, or joint venture -between BeOpen and Licensee. This License Agreement does not grant -permission to use BeOpen trademarks or trade names in a trademark -sense to endorse or promote products or services of Licensee, or any -third party. As an exception, the "BeOpen Python" logos available at -http://www.pythonlabs.com/logos.html may be used according to the -permissions granted on that web page. - -7. By copying, installing or otherwise using the software, Licensee -agrees to be bound by the terms and conditions of this License -Agreement. - - -CNRI OPEN SOURCE GPL-COMPATIBLE LICENSE AGREEMENT -------------------------------------------------- - -1. This LICENSE AGREEMENT is between the Corporation for National -Research Initiatives, having an office at 1895 Preston White Drive, -Reston, VA 20191 ("CNRI"), and the Individual or Organization -("Licensee") accessing and otherwise using Python 1.6.1 software in -source or binary form and its associated documentation. - -2. Subject to the terms and conditions of this License Agreement, CNRI -hereby grants Licensee a nonexclusive, royalty-free, world-wide -license to reproduce, analyze, test, perform and/or display publicly, -prepare derivative works, distribute, and otherwise use Python 1.6.1 -alone or in any derivative version, provided, however, that CNRI's -License Agreement and CNRI's notice of copyright, i.e., "Copyright (c) -1995-2001 Corporation for National Research Initiatives; All Rights -Reserved" are retained in Python 1.6.1 alone or in any derivative -version prepared by Licensee. Alternately, in lieu of CNRI's License -Agreement, Licensee may substitute the following text (omitting the -quotes): "Python 1.6.1 is made available subject to the terms and -conditions in CNRI's License Agreement. This Agreement together with -Python 1.6.1 may be located on the Internet using the following -unique, persistent identifier (known as a handle): 1895.22/1013. This -Agreement may also be obtained from a proxy server on the Internet -using the following URL: http://hdl.handle.net/1895.22/1013". - -3. In the event Licensee prepares a derivative work that is based on -or incorporates Python 1.6.1 or any part thereof, and wants to make -the derivative work available to others as provided herein, then -Licensee hereby agrees to include in any such work a brief summary of -the changes made to Python 1.6.1. - -4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" -basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON -1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS -A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, -OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -7. This License Agreement shall be governed by the federal -intellectual property law of the United States, including without -limitation the federal copyright law, and, to the extent such -U.S. federal law does not apply, by the law of the Commonwealth of -Virginia, excluding Virginia's conflict of law provisions. -Notwithstanding the foregoing, with regard to derivative works based -on Python 1.6.1 that incorporate non-separable material that was -previously distributed under the GNU General Public License (GPL), the -law of the Commonwealth of Virginia shall govern this License -Agreement only as to issues arising under or with respect to -Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this -License Agreement shall be deemed to create any relationship of -agency, partnership, or joint venture between CNRI and Licensee. This -License Agreement does not grant permission to use CNRI trademarks or -trade name in a trademark sense to endorse or promote products or -services of Licensee, or any third party. - -8. By clicking on the "ACCEPT" button where indicated, or by copying, -installing or otherwise using Python 1.6.1, Licensee agrees to be -bound by the terms and conditions of this License Agreement. - - ACCEPT - - -CWI PERMISSIONS STATEMENT AND DISCLAIMER ----------------------------------------- - -Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, -The Netherlands. All rights reserved. - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, -provided that the above copyright notice appear in all copies and that -both that copyright notice and this permission notice appear in -supporting documentation, and that the name of Stichting Mathematisch -Centrum or CWI not be used in advertising or publicity pertaining to -distribution of the software without specific, written prior -permission. - -STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO -THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND -FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE -FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT -OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/docutils/licenses/python-2-2.txt b/docutils/licenses/python-2-2.txt deleted file mode 100644 index f7c869124..000000000 --- a/docutils/licenses/python-2-2.txt +++ /dev/null @@ -1,246 +0,0 @@ -A. HISTORY OF THE SOFTWARE -========================== - -Python was created in the early 1990s by Guido van Rossum at Stichting -Mathematisch Centrum (CWI, see http://www.cwi.nl) in the Netherlands -as a successor of a language called ABC. Guido remains Python's -principal author, although it includes many contributions from others. - -In 1995, Guido continued his work on Python at the Corporation for -National Research Initiatives (CNRI, see http://www.cnri.reston.va.us) -in Reston, Virginia where he released several versions of the -software. - -In May 2000, Guido and the Python core development team moved to -BeOpen.com to form the BeOpen PythonLabs team. In October of the same -year, the PythonLabs team moved to Digital Creations (see -http://www.digicool.com). In 2001, the Python Software Foundation -(PSF, see http://www.python.org/psf/) was formed, a non-profit -organization created specifically to own Python-related Intellectual -Property. Digital Creations is a sponsoring member of the PSF. - -All Python releases are Open Source (see http://www.opensource.org for -the Open Source Definition). Historically, most, but not all, Python -releases have also been GPL-compatible; the table below summarizes -the various releases. - - Release Derived Year Owner GPL- - from compatible? (1) - - 0.9.0 thru 1.2 1991-1995 CWI yes - 1.3 thru 1.5.2 1.2 1995-1999 CNRI yes - 1.6 1.5.2 2000 CNRI no - 2.0 1.6 2000 BeOpen.com no - 1.6.1 1.6 2001 CNRI no - 2.1 2.0+1.6.1 2001 PSF no - 2.0.1 2.0+1.6.1 2001 PSF yes - 2.1.1 2.1+2.0.1 2001 PSF yes - 2.2 2.1.1 2001 PSF yes - -Footnotes: - -(1) GPL-compatible doesn't mean that we're distributing Python under - the GPL. All Python licenses, unlike the GPL, let you distribute - a modified version without making your changes open source. The - GPL-compatible licenses make it possible to combine Python with - other software that is released under the GPL; the others don't. - -Thanks to the many outside volunteers who have worked under Guido's -direction to make these releases possible. - - -B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON -=============================================================== - -PSF LICENSE AGREEMENT FOR PYTHON 2.2 ------------------------------------- - -1. This LICENSE AGREEMENT is between the Python Software Foundation -("PSF"), and the Individual or Organization ("Licensee") accessing and -otherwise using Python 2.2 software in source or binary form and its -associated documentation. - -2. Subject to the terms and conditions of this License Agreement, PSF -hereby grants Licensee a nonexclusive, royalty-free, world-wide -license to reproduce, analyze, test, perform and/or display publicly, -prepare derivative works, distribute, and otherwise use Python 2.2 -alone or in any derivative version, provided, however, that PSF's -License Agreement and PSF's notice of copyright, i.e., "Copyright (c) -2001 Python Software Foundation; All Rights Reserved" are retained in -Python 2.2 alone or in any derivative version prepared by Licensee. - -3. In the event Licensee prepares a derivative work that is based on -or incorporates Python 2.2 or any part thereof, and wants to make -the derivative work available to others as provided herein, then -Licensee hereby agrees to include in any such work a brief summary of -the changes made to Python 2.2. - -4. PSF is making Python 2.2 available to Licensee on an "AS IS" -basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.2 WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON -2.2 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS -A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.2, -OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -7. Nothing in this License Agreement shall be deemed to create any -relationship of agency, partnership, or joint venture between PSF and -Licensee. This License Agreement does not grant permission to use PSF -trademarks or trade name in a trademark sense to endorse or promote -products or services of Licensee, or any third party. - -8. By copying, installing or otherwise using Python 2.2, Licensee -agrees to be bound by the terms and conditions of this License -Agreement. - - -BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0 -------------------------------------------- - -BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 - -1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an -office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the -Individual or Organization ("Licensee") accessing and otherwise using -this software in source or binary form and its associated -documentation ("the Software"). - -2. Subject to the terms and conditions of this BeOpen Python License -Agreement, BeOpen hereby grants Licensee a non-exclusive, -royalty-free, world-wide license to reproduce, analyze, test, perform -and/or display publicly, prepare derivative works, distribute, and -otherwise use the Software alone or in any derivative version, -provided, however, that the BeOpen Python License is retained in the -Software, alone or in any derivative version prepared by Licensee. - -3. BeOpen is making the Software available to Licensee on an "AS IS" -basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE -SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS -AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY -DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -5. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -6. This License Agreement shall be governed by and interpreted in all -respects by the law of the State of California, excluding conflict of -law provisions. Nothing in this License Agreement shall be deemed to -create any relationship of agency, partnership, or joint venture -between BeOpen and Licensee. This License Agreement does not grant -permission to use BeOpen trademarks or trade names in a trademark -sense to endorse or promote products or services of Licensee, or any -third party. As an exception, the "BeOpen Python" logos available at -http://www.pythonlabs.com/logos.html may be used according to the -permissions granted on that web page. - -7. By copying, installing or otherwise using the software, Licensee -agrees to be bound by the terms and conditions of this License -Agreement. - - -CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1 ---------------------------------------- - -1. This LICENSE AGREEMENT is between the Corporation for National -Research Initiatives, having an office at 1895 Preston White Drive, -Reston, VA 20191 ("CNRI"), and the Individual or Organization -("Licensee") accessing and otherwise using Python 1.6.1 software in -source or binary form and its associated documentation. - -2. Subject to the terms and conditions of this License Agreement, CNRI -hereby grants Licensee a nonexclusive, royalty-free, world-wide -license to reproduce, analyze, test, perform and/or display publicly, -prepare derivative works, distribute, and otherwise use Python 1.6.1 -alone or in any derivative version, provided, however, that CNRI's -License Agreement and CNRI's notice of copyright, i.e., "Copyright (c) -1995-2001 Corporation for National Research Initiatives; All Rights -Reserved" are retained in Python 1.6.1 alone or in any derivative -version prepared by Licensee. Alternately, in lieu of CNRI's License -Agreement, Licensee may substitute the following text (omitting the -quotes): "Python 1.6.1 is made available subject to the terms and -conditions in CNRI's License Agreement. This Agreement together with -Python 1.6.1 may be located on the Internet using the following -unique, persistent identifier (known as a handle): 1895.22/1013. This -Agreement may also be obtained from a proxy server on the Internet -using the following URL: http://hdl.handle.net/1895.22/1013". - -3. In the event Licensee prepares a derivative work that is based on -or incorporates Python 1.6.1 or any part thereof, and wants to make -the derivative work available to others as provided herein, then -Licensee hereby agrees to include in any such work a brief summary of -the changes made to Python 1.6.1. - -4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" -basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON -1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS -A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, -OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -7. This License Agreement shall be governed by the federal -intellectual property law of the United States, including without -limitation the federal copyright law, and, to the extent such -U.S. federal law does not apply, by the law of the Commonwealth of -Virginia, excluding Virginia's conflict of law provisions. -Notwithstanding the foregoing, with regard to derivative works based -on Python 1.6.1 that incorporate non-separable material that was -previously distributed under the GNU General Public License (GPL), the -law of the Commonwealth of Virginia shall govern this License -Agreement only as to issues arising under or with respect to -Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this -License Agreement shall be deemed to create any relationship of -agency, partnership, or joint venture between CNRI and Licensee. This -License Agreement does not grant permission to use CNRI trademarks or -trade name in a trademark sense to endorse or promote products or -services of Licensee, or any third party. - -8. By clicking on the "ACCEPT" button where indicated, or by copying, -installing or otherwise using Python 1.6.1, Licensee agrees to be -bound by the terms and conditions of this License Agreement. - - ACCEPT - - -CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2 --------------------------------------------------- - -Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, -The Netherlands. All rights reserved. - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, -provided that the above copyright notice appear in all copies and that -both that copyright notice and this permission notice appear in -supporting documentation, and that the name of Stichting Mathematisch -Centrum or CWI not be used in advertising or publicity pertaining to -distribution of the software without specific, written prior -permission. - -STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO -THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND -FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE -FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT -OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/docutils/licenses/python-2-3.txt b/docutils/licenses/python-2-3.txt deleted file mode 100644 index d33d9b08a..000000000 --- a/docutils/licenses/python-2-3.txt +++ /dev/null @@ -1,253 +0,0 @@ -A. HISTORY OF THE SOFTWARE -========================== - -Python was created in the early 1990s by Guido van Rossum at Stichting -Mathematisch Centrum (CWI, see http://www.cwi.nl) in the Netherlands -as a successor of a language called ABC. Guido remains Python's -principal author, although it includes many contributions from others. - -In 1995, Guido continued his work on Python at the Corporation for -National Research Initiatives (CNRI, see http://www.cnri.reston.va.us) -in Reston, Virginia where he released several versions of the -software. - -In May 2000, Guido and the Python core development team moved to -BeOpen.com to form the BeOpen PythonLabs team. In October of the same -year, the PythonLabs team moved to Digital Creations (now Zope -Corporation, see http://www.zope.com). In 2001, the Python Software -Foundation (PSF, see http://www.python.org/psf/) was formed, a -non-profit organization created specifically to own Python-related -Intellectual Property. Zope Corporation is a sponsoring member of -the PSF. - -All Python releases are Open Source (see http://www.opensource.org for -the Open Source Definition). Historically, most, but not all, Python -releases have also been GPL-compatible; the table below summarizes -the various releases. - - Release Derived Year Owner GPL- - from compatible? (1) - - 0.9.0 thru 1.2 1991-1995 CWI yes - 1.3 thru 1.5.2 1.2 1995-1999 CNRI yes - 1.6 1.5.2 2000 CNRI no - 2.0 1.6 2000 BeOpen.com no - 1.6.1 1.6 2001 CNRI no - 2.1 2.0+1.6.1 2001 PSF no - 2.0.1 2.0+1.6.1 2001 PSF yes - 2.1.1 2.1+2.0.1 2001 PSF yes - 2.2 2.1.1 2001 PSF yes - 2.1.2 2.1.1 2002 PSF yes - 2.1.3 2.1.2 2002 PSF yes - 2.2.1 2.2 2002 PSF yes - 2.2.2 2.2.1 2002 PSF yes - 2.3 2.2.2 2002-2003 PSF yes - -Footnotes: - -(1) GPL-compatible doesn't mean that we're distributing Python under - the GPL. All Python licenses, unlike the GPL, let you distribute - a modified version without making your changes open source. The - GPL-compatible licenses make it possible to combine Python with - other software that is released under the GPL; the others don't. - -Thanks to the many outside volunteers who have worked under Guido's -direction to make these releases possible. - - -B. TERMS AND CONDITIONS FOR ACCESSING OR OTHERWISE USING PYTHON -=============================================================== - -PSF LICENSE AGREEMENT FOR PYTHON 2.3 --------------------------------------- - -1. This LICENSE AGREEMENT is between the Python Software Foundation -("PSF"), and the Individual or Organization ("Licensee") accessing and -otherwise using Python 2.3 software in source or binary form and its -associated documentation. - -2. Subject to the terms and conditions of this License Agreement, PSF -hereby grants Licensee a nonexclusive, royalty-free, world-wide -license to reproduce, analyze, test, perform and/or display publicly, -prepare derivative works, distribute, and otherwise use Python 2.3 -alone or in any derivative version, provided, however, that PSF's -License Agreement and PSF's notice of copyright, i.e., "Copyright (c) -2001, 2002, 2003 Python Software Foundation; All Rights Reserved" are -retained in Python 2.3 alone or in any derivative version prepared by -Licensee. - -3. In the event Licensee prepares a derivative work that is based on -or incorporates Python 2.3 or any part thereof, and wants to make -the derivative work available to others as provided herein, then -Licensee hereby agrees to include in any such work a brief summary of -the changes made to Python 2.3. - -4. PSF is making Python 2.3 available to Licensee on an "AS IS" -basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3 WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON -2.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS -A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 2.3, -OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -7. Nothing in this License Agreement shall be deemed to create any -relationship of agency, partnership, or joint venture between PSF and -Licensee. This License Agreement does not grant permission to use PSF -trademarks or trade name in a trademark sense to endorse or promote -products or services of Licensee, or any third party. - -8. By copying, installing or otherwise using Python 2.3, Licensee -agrees to be bound by the terms and conditions of this License -Agreement. - - -BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0 -------------------------------------------- - -BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1 - -1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an -office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the -Individual or Organization ("Licensee") accessing and otherwise using -this software in source or binary form and its associated -documentation ("the Software"). - -2. Subject to the terms and conditions of this BeOpen Python License -Agreement, BeOpen hereby grants Licensee a non-exclusive, -royalty-free, world-wide license to reproduce, analyze, test, perform -and/or display publicly, prepare derivative works, distribute, and -otherwise use the Software alone or in any derivative version, -provided, however, that the BeOpen Python License is retained in the -Software, alone or in any derivative version prepared by Licensee. - -3. BeOpen is making the Software available to Licensee on an "AS IS" -basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE -SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS -AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY -DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -5. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -6. This License Agreement shall be governed by and interpreted in all -respects by the law of the State of California, excluding conflict of -law provisions. Nothing in this License Agreement shall be deemed to -create any relationship of agency, partnership, or joint venture -between BeOpen and Licensee. This License Agreement does not grant -permission to use BeOpen trademarks or trade names in a trademark -sense to endorse or promote products or services of Licensee, or any -third party. As an exception, the "BeOpen Python" logos available at -http://www.pythonlabs.com/logos.html may be used according to the -permissions granted on that web page. - -7. By copying, installing or otherwise using the software, Licensee -agrees to be bound by the terms and conditions of this License -Agreement. - - -CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1 ---------------------------------------- - -1. This LICENSE AGREEMENT is between the Corporation for National -Research Initiatives, having an office at 1895 Preston White Drive, -Reston, VA 20191 ("CNRI"), and the Individual or Organization -("Licensee") accessing and otherwise using Python 1.6.1 software in -source or binary form and its associated documentation. - -2. Subject to the terms and conditions of this License Agreement, CNRI -hereby grants Licensee a nonexclusive, royalty-free, world-wide -license to reproduce, analyze, test, perform and/or display publicly, -prepare derivative works, distribute, and otherwise use Python 1.6.1 -alone or in any derivative version, provided, however, that CNRI's -License Agreement and CNRI's notice of copyright, i.e., "Copyright (c) -1995-2001 Corporation for National Research Initiatives; All Rights -Reserved" are retained in Python 1.6.1 alone or in any derivative -version prepared by Licensee. Alternately, in lieu of CNRI's License -Agreement, Licensee may substitute the following text (omitting the -quotes): "Python 1.6.1 is made available subject to the terms and -conditions in CNRI's License Agreement. This Agreement together with -Python 1.6.1 may be located on the Internet using the following -unique, persistent identifier (known as a handle): 1895.22/1013. This -Agreement may also be obtained from a proxy server on the Internet -using the following URL: http://hdl.handle.net/1895.22/1013". - -3. In the event Licensee prepares a derivative work that is based on -or incorporates Python 1.6.1 or any part thereof, and wants to make -the derivative work available to others as provided herein, then -Licensee hereby agrees to include in any such work a brief summary of -the changes made to Python 1.6.1. - -4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" -basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR -IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND -DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS -FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT -INFRINGE ANY THIRD PARTY RIGHTS. - -5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON -1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS -A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, -OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material -breach of its terms and conditions. - -7. This License Agreement shall be governed by the federal -intellectual property law of the United States, including without -limitation the federal copyright law, and, to the extent such -U.S. federal law does not apply, by the law of the Commonwealth of -Virginia, excluding Virginia's conflict of law provisions. -Notwithstanding the foregoing, with regard to derivative works based -on Python 1.6.1 that incorporate non-separable material that was -previously distributed under the GNU General Public License (GPL), the -law of the Commonwealth of Virginia shall govern this License -Agreement only as to issues arising under or with respect to -Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this -License Agreement shall be deemed to create any relationship of -agency, partnership, or joint venture between CNRI and Licensee. This -License Agreement does not grant permission to use CNRI trademarks or -trade name in a trademark sense to endorse or promote products or -services of Licensee, or any third party. - -8. By clicking on the "ACCEPT" button where indicated, or by copying, -installing or otherwise using Python 1.6.1, Licensee agrees to be -bound by the terms and conditions of this License Agreement. - - ACCEPT - - -CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2 --------------------------------------------------- - -Copyright (c) 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, -The Netherlands. All rights reserved. - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, -provided that the above copyright notice appear in all copies and that -both that copyright notice and this permission notice appear in -supporting documentation, and that the name of Stichting Mathematisch -Centrum or CWI not be used in advertising or publicity pertaining to -distribution of the software without specific, written prior -permission. - -STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO -THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND -FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE -FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT -OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/docutils/docutils/nodes.py b/docutils/nodes.py index 1553013ad..1553013ad 100644 --- a/docutils/docutils/nodes.py +++ b/docutils/nodes.py diff --git a/docutils/docutils/parsers/__init__.py b/docutils/parsers/__init__.py index 027c25a86..027c25a86 100644 --- a/docutils/docutils/parsers/__init__.py +++ b/docutils/parsers/__init__.py diff --git a/docutils/docutils/parsers/null.py b/docutils/parsers/null.py index 61702dfaf..61702dfaf 100644 --- a/docutils/docutils/parsers/null.py +++ b/docutils/parsers/null.py diff --git a/docutils/docutils/parsers/rst/__init__.py b/docutils/parsers/rst/__init__.py index ff1d7b4f8..ff1d7b4f8 100644 --- a/docutils/docutils/parsers/rst/__init__.py +++ b/docutils/parsers/rst/__init__.py diff --git a/docutils/docutils/parsers/rst/directives/__init__.py b/docutils/parsers/rst/directives/__init__.py index 998c391e3..998c391e3 100644 --- a/docutils/docutils/parsers/rst/directives/__init__.py +++ b/docutils/parsers/rst/directives/__init__.py diff --git a/docutils/docutils/parsers/rst/directives/admonitions.py b/docutils/parsers/rst/directives/admonitions.py index 73ca18161..73ca18161 100644 --- a/docutils/docutils/parsers/rst/directives/admonitions.py +++ b/docutils/parsers/rst/directives/admonitions.py diff --git a/docutils/docutils/parsers/rst/directives/body.py b/docutils/parsers/rst/directives/body.py index 2ff89e617..2ff89e617 100644 --- a/docutils/docutils/parsers/rst/directives/body.py +++ b/docutils/parsers/rst/directives/body.py diff --git a/docutils/docutils/parsers/rst/directives/html.py b/docutils/parsers/rst/directives/html.py index 86e19dcfc..86e19dcfc 100644 --- a/docutils/docutils/parsers/rst/directives/html.py +++ b/docutils/parsers/rst/directives/html.py diff --git a/docutils/docutils/parsers/rst/directives/images.py b/docutils/parsers/rst/directives/images.py index 5aed4c01b..5aed4c01b 100644 --- a/docutils/docutils/parsers/rst/directives/images.py +++ b/docutils/parsers/rst/directives/images.py diff --git a/docutils/docutils/parsers/rst/directives/misc.py b/docutils/parsers/rst/directives/misc.py index 42f642fee..42f642fee 100644 --- a/docutils/docutils/parsers/rst/directives/misc.py +++ b/docutils/parsers/rst/directives/misc.py diff --git a/docutils/docutils/parsers/rst/directives/parts.py b/docutils/parsers/rst/directives/parts.py index 2a1a092a4..2a1a092a4 100644 --- a/docutils/docutils/parsers/rst/directives/parts.py +++ b/docutils/parsers/rst/directives/parts.py diff --git a/docutils/docutils/parsers/rst/directives/references.py b/docutils/parsers/rst/directives/references.py index 0406182b6..0406182b6 100644 --- a/docutils/docutils/parsers/rst/directives/references.py +++ b/docutils/parsers/rst/directives/references.py diff --git a/docutils/docutils/parsers/rst/directives/tables.py b/docutils/parsers/rst/directives/tables.py index 70a0de5ab..70a0de5ab 100644 --- a/docutils/docutils/parsers/rst/directives/tables.py +++ b/docutils/parsers/rst/directives/tables.py diff --git a/docutils/docutils/parsers/rst/include/README.txt b/docutils/parsers/rst/include/README.txt index cd03135f9..cd03135f9 100644 --- a/docutils/docutils/parsers/rst/include/README.txt +++ b/docutils/parsers/rst/include/README.txt diff --git a/docutils/docutils/parsers/rst/include/isoamsa.txt b/docutils/parsers/rst/include/isoamsa.txt index e6f451800..e6f451800 100644 --- a/docutils/docutils/parsers/rst/include/isoamsa.txt +++ b/docutils/parsers/rst/include/isoamsa.txt diff --git a/docutils/docutils/parsers/rst/include/isoamsb.txt b/docutils/parsers/rst/include/isoamsb.txt index 05e68d99d..05e68d99d 100644 --- a/docutils/docutils/parsers/rst/include/isoamsb.txt +++ b/docutils/parsers/rst/include/isoamsb.txt diff --git a/docutils/docutils/parsers/rst/include/isoamsc.txt b/docutils/parsers/rst/include/isoamsc.txt index 343504d83..343504d83 100644 --- a/docutils/docutils/parsers/rst/include/isoamsc.txt +++ b/docutils/parsers/rst/include/isoamsc.txt diff --git a/docutils/docutils/parsers/rst/include/isoamsn.txt b/docutils/parsers/rst/include/isoamsn.txt index 5ff17291e..5ff17291e 100644 --- a/docutils/docutils/parsers/rst/include/isoamsn.txt +++ b/docutils/parsers/rst/include/isoamsn.txt diff --git a/docutils/docutils/parsers/rst/include/isoamso.txt b/docutils/parsers/rst/include/isoamso.txt index 65cc17e99..65cc17e99 100644 --- a/docutils/docutils/parsers/rst/include/isoamso.txt +++ b/docutils/parsers/rst/include/isoamso.txt diff --git a/docutils/docutils/parsers/rst/include/isoamsr.txt b/docutils/parsers/rst/include/isoamsr.txt index a3d03dab7..a3d03dab7 100644 --- a/docutils/docutils/parsers/rst/include/isoamsr.txt +++ b/docutils/parsers/rst/include/isoamsr.txt diff --git a/docutils/docutils/parsers/rst/include/isobox.txt b/docutils/parsers/rst/include/isobox.txt index 2304f8770..2304f8770 100644 --- a/docutils/docutils/parsers/rst/include/isobox.txt +++ b/docutils/parsers/rst/include/isobox.txt diff --git a/docutils/docutils/parsers/rst/include/isocyr1.txt b/docutils/parsers/rst/include/isocyr1.txt index afee744cf..afee744cf 100644 --- a/docutils/docutils/parsers/rst/include/isocyr1.txt +++ b/docutils/parsers/rst/include/isocyr1.txt diff --git a/docutils/docutils/parsers/rst/include/isocyr2.txt b/docutils/parsers/rst/include/isocyr2.txt index fe09c015b..fe09c015b 100644 --- a/docutils/docutils/parsers/rst/include/isocyr2.txt +++ b/docutils/parsers/rst/include/isocyr2.txt diff --git a/docutils/docutils/parsers/rst/include/isodia.txt b/docutils/parsers/rst/include/isodia.txt index ede6d9946..ede6d9946 100644 --- a/docutils/docutils/parsers/rst/include/isodia.txt +++ b/docutils/parsers/rst/include/isodia.txt diff --git a/docutils/docutils/parsers/rst/include/isogrk1.txt b/docutils/parsers/rst/include/isogrk1.txt index 434368a03..434368a03 100644 --- a/docutils/docutils/parsers/rst/include/isogrk1.txt +++ b/docutils/parsers/rst/include/isogrk1.txt diff --git a/docutils/docutils/parsers/rst/include/isogrk2.txt b/docutils/parsers/rst/include/isogrk2.txt index fa59f968d..fa59f968d 100644 --- a/docutils/docutils/parsers/rst/include/isogrk2.txt +++ b/docutils/parsers/rst/include/isogrk2.txt diff --git a/docutils/docutils/parsers/rst/include/isogrk3.txt b/docutils/parsers/rst/include/isogrk3.txt index efacd980b..efacd980b 100644 --- a/docutils/docutils/parsers/rst/include/isogrk3.txt +++ b/docutils/parsers/rst/include/isogrk3.txt diff --git a/docutils/docutils/parsers/rst/include/isogrk4-wide.txt b/docutils/parsers/rst/include/isogrk4-wide.txt index 39a63075d..39a63075d 100644 --- a/docutils/docutils/parsers/rst/include/isogrk4-wide.txt +++ b/docutils/parsers/rst/include/isogrk4-wide.txt diff --git a/docutils/docutils/parsers/rst/include/isogrk4.txt b/docutils/parsers/rst/include/isogrk4.txt index 5b9f4104f..5b9f4104f 100644 --- a/docutils/docutils/parsers/rst/include/isogrk4.txt +++ b/docutils/parsers/rst/include/isogrk4.txt diff --git a/docutils/docutils/parsers/rst/include/isolat1.txt b/docutils/parsers/rst/include/isolat1.txt index 3e9ad9df3..3e9ad9df3 100644 --- a/docutils/docutils/parsers/rst/include/isolat1.txt +++ b/docutils/parsers/rst/include/isolat1.txt diff --git a/docutils/docutils/parsers/rst/include/isolat2.txt b/docutils/parsers/rst/include/isolat2.txt index 20de84576..20de84576 100644 --- a/docutils/docutils/parsers/rst/include/isolat2.txt +++ b/docutils/parsers/rst/include/isolat2.txt diff --git a/docutils/docutils/parsers/rst/include/isomfrk-wide.txt b/docutils/parsers/rst/include/isomfrk-wide.txt index 75bba2575..75bba2575 100644 --- a/docutils/docutils/parsers/rst/include/isomfrk-wide.txt +++ b/docutils/parsers/rst/include/isomfrk-wide.txt diff --git a/docutils/docutils/parsers/rst/include/isomfrk.txt b/docutils/parsers/rst/include/isomfrk.txt index 868b687a5..868b687a5 100644 --- a/docutils/docutils/parsers/rst/include/isomfrk.txt +++ b/docutils/parsers/rst/include/isomfrk.txt diff --git a/docutils/docutils/parsers/rst/include/isomopf-wide.txt b/docutils/parsers/rst/include/isomopf-wide.txt index a91ea43eb..a91ea43eb 100644 --- a/docutils/docutils/parsers/rst/include/isomopf-wide.txt +++ b/docutils/parsers/rst/include/isomopf-wide.txt diff --git a/docutils/docutils/parsers/rst/include/isomopf.txt b/docutils/parsers/rst/include/isomopf.txt index 4350db61b..4350db61b 100644 --- a/docutils/docutils/parsers/rst/include/isomopf.txt +++ b/docutils/parsers/rst/include/isomopf.txt diff --git a/docutils/docutils/parsers/rst/include/isomscr-wide.txt b/docutils/parsers/rst/include/isomscr-wide.txt index 34b278b98..34b278b98 100644 --- a/docutils/docutils/parsers/rst/include/isomscr-wide.txt +++ b/docutils/parsers/rst/include/isomscr-wide.txt diff --git a/docutils/docutils/parsers/rst/include/isomscr.txt b/docutils/parsers/rst/include/isomscr.txt index a77890e97..a77890e97 100644 --- a/docutils/docutils/parsers/rst/include/isomscr.txt +++ b/docutils/parsers/rst/include/isomscr.txt diff --git a/docutils/docutils/parsers/rst/include/isonum.txt b/docutils/parsers/rst/include/isonum.txt index 35793b365..35793b365 100644 --- a/docutils/docutils/parsers/rst/include/isonum.txt +++ b/docutils/parsers/rst/include/isonum.txt diff --git a/docutils/docutils/parsers/rst/include/isopub.txt b/docutils/parsers/rst/include/isopub.txt index bc5b6d491..bc5b6d491 100644 --- a/docutils/docutils/parsers/rst/include/isopub.txt +++ b/docutils/parsers/rst/include/isopub.txt diff --git a/docutils/docutils/parsers/rst/include/isotech.txt b/docutils/parsers/rst/include/isotech.txt index 01f7e346f..01f7e346f 100644 --- a/docutils/docutils/parsers/rst/include/isotech.txt +++ b/docutils/parsers/rst/include/isotech.txt diff --git a/docutils/docutils/parsers/rst/include/mmlalias.txt b/docutils/parsers/rst/include/mmlalias.txt index cabc54ac4..cabc54ac4 100644 --- a/docutils/docutils/parsers/rst/include/mmlalias.txt +++ b/docutils/parsers/rst/include/mmlalias.txt diff --git a/docutils/docutils/parsers/rst/include/mmlextra-wide.txt b/docutils/parsers/rst/include/mmlextra-wide.txt index 0177ccc09..0177ccc09 100644 --- a/docutils/docutils/parsers/rst/include/mmlextra-wide.txt +++ b/docutils/parsers/rst/include/mmlextra-wide.txt diff --git a/docutils/docutils/parsers/rst/include/mmlextra.txt b/docutils/parsers/rst/include/mmlextra.txt index 790a9775a..790a9775a 100644 --- a/docutils/docutils/parsers/rst/include/mmlextra.txt +++ b/docutils/parsers/rst/include/mmlextra.txt diff --git a/docutils/docutils/parsers/rst/include/s5defs.txt b/docutils/parsers/rst/include/s5defs.txt index dca77ca43..dca77ca43 100644 --- a/docutils/docutils/parsers/rst/include/s5defs.txt +++ b/docutils/parsers/rst/include/s5defs.txt diff --git a/docutils/docutils/parsers/rst/include/xhtml1-lat1.txt b/docutils/parsers/rst/include/xhtml1-lat1.txt index 824dc61c0..824dc61c0 100644 --- a/docutils/docutils/parsers/rst/include/xhtml1-lat1.txt +++ b/docutils/parsers/rst/include/xhtml1-lat1.txt diff --git a/docutils/docutils/parsers/rst/include/xhtml1-special.txt b/docutils/parsers/rst/include/xhtml1-special.txt index dc6f5753c..dc6f5753c 100644 --- a/docutils/docutils/parsers/rst/include/xhtml1-special.txt +++ b/docutils/parsers/rst/include/xhtml1-special.txt diff --git a/docutils/docutils/parsers/rst/include/xhtml1-symbol.txt b/docutils/parsers/rst/include/xhtml1-symbol.txt index 8fe97f808..8fe97f808 100644 --- a/docutils/docutils/parsers/rst/include/xhtml1-symbol.txt +++ b/docutils/parsers/rst/include/xhtml1-symbol.txt diff --git a/docutils/docutils/parsers/rst/languages/__init__.py b/docutils/parsers/rst/languages/__init__.py index be6feb644..be6feb644 100644 --- a/docutils/docutils/parsers/rst/languages/__init__.py +++ b/docutils/parsers/rst/languages/__init__.py diff --git a/docutils/docutils/parsers/rst/languages/af.py b/docutils/parsers/rst/languages/af.py index c2d8fd4c7..c2d8fd4c7 100644 --- a/docutils/docutils/parsers/rst/languages/af.py +++ b/docutils/parsers/rst/languages/af.py diff --git a/docutils/docutils/parsers/rst/languages/ca.py b/docutils/parsers/rst/languages/ca.py index ed181668d..ed181668d 100644 --- a/docutils/docutils/parsers/rst/languages/ca.py +++ b/docutils/parsers/rst/languages/ca.py diff --git a/docutils/docutils/parsers/rst/languages/cs.py b/docutils/parsers/rst/languages/cs.py index 169d2c4f7..169d2c4f7 100644 --- a/docutils/docutils/parsers/rst/languages/cs.py +++ b/docutils/parsers/rst/languages/cs.py diff --git a/docutils/docutils/parsers/rst/languages/de.py b/docutils/parsers/rst/languages/de.py index da528a7be..da528a7be 100644 --- a/docutils/docutils/parsers/rst/languages/de.py +++ b/docutils/parsers/rst/languages/de.py diff --git a/docutils/docutils/parsers/rst/languages/en.py b/docutils/parsers/rst/languages/en.py index 1c0d7edba..1c0d7edba 100644 --- a/docutils/docutils/parsers/rst/languages/en.py +++ b/docutils/parsers/rst/languages/en.py diff --git a/docutils/docutils/parsers/rst/languages/eo.py b/docutils/parsers/rst/languages/eo.py index 8565d6c8d..8565d6c8d 100644 --- a/docutils/docutils/parsers/rst/languages/eo.py +++ b/docutils/parsers/rst/languages/eo.py diff --git a/docutils/docutils/parsers/rst/languages/es.py b/docutils/parsers/rst/languages/es.py index 8e86bae37..8e86bae37 100644 --- a/docutils/docutils/parsers/rst/languages/es.py +++ b/docutils/parsers/rst/languages/es.py diff --git a/docutils/docutils/parsers/rst/languages/fi.py b/docutils/parsers/rst/languages/fi.py index 8f92a67ad..8f92a67ad 100644 --- a/docutils/docutils/parsers/rst/languages/fi.py +++ b/docutils/parsers/rst/languages/fi.py diff --git a/docutils/docutils/parsers/rst/languages/fr.py b/docutils/parsers/rst/languages/fr.py index 7520f743b..7520f743b 100644 --- a/docutils/docutils/parsers/rst/languages/fr.py +++ b/docutils/parsers/rst/languages/fr.py diff --git a/docutils/docutils/parsers/rst/languages/it.py b/docutils/parsers/rst/languages/it.py index cc1701941..cc1701941 100644 --- a/docutils/docutils/parsers/rst/languages/it.py +++ b/docutils/parsers/rst/languages/it.py diff --git a/docutils/docutils/parsers/rst/languages/ja.py b/docutils/parsers/rst/languages/ja.py index 0bb701d85..0bb701d85 100644 --- a/docutils/docutils/parsers/rst/languages/ja.py +++ b/docutils/parsers/rst/languages/ja.py diff --git a/docutils/docutils/parsers/rst/languages/nl.py b/docutils/parsers/rst/languages/nl.py index baaf2ae70..baaf2ae70 100644 --- a/docutils/docutils/parsers/rst/languages/nl.py +++ b/docutils/parsers/rst/languages/nl.py diff --git a/docutils/docutils/parsers/rst/languages/pt_br.py b/docutils/parsers/rst/languages/pt_br.py index 43ebfaa3b..43ebfaa3b 100644 --- a/docutils/docutils/parsers/rst/languages/pt_br.py +++ b/docutils/parsers/rst/languages/pt_br.py diff --git a/docutils/docutils/parsers/rst/languages/ru.py b/docutils/parsers/rst/languages/ru.py index 18354f738..18354f738 100644 --- a/docutils/docutils/parsers/rst/languages/ru.py +++ b/docutils/parsers/rst/languages/ru.py diff --git a/docutils/docutils/parsers/rst/languages/sk.py b/docutils/parsers/rst/languages/sk.py index 513c432f4..513c432f4 100644 --- a/docutils/docutils/parsers/rst/languages/sk.py +++ b/docutils/parsers/rst/languages/sk.py diff --git a/docutils/docutils/parsers/rst/languages/sv.py b/docutils/parsers/rst/languages/sv.py index 8ffe76e50..8ffe76e50 100644 --- a/docutils/docutils/parsers/rst/languages/sv.py +++ b/docutils/parsers/rst/languages/sv.py diff --git a/docutils/docutils/parsers/rst/languages/zh_cn.py b/docutils/parsers/rst/languages/zh_cn.py index dee301ca6..dee301ca6 100644 --- a/docutils/docutils/parsers/rst/languages/zh_cn.py +++ b/docutils/parsers/rst/languages/zh_cn.py diff --git a/docutils/docutils/parsers/rst/languages/zh_tw.py b/docutils/parsers/rst/languages/zh_tw.py index 77574b591..77574b591 100644 --- a/docutils/docutils/parsers/rst/languages/zh_tw.py +++ b/docutils/parsers/rst/languages/zh_tw.py diff --git a/docutils/docutils/parsers/rst/roles.py b/docutils/parsers/rst/roles.py index 554e1f441..554e1f441 100644 --- a/docutils/docutils/parsers/rst/roles.py +++ b/docutils/parsers/rst/roles.py diff --git a/docutils/docutils/parsers/rst/states.py b/docutils/parsers/rst/states.py index 363ef8fdd..363ef8fdd 100644 --- a/docutils/docutils/parsers/rst/states.py +++ b/docutils/parsers/rst/states.py diff --git a/docutils/docutils/parsers/rst/tableparser.py b/docutils/parsers/rst/tableparser.py index 1d5dc9dfd..1d5dc9dfd 100644 --- a/docutils/docutils/parsers/rst/tableparser.py +++ b/docutils/parsers/rst/tableparser.py diff --git a/docutils/docutils/readers/__init__.py b/docutils/readers/__init__.py index b3a7e64eb..b3a7e64eb 100644 --- a/docutils/docutils/readers/__init__.py +++ b/docutils/readers/__init__.py diff --git a/docutils/docutils/readers/doctree.py b/docutils/readers/doctree.py index 4138fb51e..4138fb51e 100644 --- a/docutils/docutils/readers/doctree.py +++ b/docutils/readers/doctree.py diff --git a/docutils/docutils/readers/pep.py b/docutils/readers/pep.py index b181e20c8..b181e20c8 100644 --- a/docutils/docutils/readers/pep.py +++ b/docutils/readers/pep.py diff --git a/docutils/docutils/readers/python/__init__.py b/docutils/readers/python/__init__.py index ba147a3d5..ba147a3d5 100644 --- a/docutils/docutils/readers/python/__init__.py +++ b/docutils/readers/python/__init__.py diff --git a/docutils/docutils/readers/python/moduleparser.py b/docutils/readers/python/moduleparser.py index 03d57c948..03d57c948 100644 --- a/docutils/docutils/readers/python/moduleparser.py +++ b/docutils/readers/python/moduleparser.py diff --git a/docutils/docutils/readers/python/pynodes.py b/docutils/readers/python/pynodes.py index 61e21f10e..61e21f10e 100644 --- a/docutils/docutils/readers/python/pynodes.py +++ b/docutils/readers/python/pynodes.py diff --git a/docutils/docutils/readers/standalone.py b/docutils/readers/standalone.py index df291128f..df291128f 100644 --- a/docutils/docutils/readers/standalone.py +++ b/docutils/readers/standalone.py diff --git a/docutils/setup.py b/docutils/setup.py deleted file mode 100755 index 84032bdac..000000000 --- a/docutils/setup.py +++ /dev/null @@ -1,158 +0,0 @@ -#!/usr/bin/env python -# $Id$ -# Copyright: This file has been placed in the public domain. - -import sys -import os -import glob -from distutils.core import setup -from distutils.command.build_py import build_py - -# From <http://groups.google.de/groups?as_umsgid=f70e3538.0404141327.6cea58ca@posting.google.com>. -from distutils.command.install import INSTALL_SCHEMES -for scheme in INSTALL_SCHEMES.values(): - scheme['data'] = scheme['purelib'] - - -def do_setup(): - kwargs = package_data.copy() - extras = get_extras() - if extras: - kwargs['py_modules'] = extras - if sys.hexversion >= 0x02030000: # Python 2.3 - kwargs['classifiers'] = classifiers - else: - kwargs['cmdclass'] = {'build_py': dual_build_py} - dist = setup(**kwargs) - return dist - -s5_theme_files = [] -for dir in glob.glob('docutils/writers/s5_html/themes/*'): - if os.path.isdir(dir): - theme_files = glob.glob('%s/*' % dir) - s5_theme_files.append((dir, theme_files)) - -package_data = { - 'name': 'docutils', - 'description': 'Docutils -- Python Documentation Utilities', - 'long_description': """\ -Docutils is a modular system for processing documentation -into useful formats, such as HTML, XML, and LaTeX. For -input Docutils supports reStructuredText, an easy-to-read, -what-you-see-is-what-you-get plaintext markup syntax.""", # wrap at col 60 - 'url': 'http://docutils.sourceforge.net/', - 'version': '0.4', - 'author': 'David Goodger', - 'author_email': 'goodger@users.sourceforge.net', - 'license': 'public domain, Python, BSD, GPL (see COPYING.txt)', - 'platforms': 'OS-independent', - 'package_dir': {'docutils': 'docutils', '': 'extras'}, - 'packages': ['docutils', - 'docutils.languages', - 'docutils.parsers', - 'docutils.parsers.rst', - 'docutils.parsers.rst.directives', - 'docutils.parsers.rst.languages', - 'docutils.readers', - 'docutils.readers.python', - 'docutils.transforms', - 'docutils.writers', - 'docutils.writers.html4css1', - 'docutils.writers.pep_html', - 'docutils.writers.s5_html', - 'docutils.writers.latex2e', - 'docutils.writers.newlatex2e'], - 'data_files': ([('docutils/parsers/rst/include', - glob.glob('docutils/parsers/rst/include/*.txt')), - ('docutils/writers/html4css1', - ['docutils/writers/html4css1/html4css1.css']), - ('docutils/writers/latex2e', - ['docutils/writers/latex2e/latex2e.tex']), - ('docutils/writers/newlatex2e', - ['docutils/writers/newlatex2e/base.tex']), - ('docutils/writers/pep_html', - ['docutils/writers/pep_html/pep.css', - 'docutils/writers/pep_html/template.txt']), - ('docutils/writers/s5_html/themes', - ['docutils/writers/s5_html/themes/README.txt']),] - + s5_theme_files), - 'scripts' : ['tools/rst2html.py', - 'tools/rst2s5.py', - 'tools/rst2latex.py', - 'tools/rst2newlatex.py', - 'tools/rst2xml.py', - 'tools/rst2pseudoxml.py'],} -"""Distutils setup parameters.""" - -classifiers = [ - 'Development Status :: 3 - Alpha', - 'Environment :: Console', - 'Intended Audience :: End Users/Desktop', - 'Intended Audience :: Other Audience', - 'Intended Audience :: Developers', - 'Intended Audience :: System Administrators', - 'License :: Public Domain', - 'License :: OSI Approved :: Python Software Foundation License', - 'License :: OSI Approved :: BSD License', - 'License :: OSI Approved :: GNU General Public License (GPL)', - 'Operating System :: OS Independent', - 'Programming Language :: Python', - 'Topic :: Documentation', - 'Topic :: Software Development :: Documentation', - 'Topic :: Text Processing', - 'Natural Language :: English', # main/default language, keep first - 'Natural Language :: Afrikaans', - 'Natural Language :: Esperanto', - 'Natural Language :: French', - 'Natural Language :: German', - 'Natural Language :: Italian', - 'Natural Language :: Russian', - 'Natural Language :: Slovak', - 'Natural Language :: Spanish', - 'Natural Language :: Swedish',] -"""Trove classifiers for the Distutils "register" command; -Python 2.3 and up.""" - -extra_modules = [('optparse', '1.4.1', None), - ('textwrap', None, None), - ('roman', '1.4', ['toRoman', 'fromRoman', - 'InvalidRomanNumeralError'])] -"""Third-party modules to install if they're not already present. -List of (module name, minimum __version__ string, [attribute names]).""" - -def get_extras(): - extras = [] - for module_name, version, attributes in extra_modules: - try: - module = __import__(module_name) - if version and module.__version__ < version: - raise ValueError - for attribute in attributes or []: - getattr(module, attribute) - print ('"%s" module already present; ignoring extras/%s.py.' - % (module_name, module_name)) - except (ImportError, AttributeError, ValueError): - extras.append(module_name) - return extras - - -class dual_build_py(build_py): - - """ - This class allows the distribution of both packages *and* modules with one - call to `distutils.core.setup()` (necessary for pre-2.3 Python). Thanks - to Thomas Heller. - """ - - def run(self): - if not self.py_modules and not self.packages: - return - if self.py_modules: - self.build_modules() - if self.packages: - self.build_packages() - self.byte_compile(self.get_outputs(include_bytecode=0)) - - -if __name__ == '__main__' : - do_setup() diff --git a/docutils/docutils/statemachine.py b/docutils/statemachine.py index b14b308f7..b14b308f7 100644 --- a/docutils/docutils/statemachine.py +++ b/docutils/statemachine.py diff --git a/docutils/test/DocutilsTestSupport.py b/docutils/test/DocutilsTestSupport.py deleted file mode 100644 index c30b263d6..000000000 --- a/docutils/test/DocutilsTestSupport.py +++ /dev/null @@ -1,868 +0,0 @@ -# Authors: David Goodger; Garth Kidd -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Exports the following: - -:Modules: - - `statemachine` is 'docutils.statemachine' - - `nodes` is 'docutils.nodes' - - `urischemes` is 'docutils.urischemes' - - `utils` is 'docutils.utils' - - `transforms` is 'docutils.transforms' - - `states` is 'docutils.parsers.rst.states' - - `tableparser` is 'docutils.parsers.rst.tableparser' - -:Classes: - - `StandardTestCase` - - `CustomTestCase` - - `CustomTestSuite` - - `TransformTestCase` - - `TransformTestSuite` - - `ParserTestCase` - - `ParserTestSuite` - - `ParserTransformTestCase` - - `PEPParserTestCase` - - `PEPParserTestSuite` - - `GridTableParserTestCase` - - `GridTableParserTestSuite` - - `SimpleTableParserTestCase` - - `SimpleTableParserTestSuite` - - `WriterPublishTestCase` - - `LatexWriterPublishTestCase` - - `PseudoXMLWriterPublishTestCase` - - `HtmlWriterPublishTestCase` - - `PublishTestSuite` - - `HtmlFragmentTestSuite` - - `DevNull` (output sink) -""" -__docformat__ = 'reStructuredText' - -import sys -import os - -testroot = os.path.abspath(os.path.dirname(__file__) or os.curdir) -os.chdir(testroot) -sys.path.insert(0, os.path.normpath(os.path.join(testroot, '..'))) -sys.path.insert(0, testroot) -sys.path.append(os.path.normpath(os.path.join(testroot, '..', 'extras'))) - -import unittest -import docutils_difflib -import inspect -from pprint import pformat -from types import UnicodeType, StringType -import package_unittest -import docutils -import docutils.core -from docutils import frontend, nodes, statemachine, urischemes, utils -from docutils.transforms import universal -from docutils.parsers import rst -from docutils.parsers.rst import states, tableparser, roles, languages -from docutils.readers import standalone, pep -from docutils.statemachine import StringList, string2lines - -try: - from docutils.readers.python import moduleparser - from tokenize import generate_tokens - del generate_tokens -except ImportError: # moduleparser depends on modules added in Python 2.2 - moduleparser = None - -try: - import mypdb as pdb -except: - import pdb - - -# Hack to make repr(StringList) look like repr(list): -StringList.__repr__ = StringList.__str__ - - -class DevNull: - - """Output sink.""" - - def write(self, string): - pass - - def close(self): - pass - - -class StandardTestCase(unittest.TestCase): - - """ - Helper class, providing the same interface as unittest.TestCase, - but with useful setUp and comparison methods. - """ - - def setUp(self): - os.chdir(testroot) - - def failUnlessEqual(self, first, second, msg=None): - """Fail if the two objects are unequal as determined by the '==' - operator. - """ - if not first == second: - raise self.failureException, \ - (msg or '%s != %s' % _format_str(first, second)) - - def failIfEqual(self, first, second, msg=None): - """Fail if the two objects are equal as determined by the '==' - operator. - """ - if first == second: - raise self.failureException, \ - (msg or '%s == %s' % _format_str(first, second)) - - # Synonyms for assertion methods - - assertEqual = assertEquals = failUnlessEqual - - assertNotEqual = assertNotEquals = failIfEqual - - -class CustomTestCase(StandardTestCase): - - """ - Helper class, providing extended functionality over unittest.TestCase. - - The methods failUnlessEqual and failIfEqual have been overwritten - to provide better support for multi-line strings. Furthermore, - see the compare_output method and the parameter list of __init__. - """ - - compare = docutils_difflib.Differ().compare - """Comparison method shared by all subclasses.""" - - def __init__(self, method_name, input, expected, id, run_in_debugger=0, - suite_settings=None): - """ - Initialise the CustomTestCase. - - Arguments: - - method_name -- name of test method to run. - input -- input to the parser. - expected -- expected output from the parser. - id -- unique test identifier, used by the test framework. - run_in_debugger -- if true, run this test under the pdb debugger. - suite_settings -- settings overrides for this test suite. - """ - self.id = id - self.input = input - self.expected = expected - self.run_in_debugger = run_in_debugger - self.suite_settings = suite_settings or {} - - # Ring your mother. - unittest.TestCase.__init__(self, method_name) - - def __str__(self): - """ - Return string conversion. Overridden to give test id, in addition to - method name. - """ - return '%s; %s' % (self.id, unittest.TestCase.__str__(self)) - - def __repr__(self): - return "<%s %s>" % (self.id, unittest.TestCase.__repr__(self)) - - def clear_roles(self): - # Language-specific roles and roles added by the - # "default-role" and "role" directives are currently stored - # globally in the roles._roles dictionary. This workaround - # empties that dictionary. - roles._roles = {} - - def setUp(self): - StandardTestCase.setUp(self) - self.clear_roles() - - def compare_output(self, input, output, expected): - """`input`, `output`, and `expected` should all be strings.""" - if isinstance(input, UnicodeType): - input = input.encode('raw_unicode_escape') - if isinstance(output, UnicodeType): - output = output.encode('raw_unicode_escape') - if isinstance(expected, UnicodeType): - expected = expected.encode('raw_unicode_escape') - try: - self.assertEquals(output, expected) - except AssertionError, error: - print >>sys.stderr, '\n%s\ninput:' % (self,) - print >>sys.stderr, input - try: - comparison = ''.join(self.compare(expected.splitlines(1), - output.splitlines(1))) - print >>sys.stderr, '-: expected\n+: output' - print >>sys.stderr, comparison - except AttributeError: # expected or output not a string - # alternative output for non-strings: - print >>sys.stderr, 'expected: %r' % expected - print >>sys.stderr, 'output: %r' % output - raise error - - -class CustomTestSuite(unittest.TestSuite): - - """ - A collection of CustomTestCases. - - Provides test suite ID generation and a method for adding test cases. - """ - - id = '' - """Identifier for the TestSuite. Prepended to the - TestCase identifiers to make identification easier.""" - - next_test_case_id = 0 - """The next identifier to use for non-identified test cases.""" - - def __init__(self, tests=(), id=None, suite_settings=None): - """ - Initialize the CustomTestSuite. - - Arguments: - - id -- identifier for the suite, prepended to test cases. - suite_settings -- settings overrides for this test suite. - """ - unittest.TestSuite.__init__(self, tests) - self.suite_settings = suite_settings or {} - if id is None: - mypath = os.path.abspath( - sys.modules[CustomTestSuite.__module__].__file__) - outerframes = inspect.getouterframes(inspect.currentframe()) - for outerframe in outerframes[1:]: - if outerframe[3] != '__init__': - callerpath = outerframe[1] - if callerpath is None: - # It happens sometimes. Why is a mystery. - callerpath = os.getcwd() - callerpath = os.path.abspath(callerpath) - break - mydir, myname = os.path.split(mypath) - if not mydir: - mydir = os.curdir - if callerpath.startswith(mydir): - self.id = callerpath[len(mydir) + 1:] # caller's module - else: - self.id = callerpath - else: - self.id = id - - def addTestCase(self, test_case_class, method_name, input, expected, - id=None, run_in_debugger=0, **kwargs): - """ - Create a CustomTestCase in the CustomTestSuite. - Also return it, just in case. - - Arguments: - - test_case_class -- the CustomTestCase to add - method_name -- a string; CustomTestCase.method_name is the test - input -- input to the parser. - expected -- expected output from the parser. - id -- unique test identifier, used by the test framework. - run_in_debugger -- if true, run this test under the pdb debugger. - """ - if id is None: # generate id if required - id = self.next_test_case_id - self.next_test_case_id += 1 - # test identifier will become suiteid.testid - tcid = '%s: %s' % (self.id, id) - # suite_settings may be passed as a parameter; - # if not, set from attribute: - kwargs.setdefault('suite_settings', self.suite_settings) - # generate and add test case - tc = test_case_class(method_name, input, expected, tcid, - run_in_debugger=run_in_debugger, **kwargs) - self.addTest(tc) - return tc - - def generate_no_tests(self, *args, **kwargs): - pass - - -class TransformTestCase(CustomTestCase): - - """ - Output checker for the transform. - - Should probably be called TransformOutputChecker, but I can deal with - that later when/if someone comes up with a category of transform test - cases that have nothing to do with the input and output of the transform. - """ - - option_parser = frontend.OptionParser(components=(rst.Parser,)) - settings = option_parser.get_default_values() - settings.report_level = 1 - settings.halt_level = 5 - settings.debug = package_unittest.debug - settings.warning_stream = DevNull() - unknown_reference_resolvers = () - - def __init__(self, *args, **kwargs): - self.transforms = kwargs['transforms'] - """List of transforms to perform for this test case.""" - - self.parser = kwargs['parser'] - """Input parser for this test case.""" - - del kwargs['transforms'], kwargs['parser'] # only wanted here - CustomTestCase.__init__(self, *args, **kwargs) - - def supports(self, format): - return 1 - - def test_transforms(self): - if self.run_in_debugger: - pdb.set_trace() - settings = self.settings.copy() - settings.__dict__.update(self.suite_settings) - document = utils.new_document('test data', settings) - self.parser.parse(self.input, document) - # Don't do a ``populate_from_components()`` because that would - # enable the Transformer's default transforms. - document.transformer.add_transforms(self.transforms) - document.transformer.add_transform(universal.TestMessages) - document.transformer.components['writer'] = self - document.transformer.apply_transforms() - output = document.pformat() - self.compare_output(self.input, output, self.expected) - - def test_transforms_verbosely(self): - if self.run_in_debugger: - pdb.set_trace() - print '\n', self.id - print '-' * 70 - print self.input - settings = self.settings.copy() - settings.__dict__.update(self.suite_settings) - document = utils.new_document('test data', settings) - self.parser.parse(self.input, document) - print '-' * 70 - print document.pformat() - for transformClass in self.transforms: - transformClass(document).apply() - output = document.pformat() - print '-' * 70 - print output - self.compare_output(self.input, output, self.expected) - - -class TransformTestSuite(CustomTestSuite): - - """ - A collection of TransformTestCases. - - A TransformTestSuite instance manufactures TransformTestCases, - keeps track of them, and provides a shared test fixture (a-la - setUp and tearDown). - """ - - def __init__(self, parser, suite_settings=None): - self.parser = parser - """Parser shared by all test cases.""" - - CustomTestSuite.__init__(self, suite_settings=suite_settings) - - def generateTests(self, dict, dictname='totest', - testmethod='test_transforms'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type's name) maps to a tuple, whose - first item is a list of transform classes and whose second - item is a list of tests. Each test is a list: input, expected - output, optional modifier. The optional third entry, a - behavior modifier, can be 0 (temporarily disable this test) or - 1 (run this test under the pdb debugger). Tests should be - self-documenting and not require external comments. - """ - for name, (transforms, cases) in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - # TODO: (maybe) change the 3rd argument to a dict, so it - # can handle more cases by keyword ('disable', 'debug', - # 'settings'), here and in other generateTests methods. - # But there's also the method that - # HtmlPublishPartsTestSuite uses <DJG> - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - TransformTestCase, testmethod, - transforms=transforms, parser=self.parser, - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class ParserTestCase(CustomTestCase): - - """ - Output checker for the parser. - - Should probably be called ParserOutputChecker, but I can deal with - that later when/if someone comes up with a category of parser test - cases that have nothing to do with the input and output of the parser. - """ - - parser = rst.Parser() - """Parser shared by all ParserTestCases.""" - - option_parser = frontend.OptionParser(components=(rst.Parser,)) - settings = option_parser.get_default_values() - settings.report_level = 5 - settings.halt_level = 5 - settings.debug = package_unittest.debug - - def test_parser(self): - if self.run_in_debugger: - pdb.set_trace() - settings = self.settings.copy() - settings.__dict__.update(self.suite_settings) - document = utils.new_document('test data', settings) - self.parser.parse(self.input, document) - output = document.pformat() - self.compare_output(self.input, output, self.expected) - - -class ParserTestSuite(CustomTestSuite): - - """ - A collection of ParserTestCases. - - A ParserTestSuite instance manufactures ParserTestCases, - keeps track of them, and provides a shared test fixture (a-la - setUp and tearDown). - """ - - test_case_class = ParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: input, expected output, optional modifier. The - optional third entry, a behavior modifier, can be 0 (temporarily - disable this test) or 1 (run this test under the pdb debugger). Tests - should be self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - self.test_case_class, 'test_parser', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PEPParserTestCase(ParserTestCase): - - """PEP-specific parser test case.""" - - parser = rst.Parser(rfc2822=1, inliner=rst.states.Inliner()) - """Parser shared by all PEPParserTestCases.""" - - option_parser = frontend.OptionParser(components=(rst.Parser, pep.Reader)) - settings = option_parser.get_default_values() - settings.report_level = 5 - settings.halt_level = 5 - settings.debug = package_unittest.debug - - -class PEPParserTestSuite(ParserTestSuite): - - """A collection of PEPParserTestCases.""" - - test_case_class = PEPParserTestCase - - -class GridTableParserTestCase(CustomTestCase): - - parser = tableparser.GridTableParser() - - def test_parse_table(self): - self.parser.setup(StringList(string2lines(self.input), 'test data')) - try: - self.parser.find_head_body_sep() - self.parser.parse_table() - output = self.parser.cells - except Exception, details: - output = '%s: %s' % (details.__class__.__name__, details) - self.compare_output(self.input, pformat(output) + '\n', - pformat(self.expected) + '\n') - - def test_parse(self): - try: - output = self.parser.parse(StringList(string2lines(self.input), - 'test data')) - except Exception, details: - output = '%s: %s' % (details.__class__.__name__, details) - self.compare_output(self.input, pformat(output) + '\n', - pformat(self.expected) + '\n') - - -class GridTableParserTestSuite(CustomTestSuite): - - """ - A collection of GridTableParserTestCases. - - A GridTableParserTestSuite instance manufactures GridTableParserTestCases, - keeps track of them, and provides a shared test fixture (a-la setUp and - tearDown). - """ - - test_case_class = GridTableParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: an input table, expected output from parse_table(), - expected output from parse(), optional modifier. The optional fourth - entry, a behavior modifier, can be 0 (temporarily disable this test) - or 1 (run this test under the pdb debugger). Tests should be - self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case) == 4: - if case[-1]: - run_in_debugger = 1 - else: - continue - self.addTestCase(self.test_case_class, 'test_parse_table', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - self.addTestCase(self.test_case_class, 'test_parse', - input=case[0], expected=case[2], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class SimpleTableParserTestCase(GridTableParserTestCase): - - parser = tableparser.SimpleTableParser() - - -class SimpleTableParserTestSuite(CustomTestSuite): - - """ - A collection of SimpleTableParserTestCases. - """ - - test_case_class = SimpleTableParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: an input table, expected output from parse(), optional - modifier. The optional third entry, a behavior modifier, can be 0 - (temporarily disable this test) or 1 (run this test under the pdb - debugger). Tests should be self-documenting and not require external - comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case) == 3: - if case[-1]: - run_in_debugger = 1 - else: - continue - self.addTestCase(self.test_case_class, 'test_parse', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PythonModuleParserTestCase(CustomTestCase): - - def test_parser(self): - if self.run_in_debugger: - pdb.set_trace() - module = moduleparser.parse_module(self.input, 'test data').pformat() - output = str(module) - self.compare_output(self.input, output, self.expected) - - def test_token_parser_rhs(self): - if self.run_in_debugger: - pdb.set_trace() - tr = moduleparser.TokenParser(self.input) - output = tr.rhs(1) - self.compare_output(self.input, output, self.expected) - - -class PythonModuleParserTestSuite(CustomTestSuite): - - """ - A collection of PythonModuleParserTestCase. - """ - - notified = None - - def __init__(self, *args, **kwargs): - if moduleparser is None: - if not self.notified: - print ('Tests of docutils.readers.python skipped; ' - 'Python 2.2 or higher required.') - PythonModuleParserTestSuite.notified = 1 - self.generateTests = self.generate_no_tests - CustomTestSuite.__init__(self, *args, **kwargs) - - def generateTests(self, dict, dictname='totest', - testmethod='test_parser'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type's name) maps to a list of tests. Each - test is a list: input, expected output, optional modifier. The - optional third entry, a behavior modifier, can be 0 (temporarily - disable this test) or 1 (run this test under the pdb debugger). Tests - should be self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - PythonModuleParserTestCase, testmethod, - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class WriterPublishTestCase(CustomTestCase, docutils.SettingsSpec): - - """ - Test case for publish. - """ - - settings_default_overrides = {'_disable_config': 1, - 'strict_visitor': 1} - writer_name = '' # set in subclasses or constructor - - def __init__(self, *args, **kwargs): - if kwargs.has_key('writer_name'): - self.writer_name = kwargs['writer_name'] - del kwargs['writer_name'] - CustomTestCase.__init__(self, *args, **kwargs) - - def test_publish(self): - if self.run_in_debugger: - pdb.set_trace() - output = docutils.core.publish_string( - source=self.input, - reader_name='standalone', - parser_name='restructuredtext', - writer_name=self.writer_name, - settings_spec=self, - settings_overrides=self.suite_settings) - self.compare_output(self.input, output, self.expected) - - -class PublishTestSuite(CustomTestSuite): - - def __init__(self, writer_name, suite_settings=None): - """ - `writer_name` is the name of the writer to use. - """ - CustomTestSuite.__init__(self, suite_settings=suite_settings) - self.test_class = WriterPublishTestCase - self.writer_name = writer_name - - def generateTests(self, dict, dictname='totest'): - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - self.test_class, 'test_publish', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger, - # Passed to constructor of self.test_class: - writer_name=self.writer_name) - - -class HtmlPublishPartsTestSuite(CustomTestSuite): - - def generateTests(self, dict, dictname='totest'): - for name, (settings_overrides, cases) in dict.items(): - settings = self.suite_settings.copy() - settings.update(settings_overrides) - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - HtmlWriterPublishPartsTestCase, 'test_publish', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger, - suite_settings=settings) - - -class HtmlWriterPublishPartsTestCase(WriterPublishTestCase): - - """ - Test case for HTML writer via the publish_parts interface. - """ - - writer_name = 'html' - - settings_default_overrides = \ - WriterPublishTestCase.settings_default_overrides.copy() - settings_default_overrides['stylesheet'] = '' - - def test_publish(self): - if self.run_in_debugger: - pdb.set_trace() - parts = docutils.core.publish_parts( - source=self.input, - reader_name='standalone', - parser_name='restructuredtext', - writer_name=self.writer_name, - settings_spec=self, - settings_overrides=self.suite_settings) - output = self.format_output(parts) - # interpolate standard variables: - expected = self.expected % {'version': docutils.__version__} - self.compare_output(self.input, output, expected) - - - standard_content_type_template = ('<meta http-equiv="Content-Type"' - ' content="text/html; charset=%s" />\n') - standard_generator_template = ( - '<meta name="generator"' - ' content="Docutils %s: http://docutils.sourceforge.net/" />\n') - standard_html_meta_value = ( - standard_content_type_template - + standard_generator_template % docutils.__version__) - standard_meta_value = standard_html_meta_value % 'utf-8' - standard_html_prolog = """\ -<?xml version="1.0" encoding="%s" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -""" - - def format_output(self, parts): - """Minimize & standardize the output.""" - # remove redundant parts: - del parts['whole'] - assert parts['body'] == parts['fragment'] - del parts['body'] - # remove standard portions: - parts['meta'] = parts['meta'].replace(self.standard_meta_value, '') - parts['html_head'] = parts['html_head'].replace( - self.standard_html_meta_value, '...') - parts['html_prolog'] = parts['html_prolog'].replace( - self.standard_html_prolog, '') - # remove empty values: - for key in parts.keys(): - if not parts[key]: - del parts[key] - # standard output format: - keys = parts.keys() - keys.sort() - output = [] - for key in keys: - output.append("%r: '''%s'''" - % (key, parts[key].encode('raw_unicode_escape'))) - if output[-1].endswith("\n'''"): - output[-1] = output[-1][:-4] + "\\n'''" - return '{' + ',\n '.join(output) + '}\n' - - -def exception_data(code): - """ - Execute `code` and return the resulting exception, the exception arguments, - and the formatted exception string. - """ - try: - exec(code) - except Exception, detail: - return (detail, detail.args, - '%s: %s' % (detail.__class__.__name__, detail)) - - -def _format_str(*args): - r""" - Return a tuple containing representations of all args. - - Same as map(repr, args) except that it returns multi-line - representations for strings containing newlines, e.g.:: - - '''\ - foo \n\ - bar - - baz''' - - instead of:: - - 'foo \nbar\n\nbaz' - - This is a helper function for CustomTestCase. - """ - import re - return_tuple = [] - for i in args: - r = repr(i) - if ( (isinstance(i, StringType) or isinstance(i, UnicodeType)) - and '\n' in i): - stripped = '' - if isinstance(i, UnicodeType): - # stripped = 'u' or 'U' - stripped = r[0] - r = r[1:] - # quote_char = "'" or '"' - quote_char = r[0] - assert quote_char in ("'", '"') - assert r[0] == r[-1] - r = r[1:-1] - r = (stripped + 3 * quote_char + '\\\n' + - re.sub(r'(?<!\\)((\\\\)*)\\n', r'\1\n', r) + - 3 * quote_char) - r = re.sub(r' \n', r' \\n\\\n', r) - return_tuple.append(r) - return tuple(return_tuple) diff --git a/docutils/test/alltests.py b/docutils/test/alltests.py deleted file mode 100755 index b28541af1..000000000 --- a/docutils/test/alltests.py +++ /dev/null @@ -1,98 +0,0 @@ -#!/bin/sh -''''exec python -u "$0" "$@" #''' - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -__doc__ = \ -""" -All modules named 'test_*.py' in the current directory, and recursively in -subdirectories (packages) called 'test_*', are loaded and test suites within -are run. -""" - -import time -# Start point for actual elapsed time, including imports -# and setup outside of unittest. -start = time.time() - -import sys -import os -from types import UnicodeType -import DocutilsTestSupport # must be imported before docutils -import docutils - - -def new_exception_str(self): - for i in self.args: - if isinstance(i, UnicodeType): - raise RuntimeError('Error (unicode): %r' % (self.args,)) - return old_exception_str(self) - -old_exception_str = Exception.__str__ -Exception.__str__ = new_exception_str - - -class Tee: - - """Write to a file and a stream (default: stdout) simultaneously.""" - - def __init__(self, filename, stream=sys.__stdout__): - self.file = open(filename, 'w') - self.stream = stream - - def write(self, string): - self.stream.write(string) - self.file.write(string) - - def flush(self): - self.stream.flush() - self.file.flush() - - -def pformat(suite): - step = 4 - suitestr = repr(suite).replace('=[<', '=[\n<').replace(', ', ',\n') - indent = 0 - output = [] - for line in suitestr.splitlines(): - output.append(' ' * indent + line) - if line[-1:] == '[': - indent += step - else: - if line [-5:] == ']>]>,': - indent -= step * 2 - elif line[-3:] == ']>,': - indent -= step - return '\n'.join(output) - -def suite(): - path, script = os.path.split(sys.argv[0]) - suite = package_unittest.loadTestModules(DocutilsTestSupport.testroot, - 'test_', packages=1) - sys.stdout.flush() - return suite - -# must redirect stderr *before* first import of unittest -sys.stdout = sys.stderr = Tee('alltests.out') - -import package_unittest - - -if __name__ == '__main__': - suite = suite() - print ('Testing Docutils %s [%s] with Python %s on %s at %s' - % (docutils.__version__, docutils.__version_details__, - sys.version.split()[0], - time.strftime('%Y-%m-%d'), time.strftime('%H:%M:%S'))) - print 'Working directory: %s' % os.getcwd() - print 'Docutils package: %s' % os.path.dirname(docutils.__file__) - sys.stdout.flush() - package_unittest.main(suite) - #if package_unittest.verbosity > 1: - # print >>sys.stderr, pformat(suite) # check the test suite - finish = time.time() - print 'Elapsed time: %.3f seconds' % (finish - start) diff --git a/docutils/test/coverage.sh b/docutils/test/coverage.sh deleted file mode 100755 index 3edea0e2a..000000000 --- a/docutils/test/coverage.sh +++ /dev/null @@ -1,45 +0,0 @@ -#!/bin/bash - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This script has been placed in the public domain. - -set -e -proj="${PWD##*/}" -if test "$proj" == test; then - cd .. - proj="${PWD##*/}" -fi -if test "$1"; then - proj="$1" -fi -echo "Performing code coverage test for project \"$proj\"..." -echo -echo "Please be patient; coverage tracking slows test execution down by more" -echo "than factor 10." -echo -cd test -rm -rf cover -mkdir -p cover -python -u -m trace --count --coverdir=cover --missing alltests.py -cd .. -echo -echo -echo Uncovered lines -echo =============== -echo -( - find "$proj" -name \*.py | while read i; do - i="${i%.py}" - test -f test/cover/"${i//\//.}".cover -o "${i##*/}" == Template || echo "${i//\//.}" "`cat "$i.py" | wc -l`" - done - cd test/cover - find . \( -name . -o ! -name "$proj".\* -exec rm {} \; \) - for i in *.cover; do - sed 's/^>>>>>> \(.*"""\)/ \1/' < "$i" > "${i%.cover}" - rm "$i" - done - for i in *; do echo -n "$i "; grep -c '^>>>>>> ' "$i" || true; done -) | grep -v ' 0$' | sort -nk 2 diff --git a/docutils/test/data/config_1.txt b/docutils/test/data/config_1.txt deleted file mode 100644 index b19a213b3..000000000 --- a/docutils/test/data/config_1.txt +++ /dev/null @@ -1,26 +0,0 @@ -# Test config file (new format) - -[general] - -source-link: on -datestamp: %Y-%m-%d %H:%M UTC -generator: true - - -[restructuredtext parser] - -trim-footnote-reference-space: 1 -tab-width = 8 - - -[html4css1 writer] - -stylesheet-path: stylesheets/default.css - - -[pep_html writer] - -template: pep-html-template -stylesheet-path: stylesheets/pep.css -python-home: http://www.python.org -no-random: yes diff --git a/docutils/test/data/config_2.txt b/docutils/test/data/config_2.txt deleted file mode 100644 index 35c307c6c..000000000 --- a/docutils/test/data/config_2.txt +++ /dev/null @@ -1,11 +0,0 @@ -# Test config file (new format) - -[general] - -generator: no - - -[html4css1 writer] - -footnote-references: superscript -stylesheet-path: test.css diff --git a/docutils/test/data/config_error_handler.txt b/docutils/test/data/config_error_handler.txt deleted file mode 100644 index 82e341649..000000000 --- a/docutils/test/data/config_error_handler.txt +++ /dev/null @@ -1,2 +0,0 @@ -[general] -error_encoding: ascii:strict diff --git a/docutils/test/data/config_list.txt b/docutils/test/data/config_list.txt deleted file mode 100644 index fde6793c9..000000000 --- a/docutils/test/data/config_list.txt +++ /dev/null @@ -1,8 +0,0 @@ -[general] -expose_internals: a - -[html4css1 writer] -expose_internals: b:c:d - -[pep_html writer] -expose_internals: e diff --git a/docutils/test/data/config_list_2.txt b/docutils/test/data/config_list_2.txt deleted file mode 100644 index 6f8d69f07..000000000 --- a/docutils/test/data/config_list_2.txt +++ /dev/null @@ -1,2 +0,0 @@ -[general] -expose_internals: f diff --git a/docutils/test/data/config_old.txt b/docutils/test/data/config_old.txt deleted file mode 100644 index fa07d6dab..000000000 --- a/docutils/test/data/config_old.txt +++ /dev/null @@ -1,14 +0,0 @@ -# Test config file (old format) - -[options] - -source-link: 1 -datestamp: %Y-%m-%d %H:%M UTC -generator: 1 - -stylesheet-path: stylesheets/default.css - -pep-template: pep-html-template -pep-stylesheet-path: stylesheets/pep.css -python-home: http://www.python.org -no-random: 1 diff --git a/docutils/test/data/csv_data.txt b/docutils/test/data/csv_data.txt deleted file mode 100644 index f33f47f7f..000000000 --- a/docutils/test/data/csv_data.txt +++ /dev/null @@ -1 +0,0 @@ -foo, bar diff --git a/docutils/test/data/csv_dep.txt b/docutils/test/data/csv_dep.txt deleted file mode 100644 index 14620a926..000000000 --- a/docutils/test/data/csv_dep.txt +++ /dev/null @@ -1,2 +0,0 @@ -.. csv-table:: - :file: csv_data.txt diff --git a/docutils/test/data/dependencies.txt b/docutils/test/data/dependencies.txt deleted file mode 100644 index cc18c8f0c..000000000 --- a/docutils/test/data/dependencies.txt +++ /dev/null @@ -1,8 +0,0 @@ -.. image:: some_image.png - -.. include:: include.txt - -.. raw:: HTML - :file: raw.txt - -.. include:: include.txt diff --git a/docutils/test/data/include.txt b/docutils/test/data/include.txt deleted file mode 100644 index ae2a894bb..000000000 --- a/docutils/test/data/include.txt +++ /dev/null @@ -1 +0,0 @@ -Some include text. diff --git a/docutils/test/data/raw.txt b/docutils/test/data/raw.txt deleted file mode 100644 index e69de29bb..000000000 --- a/docutils/test/data/raw.txt +++ /dev/null diff --git a/docutils/test/data/stylesheet.txt b/docutils/test/data/stylesheet.txt deleted file mode 100644 index e69de29bb..000000000 --- a/docutils/test/data/stylesheet.txt +++ /dev/null diff --git a/docutils/test/docutils.conf b/docutils/test/docutils.conf deleted file mode 100644 index df4b1e46a..000000000 --- a/docutils/test/docutils.conf +++ /dev/null @@ -1,11 +0,0 @@ -[general] -# This tests the test framework; this config file should *not* be read -# when testing. -source-link: yes -datestamp: %Y-%m-%d %H:%M UTC (If you see this in test output, there's a bug in the test code!) -generator: on - -[buildhtml application] -# This part is not for testing, but to prevent tools/buildhtml.py from -# processing text files in and below this directory. -prune: . diff --git a/docutils/test/docutils_difflib.py b/docutils/test/docutils_difflib.py deleted file mode 100644 index a41d4d5ba..000000000 --- a/docutils/test/docutils_difflib.py +++ /dev/null @@ -1,1089 +0,0 @@ -#! /usr/bin/env python - -""" -Module difflib -- helpers for computing deltas between objects. - -Function get_close_matches(word, possibilities, n=3, cutoff=0.6): - Use SequenceMatcher to return list of the best "good enough" matches. - -Function ndiff(a, b): - Return a delta: the difference between `a` and `b` (lists of strings). - -Function restore(delta, which): - Return one of the two sequences that generated an ndiff delta. - -Class SequenceMatcher: - A flexible class for comparing pairs of sequences of any type. - -Class Differ: - For producing human-readable deltas from sequences of lines of text. -""" - -__all__ = ['get_close_matches', 'ndiff', 'restore', 'SequenceMatcher', - 'Differ'] - -TRACE = 0 - -class SequenceMatcher: - - """ - SequenceMatcher is a flexible class for comparing pairs of sequences of - any type, so long as the sequence elements are hashable. The basic - algorithm predates, and is a little fancier than, an algorithm - published in the late 1980's by Ratcliff and Obershelp under the - hyperbolic name "gestalt pattern matching". The basic idea is to find - the longest contiguous matching subsequence that contains no "junk" - elements (R-O doesn't address junk). The same idea is then applied - recursively to the pieces of the sequences to the left and to the right - of the matching subsequence. This does not yield minimal edit - sequences, but does tend to yield matches that "look right" to people. - - SequenceMatcher tries to compute a "human-friendly diff" between two - sequences. Unlike e.g. UNIX(tm) diff, the fundamental notion is the - longest *contiguous* & junk-free matching subsequence. That's what - catches peoples' eyes. The Windows(tm) windiff has another interesting - notion, pairing up elements that appear uniquely in each sequence. - That, and the method here, appear to yield more intuitive difference - reports than does diff. This method appears to be the least vulnerable - to synching up on blocks of "junk lines", though (like blank lines in - ordinary text files, or maybe "<P>" lines in HTML files). That may be - because this is the only method of the 3 that has a *concept* of - "junk" <wink>. - - Example, comparing two strings, and considering blanks to be "junk": - - >>> s = SequenceMatcher(lambda x: x == " ", - ... "private Thread currentThread;", - ... "private volatile Thread currentThread;") - >>> - - .ratio() returns a float in [0, 1], measuring the "similarity" of the - sequences. As a rule of thumb, a .ratio() value over 0.6 means the - sequences are close matches: - - >>> print round(s.ratio(), 3) - 0.866 - >>> - - If you're only interested in where the sequences match, - .get_matching_blocks() is handy: - - >>> for block in s.get_matching_blocks(): - ... print "a[%d] and b[%d] match for %d elements" % block - a[0] and b[0] match for 8 elements - a[8] and b[17] match for 6 elements - a[14] and b[23] match for 15 elements - a[29] and b[38] match for 0 elements - - Note that the last tuple returned by .get_matching_blocks() is always a - dummy, (len(a), len(b), 0), and this is the only case in which the last - tuple element (number of elements matched) is 0. - - If you want to know how to change the first sequence into the second, - use .get_opcodes(): - - >>> for opcode in s.get_opcodes(): - ... print "%6s a[%d:%d] b[%d:%d]" % opcode - equal a[0:8] b[0:8] - insert a[8:8] b[8:17] - equal a[8:14] b[17:23] - equal a[14:29] b[23:38] - - See the Differ class for a fancy human-friendly file differencer, which - uses SequenceMatcher both to compare sequences of lines, and to compare - sequences of characters within similar (near-matching) lines. - - See also function get_close_matches() in this module, which shows how - simple code building on SequenceMatcher can be used to do useful work. - - Timing: Basic R-O is cubic time worst case and quadratic time expected - case. SequenceMatcher is quadratic time for the worst case and has - expected-case behavior dependent in a complicated way on how many - elements the sequences have in common; best case time is linear. - - Methods: - - __init__(isjunk=None, a='', b='') - Construct a SequenceMatcher. - - set_seqs(a, b) - Set the two sequences to be compared. - - set_seq1(a) - Set the first sequence to be compared. - - set_seq2(b) - Set the second sequence to be compared. - - find_longest_match(alo, ahi, blo, bhi) - Find longest matching block in a[alo:ahi] and b[blo:bhi]. - - get_matching_blocks() - Return list of triples describing matching subsequences. - - get_opcodes() - Return list of 5-tuples describing how to turn a into b. - - ratio() - Return a measure of the sequences' similarity (float in [0,1]). - - quick_ratio() - Return an upper bound on .ratio() relatively quickly. - - real_quick_ratio() - Return an upper bound on ratio() very quickly. - """ - - def __init__(self, isjunk=None, a='', b=''): - """Construct a SequenceMatcher. - - Optional arg isjunk is None (the default), or a one-argument - function that takes a sequence element and returns true iff the - element is junk. None is equivalent to passing "lambda x: 0", i.e. - no elements are considered to be junk. For example, pass - lambda x: x in " \\t" - if you're comparing lines as sequences of characters, and don't - want to synch up on blanks or hard tabs. - - Optional arg a is the first of two sequences to be compared. By - default, an empty string. The elements of a must be hashable. See - also .set_seqs() and .set_seq1(). - - Optional arg b is the second of two sequences to be compared. By - default, an empty string. The elements of b must be hashable. See - also .set_seqs() and .set_seq2(). - """ - - # Members: - # a - # first sequence - # b - # second sequence; differences are computed as "what do - # we need to do to 'a' to change it into 'b'?" - # b2j - # for x in b, b2j[x] is a list of the indices (into b) - # at which x appears; junk elements do not appear - # b2jhas - # b2j.has_key - # fullbcount - # for x in b, fullbcount[x] == the number of times x - # appears in b; only materialized if really needed (used - # only for computing quick_ratio()) - # matching_blocks - # a list of (i, j, k) triples, where a[i:i+k] == b[j:j+k]; - # ascending & non-overlapping in i and in j; terminated by - # a dummy (len(a), len(b), 0) sentinel - # opcodes - # a list of (tag, i1, i2, j1, j2) tuples, where tag is - # one of - # 'replace' a[i1:i2] should be replaced by b[j1:j2] - # 'delete' a[i1:i2] should be deleted - # 'insert' b[j1:j2] should be inserted - # 'equal' a[i1:i2] == b[j1:j2] - # isjunk - # a user-supplied function taking a sequence element and - # returning true iff the element is "junk" -- this has - # subtle but helpful effects on the algorithm, which I'll - # get around to writing up someday <0.9 wink>. - # DON'T USE! Only __chain_b uses this. Use isbjunk. - # isbjunk - # for x in b, isbjunk(x) == isjunk(x) but much faster; - # it's really the has_key method of a hidden dict. - # DOES NOT WORK for x in a! - - self.isjunk = isjunk - self.a = self.b = None - self.set_seqs(a, b) - - def set_seqs(self, a, b): - """Set the two sequences to be compared. - - >>> s = SequenceMatcher() - >>> s.set_seqs("abcd", "bcde") - >>> s.ratio() - 0.75 - """ - - self.set_seq1(a) - self.set_seq2(b) - - def set_seq1(self, a): - """Set the first sequence to be compared. - - The second sequence to be compared is not changed. - - >>> s = SequenceMatcher(None, "abcd", "bcde") - >>> s.ratio() - 0.75 - >>> s.set_seq1("bcde") - >>> s.ratio() - 1.0 - >>> - - SequenceMatcher computes and caches detailed information about the - second sequence, so if you want to compare one sequence S against - many sequences, use .set_seq2(S) once and call .set_seq1(x) - repeatedly for each of the other sequences. - - See also set_seqs() and set_seq2(). - """ - - if a is self.a: - return - self.a = a - self.matching_blocks = self.opcodes = None - - def set_seq2(self, b): - """Set the second sequence to be compared. - - The first sequence to be compared is not changed. - - >>> s = SequenceMatcher(None, "abcd", "bcde") - >>> s.ratio() - 0.75 - >>> s.set_seq2("abcd") - >>> s.ratio() - 1.0 - >>> - - SequenceMatcher computes and caches detailed information about the - second sequence, so if you want to compare one sequence S against - many sequences, use .set_seq2(S) once and call .set_seq1(x) - repeatedly for each of the other sequences. - - See also set_seqs() and set_seq1(). - """ - - if b is self.b: - return - self.b = b - self.matching_blocks = self.opcodes = None - self.fullbcount = None - self.__chain_b() - - # For each element x in b, set b2j[x] to a list of the indices in - # b where x appears; the indices are in increasing order; note that - # the number of times x appears in b is len(b2j[x]) ... - # when self.isjunk is defined, junk elements don't show up in this - # map at all, which stops the central find_longest_match method - # from starting any matching block at a junk element ... - # also creates the fast isbjunk function ... - # note that this is only called when b changes; so for cross-product - # kinds of matches, it's best to call set_seq2 once, then set_seq1 - # repeatedly - - def __chain_b(self): - # Because isjunk is a user-defined (not C) function, and we test - # for junk a LOT, it's important to minimize the number of calls. - # Before the tricks described here, __chain_b was by far the most - # time-consuming routine in the whole module! If anyone sees - # Jim Roskind, thank him again for profile.py -- I never would - # have guessed that. - # The first trick is to build b2j ignoring the possibility - # of junk. I.e., we don't call isjunk at all yet. Throwing - # out the junk later is much cheaper than building b2j "right" - # from the start. - b = self.b - self.b2j = b2j = {} - self.b2jhas = b2jhas = b2j.has_key - for i in xrange(len(b)): - elt = b[i] - if b2jhas(elt): - b2j[elt].append(i) - else: - b2j[elt] = [i] - - # Now b2j.keys() contains elements uniquely, and especially when - # the sequence is a string, that's usually a good deal smaller - # than len(string). The difference is the number of isjunk calls - # saved. - isjunk, junkdict = self.isjunk, {} - if isjunk: - for elt in b2j.keys(): - if isjunk(elt): - junkdict[elt] = 1 # value irrelevant; it's a set - del b2j[elt] - - # Now for x in b, isjunk(x) == junkdict.has_key(x), but the - # latter is much faster. Note too that while there may be a - # lot of junk in the sequence, the number of *unique* junk - # elements is probably small. So the memory burden of keeping - # this dict alive is likely trivial compared to the size of b2j. - self.isbjunk = junkdict.has_key - - def find_longest_match(self, alo, ahi, blo, bhi): - """Find longest matching block in a[alo:ahi] and b[blo:bhi]. - - If isjunk is not defined: - - Return (i,j,k) such that a[i:i+k] is equal to b[j:j+k], where - alo <= i <= i+k <= ahi - blo <= j <= j+k <= bhi - and for all (i',j',k') meeting those conditions, - k >= k' - i <= i' - and if i == i', j <= j' - - In other words, of all maximal matching blocks, return one that - starts earliest in a, and of all those maximal matching blocks that - start earliest in a, return the one that starts earliest in b. - - >>> s = SequenceMatcher(None, " abcd", "abcd abcd") - >>> s.find_longest_match(0, 5, 0, 9) - (0, 4, 5) - - If isjunk is defined, first the longest matching block is - determined as above, but with the additional restriction that no - junk element appears in the block. Then that block is extended as - far as possible by matching (only) junk elements on both sides. So - the resulting block never matches on junk except as identical junk - happens to be adjacent to an "interesting" match. - - Here's the same example as before, but considering blanks to be - junk. That prevents " abcd" from matching the " abcd" at the tail - end of the second sequence directly. Instead only the "abcd" can - match, and matches the leftmost "abcd" in the second sequence: - - >>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd") - >>> s.find_longest_match(0, 5, 0, 9) - (1, 0, 4) - - If no blocks match, return (alo, blo, 0). - - >>> s = SequenceMatcher(None, "ab", "c") - >>> s.find_longest_match(0, 2, 0, 1) - (0, 0, 0) - """ - - # CAUTION: stripping common prefix or suffix would be incorrect. - # E.g., - # ab - # acab - # Longest matching block is "ab", but if common prefix is - # stripped, it's "a" (tied with "b"). UNIX(tm) diff does so - # strip, so ends up claiming that ab is changed to acab by - # inserting "ca" in the middle. That's minimal but unintuitive: - # "it's obvious" that someone inserted "ac" at the front. - # Windiff ends up at the same place as diff, but by pairing up - # the unique 'b's and then matching the first two 'a's. - - a, b, b2j, isbjunk = self.a, self.b, self.b2j, self.isbjunk - besti, bestj, bestsize = alo, blo, 0 - # find longest junk-free match - # during an iteration of the loop, j2len[j] = length of longest - # junk-free match ending with a[i-1] and b[j] - j2len = {} - nothing = [] - for i in xrange(alo, ahi): - # look at all instances of a[i] in b; note that because - # b2j has no junk keys, the loop is skipped if a[i] is junk - j2lenget = j2len.get - newj2len = {} - for j in b2j.get(a[i], nothing): - # a[i] matches b[j] - if j < blo: - continue - if j >= bhi: - break - k = newj2len[j] = j2lenget(j-1, 0) + 1 - if k > bestsize: - besti, bestj, bestsize = i-k+1, j-k+1, k - j2len = newj2len - - # Now that we have a wholly interesting match (albeit possibly - # empty!), we may as well suck up the matching junk on each - # side of it too. Can't think of a good reason not to, and it - # saves post-processing the (possibly considerable) expense of - # figuring out what to do with it. In the case of an empty - # interesting match, this is clearly the right thing to do, - # because no other kind of match is possible in the regions. - while besti > alo and bestj > blo and \ - isbjunk(b[bestj-1]) and \ - a[besti-1] == b[bestj-1]: - besti, bestj, bestsize = besti-1, bestj-1, bestsize+1 - while besti+bestsize < ahi and bestj+bestsize < bhi and \ - isbjunk(b[bestj+bestsize]) and \ - a[besti+bestsize] == b[bestj+bestsize]: - bestsize = bestsize + 1 - - if TRACE: - print "get_matching_blocks", alo, ahi, blo, bhi - print " returns", besti, bestj, bestsize - return besti, bestj, bestsize - - def get_matching_blocks(self): - """Return list of triples describing matching subsequences. - - Each triple is of the form (i, j, n), and means that - a[i:i+n] == b[j:j+n]. The triples are monotonically increasing in - i and in j. - - The last triple is a dummy, (len(a), len(b), 0), and is the only - triple with n==0. - - >>> s = SequenceMatcher(None, "abxcd", "abcd") - >>> s.get_matching_blocks() - [(0, 0, 2), (3, 2, 2), (5, 4, 0)] - """ - - if self.matching_blocks is not None: - return self.matching_blocks - self.matching_blocks = [] - la, lb = len(self.a), len(self.b) - self.__helper(0, la, 0, lb, self.matching_blocks) - self.matching_blocks.append( (la, lb, 0) ) - if TRACE: - print '*** matching blocks', self.matching_blocks - return self.matching_blocks - - # builds list of matching blocks covering a[alo:ahi] and - # b[blo:bhi], appending them in increasing order to answer - - def __helper(self, alo, ahi, blo, bhi, answer): - i, j, k = x = self.find_longest_match(alo, ahi, blo, bhi) - # a[alo:i] vs b[blo:j] unknown - # a[i:i+k] same as b[j:j+k] - # a[i+k:ahi] vs b[j+k:bhi] unknown - if k: - if alo < i and blo < j: - self.__helper(alo, i, blo, j, answer) - answer.append(x) - if i+k < ahi and j+k < bhi: - self.__helper(i+k, ahi, j+k, bhi, answer) - - def get_opcodes(self): - """Return list of 5-tuples describing how to turn a into b. - - Each tuple is of the form (tag, i1, i2, j1, j2). The first tuple - has i1 == j1 == 0, and remaining tuples have i1 == the i2 from the - tuple preceding it, and likewise for j1 == the previous j2. - - The tags are strings, with these meanings: - - 'replace': a[i1:i2] should be replaced by b[j1:j2] - 'delete': a[i1:i2] should be deleted. - Note that j1==j2 in this case. - 'insert': b[j1:j2] should be inserted at a[i1:i1]. - Note that i1==i2 in this case. - 'equal': a[i1:i2] == b[j1:j2] - - >>> a = "qabxcd" - >>> b = "abycdf" - >>> s = SequenceMatcher(None, a, b) - >>> for tag, i1, i2, j1, j2 in s.get_opcodes(): - ... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" % - ... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2])) - delete a[0:1] (q) b[0:0] () - equal a[1:3] (ab) b[0:2] (ab) - replace a[3:4] (x) b[2:3] (y) - equal a[4:6] (cd) b[3:5] (cd) - insert a[6:6] () b[5:6] (f) - """ - - if self.opcodes is not None: - return self.opcodes - i = j = 0 - self.opcodes = answer = [] - for ai, bj, size in self.get_matching_blocks(): - # invariant: we've pumped out correct diffs to change - # a[:i] into b[:j], and the next matching block is - # a[ai:ai+size] == b[bj:bj+size]. So we need to pump - # out a diff to change a[i:ai] into b[j:bj], pump out - # the matching block, and move (i,j) beyond the match - tag = '' - if i < ai and j < bj: - tag = 'replace' - elif i < ai: - tag = 'delete' - elif j < bj: - tag = 'insert' - if tag: - answer.append( (tag, i, ai, j, bj) ) - i, j = ai+size, bj+size - # the list of matching blocks is terminated by a - # sentinel with size 0 - if size: - answer.append( ('equal', ai, i, bj, j) ) - return answer - - def ratio(self): - """Return a measure of the sequences' similarity (float in [0,1]). - - Where T is the total number of elements in both sequences, and - M is the number of matches, this is 2,0*M / T. - Note that this is 1 if the sequences are identical, and 0 if - they have nothing in common. - - .ratio() is expensive to compute if you haven't already computed - .get_matching_blocks() or .get_opcodes(), in which case you may - want to try .quick_ratio() or .real_quick_ratio() first to get an - upper bound. - - >>> s = SequenceMatcher(None, "abcd", "bcde") - >>> s.ratio() - 0.75 - >>> s.quick_ratio() - 0.75 - >>> s.real_quick_ratio() - 1.0 - """ - - matches = reduce(lambda sum, triple: sum + triple[-1], - self.get_matching_blocks(), 0) - return 2.0 * matches / (len(self.a) + len(self.b)) - - def quick_ratio(self): - """Return an upper bound on ratio() relatively quickly. - - This isn't defined beyond that it is an upper bound on .ratio(), and - is faster to compute. - """ - - # viewing a and b as multisets, set matches to the cardinality - # of their intersection; this counts the number of matches - # without regard to order, so is clearly an upper bound - if self.fullbcount is None: - self.fullbcount = fullbcount = {} - for elt in self.b: - fullbcount[elt] = fullbcount.get(elt, 0) + 1 - fullbcount = self.fullbcount - # avail[x] is the number of times x appears in 'b' less the - # number of times we've seen it in 'a' so far ... kinda - avail = {} - availhas, matches = avail.has_key, 0 - for elt in self.a: - if availhas(elt): - numb = avail[elt] - else: - numb = fullbcount.get(elt, 0) - avail[elt] = numb - 1 - if numb > 0: - matches = matches + 1 - return 2.0 * matches / (len(self.a) + len(self.b)) - - def real_quick_ratio(self): - """Return an upper bound on ratio() very quickly. - - This isn't defined beyond that it is an upper bound on .ratio(), and - is faster to compute than either .ratio() or .quick_ratio(). - """ - - la, lb = len(self.a), len(self.b) - # can't have more matches than the number of elements in the - # shorter sequence - return 2.0 * min(la, lb) / (la + lb) - -def get_close_matches(word, possibilities, n=3, cutoff=0.6): - """Use SequenceMatcher to return list of the best "good enough" matches. - - word is a sequence for which close matches are desired (typically a - string). - - possibilities is a list of sequences against which to match word - (typically a list of strings). - - Optional arg n (default 3) is the maximum number of close matches to - return. n must be > 0. - - Optional arg cutoff (default 0.6) is a float in [0, 1]. Possibilities - that don't score at least that similar to word are ignored. - - The best (no more than n) matches among the possibilities are returned - in a list, sorted by similarity score, most similar first. - - >>> get_close_matches("appel", ["ape", "apple", "peach", "puppy"]) - ['apple', 'ape'] - >>> import keyword as _keyword - >>> get_close_matches("wheel", _keyword.kwlist) - ['while'] - >>> get_close_matches("apple", _keyword.kwlist) - [] - >>> get_close_matches("accept", _keyword.kwlist) - ['except'] - """ - - if not n > 0: - raise ValueError("n must be > 0: " + `n`) - if not 0.0 <= cutoff <= 1.0: - raise ValueError("cutoff must be in [0.0, 1.0]: " + `cutoff`) - result = [] - s = SequenceMatcher() - s.set_seq2(word) - for x in possibilities: - s.set_seq1(x) - if s.real_quick_ratio() >= cutoff and \ - s.quick_ratio() >= cutoff and \ - s.ratio() >= cutoff: - result.append((s.ratio(), x)) - # Sort by score. - result.sort() - # Retain only the best n. - result = result[-n:] - # Move best-scorer to head of list. - result.reverse() - # Strip scores. - return [x for score, x in result] - - -def _count_leading(line, ch): - """ - Return number of `ch` characters at the start of `line`. - - Example: - - >>> _count_leading(' abc', ' ') - 3 - """ - - i, n = 0, len(line) - while i < n and line[i] == ch: - i += 1 - return i - -class Differ: - r""" - Differ is a class for comparing sequences of lines of text, and - producing human-readable differences or deltas. Differ uses - SequenceMatcher both to compare sequences of lines, and to compare - sequences of characters within similar (near-matching) lines. - - Each line of a Differ delta begins with a two-letter code: - - '- ' line unique to sequence 1 - '+ ' line unique to sequence 2 - ' ' line common to both sequences - '? ' line not present in either input sequence - - Lines beginning with '? ' attempt to guide the eye to intraline - differences, and were not present in either input sequence. These lines - can be confusing if the sequences contain tab characters. - - Note that Differ makes no claim to produce a *minimal* diff. To the - contrary, minimal diffs are often counter-intuitive, because they synch - up anywhere possible, sometimes accidental matches 100 pages apart. - Restricting synch points to contiguous matches preserves some notion of - locality, at the occasional cost of producing a longer diff. - - Example: Comparing two texts. - - First we set up the texts, sequences of individual single-line strings - ending with newlines (such sequences can also be obtained from the - `readlines()` method of file-like objects): - - >>> text1 = ''' 1. Beautiful is better than ugly. - ... 2. Explicit is better than implicit. - ... 3. Simple is better than complex. - ... 4. Complex is better than complicated. - ... '''.splitlines(1) - >>> len(text1) - 4 - >>> text1[0][-1] - '\n' - >>> text2 = ''' 1. Beautiful is better than ugly. - ... 3. Simple is better than complex. - ... 4. Complicated is better than complex. - ... 5. Flat is better than nested. - ... '''.splitlines(1) - - Next we instantiate a Differ object: - - >>> d = Differ() - - Note that when instantiating a Differ object we may pass functions to - filter out line and character 'junk'. See Differ.__init__ for details. - - Finally, we compare the two: - - >>> result = d.compare(text1, text2) - - 'result' is a list of strings, so let's pretty-print it: - - >>> from pprint import pprint as _pprint - >>> _pprint(result) - [' 1. Beautiful is better than ugly.\n', - '- 2. Explicit is better than implicit.\n', - '- 3. Simple is better than complex.\n', - '+ 3. Simple is better than complex.\n', - '? ++\n', - '- 4. Complex is better than complicated.\n', - '? ^ ---- ^\n', - '+ 4. Complicated is better than complex.\n', - '? ++++ ^ ^\n', - '+ 5. Flat is better than nested.\n'] - - As a single multi-line string it looks like this: - - >>> print ''.join(result), - 1. Beautiful is better than ugly. - - 2. Explicit is better than implicit. - - 3. Simple is better than complex. - + 3. Simple is better than complex. - ? ++ - - 4. Complex is better than complicated. - ? ^ ---- ^ - + 4. Complicated is better than complex. - ? ++++ ^ ^ - + 5. Flat is better than nested. - - Methods: - - __init__(linejunk=None, charjunk=None) - Construct a text differencer, with optional filters. - - compare(a, b) - Compare two sequences of lines; return the resulting delta (list). - """ - - def __init__(self, linejunk=None, charjunk=None): - """ - Construct a text differencer, with optional filters. - - The two optional keyword parameters are for filter functions: - - - `linejunk`: A function that should accept a single string argument, - and return true iff the string is junk. The module-level function - `IS_LINE_JUNK` may be used to filter out lines without visible - characters, except for at most one splat ('#'). - - - `charjunk`: A function that should accept a string of length 1. The - module-level function `IS_CHARACTER_JUNK` may be used to filter out - whitespace characters (a blank or tab; **note**: bad idea to include - newline in this!). - """ - - self.linejunk = linejunk - self.charjunk = charjunk - self.results = [] - - def compare(self, a, b): - r""" - Compare two sequences of lines; return the resulting delta (list). - - Each sequence must contain individual single-line strings ending with - newlines. Such sequences can be obtained from the `readlines()` method - of file-like objects. The list returned is also made up of - newline-terminated strings, ready to be used with the `writelines()` - method of a file-like object. - - Example: - - >>> print ''.join(Differ().compare('one\ntwo\nthree\n'.splitlines(1), - ... 'ore\ntree\nemu\n'.splitlines(1))), - - one - ? ^ - + ore - ? ^ - - two - - three - ? - - + tree - + emu - """ - - cruncher = SequenceMatcher(self.linejunk, a, b) - for tag, alo, ahi, blo, bhi in cruncher.get_opcodes(): - if tag == 'replace': - self._fancy_replace(a, alo, ahi, b, blo, bhi) - elif tag == 'delete': - self._dump('-', a, alo, ahi) - elif tag == 'insert': - self._dump('+', b, blo, bhi) - elif tag == 'equal': - self._dump(' ', a, alo, ahi) - else: - raise ValueError, 'unknown tag ' + `tag` - results = self.results - self.results = [] - return results - - def _dump(self, tag, x, lo, hi): - """Store comparison results for a same-tagged range.""" - for i in xrange(lo, hi): - self.results.append('%s %s' % (tag, x[i])) - - def _plain_replace(self, a, alo, ahi, b, blo, bhi): - assert alo < ahi and blo < bhi - # dump the shorter block first -- reduces the burden on short-term - # memory if the blocks are of very different sizes - if bhi - blo < ahi - alo: - self._dump('+', b, blo, bhi) - self._dump('-', a, alo, ahi) - else: - self._dump('-', a, alo, ahi) - self._dump('+', b, blo, bhi) - - def _fancy_replace(self, a, alo, ahi, b, blo, bhi): - r""" - When replacing one block of lines with another, search the blocks - for *similar* lines; the best-matching pair (if any) is used as a - synch point, and intraline difference marking is done on the - similar pair. Lots of work, but often worth it. - - Example: - - >>> d = Differ() - >>> d._fancy_replace(['abcDefghiJkl\n'], 0, 1, ['abcdefGhijkl\n'], 0, 1) - >>> print ''.join(d.results), - - abcDefghiJkl - ? ^ ^ ^ - + abcdefGhijkl - ? ^ ^ ^ - """ - - if TRACE: - self.results.append('*** _fancy_replace %s %s %s %s\n' - % (alo, ahi, blo, bhi)) - self._dump('>', a, alo, ahi) - self._dump('<', b, blo, bhi) - - # don't synch up unless the lines have a similarity score of at - # least cutoff; best_ratio tracks the best score seen so far - best_ratio, cutoff = 0.74, 0.75 - cruncher = SequenceMatcher(self.charjunk) - eqi, eqj = None, None # 1st indices of equal lines (if any) - - # search for the pair that matches best without being identical - # (identical lines must be junk lines, & we don't want to synch up - # on junk -- unless we have to) - for j in xrange(blo, bhi): - bj = b[j] - cruncher.set_seq2(bj) - for i in xrange(alo, ahi): - ai = a[i] - if ai == bj: - if eqi is None: - eqi, eqj = i, j - continue - cruncher.set_seq1(ai) - # computing similarity is expensive, so use the quick - # upper bounds first -- have seen this speed up messy - # compares by a factor of 3. - # note that ratio() is only expensive to compute the first - # time it's called on a sequence pair; the expensive part - # of the computation is cached by cruncher - if cruncher.real_quick_ratio() > best_ratio and \ - cruncher.quick_ratio() > best_ratio and \ - cruncher.ratio() > best_ratio: - best_ratio, best_i, best_j = cruncher.ratio(), i, j - if best_ratio < cutoff: - # no non-identical "pretty close" pair - if eqi is None: - # no identical pair either -- treat it as a straight replace - self._plain_replace(a, alo, ahi, b, blo, bhi) - return - # no close pair, but an identical pair -- synch up on that - best_i, best_j, best_ratio = eqi, eqj, 1.0 - else: - # there's a close pair, so forget the identical pair (if any) - eqi = None - - # a[best_i] very similar to b[best_j]; eqi is None iff they're not - # identical - if TRACE: - self.results.append('*** best_ratio %s %s %s %s\n' - % (best_ratio, best_i, best_j)) - self._dump('>', a, best_i, best_i+1) - self._dump('<', b, best_j, best_j+1) - - # pump out diffs from before the synch point - self._fancy_helper(a, alo, best_i, b, blo, best_j) - - # do intraline marking on the synch pair - aelt, belt = a[best_i], b[best_j] - if eqi is None: - # pump out a '-', '?', '+', '?' quad for the synched lines - atags = btags = "" - cruncher.set_seqs(aelt, belt) - for tag, ai1, ai2, bj1, bj2 in cruncher.get_opcodes(): - la, lb = ai2 - ai1, bj2 - bj1 - if tag == 'replace': - atags += '^' * la - btags += '^' * lb - elif tag == 'delete': - atags += '-' * la - elif tag == 'insert': - btags += '+' * lb - elif tag == 'equal': - atags += ' ' * la - btags += ' ' * lb - else: - raise ValueError, 'unknown tag ' + `tag` - self._qformat(aelt, belt, atags, btags) - else: - # the synch pair is identical - self.results.append(' ' + aelt) - - # pump out diffs from after the synch point - self._fancy_helper(a, best_i+1, ahi, b, best_j+1, bhi) - - def _fancy_helper(self, a, alo, ahi, b, blo, bhi): - if alo < ahi: - if blo < bhi: - self._fancy_replace(a, alo, ahi, b, blo, bhi) - else: - self._dump('-', a, alo, ahi) - elif blo < bhi: - self._dump('+', b, blo, bhi) - - def _qformat(self, aline, bline, atags, btags): - r""" - Format "?" output and deal with leading tabs. - - Example: - - >>> d = Differ() - >>> d._qformat('\tabcDefghiJkl\n', '\t\tabcdefGhijkl\n', - ... ' ^ ^ ^ ', '+ ^ ^ ^ ') - >>> for line in d.results: print repr(line) - ... - '- \tabcDefghiJkl\n' - '? \t ^ ^ ^\n' - '+ \t\tabcdefGhijkl\n' - '? \t ^ ^ ^\n' - """ - - # Can hurt, but will probably help most of the time. - common = min(_count_leading(aline, "\t"), - _count_leading(bline, "\t")) - common = min(common, _count_leading(atags[:common], " ")) - atags = atags[common:].rstrip() - btags = btags[common:].rstrip() - - self.results.append("- " + aline) - if atags: - self.results.append("? %s%s\n" % ("\t" * common, atags)) - - self.results.append("+ " + bline) - if btags: - self.results.append("? %s%s\n" % ("\t" * common, btags)) - -# With respect to junk, an earlier version of ndiff simply refused to -# *start* a match with a junk element. The result was cases like this: -# before: private Thread currentThread; -# after: private volatile Thread currentThread; -# If you consider whitespace to be junk, the longest contiguous match -# not starting with junk is "e Thread currentThread". So ndiff reported -# that "e volatil" was inserted between the 't' and the 'e' in "private". -# While an accurate view, to people that's absurd. The current version -# looks for matching blocks that are entirely junk-free, then extends the -# longest one of those as far as possible but only with matching junk. -# So now "currentThread" is matched, then extended to suck up the -# preceding blank; then "private" is matched, and extended to suck up the -# following blank; then "Thread" is matched; and finally ndiff reports -# that "volatile " was inserted before "Thread". The only quibble -# remaining is that perhaps it was really the case that " volatile" -# was inserted after "private". I can live with that <wink>. - -import re - -def IS_LINE_JUNK(line, pat=re.compile(r"\s*#?\s*$").match): - r""" - Return 1 for ignorable line: iff `line` is blank or contains a single '#'. - - Examples: - - >>> IS_LINE_JUNK('\n') - 1 - >>> IS_LINE_JUNK(' # \n') - 1 - >>> IS_LINE_JUNK('hello\n') - 0 - """ - - return pat(line) is not None - -def IS_CHARACTER_JUNK(ch, ws=" \t"): - r""" - Return 1 for ignorable character: iff `ch` is a space or tab. - - Examples: - - >>> IS_CHARACTER_JUNK(' ') - 1 - >>> IS_CHARACTER_JUNK('\t') - 1 - >>> IS_CHARACTER_JUNK('\n') - 0 - >>> IS_CHARACTER_JUNK('x') - 0 - """ - - return ch in ws - -del re - -def ndiff(a, b, linejunk=IS_LINE_JUNK, charjunk=IS_CHARACTER_JUNK): - r""" - Compare `a` and `b` (lists of strings); return a `Differ`-style delta. - - Optional keyword parameters `linejunk` and `charjunk` are for filter - functions (or None): - - - linejunk: A function that should accept a single string argument, and - return true iff the string is junk. The default is module-level function - IS_LINE_JUNK, which filters out lines without visible characters, except - for at most one splat ('#'). - - - charjunk: A function that should accept a string of length 1. The - default is module-level function IS_CHARACTER_JUNK, which filters out - whitespace characters (a blank or tab; note: bad idea to include newline - in this!). - - Tools/scripts/ndiff.py is a command-line front-end to this function. - - Example: - - >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1), - ... 'ore\ntree\nemu\n'.splitlines(1)) - >>> print ''.join(diff), - - one - ? ^ - + ore - ? ^ - - two - - three - ? - - + tree - + emu - """ - return Differ(linejunk, charjunk).compare(a, b) - -def restore(delta, which): - r""" - Return one of the two sequences that generated a delta. - - Given a `delta` produced by `Differ.compare()` or `ndiff()`, extract - lines originating from file 1 or 2 (parameter `which`), stripping off line - prefixes. - - Examples: - - >>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1), - ... 'ore\ntree\nemu\n'.splitlines(1)) - >>> print ''.join(restore(diff, 1)), - one - two - three - >>> print ''.join(restore(diff, 2)), - ore - tree - emu - """ - try: - tag = {1: "- ", 2: "+ "}[int(which)] - except KeyError: - raise ValueError, ('unknown delta choice (must be 1 or 2): %r' - % which) - prefixes = (" ", tag) - results = [] - for line in delta: - if line[:2] in prefixes: - results.append(line[2:]) - return results - -def _test(): - import doctest, difflib - return doctest.testmod(difflib) - -if __name__ == "__main__": - _test() diff --git a/docutils/test/functional/README.txt b/docutils/test/functional/README.txt deleted file mode 100644 index fc104d52e..000000000 --- a/docutils/test/functional/README.txt +++ /dev/null @@ -1,5 +0,0 @@ -This directory stores data files for functional tests. - -Please see the documentation on `functional testing`__ for details. - -__ ../../docs/dev/testing.html#functional diff --git a/docutils/test/functional/expected/compact_lists.html b/docutils/test/functional/expected/compact_lists.html deleted file mode 100644 index a486f378a..000000000 --- a/docutils/test/functional/expected/compact_lists.html +++ /dev/null @@ -1,47 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> -<title></title> -<link rel="stylesheet" href="../../../docutils/writers/html4css1/html4css1.css" type="text/css" /> -</head> -<body> -<div class="document"> -<ul class="simple"> -<li>This is an ordinary simple bullet list.</li> -<li>It should be made compact (<p> & </p> tags omitted).</li> -</ul> -<hr class="docutils" /> -<ul> -<li><p class="first">This is a bullet list that is not simple.</p> -<p>There are multiple paragraphs in some items.</p> -</li> -<li><p class="first">It should not be made compact.</p> -</li> -<li><p class="first">Even though some items may have only one paragraph.</p> -</li> -</ul> -<hr class="docutils" /> -<ul class="open"> -<li><p class="first">This is a simple bullet list, but class="open" is set.</p> -</li> -<li><p class="first">It should not be made compact.</p> -</li> -</ul> -<hr class="docutils" /> -<ul class="compact simple"> -<li>This is a bullet list that is not simple.<p>There are multiple paragraphs in some items.</p> -</li> -<li>However, the class="compact" setting will cause -all first paragraph's <p> & </p> tags to be omitted.</li> -<li>Items with multiple paragraphs will not appear changed.</li> -<li>Items may have one paragraph, or multiple.<p>Items with multiple paragraphs will still be followed -by vertical whitespace because of the later paragraphs.</p> -</li> -<li>The effect is interesting.</li> -</ul> -</div> -</body> -</html> diff --git a/docutils/test/functional/expected/dangerous.html b/docutils/test/functional/expected/dangerous.html deleted file mode 100644 index bba9f3408..000000000 --- a/docutils/test/functional/expected/dangerous.html +++ /dev/null @@ -1,66 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> -<title></title> -<link rel="stylesheet" href="../../../docutils/writers/html4css1/html4css1.css" type="text/css" /> -</head> -<body> -<div class="document"> -<p>Potentially dangerous features (security holes):</p> -<div class="system-message"> -<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">functional/input/dangerous.txt</tt>, line 3)</p> -<p>"include" directive disabled.</p> -<pre class="literal-block"> -.. include:: /etc/passwd -</pre> -</div> -<div class="system-message"> -<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">functional/input/dangerous.txt</tt>, line 4)</p> -<p>"raw" directive disabled.</p> -<pre class="literal-block"> -.. raw:: html - :file: /etc/passwd -</pre> -</div> -<div class="system-message"> -<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">functional/input/dangerous.txt</tt>, line 6)</p> -<p>"raw" directive disabled.</p> -<pre class="literal-block"> -.. raw:: html - :url: file:///etc/passwd -</pre> -</div> -<div class="system-message"> -<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">functional/input/dangerous.txt</tt>, line 8)</p> -<p>"raw" directive disabled.</p> -<pre class="literal-block"> -.. raw:: html - - <script> - that does something really nasty - </script> -</pre> -</div> -<div class="system-message"> -<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">functional/input/dangerous.txt</tt>, line 13)</p> -<p>File and URL access deactivated; ignoring "csv-table" directive.</p> -<pre class="literal-block"> -.. csv-table:: :file: /etc/passwd -</pre> -</div> -<div class="system-message"> -<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">functional/input/dangerous.txt</tt>, line 14)</p> -<p>File and URL access deactivated; ignoring "csv-table" directive.</p> -<pre class="literal-block"> -.. csv-table:: :url: file:///etc/passwd -</pre> -</div> -<div class="figure"> -<img alt="picture.png" src="picture.png" /> -</div> -</div> -</body> -</html> diff --git a/docutils/test/functional/expected/field_name_limit.html b/docutils/test/functional/expected/field_name_limit.html deleted file mode 100644 index b4148c043..000000000 --- a/docutils/test/functional/expected/field_name_limit.html +++ /dev/null @@ -1,28 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> -<title></title> -<link rel="stylesheet" href="../../../docutils/writers/html4css1/html4css1.css" type="text/css" /> -</head> -<body> -<div class="document"> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field"><th class="field-name">short:</th><td class="field-body">This field's name is short.</td> -</tr> -<tr class="field"><th class="field-name">medium-length:</th><td class="field-body">This field's name is medium-length.</td> -</tr> -<tr class="field"><th class="field-name">long field name:</th><td class="field-body">This field's name is long.</td> -</tr> -<tr class="field"><th class="field-name">very very long field name:</th><td class="field-body">This field's name is quite long.</td> -</tr> -</tbody> -</table> -</div> -</body> -</html> diff --git a/docutils/test/functional/expected/latex_docinfo.tex b/docutils/test/functional/expected/latex_docinfo.tex deleted file mode 100644 index 04d9438f7..000000000 --- a/docutils/test/functional/expected/latex_docinfo.tex +++ /dev/null @@ -1,85 +0,0 @@ -\documentclass[10pt,a4paper,english]{article} -\usepackage{babel} -\usepackage{ae} -\usepackage{aeguill} -\usepackage{shortvrb} -\usepackage[latin1]{inputenc} -\usepackage{tabularx} -\usepackage{longtable} -\setlength{\extrarowheight}{2pt} -\usepackage{amsmath} -\usepackage{graphicx} -\usepackage{color} -\usepackage{multirow} -\usepackage{ifthen} -\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} -\usepackage[DIV12]{typearea} -%% generator Docutils: http://docutils.sourceforge.net/ -\newlength{\admonitionwidth} -\setlength{\admonitionwidth}{0.9\textwidth} -\newlength{\docinfowidth} -\setlength{\docinfowidth}{0.9\textwidth} -\newlength{\locallinewidth} -\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} -\newenvironment{optionlist}[1] -{\begin{list}{} - {\setlength{\labelwidth}{#1} - \setlength{\rightmargin}{1cm} - \setlength{\leftmargin}{\rightmargin} - \addtolength{\leftmargin}{\labelwidth} - \addtolength{\leftmargin}{\labelsep} - \renewcommand{\makelabel}{\optionlistlabel}} -}{\end{list}} -\newlength{\lineblockindentation} -\setlength{\lineblockindentation}{2.5em} -\newenvironment{lineblock}[1] -{\begin{list}{} - {\setlength{\partopsep}{\parskip} - \addtolength{\partopsep}{\baselineskip} - \topsep0pt\itemsep0.15\baselineskip\parsep0pt - \leftmargin#1} - \raggedright} -{\end{list}} -% begin: floats for footnotes tweaking. -\setlength{\floatsep}{0.5em} -\setlength{\textfloatsep}{\fill} -\addtolength{\textfloatsep}{3em} -\renewcommand{\textfraction}{0.5} -\renewcommand{\topfraction}{0.5} -\renewcommand{\bottomfraction}{0.5} -\setcounter{totalnumber}{50} -\setcounter{topnumber}{50} -\setcounter{bottomnumber}{50} -% end floats for footnotes -% some commands, that could be overwritten in the style file. -\newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}} -\newcommand{\titlereference}[1]{\textsl{#1}} -% end of "some commands" -\title{} -\author{Foo Fred~\\ -Food Foomatics {\&} Friends~\\ -foo@food.example.info~\\ -Fox St 13~\\ -Foowood \and -Bar Barney~\\ -Bar-BQ Bar~\\ -1-800-BARBQBAR~\\ -Barbara St 16~\\ -South Barwell} -\date{} -\hypersetup{ -pdfauthor={Foo Fred;Bar Barney} -} -\raggedbottom -\begin{document} -\maketitle - -%___________________________________________________________________________ -\begin{center} -\begin{tabularx}{\docinfowidth}{lX} -\end{tabularx} -\end{center} - -\setlength{\locallinewidth}{\linewidth} - -\end{document} diff --git a/docutils/test/functional/expected/misc_rst_html4css1.html b/docutils/test/functional/expected/misc_rst_html4css1.html deleted file mode 100644 index f91844693..000000000 --- a/docutils/test/functional/expected/misc_rst_html4css1.html +++ /dev/null @@ -1,15 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> -<title></title> -<link rel="stylesheet" href="foo&bar.css" type="text/css" /> -</head> -<body> -<div class="document"> -<p>simple input</p> -</div> -</body> -</html> diff --git a/docutils/test/functional/expected/pep_html.html b/docutils/test/functional/expected/pep_html.html deleted file mode 100644 index 8c1a077c5..000000000 --- a/docutils/test/functional/expected/pep_html.html +++ /dev/null @@ -1,93 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<!-- -This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new -PEP, see http://www.python.org/peps/pep-0001.html for instructions and links -to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE! ---> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> - <title>PEP 100 -- Test PEP</title> - <link rel="stylesheet" href="../../../docutils/writers/pep_html/pep.css" type="text/css" /> -</head> -<body bgcolor="white"> -<table class="navigation" cellpadding="0" cellspacing="0" - width="100%" border="0"> -<tr><td class="navicon" width="150" height="35"> -<a href="http://www.python.org/" title="Python Home Page"> -<img src="http://www.python.org/pics/PyBanner000.gif" alt="[Python]" - border="0" width="150" height="35" /></a></td> -<td class="textlinks" align="left"> -[<b><a href="http://www.python.org/">Python Home</a></b>] -[<b><a href="http://www.python.org/peps/">PEP Index</a></b>] -[<b><a href="http://www.python.org/peps/pep-0100.txt">PEP Source</a></b>] -</td></tr></table> -<div class="document"> -<table class="rfc2822 docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field"><th class="field-name">PEP:</th><td class="field-body">100</td> -</tr> -<tr class="field"><th class="field-name">Title:</th><td class="field-body">Test PEP</td> -</tr> -<tr class="field"><th class="field-name">Version:</th><td class="field-body">42</td> -</tr> -<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/nondist/peps/pep-0100.txt">A long time ago.</a></td> -</tr> -<tr class="field"><th class="field-name">Author:</th><td class="field-body">John Doe <john at example.org></td> -</tr> -<tr class="field"><th class="field-name">Discussions-To:</th><td class="field-body"><<a class="reference" href="mailto:devnull%40example.org?subject=PEP%20100">devnull at example.org</a>></td> -</tr> -<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td> -</tr> -<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> -</tr> -<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="http://www.python.org/peps/pep-0012.html">text/x-rst</a></td> -</tr> -<tr class="field"><th class="field-name">Created:</th><td class="field-body">01-Jun-2001</td> -</tr> -<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">13-Jun-2001</td> -</tr> -</tbody> -</table> -<hr /> -<div class="contents topic"> -<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> -<ul class="simple"> -<li><a class="reference" href="#abstract" id="id5" name="id5">Abstract</a></li> -<li><a class="reference" href="#copyright" id="id6" name="id6">Copyright</a></li> -<li><a class="reference" href="#references-and-footnotes" id="id7" name="id7">References and Footnotes</a></li> -</ul> -</div> -<div class="section"> -<h1><a class="toc-backref" href="#id5" id="abstract" name="abstract">Abstract</a></h1> -<p>This is just a test <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>. See the <a class="reference" href="http://www.python.org/peps/">PEP repository</a> <a class="footnote-reference" href="#id3" id="id4" name="id4">[2]</a> for the real -thing.</p> -</div> -<div class="section"> -<h1><a class="toc-backref" href="#id6" id="copyright" name="copyright">Copyright</a></h1> -<p>This document has been placed in the public domain.</p> -</div> -<div class="section"> -<h1><a class="toc-backref" href="#id7" id="references-and-footnotes" name="references-and-footnotes">References and Footnotes</a></h1> -<table class="docutils footnote" frame="void" id="id2" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>PEP editors: <a class="reference" href="mailto:peps%40python.org">peps<span>@</span>python<span>.</span>org</a></td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="id3" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id4" name="id3">[2]</a></td><td><a class="reference" href="http://www.python.org/peps/">http://www.python.org/peps/</a></td></tr> -</tbody> -</table> -</div> - -</div> -</body> -</html> - diff --git a/docutils/test/functional/expected/standalone_rst_html4css1.html b/docutils/test/functional/expected/standalone_rst_html4css1.html deleted file mode 100644 index 4f823b504..000000000 --- a/docutils/test/functional/expected/standalone_rst_html4css1.html +++ /dev/null @@ -1,1001 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> -<title>reStructuredText Test Document</title> -<meta name="author" content="David Goodger" /> -<meta name="authors" content="Me Myself I" /> -<meta name="organization" content="humankind" /> -<meta name="date" content="Now, or yesterday. Or maybe even before yesterday." /> -<meta name="copyright" content="This document has been placed in the public domain. You may do with it as you wish. You may copy, modify, redistribute, reattribute, sell, buy, rent, lease, destroy, or improve it, quote it at length, excerpt, incorporate, collate, fold, staple, or mutilate it, or do anything else to it that your or anyone else's heart desires." /> -<meta content="reStructuredText, test, parser" name="keywords" /> -<meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description" /> -<link rel="stylesheet" href="../../../docutils/writers/html4css1/html4css1.css" type="text/css" /> -</head> -<body> -<div class="header"> -Document header -<hr class="header"/> -</div> -<div class="document" id="restructuredtext-test-document"> -<span id="doctitle"></span><h1 class="title">reStructuredText Test Document</h1> -<h2 class="subtitle" id="examples-of-syntax-constructs"><span id="subtitle"></span>Examples of Syntax Constructs</h2> -<table class="docinfo" frame="void" rules="none"> -<col class="docinfo-name" /> -<col class="docinfo-content" /> -<tbody valign="top"> -<tr><th class="docinfo-name">Author:</th> -<td>David Goodger</td></tr> -<tr><th class="docinfo-name">Address:</th> -<td><pre class="address"> -123 Example Street -Example, EX Canada -A1B 2C3 -</pre> -</td></tr> -<tr><th class="docinfo-name">Contact:</th> -<td><a class="first last reference" href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a></td></tr> -<tr><th class="docinfo-name">Authors:</th> -<td>Me -<br />Myself -<br />I</td></tr> -<tr><th class="docinfo-name">Organization:</th> -<td>humankind</td></tr> -<tr><th class="docinfo-name">Date:</th> -<td>Now, or yesterday. Or maybe even <em>before</em> yesterday.</td></tr> -<tr><th class="docinfo-name">Status:</th> -<td>This is a "work in progress"</td></tr> -<tr><th class="docinfo-name">Revision:</th> -<td>is managed by a version control system.</td></tr> -<tr><th class="docinfo-name">Version:</th> -<td>1</td></tr> -<tr><th class="docinfo-name">Copyright:</th> -<td>This document has been placed in the public domain. You -may do with it as you wish. You may copy, modify, -redistribute, reattribute, sell, buy, rent, lease, -destroy, or improve it, quote it at length, excerpt, -incorporate, collate, fold, staple, or mutilate it, or do -anything else to it that your or anyone else's heart -desires.</td></tr> -<tr class="field"><th class="docinfo-name">field name:</th><td class="field-body">This is a "generic bibliographic field".</td> -</tr> -<tr class="field"><th class="docinfo-name">field name "2":</th><td class="field-body"><p class="first">Generic bibliographic fields may contain multiple body elements.</p> -<p class="last">Like this.</p> -</td> -</tr> -</tbody> -</table> -<div class="dedication topic"> -<p class="topic-title first">Dedication</p> -<p>For Docutils users & co-developers.</p> -</div> -<div class="abstract topic"> -<p class="topic-title first">Abstract</p> -<p>This is a test document, containing at least one example of each -reStructuredText construct.</p> -</div> -<!-- This is a comment. Note how any initial comments are moved by -transforms to after the document title, subtitle, and docinfo. --> -<!-- Above is the document title, and below is the subtitle. -They are transformed from section titles after parsing. --> -<!-- bibliographic fields (which also require a transform): --> -<div class="contents topic"> -<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p> -<ul class="auto-toc simple"> -<li><a class="reference" href="#structural-elements" id="id32" name="id32">1 Structural Elements</a><ul class="auto-toc"> -<li><a class="reference" href="#section-title" id="id33" name="id33">1.1 Section Title</a></li> -<li><a class="reference" href="#empty-section" id="id34" name="id34">1.2 Empty Section</a></li> -<li><a class="reference" href="#transitions" id="id35" name="id35">1.3 Transitions</a></li> -</ul> -</li> -<li><a class="reference" href="#body-elements" id="id36" name="id36">2 Body Elements</a><ul class="auto-toc"> -<li><a class="reference" href="#paragraphs" id="id37" name="id37">2.1 Paragraphs</a><ul class="auto-toc"> -<li><a class="reference" href="#inline-markup" id="id38" name="id38">2.1.1 Inline Markup</a></li> -</ul> -</li> -<li><a class="reference" href="#bullet-lists" id="id39" name="id39">2.2 Bullet Lists</a></li> -<li><a class="reference" href="#enumerated-lists" id="id40" name="id40">2.3 Enumerated Lists</a></li> -<li><a class="reference" href="#definition-lists" id="id41" name="id41">2.4 Definition Lists</a></li> -<li><a class="reference" href="#field-lists" id="id42" name="id42">2.5 Field Lists</a></li> -<li><a class="reference" href="#option-lists" id="id43" name="id43">2.6 Option Lists</a></li> -<li><a class="reference" href="#literal-blocks" id="id44" name="id44">2.7 Literal Blocks</a></li> -<li><a class="reference" href="#line-blocks" id="id45" name="id45">2.8 Line Blocks</a></li> -<li><a class="reference" href="#block-quotes" id="id46" name="id46">2.9 Block Quotes</a></li> -<li><a class="reference" href="#doctest-blocks" id="id47" name="id47">2.10 Doctest Blocks</a></li> -<li><a class="reference" href="#footnotes" id="id48" name="id48">2.11 Footnotes</a></li> -<li><a class="reference" href="#citations" id="id49" name="id49">2.12 Citations</a></li> -<li><a class="reference" href="#targets" id="id50" name="id50">2.13 Targets</a><ul class="auto-toc"> -<li><a class="reference" href="#duplicate-target-names" id="id51" name="id51">2.13.1 Duplicate Target Names</a></li> -<li><a class="reference" href="#id20" id="id52" name="id52">2.13.2 Duplicate Target Names</a></li> -</ul> -</li> -<li><a class="reference" href="#directives" id="id53" name="id53">2.14 Directives</a><ul class="auto-toc"> -<li><a class="reference" href="#document-parts" id="id54" name="id54">2.14.1 Document Parts</a></li> -<li><a class="reference" href="#images" id="id55" name="id55">2.14.2 Images</a></li> -<li><a class="reference" href="#admonitions" id="id56" name="id56">2.14.3 Admonitions</a></li> -<li><a class="reference" href="#topics-sidebars-and-rubrics" id="id57" name="id57">2.14.4 Topics, Sidebars, and Rubrics</a></li> -<li><a class="reference" href="#target-footnotes" id="id58" name="id58">2.14.5 Target Footnotes</a></li> -<li><a class="reference" href="#replacement-text" id="id59" name="id59">2.14.6 Replacement Text</a></li> -<li><a class="reference" href="#compound-paragraph" id="id60" name="id60">2.14.7 Compound Paragraph</a></li> -<li><a class="reference" href="#parsed-literal-blocks" id="id61" name="id61">2.14.8 Parsed Literal Blocks</a></li> -</ul> -</li> -<li><a class="reference" href="#substitution-definitions" id="id62" name="id62">2.15 Substitution Definitions</a></li> -<li><a class="reference" href="#comments" id="id63" name="id63">2.16 Comments</a></li> -<li><a class="reference" href="#raw-text" id="id64" name="id64">2.17 Raw text</a></li> -<li><a class="reference" href="#container" id="id65" name="id65">2.18 Container</a></li> -<li><a class="reference" href="#colspanning-tables" id="id66" name="id66">2.19 Colspanning tables</a></li> -<li><a class="reference" href="#rowspanning-tables" id="id67" name="id67">2.20 Rowspanning tables</a></li> -<li><a class="reference" href="#complex-tables" id="id68" name="id68">2.21 Complex tables</a></li> -<li><a class="reference" href="#list-tables" id="id69" name="id69">2.22 List Tables</a></li> -<li><a class="reference" href="#custom-roles" id="id70" name="id70">2.23 Custom Roles</a></li> -</ul> -</li> -<li><a class="reference" href="#error-handling" id="id71" name="id71">3 Error Handling</a></li> -</ul> -</div> -<div class="section"> -<h1><a class="toc-backref" href="#id32" id="structural-elements" name="structural-elements">1 Structural Elements</a></h1> -<div class="section"> -<h2 class="with-subtitle"><a class="toc-backref" href="#id33" id="section-title" name="section-title">1.1 Section Title</a></h2> -<h2 class="section-subtitle" id="section-subtitle"><span class="section-subtitle">Section Subtitle</span></h2> -<p>That's it, the text just above this line.</p> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id34" id="empty-section" name="empty-section">1.2 Empty Section</a></h2> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id35" id="transitions" name="transitions">1.3 Transitions</a></h2> -<p>Here's a transition:</p> -<hr class="docutils" /> -<p>It divides the section. Transitions may also occur between sections:</p> -</div> -</div> -<hr class="docutils" /> -<div class="section"> -<h1><a class="toc-backref" href="#id36" id="body-elements" name="body-elements">2 Body Elements</a></h1> -<div class="section"> -<h2><a class="toc-backref" href="#id37" id="paragraphs" name="paragraphs">2.1 Paragraphs</a></h2> -<p>A paragraph.</p> -<div class="section"> -<h3><a class="toc-backref" href="#id38" id="inline-markup" name="inline-markup">2.1.1 Inline Markup</a></h3> -<p>Paragraphs contain text and may contain inline markup: <em>emphasis</em>, -<strong>strong emphasis</strong>, <tt class="docutils literal"><span class="pre">inline</span> <span class="pre">literals</span></tt>, standalone hyperlinks -(<a class="reference" href="http://www.python.org">http://www.python.org</a>), external hyperlinks (<a class="reference" href="http://www.python.org/">Python</a> <a class="footnote-reference" href="#id25" id="id26" name="id26">[5]</a>), internal -cross-references (<a class="reference" href="#example">example</a>), external hyperlinks with embedded URIs -(<a class="reference" href="http://www.python.org">Python web site</a>), <a class="reference" href="http://www.python.org/">anonymous hyperlink -references</a> <a class="footnote-reference" href="#id25" id="id29" name="id29">[5]</a> (<a class="reference" href="http://docutils.sourceforge.net/">a second reference</a> <a class="footnote-reference" href="#id30" id="id31" name="id31">[6]</a>), footnote references (manually -numbered <a class="footnote-reference" href="#id8" id="id1" name="id1">[1]</a>, anonymous auto-numbered <a class="footnote-reference" href="#id11" id="id2" name="id2">[3]</a>, labeled auto-numbered -<a class="footnote-reference" href="#label" id="id3" name="id3">[2]</a>, or symbolic <a class="footnote-reference" href="#id12" id="id4" name="id4">[*]</a>), citation references (<a class="citation-reference" href="#cit2002" id="id5" name="id5">[CIT2002]</a>), -substitution references (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />), and <span class="target" id="inline-hyperlink-targets">inline hyperlink targets</span> -(see <a class="reference" href="#id22">Targets</a> below for a reference back to here). Character-level -inline markup is also possible (although exceedingly ugly!) in <em>re</em><tt class="docutils literal"><span class="pre">Structured</span></tt><em>Text</em>. Problems are indicated by <a href="#id23" name="id24"><span class="problematic" id="id24">|problematic|</span></a> text -(generated by processing errors; this one is intentional). Here is a -reference to the <a class="reference" href="#doctitle">doctitle</a> and the <a class="reference" href="#subtitle">subtitle</a>.</p> -<p>The default role for interpreted text is <cite>Title Reference</cite>. Here are -some explicit interpreted text roles: a PEP reference (<a class="reference" href="http://www.python.org/peps/pep-0287.html">PEP 287</a>); an -RFC reference (<a class="reference" href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>); a <sub>subscript</sub>; a <sup>superscript</sup>; -and explicit roles for <em>standard</em> <strong>inline</strong> -<tt class="docutils literal"><span class="pre">markup</span></tt>.</p> -<!-- DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! --> -<p>Let's test wrapping and whitespace significance in inline literals: -<tt class="docutils literal"><span class="pre">This</span> <span class="pre">is</span> <span class="pre">an</span> <span class="pre">example</span> <span class="pre">of</span> <span class="pre">--inline-literal</span> <span class="pre">--text,</span> <span class="pre">--including</span> <span class="pre">some--</span> -<span class="pre">strangely--hyphenated-words.</span> <span class="pre">Adjust-the-width-of-your-browser-window</span> -<span class="pre">to</span> <span class="pre">see</span> <span class="pre">how</span> <span class="pre">the</span> <span class="pre">text</span> <span class="pre">is</span> <span class="pre">wrapped.</span> <span class="pre">--</span> <span class="pre">----</span> <span class="pre">--------</span> <span class="pre">Now</span> <span class="pre">note</span> <span class="pre">the</span> -<span class="pre">spacing</span> <span class="pre">between</span> <span class="pre">the</span> <span class="pre">words</span> <span class="pre">of</span> <span class="pre">this</span> <span class="pre">sentence</span> <span class="pre">(words</span> -<span class="pre">should</span> <span class="pre">be</span> <span class="pre">grouped</span> <span class="pre">in</span> <span class="pre">pairs).</span></tt></p> -<p>If the <tt class="docutils literal"><span class="pre">--pep-references</span></tt> option was supplied, there should be a -live link to PEP 258 here.</p> -</div> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id39" id="bullet-lists" name="bullet-lists">2.2 Bullet Lists</a></h2> -<ul> -<li><p class="first">A bullet list</p> -<ul class="simple"> -<li>Nested bullet list.</li> -<li>Nested item 2.</li> -</ul> -</li> -<li><p class="first">Item 2.</p> -<p>Paragraph 2 of item 2.</p> -<ul class="simple"> -<li>Nested bullet list.</li> -<li>Nested item 2.<ul> -<li>Third level.</li> -<li>Item 2.</li> -</ul> -</li> -<li>Nested item 3.</li> -<li>This nested list should be compacted by the HTML writer.<span class="target" id="target"></span><!-- Even if this item contains a target and a comment. --> -</li> -</ul> -</li> -</ul> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id40" id="enumerated-lists" name="enumerated-lists">2.3 Enumerated Lists</a></h2> -<ol class="arabic"> -<li><p class="first">Arabic numerals.</p> -<ol class="loweralpha simple"> -<li>lower alpha)<ol class="lowerroman"> -<li>(lower roman)<ol class="upperalpha"> -<li>upper alpha.<ol class="upperroman"> -<li>upper roman)</li> -</ol> -</li> -</ol> -</li> -</ol> -</li> -</ol> -</li> -<li><p class="first">Lists that don't start at 1:</p> -<ol class="arabic simple" start="3"> -<li>Three</li> -<li>Four</li> -</ol> -<ol class="upperalpha simple" start="3"> -<li>C</li> -<li>D</li> -</ol> -<ol class="lowerroman simple" start="3"> -<li>iii</li> -<li>iv</li> -</ol> -</li> -</ol> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id41" id="definition-lists" name="definition-lists">2.4 Definition Lists</a></h2> -<dl class="docutils"> -<dt>Term</dt> -<dd>Definition</dd> -<dt>Term <span class="classifier-delimiter">:</span> <span class="classifier">classifier</span></dt> -<dd><p class="first">Definition paragraph 1.</p> -<p class="last">Definition paragraph 2.</p> -</dd> -<dt>Term</dt> -<dd>Definition</dd> -<dt>Term <span class="classifier-delimiter">:</span> <span class="classifier">classifier one</span> <span class="classifier-delimiter">:</span> <span class="classifier">classifier two</span></dt> -<dd>Definition</dd> -</dl> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id42" id="field-lists" name="field-lists">2.5 Field Lists</a></h2> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field"><th class="field-name">what:</th><td class="field-body"><p class="first">Field lists map field names to field bodies, like database -records. They are often part of an extension syntax. They are -an unambiguous variant of RFC 2822 fields.</p> -</td> -</tr> -<tr class="field"><th class="field-name">how arg1 arg2:</th><td class="field-body"><p class="first">The field marker is a colon, the field name, and a colon.</p> -<p>The field body may contain one or more body elements, indented -relative to the field marker.</p> -</td> -</tr> -<tr class="field"><th class="field-name">credits:</th><td class="field-body"><p class="credits first last">This paragraph has the <cite>credits</cite> class set. (This is actually not -about credits but just for ensuring that the class attribute -doesn't get stripped away.)</p> -</td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id43" id="option-lists" name="option-lists">2.6 Option Lists</a></h2> -<p>For listing command-line options:</p> -<table class="docutils option-list" frame="void" rules="none"> -<col class="option" /> -<col class="description" /> -<tbody valign="top"> -<tr><td class="option-group"> -<kbd><span class="option">-a</span></kbd></td> -<td>command-line option "a"</td></tr> -<tr><td class="option-group"> -<kbd><span class="option">-b <var>file</var></span></kbd></td> -<td>options can have arguments -and long descriptions</td></tr> -<tr><td class="option-group"> -<kbd><span class="option">--long</span></kbd></td> -<td>options can be long also</td></tr> -<tr><td class="option-group"> -<kbd><span class="option">--input=<var>file</var></span></kbd></td> -<td>long options can also have -arguments</td></tr> -<tr><td class="option-group" colspan="2"> -<kbd><span class="option">--very-long-option</span></kbd></td> -</tr> -<tr><td> </td><td><p class="first">The description can also start on the next line.</p> -<p class="last">The description may contain multiple body elements, -regardless of where it starts.</p> -</td></tr> -<tr><td class="option-group"> -<kbd><span class="option">-x</span>, <span class="option">-y</span>, <span class="option">-z</span></kbd></td> -<td>Multiple options are an "option group".</td></tr> -<tr><td class="option-group"> -<kbd><span class="option">-v</span>, <span class="option">--verbose</span></kbd></td> -<td>Commonly-seen: short & long options.</td></tr> -<tr><td class="option-group" colspan="2"> -<kbd><span class="option">-1 <var>file</var></span>, <span class="option">--one=<var>file</var></span>, <span class="option">--two <var>file</var></span></kbd></td> -</tr> -<tr><td> </td><td>Multiple options with arguments.</td></tr> -<tr><td class="option-group"> -<kbd><span class="option">/V</span></kbd></td> -<td>DOS/VMS-style options too</td></tr> -</tbody> -</table> -<p>There must be at least two spaces between the option and the -description.</p> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id44" id="literal-blocks" name="literal-blocks">2.7 Literal Blocks</a></h2> -<p>Literal blocks are indicated with a double-colon ("::") at the end of -the preceding paragraph (over there <tt class="docutils literal"><span class="pre">--></span></tt>). They can be indented:</p> -<pre class="literal-block"> -if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None -</pre> -<p>Or they can be quoted without indentation:</p> -<pre class="literal-block"> ->> Great idea! -> -> Why didn't I think of that? -</pre> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id45" id="line-blocks" name="line-blocks">2.8 Line Blocks</a></h2> -<p>This section tests line blocks. Line blocks are body elements which -consist of lines and other line blocks. Nested line blocks cause -indentation.</p> -<div class="line-block"> -<div class="line">This is a line block. It ends with a blank line.</div> -<div class="line-block"> -<div class="line">New lines begin with a vertical bar ("|").</div> -<div class="line">Line breaks and initial indent are significant, and preserved.</div> -<div class="line-block"> -<div class="line">Continuation lines are also possible. A long line that is intended -to wrap should begin with a space in place of the vertical bar.</div> -</div> -<div class="line">The left edge of a continuation line need not be aligned with -the left edge of the text above it.</div> -</div> -</div> -<div class="line-block"> -<div class="line">This is a second line block.</div> -<div class="line"><br /></div> -<div class="line">Blank lines are permitted internally, but they must begin with a "|".</div> -</div> -<p>Another line block, surrounded by paragraphs:</p> -<div class="line-block"> -<div class="line">And it's no good waiting by the window</div> -<div class="line">It's no good waiting for the sun</div> -<div class="line">Please believe me, the things you dream of</div> -<div class="line">They don't fall in the lap of no-one</div> -</div> -<p>Take it away, Eric the Orchestra Leader!</p> -<blockquote> -<div class="line-block"> -<div class="line">A one, two, a one two three four</div> -<div class="line"><br /></div> -<div class="line">Half a bee, philosophically,</div> -<div class="line-block"> -<div class="line">must, <em>ipso facto</em>, half not be.</div> -</div> -<div class="line">But half the bee has got to be,</div> -<div class="line-block"> -<div class="line"><em>vis a vis</em> its entity. D'you see?</div> -<div class="line"><br /></div> -</div> -<div class="line">But can a bee be said to be</div> -<div class="line-block"> -<div class="line">or not to be an entire bee,</div> -<div class="line-block"> -<div class="line">when half the bee is not a bee,</div> -<div class="line-block"> -<div class="line">due to some ancient injury?</div> -<div class="line"><br /></div> -</div> -</div> -</div> -<div class="line">Singing...</div> -</div> -</blockquote> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id46" id="block-quotes" name="block-quotes">2.9 Block Quotes</a></h2> -<p>Block quotes consist of indented body elements:</p> -<blockquote> -<p>My theory by A. Elk. Brackets Miss, brackets. This theory goes -as follows and begins now. All brontosauruses are thin at one -end, much much thicker in the middle and then thin again at the -far end. That is my theory, it is mine, and belongs to me and I -own it, and what it is too.</p> -<p class="attribution">—Anne Elk (Miss)</p> -</blockquote> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id47" id="doctest-blocks" name="doctest-blocks">2.10 Doctest Blocks</a></h2> -<pre class="doctest-block"> ->>> print 'Python-specific usage examples; begun with ">>>"' -Python-specific usage examples; begun with ">>>" ->>> print '(cut and pasted from interactive Python sessions)' -(cut and pasted from interactive Python sessions) -</pre> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id48" id="footnotes" name="footnotes">2.11 Footnotes</a></h2> -<table class="docutils footnote" frame="void" id="id8" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a name="id8">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id9">2</a>, <a class="fn-backref" href="#id21">3</a>)</em> <p>A footnote contains body elements, consistently indented by at -least 3 spaces.</p> -<p class="last">This is the footnote's second paragraph.</p> -</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="label" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a name="label">[2]</a></td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id10">2</a>)</em> Footnotes may be numbered, either manually (as in <a class="footnote-reference" href="#id8" id="id9" name="id9">[1]</a>) or -automatically using a "#"-prefixed label. This footnote has a -label so it can be referred to from multiple places, both as a -footnote reference (<a class="footnote-reference" href="#label" id="id10" name="id10">[2]</a>) and as a hyperlink reference -(<a class="reference" href="#label">label</a>).</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="id11" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id2" name="id11">[3]</a></td><td><p class="first">This footnote is numbered automatically and anonymously using a -label of "#" only.</p> -<p>This is the second paragraph.</p> -<p class="last">And this is the third paragraph.</p> -</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="id12" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id4" name="id12">[*]</a></td><td>Footnotes may also use symbols, specified with a "*" label. -Here's a reference to the next footnote: <a class="footnote-reference" href="#id14" id="id13" name="id13">[†]</a>.</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="id14" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id13" name="id14">[†]</a></td><td>This footnote shows the next symbol in the sequence.</td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="id15" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a name="id15">[4]</a></td><td>Here's an unreferenced footnote, with a reference to a -nonexistent footnote: <a href="#id80" name="id81"><span class="problematic" id="id81"><span id="id16"></span>[5]_</span></a>.</td></tr> -</tbody> -</table> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id49" id="citations" name="citations">2.12 Citations</a></h2> -<table class="docutils citation" frame="void" id="cit2002" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a name="cit2002">[CIT2002]</a></td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id17">2</a>)</em> Citations are text-labeled footnotes. They may be -rendered separately and differently from footnotes.</td></tr> -</tbody> -</table> -<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="id17" name="id17">[CIT2002]</a>, and a <a href="#id82" name="id83"><span class="problematic" id="id83"><span id="id18"></span>[nonexistent]_</span></a> -citation.</p> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id50" id="targets" name="targets"><span id="another-target"></span>2.13 Targets</a></h2> -<p id="example">This paragraph is pointed to by the explicit "example" target. A -reference can be found under <a class="reference" href="#inline-markup">Inline Markup</a>, above. <a class="reference" href="#inline-hyperlink-targets">Inline -hyperlink targets</a> are also possible.</p> -<p>Section headers are implicit targets, referred to by name. See -<a class="reference" href="#id22">Targets</a>, which is a subsection of <a class="reference" href="#body-elements">Body Elements</a>.</p> -<p>Explicit external targets are interpolated into references such as -"<a class="reference" href="http://www.python.org/">Python</a> <a class="footnote-reference" href="#id25" id="id27" name="id27">[5]</a>".</p> -<p>Targets may be indirect and anonymous. Thus <a class="reference" href="#id22">this phrase</a> may also -refer to the <a class="reference" href="#id22">Targets</a> section.</p> -<p>Here's a <a href="#id84" name="id85"><span class="problematic" id="id85">`hyperlink reference without a target`_</span></a>, which generates an -error.</p> -<div class="section"> -<h3><a class="toc-backref" href="#id51" id="duplicate-target-names" name="duplicate-target-names">2.13.1 Duplicate Target Names</a></h3> -<p>Duplicate names in section headers or other implicit targets will -generate "info" (level-1) system messages. Duplicate names in -explicit targets will generate "warning" (level-2) system messages.</p> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id52" id="id20" name="id20">2.13.2 Duplicate Target Names</a></h3> -<p>Since there are two "Duplicate Target Names" section headers, we -cannot uniquely refer to either of them by name. If we try to (like -this: <a href="#id86" name="id87"><span class="problematic" id="id87">`Duplicate Target Names`_</span></a>), an error is generated.</p> -</div> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id53" id="directives" name="directives">2.14 Directives</a></h2> -<div class="contents local topic"> -<ul class="auto-toc simple"> -<li><a class="reference" href="#document-parts" id="id72" name="id72">2.14.1 Document Parts</a></li> -<li><a class="reference" href="#images" id="id73" name="id73">2.14.2 Images</a></li> -<li><a class="reference" href="#admonitions" id="id74" name="id74">2.14.3 Admonitions</a></li> -<li><a class="reference" href="#topics-sidebars-and-rubrics" id="id75" name="id75">2.14.4 Topics, Sidebars, and Rubrics</a></li> -<li><a class="reference" href="#target-footnotes" id="id76" name="id76">2.14.5 Target Footnotes</a></li> -<li><a class="reference" href="#replacement-text" id="id77" name="id77">2.14.6 Replacement Text</a></li> -<li><a class="reference" href="#compound-paragraph" id="id78" name="id78">2.14.7 Compound Paragraph</a></li> -<li><a class="reference" href="#parsed-literal-blocks" id="id79" name="id79">2.14.8 Parsed Literal Blocks</a></li> -</ul> -</div> -<p>These are just a sample of the many reStructuredText Directives. For -others, please see -<a class="reference" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html">http://docutils.sourceforge.net/docs/ref/rst/directives.html</a>.</p> -<div class="section"> -<h3><a class="toc-backref" href="#id72" id="document-parts" name="document-parts">2.14.1 Document Parts</a></h3> -<p>An example of the "contents" directive can be seen above this section -(a local, untitled table of <a class="reference" href="#contents">contents</a>) and at the beginning of the -document (a document-wide <a class="reference" href="#table-of-contents">table of contents</a>).</p> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id73" id="images" name="images">2.14.2 Images</a></h3> -<p>An image directive (also clickable -- a hyperlink reference):</p> -<a class="reference image-reference" href="#directives"><img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" /></a> -<p>Image with multiple IDs:</p> -<span id="image-target-2"></span><span id="image-target-1"></span><img alt="../../../docs/user/rst/images/title.png" id="image-target-3" name="image-target-3" src="../../../docs/user/rst/images/title.png" /> -<p>A centered image:</p> -<div align="center" class="align-center"><img alt="../../../docs/user/rst/images/biohazard.png" class="align-center" src="../../../docs/user/rst/images/biohazard.png" /></div> -<p>A left-aligned image:</p> -<img align="left" alt="../../../docs/user/rst/images/biohazard.png" class="align-left" src="../../../docs/user/rst/images/biohazard.png" /> -<p>A right-aligned image:</p> -<img align="right" alt="../../../docs/user/rst/images/biohazard.png" class="align-right" src="../../../docs/user/rst/images/biohazard.png" /> -<p>A figure directive:</p> -<div align="right" class="figclass1 figclass2 figure"> -<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/biohazard.png" style="width: 50px;" /> -<p class="caption">A figure is an image with a caption and/or a legend:</p> -<div class="legend"> -<table border="1" class="docutils"> -<colgroup> -<col width="20%" /> -<col width="80%" /> -</colgroup> -<tbody valign="top"> -<tr><td>re</td> -<td>Revised, revisited, based on 're' module.</td> -</tr> -<tr><td>Structured</td> -<td>Structure-enhanced text, structuredtext.</td> -</tr> -<tr><td>Text</td> -<td>Well it is, isn't it?</td> -</tr> -</tbody> -</table> -<p>This paragraph is also part of the legend.</p> -</div> -</div> -<div align="left" class="figclass1 figclass2 figure"> -<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/biohazard.png" style="width: 50px;" /> -<p class="caption">A left-aligned figure.</p> -<div class="legend"> -This is the legend.</div> -</div> -<p>This paragraph might flow around the figure...</p> -<p>A centered figure:</p> -<div align="center" class="figure"> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 50px;" /> -<p class="caption">This is the caption.</p> -<div class="legend"> -<p>This is the legend.</p> -<p>The legend may consist of several paragraphs.</p> -</div> -</div> -<p>This paragraph might flow around the figure...</p> -<p>A left-aligned figure:</p> -<div align="left" class="figure"> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 50px;" /> -<p class="caption">This is the caption.</p> -<div class="legend"> -<p>This is the legend.</p> -<p>The legend may consist of several paragraphs.</p> -</div> -</div> -<p>This paragraph might flow around the figure...</p> -<p>Now widths:</p> -<p>An image 2 em wide:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" /> -<p>An image 2 em wide and 30 pixel high:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em; height: 30px;" /> -<p>An image occupying 70% of the line width:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 70%;" /> -<p>An image 3 cm high:</p> -<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="height: 3cm;" /> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id74" id="admonitions" name="admonitions">2.14.3 Admonitions</a></h3> -<div class="attention"> -<p class="first admonition-title">Attention!</p> -<p class="last">Directives at large.</p> -</div> -<div class="caution"> -<p class="first admonition-title">Caution!</p> -<p class="last">Don't take any wooden nickels.</p> -</div> -<div class="danger"> -<p class="first admonition-title">!DANGER!</p> -<p class="last">Mad scientist at work!</p> -</div> -<div class="error"> -<p class="first admonition-title">Error</p> -<p class="last">Does not compute.</p> -</div> -<div class="hint"> -<p class="first admonition-title">Hint</p> -<p class="last">It's bigger than a bread box.</p> -</div> -<div class="important"> -<p class="first admonition-title">Important</p> -<ul class="last simple"> -<li>Wash behind your ears.</li> -<li>Clean up your room.</li> -<li>Call your mother.</li> -<li>Back up your data.</li> -</ul> -</div> -<div class="note"> -<p class="first admonition-title">Note</p> -<p class="last">This is a note.</p> -</div> -<div class="tip"> -<p class="first admonition-title">Tip</p> -<p class="last">15% if the service is good.</p> -</div> -<div class="warning"> -<p class="first admonition-title">Warning</p> -<p class="last">Strong prose may provoke extreme mental exertion. -Reader discretion is strongly advised.</p> -</div> -<div class="admonition-and-by-the-way admonition"> -<p class="first admonition-title">And, by the way...</p> -<p class="last">You can make up your own admonition too.</p> -</div> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id75" id="topics-sidebars-and-rubrics" name="topics-sidebars-and-rubrics">2.14.4 Topics, Sidebars, and Rubrics</a></h3> -<div class="sidebar"> -<p class="first sidebar-title">Sidebar Title</p> -<p class="sidebar-subtitle">Optional Subtitle</p> -<p>This is a sidebar. It is for text outside the flow of the main -text.</p> -<p class="rubric">This is a rubric inside a sidebar</p> -<p class="last">Sidebars often appears beside the main text with a border and -background color.</p> -</div> -<div class="topic"> -<p class="topic-title first">Topic Title</p> -<p>This is a topic.</p> -</div> -<p class="rubric">This is a rubric</p> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id76" id="target-footnotes" name="target-footnotes">2.14.5 Target Footnotes</a></h3> -<table class="docutils footnote" frame="void" id="id25" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a name="id25">[5]</a></td><td><em>(<a class="fn-backref" href="#id26">1</a>, <a class="fn-backref" href="#id27">2</a>, <a class="fn-backref" href="#id28">3</a>, <a class="fn-backref" href="#id29">4</a>)</em> <a class="reference" href="http://www.python.org/">http://www.python.org/</a></td></tr> -</tbody> -</table> -<table class="docutils footnote" frame="void" id="id30" rules="none"> -<colgroup><col class="label" /><col /></colgroup> -<tbody valign="top"> -<tr><td class="label"><a class="fn-backref" href="#id31" name="id30">[6]</a></td><td><a class="reference" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr> -</tbody> -</table> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id77" id="replacement-text" name="replacement-text">2.14.6 Replacement Text</a></h3> -<p>I recommend you try <a class="reference" href="http://www.python.org/">Python, <em>the</em> best language around</a> <a class="footnote-reference" href="#id25" id="id28" name="id28">[5]</a>.</p> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id78" id="compound-paragraph" name="compound-paragraph">2.14.7 Compound Paragraph</a></h3> -<div class="some-class compound"> -<p class="compound-first">Compound 1, paragraph 1.</p> -<p class="compound-middle">Compound 1, paragraph 2.</p> -<ul class="compound-last simple"> -<li>Compound 1, list item one.</li> -<li>Compound 1, list item two.</li> -</ul> -</div> -<p>Another compound statement:</p> -<div class="compound"> -<p class="compound-first">Compound 2, a literal block:</p> -<pre class="compound-middle literal-block"> -Compound 2, literal. -</pre> -<p class="compound-last">Compound 2, this is a test.</p> -</div> -<div class="compound"> -<p>Compound 3, only consisting of one paragraph.</p> -</div> -<div class="compound"> -<pre class="compound-first literal-block"> -Compound 4. -This one starts with a literal block. -</pre> -<p class="compound-last">Compound 4, a paragraph.</p> -</div> -<p>Now something <em>really</em> perverted -- a nested compound block. This is -just to test that it works at all; the results don't have to be -meaningful.</p> -<div class="compound"> -<p class="compound-first">Compound 5, block 1 (a paragraph).</p> -<div class="compound-middle compound"> -<p class="compound-first">Compound 6, block 2 in compound 5.</p> -<p class="compound-last">Compound 6, another paragraph.</p> -</div> -<p class="compound-last">Compound 5, block 3 (a paragraph).</p> -</div> -<div class="compound"> -<p class="compound-first">Compound 7, with a table inside:</p> -<table border="1" class="compound-middle docutils"> -<colgroup> -<col width="33%" /> -<col width="33%" /> -<col width="33%" /> -</colgroup> -<tbody valign="top"> -<tr><td><p class="first">Left cell, first -paragraph.</p> -<p class="last">Left cell, second -paragraph.</p> -</td> -<td>Middle cell, -consisting of -exactly one -paragraph.</td> -<td><p class="first">Right cell.</p> -<p>Paragraph 2.</p> -<p class="last">Paragraph 3.</p> -</td> -</tr> -</tbody> -</table> -<p class="compound-middle">Compound 7, a paragraph after the table.</p> -<p class="compound-last">Compound 7, another paragraph.</p> -</div> -</div> -<div class="section"> -<h3><a class="toc-backref" href="#id79" id="parsed-literal-blocks" name="parsed-literal-blocks">2.14.8 Parsed Literal Blocks</a></h3> -<pre class="literal-block"> -This is a parsed literal block. - This line is indented. The next line is blank. - -Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <tt class="docutils literal"><span class="pre">literal</span> -<span class="pre">text</span></tt>, footnotes <a class="footnote-reference" href="#id8" id="id21" name="id21">[1]</a>, <span class="target" id="id22">targets</span>, and <a class="reference" href="http://www.python.org/">references</a>. -</pre> -</div> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id62" id="substitution-definitions" name="substitution-definitions">2.15 Substitution Definitions</a></h2> -<p>An inline image (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />) example:</p> -<p>(Substitution definitions are not visible in the HTML source.)</p> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id63" id="comments" name="comments">2.16 Comments</a></h2> -<p>Here's one:</p> -<!-- Comments begin with two dots and a space. Anything may -follow, except for the syntax of footnotes, hyperlink -targets, directives, or substitution definitions. - -Double-dashes - - "- -" - - must be escaped somehow in HTML output. --> -<p>(View the HTML source to see the comment.)</p> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id64" id="raw-text" name="raw-text">2.17 Raw text</a></h2> -<p>This does not necessarily look nice, because there may be missing white space.</p> -<p>It's just there to freeze the behavior.</p> -A test.Second test.<div class="myclass">Another test with myclass set.</div><p>This is the <span class="myrawroleclass">fourth test</span> with myrawroleclass set.</p> -Fifth test in HTML.<br />Line two.</div> -<div class="section"> -<h2><a class="toc-backref" href="#id65" id="container" name="container">2.18 Container</a></h2> -<div class="custom container"> -<p>paragraph 1</p> -<p>paragraph 2</p> -</div> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id66" id="colspanning-tables" name="colspanning-tables">2.19 Colspanning tables</a></h2> -<p>This table has a cell spanning two columns:</p> -<table border="1" class="docutils"> -<colgroup> -<col width="31%" /> -<col width="31%" /> -<col width="38%" /> -</colgroup> -<thead valign="bottom"> -<tr><th class="head" colspan="2">Inputs</th> -<th class="head">Output</th> -</tr> -<tr><th class="head">A</th> -<th class="head">B</th> -<th class="head">A or B</th> -</tr> -</thead> -<tbody valign="top"> -<tr><td>False</td> -<td>False</td> -<td>False</td> -</tr> -<tr><td>True</td> -<td>False</td> -<td>True</td> -</tr> -<tr><td>False</td> -<td>True</td> -<td>True</td> -</tr> -<tr><td>True</td> -<td>True</td> -<td>True</td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id67" id="rowspanning-tables" name="rowspanning-tables">2.20 Rowspanning tables</a></h2> -<p>Here's a table with cells spanning several rows:</p> -<table border="1" class="docutils"> -<colgroup> -<col width="44%" /> -<col width="22%" /> -<col width="33%" /> -</colgroup> -<thead valign="bottom"> -<tr><th class="head">Header row, column 1 -(header rows optional)</th> -<th class="head">Header 2</th> -<th class="head">Header 3</th> -</tr> -</thead> -<tbody valign="top"> -<tr><td>body row 1, column 1</td> -<td>column 2</td> -<td>column 3</td> -</tr> -<tr><td>body row 2</td> -<td rowspan="2">Cells may -span rows.</td> -<td rowspan="2">Another -rowspanning -cell.</td> -</tr> -<tr><td>body row 3</td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id68" id="complex-tables" name="complex-tables">2.21 Complex tables</a></h2> -<p>Here's a complex table, which should test all features.</p> -<table border="1" class="docutils"> -<colgroup> -<col width="43%" /> -<col width="21%" /> -<col width="18%" /> -<col width="18%" /> -</colgroup> -<thead valign="bottom"> -<tr><th class="head">Header row, column 1 -(header rows optional)</th> -<th class="head">Header 2</th> -<th class="head">Header 3</th> -<th class="head">Header 4</th> -</tr> -</thead> -<tbody valign="top"> -<tr><td>body row 1, column 1</td> -<td>column 2</td> -<td>column 3</td> -<td>column 4</td> -</tr> -<tr><td>body row 2</td> -<td colspan="3">Cells may span columns.</td> -</tr> -<tr><td>body row 3</td> -<td rowspan="2"><p class="first">Cells may -span rows.</p> -<p class="last">Paragraph.</p> -</td> -<td colspan="2" rowspan="2"><ul class="first last simple"> -<li>Table cells</li> -<li>contain</li> -<li>body elements.</li> -</ul> -</td> -</tr> -<tr><td>body row 4</td> -</tr> -<tr><td>body row 5</td> -<td colspan="2">Cells may also be -empty: <tt class="docutils literal"><span class="pre">--></span></tt></td> -<td> </td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id69" id="list-tables" name="list-tables">2.22 List Tables</a></h2> -<p>Here's a list table exercising all features:</p> -<table border="1" class="test docutils"> -<caption>list table with integral header</caption> -<colgroup> -<col width="17%" /> -<col width="33%" /> -<col width="50%" /> -</colgroup> -<thead valign="bottom"> -<tr><th class="head stub">Treat</th> -<th class="head">Quantity</th> -<th class="head">Description</th> -</tr> -</thead> -<tbody valign="top"> -<tr><th class="stub">Albatross</th> -<td>2.99</td> -<td>On a stick!</td> -</tr> -<tr><th class="stub">Crunchy Frog</th> -<td>1.49</td> -<td>If we took the bones out, it wouldn't be -crunchy, now would it?</td> -</tr> -<tr><th class="stub">Gannet Ripple</th> -<td>1.99</td> -<td>On a stick!</td> -</tr> -</tbody> -</table> -</div> -<div class="section"> -<h2><a class="toc-backref" href="#id70" id="custom-roles" name="custom-roles">2.23 Custom Roles</a></h2> -<p><tt class="custom docutils literal"><span class="pre">one</span></tt> <tt class="custom docutils literal"><span class="pre">two</span></tt> <tt class="custom docutils literal"><span class="pre">three</span></tt></p> -</div> -</div> -<div class="section"> -<h1><a class="toc-backref" href="#id71" id="error-handling" name="error-handling">3 Error Handling</a></h1> -<p>Any errors caught during processing will generate system messages.</p> -<p>There should be five messages in the following, auto-generated -section, "Docutils System Messages":</p> -<!-- section should be added by Docutils automatically --> -</div> -<div class="system-messages section"> -<h1>Docutils System Messages</h1> -<div class="system-message" id="id23"> -<p class="system-message-title">System Message: <a name="id23">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 100); <em><a href="#id24">backlink</a></em></p> -Undefined substitution referenced: "problematic".</div> -<div class="system-message" id="id80"> -<p class="system-message-title">System Message: <a name="id80">ERROR/3</a> (<tt class="docutils">functional/input/standalone_rst_html4css1.txt</tt>, line 358); <em><a href="#id81">backlink</a></em></p> -Unknown target name: "5".</div> -<div class="system-message" id="id82"> -<p class="system-message-title">System Message: <a name="id82">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 367); <em><a href="#id83">backlink</a></em></p> -Unknown target name: "nonexistent".</div> -<div class="system-message" id="id84"> -<p class="system-message-title">System Message: <a name="id84">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 394); <em><a href="#id85">backlink</a></em></p> -Unknown target name: "hyperlink reference without a target".</div> -<div class="system-message" id="id86"> -<p class="system-message-title">System Message: <a name="id86">ERROR/3</a> (<tt class="docutils">functional/input/data/standard.txt</tt>, line 407); <em><a href="#id87">backlink</a></em></p> -Duplicate target name, cannot be used as a unique reference: "duplicate target names".</div> -</div> -</div> -<div class="footer"> -<hr class="footer" /> -Document footer -</div> -</body> -</html> diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex deleted file mode 100644 index ba5b63bb0..000000000 --- a/docutils/test/functional/expected/standalone_rst_latex.tex +++ /dev/null @@ -1,1556 +0,0 @@ -\documentclass[10pt,a4paper,english]{article} -\usepackage{babel} -\usepackage{ae} -\usepackage{aeguill} -\usepackage{shortvrb} -\usepackage[latin1]{inputenc} -\usepackage{tabularx} -\usepackage{longtable} -\setlength{\extrarowheight}{2pt} -\usepackage{amsmath} -\usepackage{graphicx} -\usepackage{color} -\usepackage{multirow} -\usepackage{ifthen} -\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} -\usepackage[DIV12]{typearea} -%% generator Docutils: http://docutils.sourceforge.net/ -\newlength{\admonitionwidth} -\setlength{\admonitionwidth}{0.9\textwidth} -\newlength{\docinfowidth} -\setlength{\docinfowidth}{0.9\textwidth} -\newlength{\locallinewidth} -\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} -\newenvironment{optionlist}[1] -{\begin{list}{} - {\setlength{\labelwidth}{#1} - \setlength{\rightmargin}{1cm} - \setlength{\leftmargin}{\rightmargin} - \addtolength{\leftmargin}{\labelwidth} - \addtolength{\leftmargin}{\labelsep} - \renewcommand{\makelabel}{\optionlistlabel}} -}{\end{list}} -\newlength{\lineblockindentation} -\setlength{\lineblockindentation}{2.5em} -\newenvironment{lineblock}[1] -{\begin{list}{} - {\setlength{\partopsep}{\parskip} - \addtolength{\partopsep}{\baselineskip} - \topsep0pt\itemsep0.15\baselineskip\parsep0pt - \leftmargin#1} - \raggedright} -{\end{list}} -% begin: floats for footnotes tweaking. -\setlength{\floatsep}{0.5em} -\setlength{\textfloatsep}{\fill} -\addtolength{\textfloatsep}{3em} -\renewcommand{\textfraction}{0.5} -\renewcommand{\topfraction}{0.5} -\renewcommand{\bottomfraction}{0.5} -\setcounter{totalnumber}{50} -\setcounter{topnumber}{50} -\setcounter{bottomnumber}{50} -% end floats for footnotes -% some commands, that could be overwritten in the style file. -\newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}} -\newcommand{\titlereference}[1]{\textsl{#1}} -% end of "some commands" -\title{reStructuredText Test Document\\ -\large{Examples of Syntax Constructs} -} -\author{} -\date{} -\hypersetup{ -pdftitle={reStructuredText Test Document}, -pdfauthor={David Goodger;Me;Myself;I} -} -\raggedbottom -\begin{document} -\maketitle - -%___________________________________________________________________________ -\begin{center} -\begin{tabularx}{\docinfowidth}{lX} -\textbf{Author}: & - David Goodger \\ -\textbf{Address}: & - {\raggedright -123 Example Street~\\ -Example, EX Canada~\\ -A1B 2C3 } \\ -\textbf{Contact}: & - \href{mailto:goodger@users.sourceforge.net}{goodger@users.sourceforge.net} \\ -\textbf{Author}: & - Me \\ -\textbf{Author}: & - Myself \\ -\textbf{Author}: & - I \\ -\textbf{Organization}: & - humankind \\ -\textbf{Date}: & - Now, or yesterday. Or maybe even \emph{before} yesterday. \\ -\textbf{Status}: & - This is a ``work in progress'' \\ -\textbf{Revision}: & - is managed by a version control system. \\ -\textbf{Version}: & - 1 \\ -\textbf{Copyright}: & - This document has been placed in the public domain. You -may do with it as you wish. You may copy, modify, -redistribute, reattribute, sell, buy, rent, lease, -destroy, or improve it, quote it at length, excerpt, -incorporate, collate, fold, staple, or mutilate it, or do -anything else to it that your or anyone else's heart -desires. \\ -\textbf{field name}: & - This is a ``generic bibliographic field''. \\ -\textbf{field name ``2''}: & - Generic bibliographic fields may contain multiple body elements. - -Like this. \\ -\end{tabularx} -\end{center} - -\setlength{\locallinewidth}{\linewidth} - - -\subsubsection*{~\hfill Dedication\hfill ~} - -For Docutils users {\&} co-developers. - -\subsubsection*{~\hfill Abstract\hfill ~} - -This is a test document, containing at least one example of each -reStructuredText construct. - -% This is a comment. Note how any initial comments are moved by -% transforms to after the document title, subtitle, and docinfo. -% Above is the document title, and below is the subtitle. -% They are transformed from section titles after parsing. -% bibliographic fields (which also require a transform): -\hypertarget{table-of-contents}{} -\pdfbookmark[0]{Table of Contents}{table-of-contents} -\subsubsection*{~\hfill Table of Contents\hfill ~} -\begin{list}{}{} -\item {} \href{\#structural-elements}{1~~~Structural Elements} -\begin{list}{}{} -\item {} \href{\#section-title}{1.1~~~Section Title} - -\item {} \href{\#empty-section}{1.2~~~Empty Section} - -\item {} \href{\#transitions}{1.3~~~Transitions} - -\end{list} - -\item {} \href{\#body-elements}{2~~~Body Elements} -\begin{list}{}{} -\item {} \href{\#paragraphs}{2.1~~~Paragraphs} -\begin{list}{}{} -\item {} \href{\#inline-markup}{2.1.1~~~Inline Markup} - -\end{list} - -\item {} \href{\#bullet-lists}{2.2~~~Bullet Lists} - -\item {} \href{\#enumerated-lists}{2.3~~~Enumerated Lists} - -\item {} \href{\#definition-lists}{2.4~~~Definition Lists} - -\item {} \href{\#field-lists}{2.5~~~Field Lists} - -\item {} \href{\#option-lists}{2.6~~~Option Lists} - -\item {} \href{\#literal-blocks}{2.7~~~Literal Blocks} - -\item {} \href{\#line-blocks}{2.8~~~Line Blocks} - -\item {} \href{\#block-quotes}{2.9~~~Block Quotes} - -\item {} \href{\#doctest-blocks}{2.10~~~Doctest Blocks} - -\item {} \href{\#footnotes}{2.11~~~Footnotes} - -\item {} \href{\#citations}{2.12~~~Citations} - -\item {} \href{\#targets}{2.13~~~Targets} -\begin{list}{}{} -\item {} \href{\#duplicate-target-names}{2.13.1~~~Duplicate Target Names} - -\item {} \href{\#id20}{2.13.2~~~Duplicate Target Names} - -\end{list} - -\item {} \href{\#directives}{2.14~~~Directives} -\begin{list}{}{} -\item {} \href{\#document-parts}{2.14.1~~~Document Parts} - -\item {} \href{\#images}{2.14.2~~~Images} - -\item {} \href{\#admonitions}{2.14.3~~~Admonitions} - -\item {} \href{\#topics-sidebars-and-rubrics}{2.14.4~~~Topics, Sidebars, and Rubrics} - -\item {} \href{\#target-footnotes}{2.14.5~~~Target Footnotes} - -\item {} \href{\#replacement-text}{2.14.6~~~Replacement Text} - -\item {} \href{\#compound-paragraph}{2.14.7~~~Compound Paragraph} - -\item {} \href{\#parsed-literal-blocks}{2.14.8~~~Parsed Literal Blocks} - -\end{list} - -\item {} \href{\#substitution-definitions}{2.15~~~Substitution Definitions} - -\item {} \href{\#comments}{2.16~~~Comments} - -\item {} \href{\#raw-text}{2.17~~~Raw text} - -\item {} \href{\#container}{2.18~~~Container} - -\item {} \href{\#colspanning-tables}{2.19~~~Colspanning tables} - -\item {} \href{\#rowspanning-tables}{2.20~~~Rowspanning tables} - -\end{list} - -\item {} \href{\#tests-for-the-latex-writer}{3~~~Tests for the LaTeX writer} -\begin{list}{}{} -\item {} \href{\#monospaced-non-alphanumeric-characters}{3.1~~~Monospaced non-alphanumeric characters} - -\item {} \href{\#various-non-ascii-characters}{3.2~~~Various non-ASCII characters} - -\end{list} - -\item {} \href{\#error-handling}{4~~~Error Handling} - -\end{list} - - - -%___________________________________________________________________________ - -\hypertarget{structural-elements}{} -\pdfbookmark[0]{1~~~Structural Elements}{structural-elements} -\section*{1~~~Structural Elements} - - -%___________________________________________________________________________ - -\hypertarget{section-title}{} -\pdfbookmark[1]{1.1~~~Section Title}{section-title} -\subsection*{1.1~~~Section Title} -\textbf{Section Subtitle}\vspace{0.2cm} - -\noindent -That's it, the text just above this line. - - -%___________________________________________________________________________ - -\hypertarget{empty-section}{} -\pdfbookmark[1]{1.2~~~Empty Section}{empty-section} -\subsection*{1.2~~~Empty Section} - - -%___________________________________________________________________________ - -\hypertarget{transitions}{} -\pdfbookmark[1]{1.3~~~Transitions}{transitions} -\subsection*{1.3~~~Transitions} - -Here's a transition: - - -%___________________________________________________________________________ -\hspace*{\fill}\hrulefill\hspace*{\fill} - - -It divides the section. Transitions may also occur between sections: - - -%___________________________________________________________________________ -\hspace*{\fill}\hrulefill\hspace*{\fill} - - - -%___________________________________________________________________________ - -\hypertarget{body-elements}{} -\pdfbookmark[0]{2~~~Body Elements}{body-elements} -\section*{2~~~Body Elements} - - -%___________________________________________________________________________ - -\hypertarget{paragraphs}{} -\pdfbookmark[1]{2.1~~~Paragraphs}{paragraphs} -\subsection*{2.1~~~Paragraphs} - -A paragraph. - - -%___________________________________________________________________________ - -\hypertarget{inline-markup}{} -\pdfbookmark[2]{2.1.1~~~Inline Markup}{inline-markup} -\subsubsection*{2.1.1~~~Inline Markup} - -Paragraphs contain text and may contain inline markup: \emph{emphasis}, -\textbf{strong emphasis}, \texttt{inline literals}, standalone hyperlinks -(\href{http://www.python.org}{http://www.python.org}), external hyperlinks (\href{http://www.python.org/}{Python}\raisebox{.5em}[0em]{\scriptsize\hyperlink{id25}{5}}), internal -cross-references (\href{\#example}{example}), external hyperlinks with embedded URIs -(\href{http://www.python.org}{Python web site}), \href{http://www.python.org/}{anonymous hyperlink -references}\raisebox{.5em}[0em]{\scriptsize\hyperlink{id25}{5}} (\href{http://docutils.sourceforge.net/}{a second reference}\raisebox{.5em}[0em]{\scriptsize\hyperlink{id30}{6}}), footnote references (manually -numbered\raisebox{.5em}[0em]{\scriptsize\hyperlink{id8}{1}}, anonymous auto-numbered\raisebox{.5em}[0em]{\scriptsize\hyperlink{id11}{3}}, labeled auto-numbered\raisebox{.5em}[0em]{\scriptsize\hyperlink{label}{2}}, or symbolic\raisebox{.5em}[0em]{\scriptsize\hyperlink{id12}{*}}), citation references ([\hyperlink{cit2002}{CIT2002}]), -substitution references (\includegraphics{../../../docs/user/rst/images/biohazard.png}), and \hypertarget{inline-hyperlink-targets}{inline hyperlink targets} -(see \href{\#id22}{Targets} below for a reference back to here). Character-level -inline markup is also possible (although exceedingly ugly!) in \emph{re}\texttt{Structured}\emph{Text}. Problems are indicated by {\color{red}\bfseries{}{\textbar}problematic{\textbar}} text -(generated by processing errors; this one is intentional). Here is a -reference to the \href{\#doctitle}{doctitle} and the \href{\#subtitle}{subtitle}. - -The default role for interpreted text is \titlereference{Title Reference}. Here are -some explicit interpreted text roles: a PEP reference (\href{http://www.python.org/peps/pep-0287.html}{PEP 287}); an -RFC reference (\href{http://www.faqs.org/rfcs/rfc2822.html}{RFC 2822}); a $_{subscript}$; a $^{superscript}$; -and explicit roles for \emph{standard} \textbf{inline} -\texttt{markup}. -% DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! - -Let's test wrapping and whitespace significance in inline literals: -\texttt{This is an example of -{}-inline-literal -{}-text, -{}-including some-{}- -strangely-{}-hyphenated-words. Adjust-the-width-of-your-browser-window -to see how the text is wrapped. -{}- -{}-{}-{}- -{}-{}-{}-{}-{}-{}-{}- Now note the -spacing between the words of this sentence (words -should be grouped in pairs).} - -If the \texttt{-{}-pep-references} option was supplied, there should be a -live link to PEP 258 here. - - -%___________________________________________________________________________ - -\hypertarget{bullet-lists}{} -\pdfbookmark[1]{2.2~~~Bullet Lists}{bullet-lists} -\subsection*{2.2~~~Bullet Lists} -\begin{itemize} -\item {} -A bullet list -\begin{itemize} -\item {} -Nested bullet list. - -\item {} -Nested item 2. - -\end{itemize} - -\item {} -Item 2. - -Paragraph 2 of item 2. -\begin{itemize} -\item {} -Nested bullet list. - -\item {} -Nested item 2. -\begin{itemize} -\item {} -Third level. - -\item {} -Item 2. - -\end{itemize} - -\item {} -Nested item 3. - -\item {} -This nested list should be compacted by the HTML writer. -\hypertarget{target}{}% Even if this item contains a target and a comment. - -\end{itemize} - -\end{itemize} - - -%___________________________________________________________________________ - -\hypertarget{enumerated-lists}{} -\pdfbookmark[1]{2.3~~~Enumerated Lists}{enumerated-lists} -\subsection*{2.3~~~Enumerated Lists} -\newcounter{listcnt1} -\begin{list}{\arabic{listcnt1}.} -{ -\usecounter{listcnt1} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -Arabic numerals. -\newcounter{listcnt2} -\begin{list}{\alph{listcnt2})} -{ -\usecounter{listcnt2} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -lower alpha) -\newcounter{listcnt3} -\begin{list}{(\roman{listcnt3})} -{ -\usecounter{listcnt3} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -(lower roman) -\newcounter{listcnt4} -\begin{list}{\Alph{listcnt4}.} -{ -\usecounter{listcnt4} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -upper alpha. -\newcounter{listcnt5} -\begin{list}{\Roman{listcnt5})} -{ -\usecounter{listcnt5} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -upper roman) - -\end{list} - -\end{list} - -\end{list} - -\end{list} - -\item {} -Lists that don't start at 1: -\newcounter{listcnt6} -\begin{list}{\arabic{listcnt6}.} -{ -\usecounter{listcnt6} -\addtocounter{listcnt6}{2} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -Three - -\item {} -Four - -\end{list} -\newcounter{listcnt7} -\begin{list}{\Alph{listcnt7}.} -{ -\usecounter{listcnt7} -\addtocounter{listcnt7}{2} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -C - -\item {} -D - -\end{list} -\newcounter{listcnt8} -\begin{list}{\roman{listcnt8}.} -{ -\usecounter{listcnt8} -\addtocounter{listcnt8}{2} -\setlength{\rightmargin}{\leftmargin} -} -\item {} -iii - -\item {} -iv - -\end{list} - -\end{list} - - -%___________________________________________________________________________ - -\hypertarget{definition-lists}{} -\pdfbookmark[1]{2.4~~~Definition Lists}{definition-lists} -\subsection*{2.4~~~Definition Lists} -\begin{description} -%[visit_definition_list_item] -\item[{Term}] %[visit_definition] - -Definition - -%[depart_definition] -%[depart_definition_list_item] -%[visit_definition_list_item] -\item[{Term}] (\textbf{classifier}) -%[visit_definition] - -Definition paragraph 1. - -Definition paragraph 2. - -%[depart_definition] -%[depart_definition_list_item] -%[visit_definition_list_item] -\item[{Term}] %[visit_definition] - -Definition - -%[depart_definition] -%[depart_definition_list_item] -%[visit_definition_list_item] -\item[{Term}] (\textbf{classifier one}) -(\textbf{classifier two}) -%[visit_definition] - -Definition - -%[depart_definition] -%[depart_definition_list_item] -\end{description} - - -%___________________________________________________________________________ - -\hypertarget{field-lists}{} -\pdfbookmark[1]{2.5~~~Field Lists}{field-lists} -\subsection*{2.5~~~Field Lists} -\begin{quote} -\begin{description} -\item [what:] -Field lists map field names to field bodies, like database -records. They are often part of an extension syntax. They are -an unambiguous variant of RFC 2822 fields. - - -\item [how arg1 arg2:] -The field marker is a colon, the field name, and a colon. - -The field body may contain one or more body elements, indented -relative to the field marker. - - -\item [credits:] -This paragraph has the \titlereference{credits} class set. (This is actually not -about credits but just for ensuring that the class attribute -doesn't get stripped away.) - - -\end{description} -\end{quote} - - -%___________________________________________________________________________ - -\hypertarget{option-lists}{} -\pdfbookmark[1]{2.6~~~Option Lists}{option-lists} -\subsection*{2.6~~~Option Lists} - -For listing command-line options: -% [option list] -\begin{optionlist}{3cm} -\item [-a] -command-line option ``a'' -\item [-b file] -options can have arguments -and long descriptions -\item [-{}-long] -options can be long also -\item [-{}-input=file] -long options can also have -arguments -\item [-{}-very-long-option] -The description can also start on the next line. - -The description may contain multiple body elements, -regardless of where it starts. -\item [-x, -y, -z] -Multiple options are an ``option group''. -\item [-v, -{}-verbose] -Commonly-seen: short {\&} long options. -\item [-1 file, -{}-one=file, -{}-two file] -Multiple options with arguments. -\item [/V] -DOS/VMS-style options too -\end{optionlist} - -There must be at least two spaces between the option and the -description. - - -%___________________________________________________________________________ - -\hypertarget{literal-blocks}{} -\pdfbookmark[1]{2.7~~~Literal Blocks}{literal-blocks} -\subsection*{2.7~~~Literal Blocks} - -Literal blocks are indicated with a double-colon (``::'') at the end of -the preceding paragraph (over there \texttt{-{}->}). They can be indented: -\begin{quote}{\ttfamily \raggedright \noindent -if~literal{\_}block:~\\ -~~~~text~=~'is~left~as-is'~\\ -~~~~spaces{\_}and{\_}linebreaks~=~'are~preserved'~\\ -~~~~markup{\_}processing~=~None -}\end{quote} - -Or they can be quoted without indentation: -\begin{quote}{\ttfamily \raggedright \noindent ->{}>~Great~idea!~\\ ->~\\ ->~Why~didn't~I~think~of~that? -}\end{quote} - - -%___________________________________________________________________________ - -\hypertarget{line-blocks}{} -\pdfbookmark[1]{2.8~~~Line Blocks}{line-blocks} -\subsection*{2.8~~~Line Blocks} - -This section tests line blocks. Line blocks are body elements which -consist of lines and other line blocks. Nested line blocks cause -indentation. - -\begin{lineblock}{0em} -\item[] This is a line block. It ends with a blank line. -\item[] -\begin{lineblock}{\lineblockindentation} -\item[] New lines begin with a vertical bar (``{\textbar}''). -\item[] Line breaks and initial indent are significant, and preserved. -\item[] -\begin{lineblock}{\lineblockindentation} -\item[] Continuation lines are also possible. A long line that is intended -to wrap should begin with a space in place of the vertical bar. -\end{lineblock} -\item[] The left edge of a continuation line need not be aligned with -the left edge of the text above it. -\end{lineblock} -\end{lineblock} - -\begin{lineblock}{0em} -\item[] This is a second line block. -\item[] -\item[] Blank lines are permitted internally, but they must begin with a ``{\textbar}''. -\end{lineblock} - -Another line block, surrounded by paragraphs: - -\begin{lineblock}{0em} -\item[] And it's no good waiting by the window -\item[] It's no good waiting for the sun -\item[] Please believe me, the things you dream of -\item[] They don't fall in the lap of no-one -\end{lineblock} - -Take it away, Eric the Orchestra Leader! -\begin{quote} - -\begin{lineblock}{0em} -\item[] A one, two, a one two three four -\item[] -\item[] Half a bee, philosophically, -\item[] -\begin{lineblock}{\lineblockindentation} -\item[] must, \emph{ipso facto}, half not be. -\end{lineblock} -\item[] But half the bee has got to be, -\item[] -\begin{lineblock}{\lineblockindentation} -\item[] \emph{vis a vis} its entity. D'you see? -\item[] -\end{lineblock} -\item[] But can a bee be said to be -\item[] -\begin{lineblock}{\lineblockindentation} -\item[] or not to be an entire bee, -\item[] -\begin{lineblock}{\lineblockindentation} -\item[] when half the bee is not a bee, -\item[] -\begin{lineblock}{\lineblockindentation} -\item[] due to some ancient injury? -\item[] -\end{lineblock} -\end{lineblock} -\end{lineblock} -\item[] Singing... -\end{lineblock} -\end{quote} - - -%___________________________________________________________________________ - -\hypertarget{block-quotes}{} -\pdfbookmark[1]{2.9~~~Block Quotes}{block-quotes} -\subsection*{2.9~~~Block Quotes} - -Block quotes consist of indented body elements: -\begin{quote} - -My theory by A. Elk. Brackets Miss, brackets. This theory goes -as follows and begins now. All brontosauruses are thin at one -end, much much thicker in the middle and then thin again at the -far end. That is my theory, it is mine, and belongs to me and I -own it, and what it is too. - -\begin{flushright} ----Anne Elk (Miss) -\end{flushright} -\end{quote} - - -%___________________________________________________________________________ - -\hypertarget{doctest-blocks}{} -\pdfbookmark[1]{2.10~~~Doctest Blocks}{doctest-blocks} -\subsection*{2.10~~~Doctest Blocks} -\begin{verbatim}>>> print 'Python-specific usage examples; begun with ">>>"' -Python-specific usage examples; begun with ">>>" ->>> print '(cut and pasted from interactive Python sessions)' -(cut and pasted from interactive Python sessions)\end{verbatim} - - -%___________________________________________________________________________ - -\hypertarget{footnotes}{} -\pdfbookmark[1]{2.11~~~Footnotes}{footnotes} -\subsection*{2.11~~~Footnotes} -\begin{figure}[b]\hypertarget{id8}$^{1}$ -A footnote contains body elements, consistently indented by at -least 3 spaces. - -This is the footnote's second paragraph. -\end{figure} -\begin{figure}[b]\hypertarget{label}$^{2}$ -Footnotes may be numbered, either manually (as in\raisebox{.5em}[0em]{\scriptsize\hyperlink{id8}{1}}) or -automatically using a ``{\#}''-prefixed label. This footnote has a -label so it can be referred to from multiple places, both as a -footnote reference (\raisebox{.5em}[0em]{\scriptsize\hyperlink{label}{2}}) and as a hyperlink reference -(\href{\#label}{label}). -\end{figure} -\begin{figure}[b]\hypertarget{id11}$^{3}$ -This footnote is numbered automatically and anonymously using a -label of ``{\#}'' only. - -This is the second paragraph. - -And this is the third paragraph. -\end{figure} -\begin{figure}[b]\hypertarget{id12}$^{*}$ -Footnotes may also use symbols, specified with a ``*'' label. -Here's a reference to the next footnote:\raisebox{.5em}[0em]{\scriptsize\hyperlink{id14}{{\dag}}}. -\end{figure} -\begin{figure}[b]\hypertarget{id14}$^{{\dag}}$ -This footnote shows the next symbol in the sequence. -\end{figure} -\begin{figure}[b]\hypertarget{id15}$^{4}$ -Here's an unreferenced footnote, with a reference to a -nonexistent footnote:{\color{red}\bfseries{}{[}5{]}{\_}}. -\end{figure} - - -%___________________________________________________________________________ - -\hypertarget{citations}{} -\pdfbookmark[1]{2.12~~~Citations}{citations} -\subsection*{2.12~~~Citations} -\begin{figure}[b]\hypertarget{cit2002}[CIT2002] -Citations are text-labeled footnotes. They may be -rendered separately and differently from footnotes. -\end{figure} - -Here's a reference to the above, [\hyperlink{cit2002}{CIT2002}], and a {\color{red}\bfseries{}{[}nonexistent{]}{\_}} -citation. - - -%___________________________________________________________________________ - -\hypertarget{targets}{} -\hypertarget{another-target}{} -\pdfbookmark[1]{2.13~~~Targets}{targets} -\pdfbookmark[1]{2.13~~~Targets}{another-target} -\subsection*{2.13~~~Targets} - -This paragraph is pointed to by the explicit ``example'' target. A -reference can be found under \href{\#inline-markup}{Inline Markup}, above. \href{\#inline-hyperlink-targets}{Inline -hyperlink targets} are also possible. - -Section headers are implicit targets, referred to by name. See -\href{\#id22}{Targets}, which is a subsection of \href{\#body-elements}{Body Elements}. - -Explicit external targets are interpolated into references such as -``\href{http://www.python.org/}{Python}\raisebox{.5em}[0em]{\scriptsize\hyperlink{id25}{5}}''. - -Targets may be indirect and anonymous. Thus \href{\#id22}{this phrase} may also -refer to the \href{\#id22}{Targets} section. - -Here's a {\color{red}\bfseries{}`hyperlink reference without a target`{\_}}, which generates an -error. - - -%___________________________________________________________________________ - -\hypertarget{duplicate-target-names}{} -\pdfbookmark[2]{2.13.1~~~Duplicate Target Names}{duplicate-target-names} -\subsubsection*{2.13.1~~~Duplicate Target Names} - -Duplicate names in section headers or other implicit targets will -generate ``info'' (level-1) system messages. Duplicate names in -explicit targets will generate ``warning'' (level-2) system messages. - - -%___________________________________________________________________________ - -\hypertarget{id20}{} -\pdfbookmark[2]{2.13.2~~~Duplicate Target Names}{id20} -\subsubsection*{2.13.2~~~Duplicate Target Names} - -Since there are two ``Duplicate Target Names'' section headers, we -cannot uniquely refer to either of them by name. If we try to (like -this: {\color{red}\bfseries{}`Duplicate Target Names`{\_}}), an error is generated. - - -%___________________________________________________________________________ - -\hypertarget{directives}{} -\pdfbookmark[1]{2.14~~~Directives}{directives} -\subsection*{2.14~~~Directives} -\begin{list}{}{} -\item {} \href{\#document-parts}{2.14.1~~~Document Parts} - -\item {} \href{\#images}{2.14.2~~~Images} - -\item {} \href{\#admonitions}{2.14.3~~~Admonitions} - -\item {} \href{\#topics-sidebars-and-rubrics}{2.14.4~~~Topics, Sidebars, and Rubrics} - -\item {} \href{\#target-footnotes}{2.14.5~~~Target Footnotes} - -\item {} \href{\#replacement-text}{2.14.6~~~Replacement Text} - -\item {} \href{\#compound-paragraph}{2.14.7~~~Compound Paragraph} - -\item {} \href{\#parsed-literal-blocks}{2.14.8~~~Parsed Literal Blocks} - -\end{list} - - -These are just a sample of the many reStructuredText Directives. For -others, please see -\href{http://docutils.sourceforge.net/docs/ref/rst/directives.html}{http://docutils.sourceforge.net/docs/ref/rst/directives.html}. - - -%___________________________________________________________________________ - -\hypertarget{document-parts}{} -\pdfbookmark[2]{2.14.1~~~Document Parts}{document-parts} -\subsubsection*{2.14.1~~~Document Parts} - -An example of the ``contents'' directive can be seen above this section -(a local, untitled table of \href{\#contents}{contents}) and at the beginning of the -document (a document-wide \href{\#table-of-contents}{table of contents}). - - -%___________________________________________________________________________ - -\hypertarget{images}{} -\pdfbookmark[2]{2.14.2~~~Images}{images} -\subsubsection*{2.14.2~~~Images} - -An image directive (also clickable -{}- a hyperlink reference): -\href{\#directives}{\includegraphics{../../../docs/user/rst/images/title.png}} -Image with multiple IDs: - -\includegraphics{../../../docs/user/rst/images/title.png} - -A centered image: - -{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png}\hfill} - -A left-aligned image: - -{\includegraphics{../../../docs/user/rst/images/biohazard.png}\hfill} - -A right-aligned image: - -{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png}} - -A figure directive: -\begin{figure}[htbp]\begin{flushright} - -\includegraphics[width=50]{../../../docs/user/rst/images/biohazard.png} -\caption{A figure is an image with a caption and/or a legend:}{\small -\begin{longtable}[c]{|p{0.16\locallinewidth}|p{0.56\locallinewidth}|} -\hline - -re - & -Revised, revisited, based on 're' module. - \\ -\hline - -Structured - & -Structure-enhanced text, structuredtext. - \\ -\hline - -Text - & -Well it is, isn't it? - \\ -\hline -\end{longtable} - -This paragraph is also part of the legend. -}\end{flushright}\end{figure} -\begin{figure}[htbp]\begin{flushleft} - -\includegraphics[width=50]{../../../docs/user/rst/images/biohazard.png} -\caption{A left-aligned figure.}{\small -This is the legend. -}\end{flushleft}\end{figure} - -This paragraph might flow around the figure... - -A centered figure: -\begin{figure}[htbp]\begin{flushcenter} - -\includegraphics[width=50]{../../../docs/user/rst/images/biohazard.png} -\caption{This is the caption.}{\small -This is the legend. - -The legend may consist of several paragraphs. -}\end{flushcenter}\end{figure} - -This paragraph might flow around the figure... - -A left-aligned figure: -\begin{figure}[htbp]\begin{flushleft} - -\includegraphics[width=50]{../../../docs/user/rst/images/biohazard.png} -\caption{This is the caption.}{\small -This is the legend. - -The legend may consist of several paragraphs. -}\end{flushleft}\end{figure} - -This paragraph might flow around the figure... - -Now widths: - -An image 2 em wide: - -\includegraphics[width=2em]{../../../docs/user/rst/images/biohazard.png} - -An image 2 em wide and 30 pixel high: - -\includegraphics[width=2em]{../../../docs/user/rst/images/biohazard.png} - -An image occupying 70{\%} of the line width: - -\includegraphics[width=70%]{../../../docs/user/rst/images/biohazard.png} - -An image 3 cm high: - -\includegraphics{../../../docs/user/rst/images/biohazard.png} - - -%___________________________________________________________________________ - -\hypertarget{admonitions}{} -\pdfbookmark[2]{2.14.3~~~Admonitions}{admonitions} -\subsubsection*{2.14.3~~~Admonitions} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Attention!} -\vspace{2mm} - -Directives at large. -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Caution!} -\vspace{2mm} - -Don't take any wooden nickels. -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large !DANGER!} -\vspace{2mm} - -Mad scientist at work! -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Error} -\vspace{2mm} - -Does not compute. -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Hint} -\vspace{2mm} - -It's bigger than a bread box. -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Important} -\vspace{2mm} -\begin{itemize} -\item {} -Wash behind your ears. - -\item {} -Clean up your room. - -\item {} -Call your mother. - -\item {} -Back up your data. - -\end{itemize} -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Note} -\vspace{2mm} - -This is a note. -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Tip} -\vspace{2mm} - -15{\%} if the service is good. -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\textbf{\large Warning} -\vspace{2mm} - -Strong prose may provoke extreme mental exertion. -Reader discretion is strongly advised. -}} -\end{sffamily} -\end{center} -\begin{center}\begin{sffamily} -\fbox{\parbox{\admonitionwidth}{ -\vspace{2mm} -\textbf{\large And, by the way...} -\smallskip - -You can make up your own admonition too. -}} -\end{sffamily} -\end{center} - - -%___________________________________________________________________________ - -\hypertarget{topics-sidebars-and-rubrics}{} -\pdfbookmark[2]{2.14.4~~~Topics, Sidebars, and Rubrics}{topics-sidebars-and-rubrics} -\subsubsection*{2.14.4~~~Topics, Sidebars, and Rubrics} - -\setlength{\locallinewidth}{0.9\admonitionwidth} -\begin{center}\begin{sffamily} -\fbox{\colorbox[gray]{0.80}{\parbox{\admonitionwidth}{ -\textbf{\large Sidebar Title} -\smallskip -~\\ -\textbf{Optional Subtitle} -\smallskip - -This is a sidebar. It is for text outside the flow of the main -text. -\rubric{This is a rubric inside a sidebar} - -Sidebars often appears beside the main text with a border and -background color. -}}} -\end{sffamily} -\end{center} - -\setlength{\locallinewidth}{\linewidth} -\subsubsection*{~\hfill Topic Title\hfill ~} - -This is a topic. - -\rubric{This is a rubric} - - -%___________________________________________________________________________ - -\hypertarget{target-footnotes}{} -\pdfbookmark[2]{2.14.5~~~Target Footnotes}{target-footnotes} -\subsubsection*{2.14.5~~~Target Footnotes} -\begin{figure}[b]\hypertarget{id25}$^{5}$ -\href{http://www.python.org/}{http://www.python.org/} -\end{figure} -\begin{figure}[b]\hypertarget{id30}$^{6}$ -\href{http://docutils.sourceforge.net/}{http://docutils.sourceforge.net/} -\end{figure} - - -%___________________________________________________________________________ - -\hypertarget{replacement-text}{} -\pdfbookmark[2]{2.14.6~~~Replacement Text}{replacement-text} -\subsubsection*{2.14.6~~~Replacement Text} - -I recommend you try \href{http://www.python.org/}{Python, \emph{the} best language around}\raisebox{.5em}[0em]{\scriptsize\hyperlink{id25}{5}}. - - -%___________________________________________________________________________ - -\hypertarget{compound-paragraph}{} -\pdfbookmark[2]{2.14.7~~~Compound Paragraph}{compound-paragraph} -\subsubsection*{2.14.7~~~Compound Paragraph} - -Compound 1, paragraph 1. - -Compound 1, paragraph 2. -\begin{itemize} -\item {} -Compound 1, list item one. - -\item {} -Compound 1, list item two. - -\end{itemize} - -Another compound statement: - -Compound 2, a literal block: -\begin{quote}{\ttfamily \raggedright \noindent -Compound~2,~literal. -}\end{quote} -Compound 2, this is a test. - -Compound 3, only consisting of one paragraph. -\begin{quote}{\ttfamily \raggedright \noindent -Compound~4.~\\ -This~one~starts~with~a~literal~block. -}\end{quote} -Compound 4, a paragraph. - -Now something \emph{really} perverted -{}- a nested compound block. This is -just to test that it works at all; the results don't have to be -meaningful. - -Compound 5, block 1 (a paragraph). - -Compound 6, block 2 in compound 5. - -Compound 6, another paragraph. - -Compound 5, block 3 (a paragraph). - -Compound 7, with a table inside: - -\begin{longtable}[c]{|p{0.25\locallinewidth}|p{0.25\locallinewidth}|p{0.25\locallinewidth}|} -\hline - -Left cell, first -paragraph. - -Left cell, second -paragraph. - & -Middle cell, -consisting of -exactly one -paragraph. - & -Right cell. - -Paragraph 2. - -Paragraph 3. - \\ -\hline -\end{longtable} -Compound 7, a paragraph after the table. - -Compound 7, another paragraph. - - -%___________________________________________________________________________ - -\hypertarget{parsed-literal-blocks}{} -\pdfbookmark[2]{2.14.8~~~Parsed Literal Blocks}{parsed-literal-blocks} -\subsubsection*{2.14.8~~~Parsed Literal Blocks} -\begin{quote}{\ttfamily \raggedright \noindent -This~is~a~parsed~literal~block.~\\ -~~~~This~line~is~indented.~~The~next~line~is~blank.~\\ -~\\ -Inline~markup~is~supported,~e.g.~\emph{emphasis},~\textbf{strong},~\texttt{literal~\\ -text},~footnotes\raisebox{.5em}[0em]{\scriptsize\hyperlink{id8}{1}},~\hypertarget{id22}{targets},~and~\href{http://www.python.org/}{references}. -}\end{quote} - - -%___________________________________________________________________________ - -\hypertarget{substitution-definitions}{} -\pdfbookmark[1]{2.15~~~Substitution Definitions}{substitution-definitions} -\subsection*{2.15~~~Substitution Definitions} - -An inline image (\includegraphics{../../../docs/user/rst/images/biohazard.png}) example: - -(Substitution definitions are not visible in the HTML source.) - - -%___________________________________________________________________________ - -\hypertarget{comments}{} -\pdfbookmark[1]{2.16~~~Comments}{comments} -\subsection*{2.16~~~Comments} - -Here's one: -% Comments begin with two dots and a space. Anything may -% follow, except for the syntax of footnotes, hyperlink -% targets, directives, or substitution definitions. -% -% Double-dashes -- "--" -- must be escaped somehow in HTML output. - -(View the HTML source to see the comment.) - - -%___________________________________________________________________________ - -\hypertarget{raw-text}{} -\pdfbookmark[1]{2.17~~~Raw text}{raw-text} -\subsection*{2.17~~~Raw text} - -This does not necessarily look nice, because there may be missing white space. - -It's just there to freeze the behavior. -A test.Second test.Another test with myclass set. -This is the fourth test with myrawroleclass set. -Fifth test in LaTeX.\\Line two. - -%___________________________________________________________________________ - -\hypertarget{container}{} -\pdfbookmark[1]{2.18~~~Container}{container} -\subsection*{2.18~~~Container} - -paragraph 1 - -paragraph 2 - - -%___________________________________________________________________________ - -\hypertarget{colspanning-tables}{} -\pdfbookmark[1]{2.19~~~Colspanning tables}{colspanning-tables} -\subsection*{2.19~~~Colspanning tables} - -This table has a cell spanning two columns: - -\begin{longtable}[c]{|p{0.07\locallinewidth}|p{0.07\locallinewidth}|p{0.09\locallinewidth}|} -\hline -\multicolumn{2}{|l|}{\textbf{ -Inputs -}} & \textbf{ -Output -} \\ -\hline -\textbf{ -A -} & \textbf{ -B -} & \textbf{ -A or B -} \\ -\hline -\endhead - -False - & -False - & -False - \\ -\hline - -True - & -False - & -True - \\ -\hline - -False - & -True - & -True - \\ -\hline - -True - & -True - & -True - \\ -\hline -\end{longtable} - - -%___________________________________________________________________________ - -\hypertarget{rowspanning-tables}{} -\pdfbookmark[1]{2.20~~~Rowspanning tables}{rowspanning-tables} -\subsection*{2.20~~~Rowspanning tables} - -Here's a table with cells spanning several rows: - -\begin{longtable}[c]{|p{0.30\locallinewidth}|p{0.16\locallinewidth}|p{0.23\locallinewidth}|} -\hline -\textbf{ -Header row, column 1 -(header rows optional) -} & \textbf{ -Header 2 -} & \textbf{ -Header 3 -} \\ -\hline -\endhead - -body row 1, column 1 - & -column 2 - & -column 3 - \\ -\hline - -body row 2 - & \multirow{2}{0.16\locallinewidth}{ -Cells may -span rows. -} & \multirow{2}{0.23\locallinewidth}{ -Another -rowspanning -cell. -} \\ -\cline{1-1} - -body row 3 - & \\ -\hline -\end{longtable} - - -%___________________________________________________________________________ - -\hypertarget{tests-for-the-latex-writer}{} -\pdfbookmark[0]{3~~~Tests for the LaTeX writer}{tests-for-the-latex-writer} -\section*{3~~~Tests for the LaTeX writer} - - -%___________________________________________________________________________ - -\hypertarget{monospaced-non-alphanumeric-characters}{} -\pdfbookmark[1]{3.1~~~Monospaced non-alphanumeric characters}{monospaced-non-alphanumeric-characters} -\subsection*{3.1~~~Monospaced non-alphanumeric characters} - -These are all ASCII characters except a-zA-Z0-9 and space: - -\texttt{!!!"{}"{}"{\#}{\#}{\#}{\$}{\$}{\$}{\%}{\%}{\%}{\&}{\&}{\&}'{}'{}'((()))***+++,{},{},-{}-{}-...///:::} - -\texttt{;;;<{}<{}<===>{}>{}>???@@@{[}{[}{[}{\textbackslash}{\textbackslash}{\textbackslash}{]}{]}{]}{\textasciicircum}{\textasciicircum}{\textasciicircum}{\_}{\_}{\_}`{}`{}`{\{}{\{}{\{}|||{\}}{\}}{\}}{\textasciitilde}{\textasciitilde}{\textasciitilde}} - -\texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} - -The two lines of non-alphanumeric characters should both have the same -width as the third line. - - -%___________________________________________________________________________ - -\hypertarget{various-non-ascii-characters}{} -\pdfbookmark[1]{3.2~~~Various non-ASCII characters}{various-non-ascii-characters} -\subsection*{3.2~~~Various non-ASCII characters} - -\begin{longtable}[c]{|p{0.03\locallinewidth}|p{0.42\locallinewidth}|} -\hline - -© - & -copyright sign - \\ -\hline - -® - & -registered sign - \\ -\hline - -« - & -left pointing guillemet - \\ -\hline - -» - & -right pointing guillemet - \\ -\hline - -{--} - & -en-dash - \\ -\hline - -{---} - & -em-dash - \\ -\hline - -` - & -single turned comma quotation mark - \\ -\hline - -' - & -single comma quotation mark - \\ -\hline - -, - & -low single comma quotation mark - \\ -\hline - -`` - & -double turned comma quotation mark - \\ -\hline - -'' - & -double comma quotation mark - \\ -\hline - -,, - & -low double comma quotation mark - \\ -\hline - -{\dag} - & -dagger - \\ -\hline - -{\ddag} - & -double dagger - \\ -\hline - -{\dots} - & -ellipsis - \\ -\hline - -{\texttrademark} - & -trade mark sign - \\ -\hline - -{$\Leftrightarrow$} - & -left-right double arrow - \\ -\hline -\end{longtable} - -The following line should not be wrapped, because it uses -non-breakable spaces: - -X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X - - -%___________________________________________________________________________ - -\hypertarget{error-handling}{} -\pdfbookmark[0]{4~~~Error Handling}{error-handling} -\section*{4~~~Error Handling} - -Any errors caught during processing will generate system messages. - -There should be five messages in the following, auto-generated -section, ``Docutils System Messages'': -% section should be added by Docutils automatically - - -%___________________________________________________________________________ - -\section*{Docutils System Messages} - -Undefined substitution referenced: ``problematic''. - - -Unknown target name: ``5''. - - -Unknown target name: ``nonexistent''. - - -Unknown target name: ``hyperlink reference without a target''. - - -Duplicate target name, cannot be used as a unique reference: ``duplicate target names''. - - -\end{document} diff --git a/docutils/test/functional/expected/standalone_rst_pseudoxml.txt b/docutils/test/functional/expected/standalone_rst_pseudoxml.txt deleted file mode 100644 index 193f8c37c..000000000 --- a/docutils/test/functional/expected/standalone_rst_pseudoxml.txt +++ /dev/null @@ -1,1841 +0,0 @@ -<document ids="restructuredtext-test-document doctitle" names="restructuredtext\ test\ document doctitle" source="functional/input/standalone_rst_pseudoxml.txt" title="reStructuredText Test Document"> - <title> - reStructuredText Test Document - <subtitle ids="examples-of-syntax-constructs subtitle" names="examples\ of\ syntax\ constructs subtitle"> - Examples of Syntax Constructs - <decoration> - <header> - <paragraph> - Document header - <footer> - <paragraph> - Document footer - <docinfo> - <author> - David Goodger - <address xml:space="preserve"> - 123 Example Street - Example, EX Canada - A1B 2C3 - <contact> - <reference refuri="mailto:goodger@users.sourceforge.net"> - goodger@users.sourceforge.net - <authors> - <author> - Me - <author> - Myself - <author> - I - <organization> - humankind - <date> - Now, or yesterday. Or maybe even - <emphasis> - before - yesterday. - <status> - This is a "work in progress" - <revision> - is managed by a version control system. - <version> - 1 - <copyright> - This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. - <field> - <field_name> - field name - <field_body> - <paragraph> - This is a "generic bibliographic field". - <field> - <field_name> - field name "2" - <field_body> - <paragraph> - Generic bibliographic fields may contain multiple body elements. - <paragraph> - Like this. - <topic classes="dedication"> - <title> - Dedication - <paragraph> - For Docutils users & co-developers. - <topic classes="abstract"> - <title> - Abstract - <paragraph> - This is a test document, containing at least one example of each - reStructuredText construct. - <comment xml:space="preserve"> - This is a comment. Note how any initial comments are moved by - transforms to after the document title, subtitle, and docinfo. - <target refid="doctitle"> - <comment xml:space="preserve"> - Above is the document title, and below is the subtitle. - They are transformed from section titles after parsing. - <target refid="subtitle"> - <comment xml:space="preserve"> - bibliographic fields (which also require a transform): - <meta content="reStructuredText, test, parser" name="keywords"> - <meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description"> - <topic classes="contents" ids="table-of-contents" names="table\ of\ contents"> - <title> - Table of Contents - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id32" refid="structural-elements"> - <generated classes="sectnum"> - 1   - Structural Elements - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id33" refid="section-title"> - <generated classes="sectnum"> - 1.1   - Section Title - <list_item> - <paragraph> - <reference ids="id34" refid="empty-section"> - <generated classes="sectnum"> - 1.2   - Empty Section - <list_item> - <paragraph> - <reference ids="id35" refid="transitions"> - <generated classes="sectnum"> - 1.3   - Transitions - <list_item> - <paragraph> - <reference ids="id36" refid="body-elements"> - <generated classes="sectnum"> - 2   - Body Elements - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id37" refid="paragraphs"> - <generated classes="sectnum"> - 2.1   - Paragraphs - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id38" refid="inline-markup"> - <generated classes="sectnum"> - 2.1.1   - Inline Markup - <list_item> - <paragraph> - <reference ids="id39" refid="bullet-lists"> - <generated classes="sectnum"> - 2.2   - Bullet Lists - <list_item> - <paragraph> - <reference ids="id40" refid="enumerated-lists"> - <generated classes="sectnum"> - 2.3   - Enumerated Lists - <list_item> - <paragraph> - <reference ids="id41" refid="definition-lists"> - <generated classes="sectnum"> - 2.4   - Definition Lists - <list_item> - <paragraph> - <reference ids="id42" refid="field-lists"> - <generated classes="sectnum"> - 2.5   - Field Lists - <list_item> - <paragraph> - <reference ids="id43" refid="option-lists"> - <generated classes="sectnum"> - 2.6   - Option Lists - <list_item> - <paragraph> - <reference ids="id44" refid="literal-blocks"> - <generated classes="sectnum"> - 2.7   - Literal Blocks - <list_item> - <paragraph> - <reference ids="id45" refid="line-blocks"> - <generated classes="sectnum"> - 2.8   - Line Blocks - <list_item> - <paragraph> - <reference ids="id46" refid="block-quotes"> - <generated classes="sectnum"> - 2.9   - Block Quotes - <list_item> - <paragraph> - <reference ids="id47" refid="doctest-blocks"> - <generated classes="sectnum"> - 2.10   - Doctest Blocks - <list_item> - <paragraph> - <reference ids="id48" refid="footnotes"> - <generated classes="sectnum"> - 2.11   - Footnotes - <list_item> - <paragraph> - <reference ids="id49" refid="citations"> - <generated classes="sectnum"> - 2.12   - Citations - <list_item> - <paragraph> - <reference ids="id50" refid="targets"> - <generated classes="sectnum"> - 2.13   - Targets - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id51" refid="duplicate-target-names"> - <generated classes="sectnum"> - 2.13.1   - Duplicate Target Names - <list_item> - <paragraph> - <reference ids="id52" refid="id20"> - <generated classes="sectnum"> - 2.13.2   - Duplicate Target Names - <list_item> - <paragraph> - <reference ids="id53" refid="directives"> - <generated classes="sectnum"> - 2.14   - Directives - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id54" refid="document-parts"> - <generated classes="sectnum"> - 2.14.1   - Document Parts - <list_item> - <paragraph> - <reference ids="id55" refid="images"> - <generated classes="sectnum"> - 2.14.2   - Images - <list_item> - <paragraph> - <reference ids="id56" refid="admonitions"> - <generated classes="sectnum"> - 2.14.3   - Admonitions - <list_item> - <paragraph> - <reference ids="id57" refid="topics-sidebars-and-rubrics"> - <generated classes="sectnum"> - 2.14.4   - Topics, Sidebars, and Rubrics - <list_item> - <paragraph> - <reference ids="id58" refid="target-footnotes"> - <generated classes="sectnum"> - 2.14.5   - Target Footnotes - <list_item> - <paragraph> - <reference ids="id59" refid="replacement-text"> - <generated classes="sectnum"> - 2.14.6   - Replacement Text - <list_item> - <paragraph> - <reference ids="id60" refid="compound-paragraph"> - <generated classes="sectnum"> - 2.14.7   - Compound Paragraph - <list_item> - <paragraph> - <reference ids="id61" refid="parsed-literal-blocks"> - <generated classes="sectnum"> - 2.14.8   - Parsed Literal Blocks - <list_item> - <paragraph> - <reference ids="id62" refid="substitution-definitions"> - <generated classes="sectnum"> - 2.15   - Substitution Definitions - <list_item> - <paragraph> - <reference ids="id63" refid="comments"> - <generated classes="sectnum"> - 2.16   - Comments - <list_item> - <paragraph> - <reference ids="id64" refid="raw-text"> - <generated classes="sectnum"> - 2.17   - Raw text - <list_item> - <paragraph> - <reference ids="id65" refid="container"> - <generated classes="sectnum"> - 2.18   - Container - <list_item> - <paragraph> - <reference ids="id66" refid="colspanning-tables"> - <generated classes="sectnum"> - 2.19   - Colspanning tables - <list_item> - <paragraph> - <reference ids="id67" refid="rowspanning-tables"> - <generated classes="sectnum"> - 2.20   - Rowspanning tables - <list_item> - <paragraph> - <reference ids="id68" refid="complex-tables"> - <generated classes="sectnum"> - 2.21   - Complex tables - <list_item> - <paragraph> - <reference ids="id69" refid="list-tables"> - <generated classes="sectnum"> - 2.22   - List Tables - <list_item> - <paragraph> - <reference ids="id70" refid="error-handling"> - <generated classes="sectnum"> - 3   - Error Handling - <section ids="structural-elements" names="structural\ elements"> - <title auto="1" refid="id32"> - <generated classes="sectnum"> - 1   - Structural Elements - <section ids="section-title" names="section\ title"> - <title auto="1" refid="id33"> - <generated classes="sectnum"> - 1.1   - Section Title - <subtitle ids="section-subtitle" names="section\ subtitle"> - Section Subtitle - <paragraph> - That's it, the text just above this line. - <section ids="empty-section" names="empty\ section"> - <title auto="1" refid="id34"> - <generated classes="sectnum"> - 1.2   - Empty Section - <section ids="transitions" names="transitions"> - <title auto="1" refid="id35"> - <generated classes="sectnum"> - 1.3   - Transitions - <paragraph> - Here's a transition: - <transition> - <paragraph> - It divides the section. Transitions may also occur between sections: - <transition> - <section ids="body-elements" names="body\ elements"> - <title auto="1" refid="id36"> - <generated classes="sectnum"> - 2   - Body Elements - <section ids="paragraphs" names="paragraphs"> - <title auto="1" refid="id37"> - <generated classes="sectnum"> - 2.1   - Paragraphs - <paragraph> - A paragraph. - <section ids="inline-markup" names="inline\ markup"> - <title auto="1" refid="id38"> - <generated classes="sectnum"> - 2.1.1   - Inline Markup - <paragraph> - Paragraphs contain text and may contain inline markup: - <emphasis> - emphasis - , - <strong> - strong emphasis - , - <literal> - inline literals - , standalone hyperlinks - ( - <reference refuri="http://www.python.org"> - http://www.python.org - ), external hyperlinks ( - <reference name="Python" refuri="http://www.python.org/"> - Python - - <footnote_reference auto="1" ids="id26" refid="id25"> - 5 - ), internal - cross-references ( - <reference name="example" refid="example"> - example - ), external hyperlinks with embedded URIs - ( - <reference name="Python web site" refuri="http://www.python.org"> - Python web site - ), - <reference anonymous="1" name="anonymous hyperlink references" refuri="http://www.python.org/"> - anonymous hyperlink - references - - <footnote_reference auto="1" ids="id29" refid="id25"> - 5 - ( - <reference anonymous="1" name="a second reference" refuri="http://docutils.sourceforge.net/"> - a second reference - - <footnote_reference auto="1" ids="id31" refid="id30"> - 6 - ), footnote references (manually - numbered - <footnote_reference ids="id1" refid="id8"> - 1 - , anonymous auto-numbered - <footnote_reference auto="1" ids="id2" refid="id11"> - 3 - , labeled auto-numbered - <footnote_reference auto="1" ids="id3" refid="label"> - 2 - , or symbolic - <footnote_reference auto="*" ids="id4" refid="id12"> - * - ), citation references ( - <citation_reference ids="id5" refid="cit2002"> - CIT2002 - ), - substitution references ( - <image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png"> - ), and - <target ids="inline-hyperlink-targets" names="inline\ hyperlink\ targets"> - inline hyperlink targets - - (see - <reference name="Targets" refid="id22"> - Targets - below for a reference back to here). Character-level - inline markup is also possible (although exceedingly ugly!) in - <emphasis> - re - <literal> - Structured - <emphasis> - Text - . Problems are indicated by - <problematic ids="id24" refid="id23"> - |problematic| - text - (generated by processing errors; this one is intentional). Here is a - reference to the - <reference name="doctitle" refid="doctitle"> - doctitle - and the - <reference name="subtitle" refid="subtitle"> - subtitle - . - <target anonymous="1" ids="id6" refuri="http://www.python.org/"> - <target anonymous="1" ids="id7" refuri="http://docutils.sourceforge.net/"> - <paragraph> - The default role for interpreted text is - <title_reference> - Title Reference - . Here are - some explicit interpreted text roles: a PEP reference ( - <reference refuri="http://www.python.org/peps/pep-0287.html"> - PEP 287 - ); an - RFC reference ( - <reference refuri="http://www.faqs.org/rfcs/rfc2822.html"> - RFC 2822 - ); a - <subscript> - subscript - ; a - <superscript> - superscript - ; - and explicit roles for - <emphasis> - standard - - <strong> - inline - - <literal> - markup - . - <comment xml:space="preserve"> - DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! - <paragraph> - Let's test wrapping and whitespace significance in inline literals: - <literal> - This is an example of --inline-literal --text, --including some-- - strangely--hyphenated-words. Adjust-the-width-of-your-browser-window - to see how the text is wrapped. -- ---- -------- Now note the - spacing between the words of this sentence (words - should be grouped in pairs). - <paragraph> - If the - <literal> - --pep-references - option was supplied, there should be a - live link to PEP 258 here. - <section ids="bullet-lists" names="bullet\ lists"> - <title auto="1" refid="id39"> - <generated classes="sectnum"> - 2.2   - Bullet Lists - <bullet_list bullet="-"> - <list_item> - <paragraph> - A bullet list - <bullet_list bullet="+"> - <list_item> - <paragraph> - Nested bullet list. - <list_item> - <paragraph> - Nested item 2. - <list_item> - <paragraph> - Item 2. - <paragraph> - Paragraph 2 of item 2. - <bullet_list bullet="*"> - <list_item> - <paragraph> - Nested bullet list. - <list_item> - <paragraph> - Nested item 2. - <bullet_list bullet="-"> - <list_item> - <paragraph> - Third level. - <list_item> - <paragraph> - Item 2. - <list_item> - <paragraph> - Nested item 3. - <list_item> - <paragraph> - This nested list should be compacted by the HTML writer. - <target ids="target" names="target"> - <comment xml:space="preserve"> - Even if this item contains a target and a comment. - <section ids="enumerated-lists" names="enumerated\ lists"> - <title auto="1" refid="id40"> - <generated classes="sectnum"> - 2.3   - Enumerated Lists - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Arabic numerals. - <enumerated_list enumtype="loweralpha" prefix="" suffix=")"> - <list_item> - <paragraph> - lower alpha) - <enumerated_list enumtype="lowerroman" prefix="(" suffix=")"> - <list_item> - <paragraph> - (lower roman) - <enumerated_list enumtype="upperalpha" prefix="" suffix="."> - <list_item> - <paragraph> - upper alpha. - <enumerated_list enumtype="upperroman" prefix="" suffix=")"> - <list_item> - <paragraph> - upper roman) - <list_item> - <paragraph> - Lists that don't start at 1: - <enumerated_list enumtype="arabic" prefix="" start="3" suffix="."> - <list_item> - <paragraph> - Three - <list_item> - <paragraph> - Four - <enumerated_list enumtype="upperalpha" prefix="" start="3" suffix="."> - <list_item> - <paragraph> - C - <list_item> - <paragraph> - D - <enumerated_list enumtype="lowerroman" prefix="" start="3" suffix="."> - <list_item> - <paragraph> - iii - <list_item> - <paragraph> - iv - <section ids="definition-lists" names="definition\ lists"> - <title auto="1" refid="id41"> - <generated classes="sectnum"> - 2.4   - Definition Lists - <definition_list> - <definition_list_item> - <term> - Term - <definition> - <paragraph> - Definition - <definition_list_item> - <term> - Term - <classifier> - classifier - <definition> - <paragraph> - Definition paragraph 1. - <paragraph> - Definition paragraph 2. - <definition_list_item> - <term> - Term - <definition> - <paragraph> - Definition - <definition_list_item> - <term> - Term - <classifier> - classifier one - <classifier> - classifier two - <definition> - <paragraph> - Definition - <section ids="field-lists" names="field\ lists"> - <title auto="1" refid="id42"> - <generated classes="sectnum"> - 2.5   - Field Lists - <field_list> - <field> - <field_name> - what - <field_body> - <paragraph> - Field lists map field names to field bodies, like database - records. They are often part of an extension syntax. They are - an unambiguous variant of RFC 2822 fields. - <field> - <field_name> - how arg1 arg2 - <field_body> - <paragraph> - The field marker is a colon, the field name, and a colon. - <paragraph> - The field body may contain one or more body elements, indented - relative to the field marker. - <field> - <field_name> - credits - <field_body> - <paragraph classes="credits"> - This paragraph has the - <title_reference> - credits - class set. (This is actually not - about credits but just for ensuring that the class attribute - doesn't get stripped away.) - <section ids="option-lists" names="option\ lists"> - <title auto="1" refid="id43"> - <generated classes="sectnum"> - 2.6   - Option Lists - <paragraph> - For listing command-line options: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - command-line option "a" - <option_list_item> - <option_group> - <option> - <option_string> - -b - <option_argument delimiter=" "> - file - <description> - <paragraph> - options can have arguments - and long descriptions - <option_list_item> - <option_group> - <option> - <option_string> - --long - <description> - <paragraph> - options can be long also - <option_list_item> - <option_group> - <option> - <option_string> - --input - <option_argument delimiter="="> - file - <description> - <paragraph> - long options can also have - arguments - <option_list_item> - <option_group> - <option> - <option_string> - --very-long-option - <description> - <paragraph> - The description can also start on the next line. - <paragraph> - The description may contain multiple body elements, - regardless of where it starts. - <option_list_item> - <option_group> - <option> - <option_string> - -x - <option> - <option_string> - -y - <option> - <option_string> - -z - <description> - <paragraph> - Multiple options are an "option group". - <option_list_item> - <option_group> - <option> - <option_string> - -v - <option> - <option_string> - --verbose - <description> - <paragraph> - Commonly-seen: short & long options. - <option_list_item> - <option_group> - <option> - <option_string> - -1 - <option_argument delimiter=" "> - file - <option> - <option_string> - --one - <option_argument delimiter="="> - file - <option> - <option_string> - --two - <option_argument delimiter=" "> - file - <description> - <paragraph> - Multiple options with arguments. - <option_list_item> - <option_group> - <option> - <option_string> - /V - <description> - <paragraph> - DOS/VMS-style options too - <paragraph> - There must be at least two spaces between the option and the - description. - <section ids="literal-blocks" names="literal\ blocks"> - <title auto="1" refid="id44"> - <generated classes="sectnum"> - 2.7   - Literal Blocks - <paragraph> - Literal blocks are indicated with a double-colon ("::") at the end of - the preceding paragraph (over there - <literal> - --> - ). They can be indented: - <literal_block xml:space="preserve"> - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - <paragraph> - Or they can be quoted without indentation: - <literal_block xml:space="preserve"> - >> Great idea! - > - > Why didn't I think of that? - <section ids="line-blocks" names="line\ blocks"> - <title auto="1" refid="id45"> - <generated classes="sectnum"> - 2.8   - Line Blocks - <paragraph> - This section tests line blocks. Line blocks are body elements which - consist of lines and other line blocks. Nested line blocks cause - indentation. - <line_block> - <line> - This is a line block. It ends with a blank line. - <line_block> - <line> - New lines begin with a vertical bar ("|"). - <line> - Line breaks and initial indent are significant, and preserved. - <line_block> - <line> - Continuation lines are also possible. A long line that is intended - to wrap should begin with a space in place of the vertical bar. - <line> - The left edge of a continuation line need not be aligned with - the left edge of the text above it. - <line_block> - <line> - This is a second line block. - <line> - <line> - Blank lines are permitted internally, but they must begin with a "|". - <paragraph> - Another line block, surrounded by paragraphs: - <line_block> - <line> - And it's no good waiting by the window - <line> - It's no good waiting for the sun - <line> - Please believe me, the things you dream of - <line> - They don't fall in the lap of no-one - <paragraph> - Take it away, Eric the Orchestra Leader! - <block_quote> - <line_block> - <line> - A one, two, a one two three four - <line> - <line> - Half a bee, philosophically, - <line_block> - <line> - must, - <emphasis> - ipso facto - , half not be. - <line> - But half the bee has got to be, - <line_block> - <line> - <emphasis> - vis a vis - its entity. D'you see? - <line> - <line> - But can a bee be said to be - <line_block> - <line> - or not to be an entire bee, - <line_block> - <line> - when half the bee is not a bee, - <line_block> - <line> - due to some ancient injury? - <line> - <line> - Singing... - <section ids="block-quotes" names="block\ quotes"> - <title auto="1" refid="id46"> - <generated classes="sectnum"> - 2.9   - Block Quotes - <paragraph> - Block quotes consist of indented body elements: - <block_quote> - <paragraph> - My theory by A. Elk. Brackets Miss, brackets. This theory goes - as follows and begins now. All brontosauruses are thin at one - end, much much thicker in the middle and then thin again at the - far end. That is my theory, it is mine, and belongs to me and I - own it, and what it is too. - <attribution> - Anne Elk (Miss) - <section ids="doctest-blocks" names="doctest\ blocks"> - <title auto="1" refid="id47"> - <generated classes="sectnum"> - 2.10   - Doctest Blocks - <doctest_block xml:space="preserve"> - >>> print 'Python-specific usage examples; begun with ">>>"' - Python-specific usage examples; begun with ">>>" - >>> print '(cut and pasted from interactive Python sessions)' - (cut and pasted from interactive Python sessions) - <section ids="footnotes" names="footnotes"> - <title auto="1" refid="id48"> - <generated classes="sectnum"> - 2.11   - Footnotes - <footnote backrefs="id1 id9 id21" ids="id8" names="1"> - <label> - 1 - <paragraph> - A footnote contains body elements, consistently indented by at - least 3 spaces. - <paragraph> - This is the footnote's second paragraph. - <footnote auto="1" backrefs="id3 id10" ids="label" names="label"> - <label> - 2 - <paragraph> - Footnotes may be numbered, either manually (as in - <footnote_reference ids="id9" refid="id8"> - 1 - ) or - automatically using a "#"-prefixed label. This footnote has a - label so it can be referred to from multiple places, both as a - footnote reference ( - <footnote_reference auto="1" ids="id10" refid="label"> - 2 - ) and as a hyperlink reference - ( - <reference name="label" refid="label"> - label - ). - <footnote auto="1" backrefs="id2" ids="id11" names="3"> - <label> - 3 - <paragraph> - This footnote is numbered automatically and anonymously using a - label of "#" only. - <paragraph> - This is the second paragraph. - <paragraph> - And this is the third paragraph. - <footnote auto="*" backrefs="id4" ids="id12"> - <label> - * - <paragraph> - Footnotes may also use symbols, specified with a "*" label. - Here's a reference to the next footnote: - <footnote_reference auto="*" ids="id13" refid="id14"> - †- . - <footnote auto="*" backrefs="id13" ids="id14"> - <label> - †- <paragraph> - This footnote shows the next symbol in the sequence. - <footnote ids="id15" names="4"> - <label> - 4 - <paragraph> - Here's an unreferenced footnote, with a reference to a - nonexistent footnote: - <problematic ids="id80 id16" refid="id79"> - [5]_ - . - <section ids="citations" names="citations"> - <title auto="1" refid="id49"> - <generated classes="sectnum"> - 2.12   - Citations - <citation backrefs="id5 id17" ids="cit2002" names="cit2002"> - <label> - CIT2002 - <paragraph> - Citations are text-labeled footnotes. They may be - rendered separately and differently from footnotes. - <paragraph> - Here's a reference to the above, - <citation_reference ids="id17" refid="cit2002"> - CIT2002 - , and a - <problematic ids="id82 id18" refid="id81"> - [nonexistent]_ - - citation. - <target refid="another-target"> - <section dupnames="targets" ids="targets another-target" names="another\ target"> - <title auto="1" refid="id50"> - <generated classes="sectnum"> - 2.13   - Targets - <target refid="example"> - <paragraph ids="example" names="example"> - This paragraph is pointed to by the explicit "example" target. A - reference can be found under - <reference name="Inline Markup" refid="inline-markup"> - Inline Markup - , above. - <reference name="Inline hyperlink targets" refid="inline-hyperlink-targets"> - Inline - hyperlink targets - are also possible. - <paragraph> - Section headers are implicit targets, referred to by name. See - <reference name="Targets" refid="id22"> - Targets - , which is a subsection of - <reference name="Body Elements" refid="body-elements"> - Body Elements - . - <paragraph> - Explicit external targets are interpolated into references such as - " - <reference name="Python" refuri="http://www.python.org/"> - Python - - <footnote_reference auto="1" ids="id27" refid="id25"> - 5 - ". - <target ids="python" names="python" refuri="http://www.python.org/"> - <paragraph> - Targets may be indirect and anonymous. Thus - <reference anonymous="1" name="this phrase" refid="id22"> - this phrase - may also - refer to the - <reference name="Targets" refid="id22"> - Targets - section. - <target anonymous="1" ids="id19" refid="id22"> - <paragraph> - Here's a - <problematic ids="id84" refid="id83"> - `hyperlink reference without a target`_ - , which generates an - error. - <section dupnames="duplicate\ target\ names" ids="duplicate-target-names"> - <title auto="1" refid="id51"> - <generated classes="sectnum"> - 2.13.1   - Duplicate Target Names - <paragraph> - Duplicate names in section headers or other implicit targets will - generate "info" (level-1) system messages. Duplicate names in - explicit targets will generate "warning" (level-2) system messages. - <section dupnames="duplicate\ target\ names" ids="id20"> - <title auto="1" refid="id52"> - <generated classes="sectnum"> - 2.13.2   - Duplicate Target Names - <paragraph> - Since there are two "Duplicate Target Names" section headers, we - cannot uniquely refer to either of them by name. If we try to (like - this: - <problematic ids="id86" refid="id85"> - `Duplicate Target Names`_ - ), an error is generated. - <section ids="directives" names="directives"> - <title auto="1" refid="id53"> - <generated classes="sectnum"> - 2.14   - Directives - <topic classes="contents local" ids="contents" names="contents"> - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id71" refid="document-parts"> - <generated classes="sectnum"> - 2.14.1   - Document Parts - <list_item> - <paragraph> - <reference ids="id72" refid="images"> - <generated classes="sectnum"> - 2.14.2   - Images - <list_item> - <paragraph> - <reference ids="id73" refid="admonitions"> - <generated classes="sectnum"> - 2.14.3   - Admonitions - <list_item> - <paragraph> - <reference ids="id74" refid="topics-sidebars-and-rubrics"> - <generated classes="sectnum"> - 2.14.4   - Topics, Sidebars, and Rubrics - <list_item> - <paragraph> - <reference ids="id75" refid="target-footnotes"> - <generated classes="sectnum"> - 2.14.5   - Target Footnotes - <list_item> - <paragraph> - <reference ids="id76" refid="replacement-text"> - <generated classes="sectnum"> - 2.14.6   - Replacement Text - <list_item> - <paragraph> - <reference ids="id77" refid="compound-paragraph"> - <generated classes="sectnum"> - 2.14.7   - Compound Paragraph - <list_item> - <paragraph> - <reference ids="id78" refid="parsed-literal-blocks"> - <generated classes="sectnum"> - 2.14.8   - Parsed Literal Blocks - <paragraph> - These are just a sample of the many reStructuredText Directives. For - others, please see - <reference refuri="http://docutils.sourceforge.net/docs/ref/rst/directives.html"> - http://docutils.sourceforge.net/docs/ref/rst/directives.html - . - <section ids="document-parts" names="document\ parts"> - <title auto="1" refid="id71"> - <generated classes="sectnum"> - 2.14.1   - Document Parts - <paragraph> - An example of the "contents" directive can be seen above this section - (a local, untitled table of - <reference name="contents" refid="contents"> - contents - ) and at the beginning of the - document (a document-wide - <reference name="table of contents" refid="table-of-contents"> - table of contents - ). - <section ids="images" names="images"> - <title auto="1" refid="id72"> - <generated classes="sectnum"> - 2.14.2   - Images - <paragraph> - An image directive (also clickable -- a hyperlink reference): - <reference name="directives" refid="directives"> - <image classes="class1 class2" uri="../../../docs/user/rst/images/title.png"> - <paragraph> - Image with multiple IDs: - <target refid="image-target-1"> - <target refid="image-target-2"> - <target refid="image-target-3"> - <image ids="image-target-3 image-target-2 image-target-1" names="image\ target\ 3 image\ target\ 2 image\ target\ 1" uri="../../../docs/user/rst/images/title.png"> - <paragraph> - A centered image: - <image align="center" uri="../../../docs/user/rst/images/biohazard.png"> - <paragraph> - A left-aligned image: - <image align="left" uri="../../../docs/user/rst/images/biohazard.png"> - <paragraph> - A right-aligned image: - <image align="right" uri="../../../docs/user/rst/images/biohazard.png"> - <paragraph> - A figure directive: - <figure align="right" classes="figclass1 figclass2"> - <image alt="reStructuredText, the markup syntax" classes="class1 class2" uri="../../../docs/user/rst/images/biohazard.png" width="50"> - <caption> - A figure is an image with a caption and/or a legend: - <legend> - <table> - <tgroup cols="2"> - <colspec colwidth="12"> - <colspec colwidth="47"> - <tbody> - <row> - <entry> - <paragraph> - re - <entry> - <paragraph> - Revised, revisited, based on 're' module. - <row> - <entry> - <paragraph> - Structured - <entry> - <paragraph> - Structure-enhanced text, structuredtext. - <row> - <entry> - <paragraph> - Text - <entry> - <paragraph> - Well it is, isn't it? - <paragraph> - This paragraph is also part of the legend. - <figure align="left" classes="figclass1 figclass2"> - <image alt="reStructuredText, the markup syntax" classes="class1 class2" uri="../../../docs/user/rst/images/biohazard.png" width="50"> - <caption> - A left-aligned figure. - <legend> - <paragraph> - This is the legend. - <paragraph> - This paragraph might flow around the figure... - <paragraph> - A centered figure: - <figure align="center"> - <image uri="../../../docs/user/rst/images/biohazard.png" width="50"> - <caption> - This is the caption. - <legend> - <paragraph> - This is the legend. - <paragraph> - The legend may consist of several paragraphs. - <paragraph> - This paragraph might flow around the figure... - <paragraph> - A left-aligned figure: - <figure align="left"> - <image uri="../../../docs/user/rst/images/biohazard.png" width="50"> - <caption> - This is the caption. - <legend> - <paragraph> - This is the legend. - <paragraph> - The legend may consist of several paragraphs. - <paragraph> - This paragraph might flow around the figure... - <paragraph> - Now widths: - <paragraph> - An image 2 em wide: - <image uri="../../../docs/user/rst/images/biohazard.png" width="2em"> - <paragraph> - An image 2 em wide and 30 pixel high: - <image height="30px" uri="../../../docs/user/rst/images/biohazard.png" width="2em"> - <paragraph> - An image occupying 70% of the line width: - <image uri="../../../docs/user/rst/images/biohazard.png" width="70%"> - <paragraph> - An image 3 cm high: - <image height="3cm" uri="../../../docs/user/rst/images/biohazard.png"> - <section ids="admonitions" names="admonitions"> - <title auto="1" refid="id73"> - <generated classes="sectnum"> - 2.14.3   - Admonitions - <attention> - <paragraph> - Directives at large. - <caution> - <paragraph> - Don't take any wooden nickels. - <danger> - <paragraph> - Mad scientist at work! - <error> - <paragraph> - Does not compute. - <hint> - <paragraph> - It's bigger than a bread box. - <important> - <bullet_list bullet="-"> - <list_item> - <paragraph> - Wash behind your ears. - <list_item> - <paragraph> - Clean up your room. - <list_item> - <paragraph> - Call your mother. - <list_item> - <paragraph> - Back up your data. - <note> - <paragraph> - This is a note. - <tip> - <paragraph> - 15% if the service is good. - <warning> - <paragraph> - Strong prose may provoke extreme mental exertion. - Reader discretion is strongly advised. - <admonition classes="admonition-and-by-the-way"> - <title> - And, by the way... - <paragraph> - You can make up your own admonition too. - <target ids="docutils" names="docutils" refuri="http://docutils.sourceforge.net/"> - <section ids="topics-sidebars-and-rubrics" names="topics,\ sidebars,\ and\ rubrics"> - <title auto="1" refid="id74"> - <generated classes="sectnum"> - 2.14.4   - Topics, Sidebars, and Rubrics - <sidebar> - <title> - Sidebar Title - <subtitle> - Optional Subtitle - <paragraph> - This is a sidebar. It is for text outside the flow of the main - text. - <rubric> - This is a rubric inside a sidebar - <paragraph> - Sidebars often appears beside the main text with a border and - background color. - <topic> - <title> - Topic Title - <paragraph> - This is a topic. - <rubric> - This is a rubric - <section ids="target-footnotes" names="target\ footnotes"> - <title auto="1" refid="id75"> - <generated classes="sectnum"> - 2.14.5   - Target Footnotes - <footnote auto="1" backrefs="id26 id27 id28 id29" ids="id25" names="TARGET_NOTE:\ id25"> - <label> - 5 - <paragraph> - <reference refuri="http://www.python.org/"> - http://www.python.org/ - <footnote auto="1" backrefs="id31" ids="id30" names="TARGET_NOTE:\ id30"> - <label> - 6 - <paragraph> - <reference refuri="http://docutils.sourceforge.net/"> - http://docutils.sourceforge.net/ - <section ids="replacement-text" names="replacement\ text"> - <title auto="1" refid="id76"> - <generated classes="sectnum"> - 2.14.6   - Replacement Text - <paragraph> - I recommend you try - <reference refuri="http://www.python.org/"> - Python, - <emphasis> - the - best language around - - <footnote_reference auto="1" ids="id28" refid="id25"> - 5 - . - <substitution_definition names="Python"> - Python, - <emphasis> - the - best language around - <section ids="compound-paragraph" names="compound\ paragraph"> - <title auto="1" refid="id77"> - <generated classes="sectnum"> - 2.14.7   - Compound Paragraph - <compound classes="some-class"> - <paragraph> - Compound 1, paragraph 1. - <paragraph> - Compound 1, paragraph 2. - <bullet_list bullet="*"> - <list_item> - <paragraph> - Compound 1, list item one. - <list_item> - <paragraph> - Compound 1, list item two. - <paragraph> - Another compound statement: - <compound> - <paragraph> - Compound 2, a literal block: - <literal_block xml:space="preserve"> - Compound 2, literal. - <paragraph> - Compound 2, this is a test. - <compound> - <paragraph> - Compound 3, only consisting of one paragraph. - <compound> - <literal_block xml:space="preserve"> - Compound 4. - This one starts with a literal block. - <paragraph> - Compound 4, a paragraph. - <paragraph> - Now something - <emphasis> - really - perverted -- a nested compound block. This is - just to test that it works at all; the results don't have to be - meaningful. - <compound> - <paragraph> - Compound 5, block 1 (a paragraph). - <compound> - <paragraph> - Compound 6, block 2 in compound 5. - <paragraph> - Compound 6, another paragraph. - <paragraph> - Compound 5, block 3 (a paragraph). - <compound> - <paragraph> - Compound 7, with a table inside: - <table> - <tgroup cols="3"> - <colspec colwidth="20"> - <colspec colwidth="20"> - <colspec colwidth="20"> - <tbody> - <row> - <entry> - <paragraph> - Left cell, first - paragraph. - <paragraph> - Left cell, second - paragraph. - <entry> - <paragraph> - Middle cell, - consisting of - exactly one - paragraph. - <entry> - <paragraph> - Right cell. - <paragraph> - Paragraph 2. - <paragraph> - Paragraph 3. - <paragraph> - Compound 7, a paragraph after the table. - <paragraph> - Compound 7, another paragraph. - <section ids="parsed-literal-blocks" names="parsed\ literal\ blocks"> - <title auto="1" refid="id78"> - <generated classes="sectnum"> - 2.14.8   - Parsed Literal Blocks - <literal_block xml:space="preserve"> - This is a parsed literal block. - This line is indented. The next line is blank. - - Inline markup is supported, e.g. - <emphasis> - emphasis - , - <strong> - strong - , - <literal> - literal - text - , footnotes - <footnote_reference ids="id21" refid="id8"> - 1 - , - <target ids="id22" names="targets"> - targets - , and - <reference name="references" refuri="http://www.python.org/"> - references - <target ids="references" names="references" refuri="http://www.python.org/"> - . - <section ids="substitution-definitions" names="substitution\ definitions"> - <title auto="1" refid="id62"> - <generated classes="sectnum"> - 2.15   - Substitution Definitions - <paragraph> - An inline image ( - <image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png"> - ) example: - <substitution_definition names="EXAMPLE"> - <image alt="EXAMPLE" uri="../../../docs/user/rst/images/biohazard.png"> - <paragraph> - (Substitution definitions are not visible in the HTML source.) - <section ids="comments" names="comments"> - <title auto="1" refid="id63"> - <generated classes="sectnum"> - 2.16   - Comments - <paragraph> - Here's one: - <comment xml:space="preserve"> - Comments begin with two dots and a space. Anything may - follow, except for the syntax of footnotes, hyperlink - targets, directives, or substitution definitions. - - Double-dashes -- "--" -- must be escaped somehow in HTML output. - <paragraph> - (View the HTML source to see the comment.) - <section ids="raw-text" names="raw\ text"> - <title auto="1" refid="id64"> - <generated classes="sectnum"> - 2.17   - Raw text - <paragraph> - This does not necessarily look nice, because there may be missing white space. - <paragraph> - It's just there to freeze the behavior. - <raw format="html latex" xml:space="preserve"> - A test. - <raw format="html latex" xml:space="preserve"> - Second test. - <raw classes="myclass" format="html latex" xml:space="preserve"> - Another test with myclass set. - <paragraph> - This is the - <raw classes="myrawroleclass" format="html latex" xml:space="preserve"> - fourth test - with myrawroleclass set. - <raw format="html" xml:space="preserve"> - Fifth test in HTML.<br />Line two. - <raw format="latex" xml:space="preserve"> - Fifth test in LaTeX.\\Line two. - <section ids="container" names="container"> - <title auto="1" refid="id65"> - <generated classes="sectnum"> - 2.18   - Container - <container classes="custom"> - <paragraph> - paragraph 1 - <paragraph> - paragraph 2 - <section ids="colspanning-tables" names="colspanning\ tables"> - <title auto="1" refid="id66"> - <generated classes="sectnum"> - 2.19   - Colspanning tables - <paragraph> - This table has a cell spanning two columns: - <table> - <tgroup cols="3"> - <colspec colwidth="5"> - <colspec colwidth="5"> - <colspec colwidth="6"> - <thead> - <row> - <entry morecols="1"> - <paragraph> - Inputs - <entry> - <paragraph> - Output - <row> - <entry> - <paragraph> - A - <entry> - <paragraph> - B - <entry> - <paragraph> - A or B - <tbody> - <row> - <entry> - <paragraph> - False - <entry> - <paragraph> - False - <entry> - <paragraph> - False - <row> - <entry> - <paragraph> - True - <entry> - <paragraph> - False - <entry> - <paragraph> - True - <row> - <entry> - <paragraph> - False - <entry> - <paragraph> - True - <entry> - <paragraph> - True - <row> - <entry> - <paragraph> - True - <entry> - <paragraph> - True - <entry> - <paragraph> - True - <section ids="rowspanning-tables" names="rowspanning\ tables"> - <title auto="1" refid="id67"> - <generated classes="sectnum"> - 2.20   - Rowspanning tables - <paragraph> - Here's a table with cells spanning several rows: - <table> - <tgroup cols="3"> - <colspec colwidth="24"> - <colspec colwidth="12"> - <colspec colwidth="18"> - <thead> - <row> - <entry> - <paragraph> - Header row, column 1 - (header rows optional) - <entry> - <paragraph> - Header 2 - <entry> - <paragraph> - Header 3 - <tbody> - <row> - <entry> - <paragraph> - body row 1, column 1 - <entry> - <paragraph> - column 2 - <entry> - <paragraph> - column 3 - <row> - <entry> - <paragraph> - body row 2 - <entry morerows="1"> - <paragraph> - Cells may - span rows. - <entry morerows="1"> - <paragraph> - Another - rowspanning - cell. - <row> - <entry> - <paragraph> - body row 3 - <section ids="complex-tables" names="complex\ tables"> - <title auto="1" refid="id68"> - <generated classes="sectnum"> - 2.21   - Complex tables - <paragraph> - Here's a complex table, which should test all features. - <table> - <tgroup cols="4"> - <colspec colwidth="24"> - <colspec colwidth="12"> - <colspec colwidth="10"> - <colspec colwidth="10"> - <thead> - <row> - <entry> - <paragraph> - Header row, column 1 - (header rows optional) - <entry> - <paragraph> - Header 2 - <entry> - <paragraph> - Header 3 - <entry> - <paragraph> - Header 4 - <tbody> - <row> - <entry> - <paragraph> - body row 1, column 1 - <entry> - <paragraph> - column 2 - <entry> - <paragraph> - column 3 - <entry> - <paragraph> - column 4 - <row> - <entry> - <paragraph> - body row 2 - <entry morecols="2"> - <paragraph> - Cells may span columns. - <row> - <entry> - <paragraph> - body row 3 - <entry morerows="1"> - <paragraph> - Cells may - span rows. - <paragraph> - Paragraph. - <entry morecols="1" morerows="1"> - <bullet_list bullet="-"> - <list_item> - <paragraph> - Table cells - <list_item> - <paragraph> - contain - <list_item> - <paragraph> - body elements. - <row> - <entry> - <paragraph> - body row 4 - <row> - <entry> - <paragraph> - body row 5 - <entry morecols="1"> - <paragraph> - Cells may also be - empty: - <literal> - --> - <entry> - <section ids="list-tables" names="list\ tables"> - <title auto="1" refid="id69"> - <generated classes="sectnum"> - 2.22   - List Tables - <paragraph> - Here's a list table exercising all features: - <table classes="test"> - <title> - list table with integral header - <tgroup cols="3"> - <colspec colwidth="10" stub="1"> - <colspec colwidth="20"> - <colspec colwidth="30"> - <thead> - <row> - <entry> - <paragraph> - Treat - <entry> - <paragraph> - Quantity - <entry> - <paragraph> - Description - <tbody> - <row> - <entry> - <paragraph> - Albatross - <entry> - <paragraph> - 2.99 - <entry> - <paragraph> - On a stick! - <row> - <entry> - <paragraph> - Crunchy Frog - <entry> - <paragraph> - 1.49 - <entry> - <paragraph> - If we took the bones out, it wouldn't be - crunchy, now would it? - <row> - <entry> - <paragraph> - Gannet Ripple - <entry> - <paragraph> - 1.99 - <entry> - <paragraph> - On a stick! - <section ids="error-handling" names="error\ handling"> - <title auto="1" refid="id70"> - <generated classes="sectnum"> - 3   - Error Handling - <paragraph> - Any errors caught during processing will generate system messages. - <paragraph> - There should be five messages in the following, auto-generated - section, "Docutils System Messages": - <comment xml:space="preserve"> - section should be added by Docutils automatically - <section classes="system-messages"> - <title> - Docutils System Messages - <system_message backrefs="id24" ids="id23" level="3" line="100" source="functional/input/data/standard.txt" type="ERROR"> - <paragraph> - Undefined substitution referenced: "problematic". - <system_message backrefs="id80" ids="id79" level="3" line="358" source="functional/input/standalone_rst_pseudoxml.txt" type="ERROR"> - <paragraph> - Unknown target name: "5". - <system_message backrefs="id82" ids="id81" level="3" line="367" source="functional/input/data/standard.txt" type="ERROR"> - <paragraph> - Unknown target name: "nonexistent". - <system_message backrefs="id84" ids="id83" level="3" line="394" source="functional/input/data/standard.txt" type="ERROR"> - <paragraph> - Unknown target name: "hyperlink reference without a target". - <system_message backrefs="id86" ids="id85" level="3" line="407" source="functional/input/data/standard.txt" type="ERROR"> - <paragraph> - Duplicate target name, cannot be used as a unique reference: "duplicate target names". diff --git a/docutils/test/functional/expected/standalone_rst_s5_html_1.html b/docutils/test/functional/expected/standalone_rst_s5_html_1.html deleted file mode 100644 index 54caa3916..000000000 --- a/docutils/test/functional/expected/standalone_rst_s5_html_1.html +++ /dev/null @@ -1,152 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> -<meta name="version" content="S5 1.1" /> -<title>Slide Shows</title> -<meta name="author" content="David Goodger" /> -<meta name="date" content="2005-11-28" /> -<link rel="stylesheet" href="../../../docutils/writers/html4css1/html4css1.css" type="text/css" /> -<!-- configuration parameters --> -<meta name="defaultView" content="slideshow" /> -<meta name="controlVis" content="hidden" /> -<!-- style sheet links --> -<script src="ui/small-black/slides.js" type="text/javascript"></script> -<link rel="stylesheet" href="ui/small-black/slides.css" - type="text/css" media="projection" id="slideProj" /> -<link rel="stylesheet" href="ui/small-black/outline.css" - type="text/css" media="screen" id="outlineStyle" /> -<link rel="stylesheet" href="ui/small-black/print.css" - type="text/css" media="print" id="slidePrint" /> -<link rel="stylesheet" href="ui/small-black/opera.css" - type="text/css" media="projection" id="operaFix" /> - -<style type="text/css"> -#currentSlide {display: none;} -</style> -</head> -<body> -<div class="layout"> -<div id="controls"></div> -<div id="currentSlide"></div> -<div id="header"> - -</div> -<div id="footer"> -<h1>Slide Shows</h1> -<h2>Location • Date</h2> -</div> -</div> -<div class="presentation"> -<div class="slide" id="slide0"> -<h1 class="title">Slide Shows</h1> -<table class="docinfo" frame="void" rules="none"> -<col class="docinfo-name" /> -<col class="docinfo-content" /> -<tbody valign="top"> -<tr><th class="docinfo-name">Author:</th> -<td>David Goodger</td></tr> -<tr><th class="docinfo-name">Date:</th> -<td>2005-11-28</td></tr> -</tbody> -</table> -<!-- Definitions of interpreted text roles (classes) for S5/HTML data. --> -<!-- This data file has been placed in the public domain. --> -<!-- Colours -======= --> -<!-- Text Sizes -========== --> -<!-- Display in Slides (Presentation Mode) Only -========================================== --> -<!-- Display in Outline Mode Only -============================ --> -<!-- Display in Print Only -===================== --> -<!-- Incremental Display -=================== --> -<div class="contents handout topic"> -<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> -<ul class="simple"> -<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li> -<li><a class="reference" href="#features-1" id="id2" name="id2">Features (1)</a></li> -<li><a class="reference" href="#features-2" id="id3" name="id3">Features (2)</a></li> -<li><a class="reference" href="#checklist" id="id4" name="id4">Checklist</a></li> -</ul> -</div> -<p class="handout">This is a test. This is only a test. If this were a real slide -show, there would be a projector handy.</p> -<p>Let's test the S5/HTML writer!</p> -<ul class="small simple"> -<li>Use the arrow keys to navigate.</li> -<li>Click the "Ø" button to switch between presentation & -handout/outline modes.</li> -</ul> -<div class="handout container"> -In presentation mode, mouse over to the lower right-hand corner to -display the controls.</div> - -</div> -<div class="slide" id="introduction"> -<h1>Introduction</h1> -<ul class="compact simple"> -<li>reStructuredText<p class="handout">Uses normal reStructuredText as input.</p> -</li> -<li>One section per slide<p class="handout">Each first-level section is converted into a single slide.</p> -</li> -<li>(X)HTML output<p class="handout">Presentations can be viewed using any modern graphical web browser. -The browser must support CSS, JavaScript, and XHTML. S5 even works -with IE!</p> -</li> -<li>Themes<p class="handout">A variety of themes are available.</p> -</li> -<li><tt class="docutils literal"><span class="pre">rst2s5.py</span></tt><p class="handout">The front-end tool to generate S5 slide shows.</p> -</li> -</ul> -</div> -<div class="slide" id="features-1"> -<h1>Features (1)</h1> -<p class="left">A flush-left paragraph</p> -<p class="center">A centered paragraph</p> -<p class="right">A flush-right paragraph</p> -<p>Some colours: <span class="black">black</span> [black], <span class="gray">gray</span>, <span class="silver">silver</span>, -<span class="white">white</span> [white], <span class="maroon">maroon</span>, <span class="red">red</span>, -<span class="magenta">magenta</span>, <span class="fuchsia">fuchsia</span>, <span class="pink">pink</span>, -<span class="orange">orange</span>, <span class="yellow">yellow</span>, <span class="lime">lime</span>, <span class="green">green</span>, -<span class="olive">olive</span>, <span class="teal">teal</span>, <span class="cyan">cyan</span>, <span class="aqua">aqua</span>, -<span class="blue">blue</span>, <span class="navy">navy</span>, <span class="purple">purple</span></p> -</div> -<div class="slide" id="features-2"> -<h1>Features (2)</h1> -<p><span class="incremental">Some</span> <span class="incremental">incremental</span> <span class="incremental">text.</span></p> -<ul class="incremental open"> -<li><p class="first"><span class="tiny">tiny</span> (class & role name: "tiny", e.g. "<tt class="docutils literal"><span class="pre">:tiny:`text`</span></tt>")</p> -</li> -<li><p class="first"><span class="small">small</span> ("small")</p> -</li> -<li><p class="first">normal (unstyled)</p> -</li> -<li><p class="first"><span class="big">big</span> ("big")</p> -</li> -<li><p class="first"><span class="huge">huge</span> ("huge")</p> -</li> -</ul> -</div> -<div class="slide" id="checklist"> -<h1>Checklist</h1> -<ul class="simple"> -<li>The document title should be duplicated on each slide in the footer -(except for the first slide, <tt class="docutils literal"><span class="pre">slide0</span></tt>, where the entire footer is -disabled).</li> -<li>The footer also contains a second line, "Location • Date"</li> -<li>There's no table of contents on the first slide, although it does -appear in the handout/outline.</li> -<li>Handout material is not displayed in presentation mode.</li> -<li>The theme directories should be created, and the theme files copied -over.</li> -</ul> -</div> -</div> -</body> -</html> diff --git a/docutils/test/functional/expected/standalone_rst_s5_html_2.html b/docutils/test/functional/expected/standalone_rst_s5_html_2.html deleted file mode 100644 index e6e474a25..000000000 --- a/docutils/test/functional/expected/standalone_rst_s5_html_2.html +++ /dev/null @@ -1,148 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> -<head> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> -<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> -<meta name="version" content="S5 1.1" /> -<title>Slide Shows</title> -<meta name="author" content="David Goodger" /> -<meta name="date" content="2005-11-28" /> -<link rel="stylesheet" href="../../../docutils/writers/html4css1/html4css1.css" type="text/css" /> -<!-- configuration parameters --> -<meta name="defaultView" content="slideshow" /> -<meta name="controlVis" content="hidden" /> -<!-- style sheet links --> -<script src="ui/default/slides.js" type="text/javascript"></script> -<link rel="stylesheet" href="ui/default/slides.css" - type="text/css" media="projection" id="slideProj" /> -<link rel="stylesheet" href="ui/default/outline.css" - type="text/css" media="screen" id="outlineStyle" /> -<link rel="stylesheet" href="ui/default/print.css" - type="text/css" media="print" id="slidePrint" /> -<link rel="stylesheet" href="ui/default/opera.css" - type="text/css" media="projection" id="operaFix" /> -</head> -<body> -<div class="layout"> -<div id="controls"></div> -<div id="currentSlide"></div> -<div id="header"> - -</div> -<div id="footer"> -<h1>Slide Shows</h1> -<h2>Location • Date</h2> -</div> -</div> -<div class="presentation"> -<div class="slide" id="slide0"> -<h1 class="title">Slide Shows</h1> -<table class="docinfo" frame="void" rules="none"> -<col class="docinfo-name" /> -<col class="docinfo-content" /> -<tbody valign="top"> -<tr><th class="docinfo-name">Author:</th> -<td>David Goodger</td></tr> -<tr><th class="docinfo-name">Date:</th> -<td>2005-11-28</td></tr> -</tbody> -</table> -<!-- Definitions of interpreted text roles (classes) for S5/HTML data. --> -<!-- This data file has been placed in the public domain. --> -<!-- Colours -======= --> -<!-- Text Sizes -========== --> -<!-- Display in Slides (Presentation Mode) Only -========================================== --> -<!-- Display in Outline Mode Only -============================ --> -<!-- Display in Print Only -===================== --> -<!-- Incremental Display -=================== --> -<div class="contents handout topic"> -<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> -<ul class="simple"> -<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li> -<li><a class="reference" href="#features-1" id="id2" name="id2">Features (1)</a></li> -<li><a class="reference" href="#features-2" id="id3" name="id3">Features (2)</a></li> -<li><a class="reference" href="#checklist" id="id4" name="id4">Checklist</a></li> -</ul> -</div> -<p class="handout">This is a test. This is only a test. If this were a real slide -show, there would be a projector handy.</p> -<p>Let's test the S5/HTML writer!</p> -<ul class="small simple"> -<li>Use the arrow keys to navigate.</li> -<li>Click the "Ø" button to switch between presentation & -handout/outline modes.</li> -</ul> -<div class="handout container"> -In presentation mode, mouse over to the lower right-hand corner to -display the controls.</div> - -</div> -<div class="slide" id="introduction"> -<h1>Introduction</h1> -<ul class="compact simple"> -<li>reStructuredText<p class="handout">Uses normal reStructuredText as input.</p> -</li> -<li>One section per slide<p class="handout">Each first-level section is converted into a single slide.</p> -</li> -<li>(X)HTML output<p class="handout">Presentations can be viewed using any modern graphical web browser. -The browser must support CSS, JavaScript, and XHTML. S5 even works -with IE!</p> -</li> -<li>Themes<p class="handout">A variety of themes are available.</p> -</li> -<li><tt class="docutils literal"><span class="pre">rst2s5.py</span></tt><p class="handout">The front-end tool to generate S5 slide shows.</p> -</li> -</ul> -</div> -<div class="slide" id="features-1"> -<h1>Features (1)</h1> -<p class="left">A flush-left paragraph</p> -<p class="center">A centered paragraph</p> -<p class="right">A flush-right paragraph</p> -<p>Some colours: <span class="black">black</span> [black], <span class="gray">gray</span>, <span class="silver">silver</span>, -<span class="white">white</span> [white], <span class="maroon">maroon</span>, <span class="red">red</span>, -<span class="magenta">magenta</span>, <span class="fuchsia">fuchsia</span>, <span class="pink">pink</span>, -<span class="orange">orange</span>, <span class="yellow">yellow</span>, <span class="lime">lime</span>, <span class="green">green</span>, -<span class="olive">olive</span>, <span class="teal">teal</span>, <span class="cyan">cyan</span>, <span class="aqua">aqua</span>, -<span class="blue">blue</span>, <span class="navy">navy</span>, <span class="purple">purple</span></p> -</div> -<div class="slide" id="features-2"> -<h1>Features (2)</h1> -<p><span class="incremental">Some</span> <span class="incremental">incremental</span> <span class="incremental">text.</span></p> -<ul class="incremental open"> -<li><p class="first"><span class="tiny">tiny</span> (class & role name: "tiny", e.g. "<tt class="docutils literal"><span class="pre">:tiny:`text`</span></tt>")</p> -</li> -<li><p class="first"><span class="small">small</span> ("small")</p> -</li> -<li><p class="first">normal (unstyled)</p> -</li> -<li><p class="first"><span class="big">big</span> ("big")</p> -</li> -<li><p class="first"><span class="huge">huge</span> ("huge")</p> -</li> -</ul> -</div> -<div class="slide" id="checklist"> -<h1>Checklist</h1> -<ul class="simple"> -<li>The document title should be duplicated on each slide in the footer -(except for the first slide, <tt class="docutils literal"><span class="pre">slide0</span></tt>, where the entire footer is -disabled).</li> -<li>The footer also contains a second line, "Location • Date"</li> -<li>There's no table of contents on the first slide, although it does -appear in the handout/outline.</li> -<li>Handout material is not displayed in presentation mode.</li> -<li>The theme directories should be created, and the theme files copied -over.</li> -</ul> -</div> -</div> -</body> -</html> diff --git a/docutils/test/functional/expected/ui/default/blank.gif b/docutils/test/functional/expected/ui/default/blank.gif Binary files differdeleted file mode 100644 index 75b945d25..000000000 --- a/docutils/test/functional/expected/ui/default/blank.gif +++ /dev/null diff --git a/docutils/test/functional/expected/ui/default/framing.css b/docutils/test/functional/expected/ui/default/framing.css deleted file mode 100644 index c4727f303..000000000 --- a/docutils/test/functional/expected/ui/default/framing.css +++ /dev/null @@ -1,25 +0,0 @@ -/* This file has been placed in the public domain. */ -/* The following styles size, place, and layer the slide components. - Edit these if you want to change the overall slide layout. - The commented lines can be uncommented (and modified, if necessary) - to help you with the rearrangement process. */ - -/* target = 1024x768 */ - -div#header, div#footer, .slide {width: 100%; top: 0; left: 0;} -div#header {position: fixed; top: 0; height: 3em; z-index: 1;} -div#footer {top: auto; bottom: 0; height: 2.5em; z-index: 5;} -.slide {top: 0; width: 92%; padding: 2.5em 4% 4%; z-index: 2;} -div#controls {left: 50%; bottom: 0; width: 50%; z-index: 100;} -div#controls form {position: absolute; bottom: 0; right: 0; width: 100%; - margin: 0;} -#currentSlide {position: absolute; width: 10%; left: 45%; bottom: 1em; - z-index: 10;} -html>body #currentSlide {position: fixed;} - -/* -div#header {background: #FCC;} -div#footer {background: #CCF;} -div#controls {background: #BBD;} -div#currentSlide {background: #FFC;} -*/ diff --git a/docutils/test/functional/expected/ui/default/iepngfix.htc b/docutils/test/functional/expected/ui/default/iepngfix.htc deleted file mode 100644 index 9f3d628b5..000000000 --- a/docutils/test/functional/expected/ui/default/iepngfix.htc +++ /dev/null @@ -1,42 +0,0 @@ -<public:component> -<public:attach event="onpropertychange" onevent="doFix()" /> - -<script> - -// IE5.5+ PNG Alpha Fix v1.0 by Angus Turnbull http://www.twinhelix.com -// Free usage permitted as long as this notice remains intact. - -// This must be a path to a blank image. That's all the configuration you need here. -var blankImg = 'ui/default/blank.gif'; - -var f = 'DXImageTransform.Microsoft.AlphaImageLoader'; - -function filt(s, m) { - if (filters[f]) { - filters[f].enabled = s ? true : false; - if (s) with (filters[f]) { src = s; sizingMethod = m } - } else if (s) style.filter = 'progid:'+f+'(src="'+s+'",sizingMethod="'+m+'")'; -} - -function doFix() { - if ((parseFloat(navigator.userAgent.match(/MSIE (\S+)/)[1]) < 5.5) || - (event && !/(background|src)/.test(event.propertyName))) return; - - if (tagName == 'IMG') { - if ((/\.png$/i).test(src)) { - filt(src, 'image'); // was 'scale' - src = blankImg; - } else if (src.indexOf(blankImg) < 0) filt(); - } else if (style.backgroundImage) { - if (style.backgroundImage.match(/^url[("']+(.*\.png)[)"']+$/i)) { - var s = RegExp.$1; - style.backgroundImage = ''; - filt(s, 'crop'); - } else filt(); - } -} - -doFix(); - -</script> -</public:component>
\ No newline at end of file diff --git a/docutils/test/functional/expected/ui/default/opera.css b/docutils/test/functional/expected/ui/default/opera.css deleted file mode 100644 index c9d1148be..000000000 --- a/docutils/test/functional/expected/ui/default/opera.css +++ /dev/null @@ -1,8 +0,0 @@ -/* This file has been placed in the public domain. */ -/* DO NOT CHANGE THESE unless you really want to break Opera Show */ -.slide { - visibility: visible !important; - position: static !important; - page-break-before: always; -} -#slide0 {page-break-before: avoid;} diff --git a/docutils/test/functional/expected/ui/default/outline.css b/docutils/test/functional/expected/ui/default/outline.css deleted file mode 100644 index fa767e227..000000000 --- a/docutils/test/functional/expected/ui/default/outline.css +++ /dev/null @@ -1,16 +0,0 @@ -/* This file has been placed in the public domain. */ -/* Don't change this unless you want the layout stuff to show up in the - outline view! */ - -.layout div, #footer *, #controlForm * {display: none;} -#footer, #controls, #controlForm, #navLinks, #toggle { - display: block; visibility: visible; margin: 0; padding: 0;} -#toggle {float: right; padding: 0.5em;} -html>body #toggle {position: fixed; top: 0; right: 0;} - -/* making the outline look pretty-ish */ - -#slide0 h1, #slide0 h2, #slide0 h3, #slide0 h4 {border: none; margin: 0;} -#toggle {border: 1px solid; border-width: 0 0 1px 1px; background: #FFF;} - -.outline {display: inline ! important;} diff --git a/docutils/test/functional/expected/ui/default/pretty.css b/docutils/test/functional/expected/ui/default/pretty.css deleted file mode 100644 index 1cede72d4..000000000 --- a/docutils/test/functional/expected/ui/default/pretty.css +++ /dev/null @@ -1,120 +0,0 @@ -/* This file has been placed in the public domain. */ -/* Following are the presentation styles -- edit away! */ - -html, body {margin: 0; padding: 0;} -body {background: white; color: black;} -/* Replace the background style above with the style below (and again for - div#header) for a graphic: */ -/* background: white url(bodybg.gif) -16px 0 no-repeat; */ -:link, :visited {text-decoration: none; color: #00C;} -#controls :active {color: #88A !important;} -#controls :focus {outline: 1px dotted #227;} -h1, h2, h3, h4 {font-size: 100%; margin: 0; padding: 0; font-weight: inherit;} - -blockquote {padding: 0 2em 0.5em; margin: 0 1.5em 0.5em;} -blockquote p {margin: 0;} - -kbd {font-weight: bold; font-size: 1em;} -sup {font-size: smaller; line-height: 1px;} - -.slide pre {padding: 0; margin-left: 0; margin-right: 0; font-size: 90%;} -.slide ul ul li {list-style: square;} -.slide img.leader {display: block; margin: 0 auto;} -.slide tt {font-size: 90%;} - -div#header, div#footer {background: #005; color: #AAB; font-family: sans-serif;} -/* background: #005 url(bodybg.gif) -16px 0 no-repeat; */ -div#footer {font-size: 0.5em; font-weight: bold; padding: 1em 0;} -#footer h1 {display: block; padding: 0 1em;} -#footer h2 {display: block; padding: 0.8em 1em 0;} - -.slide {font-size: 1.2em;} -.slide h1 {position: absolute; top: 0.45em; z-index: 1; - margin: 0; padding-left: 0.7em; white-space: nowrap; - font: bold 150% sans-serif; color: #DDE; background: #005;} -.slide h2 {font: bold 120%/1em sans-serif; padding-top: 0.5em;} -.slide h3 {font: bold 100% sans-serif; padding-top: 0.5em;} -h1 abbr {font-variant: small-caps;} - -div#controls {position: absolute; left: 50%; bottom: 0; - width: 50%; text-align: right; font: bold 0.9em sans-serif;} -html>body div#controls {position: fixed; padding: 0 0 1em 0; top: auto;} -div#controls form {position: absolute; bottom: 0; right: 0; width: 100%; - margin: 0; padding: 0;} -#controls #navLinks a {padding: 0; margin: 0 0.5em; - background: #005; border: none; color: #779; cursor: pointer;} -#controls #navList {height: 1em;} -#controls #navList #jumplist {position: absolute; bottom: 0; right: 0; - background: #DDD; color: #227;} - -#currentSlide {text-align: center; font-size: 0.5em; color: #449; - font-family: sans-serif; font-weight: bold;} - -#slide0 {padding-top: 1.5em} -#slide0 h1 {position: static; margin: 1em 0 0; padding: 0; color: #000; - font: bold 2em sans-serif; white-space: normal; background: transparent;} -#slide0 h2 {font: bold italic 1em sans-serif; margin: 0.25em;} -#slide0 h3 {margin-top: 1.5em; font-size: 1.5em;} -#slide0 h4 {margin-top: 0; font-size: 1em;} - -ul.urls {list-style: none; display: inline; margin: 0;} -.urls li {display: inline; margin: 0;} -.external {border-bottom: 1px dotted gray;} -html>body .external {border-bottom: none;} -.external:after {content: " \274F"; font-size: smaller; color: #77B;} - -.incremental, .incremental *, .incremental *:after {visibility: visible; - color: white; border: 0;} -img.incremental {visibility: hidden;} -.slide .current {color: green;} - -.slide-display {display: inline ! important;} - -.huge {font-family: sans-serif; font-weight: bold; font-size: 150%;} -.big {font-family: sans-serif; font-weight: bold; font-size: 120%;} -.small {font-size: 75%;} -.tiny {font-size: 50%;} -.huge tt, .big tt, .small tt, .tiny tt {font-size: 115%;} -.huge pre, .big pre, .small pre, .tiny pre {font-size: 115%;} - -.maroon {color: maroon;} -.red {color: red;} -.magenta {color: magenta;} -.fuchsia {color: fuchsia;} -.pink {color: #FAA;} -.orange {color: orange;} -.yellow {color: yellow;} -.lime {color: lime;} -.green {color: green;} -.olive {color: olive;} -.teal {color: teal;} -.cyan {color: cyan;} -.aqua {color: aqua;} -.blue {color: blue;} -.navy {color: navy;} -.purple {color: purple;} -.black {color: black;} -.gray {color: gray;} -.silver {color: silver;} -.white {color: white;} - -.left {text-align: left ! important;} -.center {text-align: center ! important;} -.right {text-align: right ! important;} - -.animation {position: relative; margin: 1em 0; padding: 0;} -.animation img {position: absolute;} - -/* Docutils-specific overrides */ - -.slide table.docinfo {margin: 1em 0 0.5em 2em;} - -pre.literal-block, pre.doctest-block {background-color: white;} - -tt.docutils {background-color: white;} - -/* diagnostics */ -/* -li:after {content: " [" attr(class) "]"; color: #F88;} -div:before {content: "[" attr(class) "]"; color: #F88;} -*/ diff --git a/docutils/test/functional/expected/ui/default/print.css b/docutils/test/functional/expected/ui/default/print.css deleted file mode 100644 index 9d057cc8c..000000000 --- a/docutils/test/functional/expected/ui/default/print.css +++ /dev/null @@ -1,24 +0,0 @@ -/* This file has been placed in the public domain. */ -/* The following rule is necessary to have all slides appear in print! - DO NOT REMOVE IT! */ -.slide, ul {page-break-inside: avoid; visibility: visible !important;} -h1 {page-break-after: avoid;} - -body {font-size: 12pt; background: white;} -* {color: black;} - -#slide0 h1 {font-size: 200%; border: none; margin: 0.5em 0 0.25em;} -#slide0 h3 {margin: 0; padding: 0;} -#slide0 h4 {margin: 0 0 0.5em; padding: 0;} -#slide0 {margin-bottom: 3em;} - -#header {display: none;} -#footer h1 {margin: 0; border-bottom: 1px solid; color: gray; - font-style: italic;} -#footer h2, #controls {display: none;} - -.print {display: inline ! important;} - -/* The following rule keeps the layout stuff out of print. - Remove at your own risk! */ -.layout, .layout * {display: none !important;} diff --git a/docutils/test/functional/expected/ui/default/s5-core.css b/docutils/test/functional/expected/ui/default/s5-core.css deleted file mode 100644 index 6965f5e8f..000000000 --- a/docutils/test/functional/expected/ui/default/s5-core.css +++ /dev/null @@ -1,11 +0,0 @@ -/* This file has been placed in the public domain. */ -/* Do not edit or override these styles! - The system will likely break if you do. */ - -div#header, div#footer, div#controls, .slide {position: absolute;} -html>body div#header, html>body div#footer, - html>body div#controls, html>body .slide {position: fixed;} -.handout {display: none;} -.layout {display: block;} -.slide, .hideme, .incremental {visibility: hidden;} -#slide0 {visibility: visible;} diff --git a/docutils/test/functional/expected/ui/default/slides.css b/docutils/test/functional/expected/ui/default/slides.css deleted file mode 100644 index 82bdc0ee0..000000000 --- a/docutils/test/functional/expected/ui/default/slides.css +++ /dev/null @@ -1,10 +0,0 @@ -/* This file has been placed in the public domain. */ - -/* required to make the slide show run at all */ -@import url(s5-core.css); - -/* sets basic placement and size of slide components */ -@import url(framing.css); - -/* styles that make the slides look good */ -@import url(pretty.css); diff --git a/docutils/test/functional/expected/ui/default/slides.js b/docutils/test/functional/expected/ui/default/slides.js deleted file mode 100644 index 81e04e5d4..000000000 --- a/docutils/test/functional/expected/ui/default/slides.js +++ /dev/null @@ -1,558 +0,0 @@ -// S5 v1.1 slides.js -- released into the Public Domain -// Modified for Docutils (http://docutils.sf.net) by David Goodger -// -// Please see http://www.meyerweb.com/eric/tools/s5/credits.html for -// information about all the wonderful and talented contributors to this code! - -var undef; -var slideCSS = ''; -var snum = 0; -var smax = 1; -var slideIDs = new Array(); -var incpos = 0; -var number = undef; -var s5mode = true; -var defaultView = 'slideshow'; -var controlVis = 'visible'; - -var isIE = navigator.appName == 'Microsoft Internet Explorer' ? 1 : 0; -var isOp = navigator.userAgent.indexOf('Opera') > -1 ? 1 : 0; -var isGe = navigator.userAgent.indexOf('Gecko') > -1 && navigator.userAgent.indexOf('Safari') < 1 ? 1 : 0; - -function hasClass(object, className) { - if (!object.className) return false; - return (object.className.search('(^|\\s)' + className + '(\\s|$)') != -1); -} - -function hasValue(object, value) { - if (!object) return false; - return (object.search('(^|\\s)' + value + '(\\s|$)') != -1); -} - -function removeClass(object,className) { - if (!object) return; - object.className = object.className.replace(new RegExp('(^|\\s)'+className+'(\\s|$)'), RegExp.$1+RegExp.$2); -} - -function addClass(object,className) { - if (!object || hasClass(object, className)) return; - if (object.className) { - object.className += ' '+className; - } else { - object.className = className; - } -} - -function GetElementsWithClassName(elementName,className) { - var allElements = document.getElementsByTagName(elementName); - var elemColl = new Array(); - for (var i = 0; i< allElements.length; i++) { - if (hasClass(allElements[i], className)) { - elemColl[elemColl.length] = allElements[i]; - } - } - return elemColl; -} - -function isParentOrSelf(element, id) { - if (element == null || element.nodeName=='BODY') return false; - else if (element.id == id) return true; - else return isParentOrSelf(element.parentNode, id); -} - -function nodeValue(node) { - var result = ""; - if (node.nodeType == 1) { - var children = node.childNodes; - for (var i = 0; i < children.length; ++i) { - result += nodeValue(children[i]); - } - } - else if (node.nodeType == 3) { - result = node.nodeValue; - } - return(result); -} - -function slideLabel() { - var slideColl = GetElementsWithClassName('*','slide'); - var list = document.getElementById('jumplist'); - smax = slideColl.length; - for (var n = 0; n < smax; n++) { - var obj = slideColl[n]; - - var did = 'slide' + n.toString(); - if (obj.getAttribute('id')) { - slideIDs[n] = obj.getAttribute('id'); - } - else { - obj.setAttribute('id',did); - slideIDs[n] = did; - } - if (isOp) continue; - - var otext = ''; - var menu = obj.firstChild; - if (!menu) continue; // to cope with empty slides - while (menu && menu.nodeType == 3) { - menu = menu.nextSibling; - } - if (!menu) continue; // to cope with slides with only text nodes - - var menunodes = menu.childNodes; - for (var o = 0; o < menunodes.length; o++) { - otext += nodeValue(menunodes[o]); - } - list.options[list.length] = new Option(n + ' : ' + otext, n); - } -} - -function currentSlide() { - var cs; - var footer_nodes; - var vis = 'visible'; - if (document.getElementById) { - cs = document.getElementById('currentSlide'); - footer_nodes = document.getElementById('footer').childNodes; - } else { - cs = document.currentSlide; - footer = document.footer.childNodes; - } - cs.innerHTML = '<span id="csHere">' + snum + '<\/span> ' + - '<span id="csSep">\/<\/span> ' + - '<span id="csTotal">' + (smax-1) + '<\/span>'; - if (snum == 0) { - vis = 'hidden'; - } - cs.style.visibility = vis; - for (var i = 0; i < footer_nodes.length; i++) { - if (footer_nodes[i].nodeType == 1) { - footer_nodes[i].style.visibility = vis; - } - } -} - -function go(step) { - if (document.getElementById('slideProj').disabled || step == 0) return; - var jl = document.getElementById('jumplist'); - var cid = slideIDs[snum]; - var ce = document.getElementById(cid); - if (incrementals[snum].length > 0) { - for (var i = 0; i < incrementals[snum].length; i++) { - removeClass(incrementals[snum][i], 'current'); - removeClass(incrementals[snum][i], 'incremental'); - } - } - if (step != 'j') { - snum += step; - lmax = smax - 1; - if (snum > lmax) snum = lmax; - if (snum < 0) snum = 0; - } else - snum = parseInt(jl.value); - var nid = slideIDs[snum]; - var ne = document.getElementById(nid); - if (!ne) { - ne = document.getElementById(slideIDs[0]); - snum = 0; - } - if (step < 0) {incpos = incrementals[snum].length} else {incpos = 0;} - if (incrementals[snum].length > 0 && incpos == 0) { - for (var i = 0; i < incrementals[snum].length; i++) { - if (hasClass(incrementals[snum][i], 'current')) - incpos = i + 1; - else - addClass(incrementals[snum][i], 'incremental'); - } - } - if (incrementals[snum].length > 0 && incpos > 0) - addClass(incrementals[snum][incpos - 1], 'current'); - ce.style.visibility = 'hidden'; - ne.style.visibility = 'visible'; - jl.selectedIndex = snum; - currentSlide(); - number = 0; -} - -function goTo(target) { - if (target >= smax || target == snum) return; - go(target - snum); -} - -function subgo(step) { - if (step > 0) { - removeClass(incrementals[snum][incpos - 1],'current'); - removeClass(incrementals[snum][incpos], 'incremental'); - addClass(incrementals[snum][incpos],'current'); - incpos++; - } else { - incpos--; - removeClass(incrementals[snum][incpos],'current'); - addClass(incrementals[snum][incpos], 'incremental'); - addClass(incrementals[snum][incpos - 1],'current'); - } -} - -function toggle() { - var slideColl = GetElementsWithClassName('*','slide'); - var slides = document.getElementById('slideProj'); - var outline = document.getElementById('outlineStyle'); - if (!slides.disabled) { - slides.disabled = true; - outline.disabled = false; - s5mode = false; - fontSize('1em'); - for (var n = 0; n < smax; n++) { - var slide = slideColl[n]; - slide.style.visibility = 'visible'; - } - } else { - slides.disabled = false; - outline.disabled = true; - s5mode = true; - fontScale(); - for (var n = 0; n < smax; n++) { - var slide = slideColl[n]; - slide.style.visibility = 'hidden'; - } - slideColl[snum].style.visibility = 'visible'; - } -} - -function showHide(action) { - var obj = GetElementsWithClassName('*','hideme')[0]; - switch (action) { - case 's': obj.style.visibility = 'visible'; break; - case 'h': obj.style.visibility = 'hidden'; break; - case 'k': - if (obj.style.visibility != 'visible') { - obj.style.visibility = 'visible'; - } else { - obj.style.visibility = 'hidden'; - } - break; - } -} - -// 'keys' code adapted from MozPoint (http://mozpoint.mozdev.org/) -function keys(key) { - if (!key) { - key = event; - key.which = key.keyCode; - } - if (key.which == 84) { - toggle(); - return; - } - if (s5mode) { - switch (key.which) { - case 10: // return - case 13: // enter - if (window.event && isParentOrSelf(window.event.srcElement, 'controls')) return; - if (key.target && isParentOrSelf(key.target, 'controls')) return; - if(number != undef) { - goTo(number); - break; - } - case 32: // spacebar - case 34: // page down - case 39: // rightkey - case 40: // downkey - if(number != undef) { - go(number); - } else if (!incrementals[snum] || incpos >= incrementals[snum].length) { - go(1); - } else { - subgo(1); - } - break; - case 33: // page up - case 37: // leftkey - case 38: // upkey - if(number != undef) { - go(-1 * number); - } else if (!incrementals[snum] || incpos <= 0) { - go(-1); - } else { - subgo(-1); - } - break; - case 36: // home - goTo(0); - break; - case 35: // end - goTo(smax-1); - break; - case 67: // c - showHide('k'); - break; - } - if (key.which < 48 || key.which > 57) { - number = undef; - } else { - if (window.event && isParentOrSelf(window.event.srcElement, 'controls')) return; - if (key.target && isParentOrSelf(key.target, 'controls')) return; - number = (((number != undef) ? number : 0) * 10) + (key.which - 48); - } - } - return false; -} - -function clicker(e) { - number = undef; - var target; - if (window.event) { - target = window.event.srcElement; - e = window.event; - } else target = e.target; - if (target.href != null || hasValue(target.rel, 'external') || isParentOrSelf(target, 'controls') || isParentOrSelf(target,'embed') || isParentOrSelf(target, 'object')) return true; - if (!e.which || e.which == 1) { - if (!incrementals[snum] || incpos >= incrementals[snum].length) { - go(1); - } else { - subgo(1); - } - } -} - -function findSlide(hash) { - var target = document.getElementById(hash); - if (target) { - for (var i = 0; i < slideIDs.length; i++) { - if (target.id == slideIDs[i]) return i; - } - } - return null; -} - -function slideJump() { - if (window.location.hash == null || window.location.hash == '') { - currentSlide(); - return; - } - if (window.location.hash == null) return; - var dest = null; - dest = findSlide(window.location.hash.slice(1)); - if (dest == null) { - dest = 0; - } - go(dest - snum); -} - -function fixLinks() { - var thisUri = window.location.href; - thisUri = thisUri.slice(0, thisUri.length - window.location.hash.length); - var aelements = document.getElementsByTagName('A'); - for (var i = 0; i < aelements.length; i++) { - var a = aelements[i].href; - var slideID = a.match('\#.+'); - if ((slideID) && (slideID[0].slice(0,1) == '#')) { - var dest = findSlide(slideID[0].slice(1)); - if (dest != null) { - if (aelements[i].addEventListener) { - aelements[i].addEventListener("click", new Function("e", - "if (document.getElementById('slideProj').disabled) return;" + - "go("+dest+" - snum); " + - "if (e.preventDefault) e.preventDefault();"), true); - } else if (aelements[i].attachEvent) { - aelements[i].attachEvent("onclick", new Function("", - "if (document.getElementById('slideProj').disabled) return;" + - "go("+dest+" - snum); " + - "event.returnValue = false;")); - } - } - } - } -} - -function externalLinks() { - if (!document.getElementsByTagName) return; - var anchors = document.getElementsByTagName('a'); - for (var i=0; i<anchors.length; i++) { - var anchor = anchors[i]; - if (anchor.getAttribute('href') && hasValue(anchor.rel, 'external')) { - anchor.target = '_blank'; - addClass(anchor,'external'); - } - } -} - -function createControls() { - var controlsDiv = document.getElementById("controls"); - if (!controlsDiv) return; - var hider = ' onmouseover="showHide(\'s\');" onmouseout="showHide(\'h\');"'; - var hideDiv, hideList = ''; - if (controlVis == 'hidden') { - hideDiv = hider; - } else { - hideList = hider; - } - controlsDiv.innerHTML = '<form action="#" id="controlForm"' + hideDiv + '>' + - '<div id="navLinks">' + - '<a accesskey="t" id="toggle" href="javascript:toggle();">Ø<\/a>' + - '<a accesskey="z" id="prev" href="javascript:go(-1);">«<\/a>' + - '<a accesskey="x" id="next" href="javascript:go(1);">»<\/a>' + - '<div id="navList"' + hideList + '><select id="jumplist" onchange="go(\'j\');"><\/select><\/div>' + - '<\/div><\/form>'; - if (controlVis == 'hidden') { - var hidden = document.getElementById('navLinks'); - } else { - var hidden = document.getElementById('jumplist'); - } - addClass(hidden,'hideme'); -} - -function fontScale() { // causes layout problems in FireFox that get fixed if browser's Reload is used; same may be true of other Gecko-based browsers - if (!s5mode) return false; - var vScale = 22; // both yield 32 (after rounding) at 1024x768 - var hScale = 32; // perhaps should auto-calculate based on theme's declared value? - if (window.innerHeight) { - var vSize = window.innerHeight; - var hSize = window.innerWidth; - } else if (document.documentElement.clientHeight) { - var vSize = document.documentElement.clientHeight; - var hSize = document.documentElement.clientWidth; - } else if (document.body.clientHeight) { - var vSize = document.body.clientHeight; - var hSize = document.body.clientWidth; - } else { - var vSize = 700; // assuming 1024x768, minus chrome and such - var hSize = 1024; // these do not account for kiosk mode or Opera Show - } - var newSize = Math.min(Math.round(vSize/vScale),Math.round(hSize/hScale)); - fontSize(newSize + 'px'); - if (isGe) { // hack to counter incremental reflow bugs - var obj = document.getElementsByTagName('body')[0]; - obj.style.display = 'none'; - obj.style.display = 'block'; - } -} - -function fontSize(value) { - if (!(s5ss = document.getElementById('s5ss'))) { - if (!isIE) { - document.getElementsByTagName('head')[0].appendChild(s5ss = document.createElement('style')); - s5ss.setAttribute('media','screen, projection'); - s5ss.setAttribute('id','s5ss'); - } else { - document.createStyleSheet(); - document.s5ss = document.styleSheets[document.styleSheets.length - 1]; - } - } - if (!isIE) { - while (s5ss.lastChild) s5ss.removeChild(s5ss.lastChild); - s5ss.appendChild(document.createTextNode('body {font-size: ' + value + ' !important;}')); - } else { - document.s5ss.addRule('body','font-size: ' + value + ' !important;'); - } -} - -function notOperaFix() { - slideCSS = document.getElementById('slideProj').href; - var slides = document.getElementById('slideProj'); - var outline = document.getElementById('outlineStyle'); - slides.setAttribute('media','screen'); - outline.disabled = true; - if (isGe) { - slides.setAttribute('href','null'); // Gecko fix - slides.setAttribute('href',slideCSS); // Gecko fix - } - if (isIE && document.styleSheets && document.styleSheets[0]) { - document.styleSheets[0].addRule('img', 'behavior: url(ui/default/iepngfix.htc)'); - document.styleSheets[0].addRule('div', 'behavior: url(ui/default/iepngfix.htc)'); - document.styleSheets[0].addRule('.slide', 'behavior: url(ui/default/iepngfix.htc)'); - } -} - -function getIncrementals(obj) { - var incrementals = new Array(); - if (!obj) - return incrementals; - var children = obj.childNodes; - for (var i = 0; i < children.length; i++) { - var child = children[i]; - if (hasClass(child, 'incremental')) { - if (child.nodeName == 'OL' || child.nodeName == 'UL') { - removeClass(child, 'incremental'); - for (var j = 0; j < child.childNodes.length; j++) { - if (child.childNodes[j].nodeType == 1) { - addClass(child.childNodes[j], 'incremental'); - } - } - } else { - incrementals[incrementals.length] = child; - removeClass(child,'incremental'); - } - } - if (hasClass(child, 'show-first')) { - if (child.nodeName == 'OL' || child.nodeName == 'UL') { - removeClass(child, 'show-first'); - if (child.childNodes[isGe].nodeType == 1) { - removeClass(child.childNodes[isGe], 'incremental'); - } - } else { - incrementals[incrementals.length] = child; - } - } - incrementals = incrementals.concat(getIncrementals(child)); - } - return incrementals; -} - -function createIncrementals() { - var incrementals = new Array(); - for (var i = 0; i < smax; i++) { - incrementals[i] = getIncrementals(document.getElementById(slideIDs[i])); - } - return incrementals; -} - -function defaultCheck() { - var allMetas = document.getElementsByTagName('meta'); - for (var i = 0; i< allMetas.length; i++) { - if (allMetas[i].name == 'defaultView') { - defaultView = allMetas[i].content; - } - if (allMetas[i].name == 'controlVis') { - controlVis = allMetas[i].content; - } - } -} - -// Key trap fix, new function body for trap() -function trap(e) { - if (!e) { - e = event; - e.which = e.keyCode; - } - try { - modifierKey = e.ctrlKey || e.altKey || e.metaKey; - } - catch(e) { - modifierKey = false; - } - return modifierKey || e.which == 0; -} - -function startup() { - defaultCheck(); - if (!isOp) createControls(); - slideLabel(); - fixLinks(); - externalLinks(); - fontScale(); - if (!isOp) { - notOperaFix(); - incrementals = createIncrementals(); - slideJump(); - if (defaultView == 'outline') { - toggle(); - } - document.onkeyup = keys; - document.onkeypress = trap; - document.onclick = clicker; - } -} - -window.onload = startup; -window.onresize = function(){setTimeout('fontScale()', 50);} diff --git a/docutils/test/functional/expected/ui/small-black/blank.gif b/docutils/test/functional/expected/ui/small-black/blank.gif Binary files differdeleted file mode 100644 index 75b945d25..000000000 --- a/docutils/test/functional/expected/ui/small-black/blank.gif +++ /dev/null diff --git a/docutils/test/functional/expected/ui/small-black/framing.css b/docutils/test/functional/expected/ui/small-black/framing.css deleted file mode 100644 index 70287dd06..000000000 --- a/docutils/test/functional/expected/ui/small-black/framing.css +++ /dev/null @@ -1,24 +0,0 @@ -/* This file has been placed in the public domain. */ -/* The following styles size, place, and layer the slide components. - Edit these if you want to change the overall slide layout. - The commented lines can be uncommented (and modified, if necessary) - to help you with the rearrangement process. */ - -/* target = 1024x768 */ - -div#header, div#footer, .slide {width: 100%; top: 0; left: 0;} -div#footer {top: auto; bottom: 0; height: 2.5em; z-index: 5;} -.slide {top: 0; width: 92%; padding: 1em 4% 0 4%; z-index: 2;} -div#controls {left: 50%; bottom: 0; width: 50%; z-index: 100;} -div#controls form {position: absolute; bottom: 0; right: 0; width: 100%; - margin: 0;} -#currentSlide {position: absolute; width: 10%; left: 45%; bottom: 1em; - z-index: 10;} -html>body #currentSlide {position: fixed;} - -/* -div#header {background: #FCC;} -div#footer {background: #CCF;} -div#controls {background: #BBD;} -div#currentSlide {background: #FFC;} -*/ diff --git a/docutils/test/functional/expected/ui/small-black/iepngfix.htc b/docutils/test/functional/expected/ui/small-black/iepngfix.htc deleted file mode 100644 index fa9f99659..000000000 --- a/docutils/test/functional/expected/ui/small-black/iepngfix.htc +++ /dev/null @@ -1,42 +0,0 @@ -<public:component> -<public:attach event="onpropertychange" onevent="doFix()" /> - -<script> - -// IE5.5+ PNG Alpha Fix v1.0 by Angus Turnbull http://www.twinhelix.com -// Free usage permitted as long as this notice remains intact. - -// This must be a path to a blank image. That's all the configuration you need here. -var blankImg = 'ui/small-black/blank.gif'; - -var f = 'DXImageTransform.Microsoft.AlphaImageLoader'; - -function filt(s, m) { - if (filters[f]) { - filters[f].enabled = s ? true : false; - if (s) with (filters[f]) { src = s; sizingMethod = m } - } else if (s) style.filter = 'progid:'+f+'(src="'+s+'",sizingMethod="'+m+'")'; -} - -function doFix() { - if ((parseFloat(navigator.userAgent.match(/MSIE (\S+)/)[1]) < 5.5) || - (event && !/(background|src)/.test(event.propertyName))) return; - - if (tagName == 'IMG') { - if ((/\.png$/i).test(src)) { - filt(src, 'image'); // was 'scale' - src = blankImg; - } else if (src.indexOf(blankImg) < 0) filt(); - } else if (style.backgroundImage) { - if (style.backgroundImage.match(/^url[("']+(.*\.png)[)"']+$/i)) { - var s = RegExp.$1; - style.backgroundImage = ''; - filt(s, 'crop'); - } else filt(); - } -} - -doFix(); - -</script> -</public:component>
\ No newline at end of file diff --git a/docutils/test/functional/expected/ui/small-black/opera.css b/docutils/test/functional/expected/ui/small-black/opera.css deleted file mode 100644 index c9d1148be..000000000 --- a/docutils/test/functional/expected/ui/small-black/opera.css +++ /dev/null @@ -1,8 +0,0 @@ -/* This file has been placed in the public domain. */ -/* DO NOT CHANGE THESE unless you really want to break Opera Show */ -.slide { - visibility: visible !important; - position: static !important; - page-break-before: always; -} -#slide0 {page-break-before: avoid;} diff --git a/docutils/test/functional/expected/ui/small-black/outline.css b/docutils/test/functional/expected/ui/small-black/outline.css deleted file mode 100644 index fa767e227..000000000 --- a/docutils/test/functional/expected/ui/small-black/outline.css +++ /dev/null @@ -1,16 +0,0 @@ -/* This file has been placed in the public domain. */ -/* Don't change this unless you want the layout stuff to show up in the - outline view! */ - -.layout div, #footer *, #controlForm * {display: none;} -#footer, #controls, #controlForm, #navLinks, #toggle { - display: block; visibility: visible; margin: 0; padding: 0;} -#toggle {float: right; padding: 0.5em;} -html>body #toggle {position: fixed; top: 0; right: 0;} - -/* making the outline look pretty-ish */ - -#slide0 h1, #slide0 h2, #slide0 h3, #slide0 h4 {border: none; margin: 0;} -#toggle {border: 1px solid; border-width: 0 0 1px 1px; background: #FFF;} - -.outline {display: inline ! important;} diff --git a/docutils/test/functional/expected/ui/small-black/pretty.css b/docutils/test/functional/expected/ui/small-black/pretty.css deleted file mode 100644 index 5c1932704..000000000 --- a/docutils/test/functional/expected/ui/small-black/pretty.css +++ /dev/null @@ -1,116 +0,0 @@ -/* This file has been placed in the public domain. */ -/* Following are the presentation styles -- edit away! */ - -html, body {margin: 0; padding: 0;} -body {background: black; color: white;} -:link, :visited {text-decoration: none; color: cyan;} -#controls :active {color: #888 !important;} -#controls :focus {outline: 1px dotted #CCC;} -h1, h2, h3, h4 {font-size: 100%; margin: 0; padding: 0; font-weight: inherit;} - -blockquote {padding: 0 2em 0.5em; margin: 0 1.5em 0.5em;} -blockquote p {margin: 0;} - -kbd {font-weight: bold; font-size: 1em;} -sup {font-size: smaller; line-height: 1px;} - -.slide pre {padding: 0; margin-left: 0; margin-right: 0; font-size: 90%;} -.slide ul ul li {list-style: square;} -.slide img.leader {display: block; margin: 0 auto;} -.slide tt {font-size: 90%;} - -div#footer {font-family: sans-serif; color: #AAA; - font-size: 0.5em; font-weight: bold; padding: 1em 0;} -#footer h1 {display: block; padding: 0 1em;} -#footer h2 {display: block; padding: 0.8em 1em 0;} - -.slide {font-size: 1.2em;} -.slide h1 {padding-top: 0; z-index: 1; margin: 0; font: bold 150% sans-serif;} -.slide h2 {font: bold 120% sans-serif; padding-top: 0.5em;} -.slide h3 {font: bold 100% sans-serif; padding-top: 0.5em;} -h1 abbr {font-variant: small-caps;} - -div#controls {position: absolute; left: 50%; bottom: 0; - width: 50%; text-align: right; font: bold 0.9em sans-serif;} -html>body div#controls {position: fixed; padding: 0 0 1em 0; top: auto;} -div#controls form {position: absolute; bottom: 0; right: 0; width: 100%; - margin: 0; padding: 0;} -#controls #navLinks a {padding: 0; margin: 0 0.5em; - border: none; color: #888; cursor: pointer;} -#controls #navList {height: 1em;} -#controls #navList #jumplist {position: absolute; bottom: 0; right: 0; - background: black; color: #CCC;} - -#currentSlide {text-align: center; font-size: 0.5em; color: #AAA; - font-family: sans-serif; font-weight: bold;} - -#slide0 {padding-top: 0em} -#slide0 h1 {position: static; margin: 1em 0 0; padding: 0; - font: bold 2em sans-serif; white-space: normal; background: transparent;} -#slide0 h2 {font: bold italic 1em sans-serif; margin: 0.25em;} -#slide0 h3 {margin-top: 1.5em; font-size: 1.5em;} -#slide0 h4 {margin-top: 0; font-size: 1em;} - -ul.urls {list-style: none; display: inline; margin: 0;} -.urls li {display: inline; margin: 0;} -.external {border-bottom: 1px dotted gray;} -html>body .external {border-bottom: none;} -.external:after {content: " \274F"; font-size: smaller; color: #FCC;} - -.incremental, .incremental *, .incremental *:after { - color: black; visibility: visible; border: 0;} -img.incremental {visibility: hidden;} -.slide .current {color: lime;} - -.slide-display {display: inline ! important;} - -.huge {font-family: sans-serif; font-weight: bold; font-size: 150%;} -.big {font-family: sans-serif; font-weight: bold; font-size: 120%;} -.small {font-size: 75%;} -.tiny {font-size: 50%;} -.huge tt, .big tt, .small tt, .tiny tt {font-size: 115%;} -.huge pre, .big pre, .small pre, .tiny pre {font-size: 115%;} - -.maroon {color: maroon;} -.red {color: red;} -.magenta {color: magenta;} -.fuchsia {color: fuchsia;} -.pink {color: #FAA;} -.orange {color: orange;} -.yellow {color: yellow;} -.lime {color: lime;} -.green {color: green;} -.olive {color: olive;} -.teal {color: teal;} -.cyan {color: cyan;} -.aqua {color: aqua;} -.blue {color: blue;} -.navy {color: navy;} -.purple {color: purple;} -.black {color: black;} -.gray {color: gray;} -.silver {color: silver;} -.white {color: white;} - -.left {text-align: left ! important;} -.center {text-align: center ! important;} -.right {text-align: right ! important;} - -.animation {position: relative; margin: 1em 0; padding: 0;} -.animation img {position: absolute;} - -/* Docutils-specific overrides */ - -.slide table.docinfo {margin: 1em 0 0.5em 2em;} - -div.sidebar {background-color: black;} - -pre.literal-block, pre.doctest-block {background-color: black;} - -tt.docutils {background-color: black;} - -/* diagnostics */ -/* -li:after {content: " [" attr(class) "]"; color: #F88;} -div:before {content: "[" attr(class) "]"; color: #F88;} -*/ diff --git a/docutils/test/functional/expected/ui/small-black/print.css b/docutils/test/functional/expected/ui/small-black/print.css deleted file mode 100644 index 9d057cc8c..000000000 --- a/docutils/test/functional/expected/ui/small-black/print.css +++ /dev/null @@ -1,24 +0,0 @@ -/* This file has been placed in the public domain. */ -/* The following rule is necessary to have all slides appear in print! - DO NOT REMOVE IT! */ -.slide, ul {page-break-inside: avoid; visibility: visible !important;} -h1 {page-break-after: avoid;} - -body {font-size: 12pt; background: white;} -* {color: black;} - -#slide0 h1 {font-size: 200%; border: none; margin: 0.5em 0 0.25em;} -#slide0 h3 {margin: 0; padding: 0;} -#slide0 h4 {margin: 0 0 0.5em; padding: 0;} -#slide0 {margin-bottom: 3em;} - -#header {display: none;} -#footer h1 {margin: 0; border-bottom: 1px solid; color: gray; - font-style: italic;} -#footer h2, #controls {display: none;} - -.print {display: inline ! important;} - -/* The following rule keeps the layout stuff out of print. - Remove at your own risk! */ -.layout, .layout * {display: none !important;} diff --git a/docutils/test/functional/expected/ui/small-black/s5-core.css b/docutils/test/functional/expected/ui/small-black/s5-core.css deleted file mode 100644 index 6965f5e8f..000000000 --- a/docutils/test/functional/expected/ui/small-black/s5-core.css +++ /dev/null @@ -1,11 +0,0 @@ -/* This file has been placed in the public domain. */ -/* Do not edit or override these styles! - The system will likely break if you do. */ - -div#header, div#footer, div#controls, .slide {position: absolute;} -html>body div#header, html>body div#footer, - html>body div#controls, html>body .slide {position: fixed;} -.handout {display: none;} -.layout {display: block;} -.slide, .hideme, .incremental {visibility: hidden;} -#slide0 {visibility: visible;} diff --git a/docutils/test/functional/expected/ui/small-black/slides.css b/docutils/test/functional/expected/ui/small-black/slides.css deleted file mode 100644 index 82bdc0ee0..000000000 --- a/docutils/test/functional/expected/ui/small-black/slides.css +++ /dev/null @@ -1,10 +0,0 @@ -/* This file has been placed in the public domain. */ - -/* required to make the slide show run at all */ -@import url(s5-core.css); - -/* sets basic placement and size of slide components */ -@import url(framing.css); - -/* styles that make the slides look good */ -@import url(pretty.css); diff --git a/docutils/test/functional/expected/ui/small-black/slides.js b/docutils/test/functional/expected/ui/small-black/slides.js deleted file mode 100644 index d628dfeaf..000000000 --- a/docutils/test/functional/expected/ui/small-black/slides.js +++ /dev/null @@ -1,558 +0,0 @@ -// S5 v1.1 slides.js -- released into the Public Domain -// Modified for Docutils (http://docutils.sf.net) by David Goodger -// -// Please see http://www.meyerweb.com/eric/tools/s5/credits.html for -// information about all the wonderful and talented contributors to this code! - -var undef; -var slideCSS = ''; -var snum = 0; -var smax = 1; -var slideIDs = new Array(); -var incpos = 0; -var number = undef; -var s5mode = true; -var defaultView = 'slideshow'; -var controlVis = 'visible'; - -var isIE = navigator.appName == 'Microsoft Internet Explorer' ? 1 : 0; -var isOp = navigator.userAgent.indexOf('Opera') > -1 ? 1 : 0; -var isGe = navigator.userAgent.indexOf('Gecko') > -1 && navigator.userAgent.indexOf('Safari') < 1 ? 1 : 0; - -function hasClass(object, className) { - if (!object.className) return false; - return (object.className.search('(^|\\s)' + className + '(\\s|$)') != -1); -} - -function hasValue(object, value) { - if (!object) return false; - return (object.search('(^|\\s)' + value + '(\\s|$)') != -1); -} - -function removeClass(object,className) { - if (!object) return; - object.className = object.className.replace(new RegExp('(^|\\s)'+className+'(\\s|$)'), RegExp.$1+RegExp.$2); -} - -function addClass(object,className) { - if (!object || hasClass(object, className)) return; - if (object.className) { - object.className += ' '+className; - } else { - object.className = className; - } -} - -function GetElementsWithClassName(elementName,className) { - var allElements = document.getElementsByTagName(elementName); - var elemColl = new Array(); - for (var i = 0; i< allElements.length; i++) { - if (hasClass(allElements[i], className)) { - elemColl[elemColl.length] = allElements[i]; - } - } - return elemColl; -} - -function isParentOrSelf(element, id) { - if (element == null || element.nodeName=='BODY') return false; - else if (element.id == id) return true; - else return isParentOrSelf(element.parentNode, id); -} - -function nodeValue(node) { - var result = ""; - if (node.nodeType == 1) { - var children = node.childNodes; - for (var i = 0; i < children.length; ++i) { - result += nodeValue(children[i]); - } - } - else if (node.nodeType == 3) { - result = node.nodeValue; - } - return(result); -} - -function slideLabel() { - var slideColl = GetElementsWithClassName('*','slide'); - var list = document.getElementById('jumplist'); - smax = slideColl.length; - for (var n = 0; n < smax; n++) { - var obj = slideColl[n]; - - var did = 'slide' + n.toString(); - if (obj.getAttribute('id')) { - slideIDs[n] = obj.getAttribute('id'); - } - else { - obj.setAttribute('id',did); - slideIDs[n] = did; - } - if (isOp) continue; - - var otext = ''; - var menu = obj.firstChild; - if (!menu) continue; // to cope with empty slides - while (menu && menu.nodeType == 3) { - menu = menu.nextSibling; - } - if (!menu) continue; // to cope with slides with only text nodes - - var menunodes = menu.childNodes; - for (var o = 0; o < menunodes.length; o++) { - otext += nodeValue(menunodes[o]); - } - list.options[list.length] = new Option(n + ' : ' + otext, n); - } -} - -function currentSlide() { - var cs; - var footer_nodes; - var vis = 'visible'; - if (document.getElementById) { - cs = document.getElementById('currentSlide'); - footer_nodes = document.getElementById('footer').childNodes; - } else { - cs = document.currentSlide; - footer = document.footer.childNodes; - } - cs.innerHTML = '<span id="csHere">' + snum + '<\/span> ' + - '<span id="csSep">\/<\/span> ' + - '<span id="csTotal">' + (smax-1) + '<\/span>'; - if (snum == 0) { - vis = 'hidden'; - } - cs.style.visibility = vis; - for (var i = 0; i < footer_nodes.length; i++) { - if (footer_nodes[i].nodeType == 1) { - footer_nodes[i].style.visibility = vis; - } - } -} - -function go(step) { - if (document.getElementById('slideProj').disabled || step == 0) return; - var jl = document.getElementById('jumplist'); - var cid = slideIDs[snum]; - var ce = document.getElementById(cid); - if (incrementals[snum].length > 0) { - for (var i = 0; i < incrementals[snum].length; i++) { - removeClass(incrementals[snum][i], 'current'); - removeClass(incrementals[snum][i], 'incremental'); - } - } - if (step != 'j') { - snum += step; - lmax = smax - 1; - if (snum > lmax) snum = lmax; - if (snum < 0) snum = 0; - } else - snum = parseInt(jl.value); - var nid = slideIDs[snum]; - var ne = document.getElementById(nid); - if (!ne) { - ne = document.getElementById(slideIDs[0]); - snum = 0; - } - if (step < 0) {incpos = incrementals[snum].length} else {incpos = 0;} - if (incrementals[snum].length > 0 && incpos == 0) { - for (var i = 0; i < incrementals[snum].length; i++) { - if (hasClass(incrementals[snum][i], 'current')) - incpos = i + 1; - else - addClass(incrementals[snum][i], 'incremental'); - } - } - if (incrementals[snum].length > 0 && incpos > 0) - addClass(incrementals[snum][incpos - 1], 'current'); - ce.style.visibility = 'hidden'; - ne.style.visibility = 'visible'; - jl.selectedIndex = snum; - currentSlide(); - number = 0; -} - -function goTo(target) { - if (target >= smax || target == snum) return; - go(target - snum); -} - -function subgo(step) { - if (step > 0) { - removeClass(incrementals[snum][incpos - 1],'current'); - removeClass(incrementals[snum][incpos], 'incremental'); - addClass(incrementals[snum][incpos],'current'); - incpos++; - } else { - incpos--; - removeClass(incrementals[snum][incpos],'current'); - addClass(incrementals[snum][incpos], 'incremental'); - addClass(incrementals[snum][incpos - 1],'current'); - } -} - -function toggle() { - var slideColl = GetElementsWithClassName('*','slide'); - var slides = document.getElementById('slideProj'); - var outline = document.getElementById('outlineStyle'); - if (!slides.disabled) { - slides.disabled = true; - outline.disabled = false; - s5mode = false; - fontSize('1em'); - for (var n = 0; n < smax; n++) { - var slide = slideColl[n]; - slide.style.visibility = 'visible'; - } - } else { - slides.disabled = false; - outline.disabled = true; - s5mode = true; - fontScale(); - for (var n = 0; n < smax; n++) { - var slide = slideColl[n]; - slide.style.visibility = 'hidden'; - } - slideColl[snum].style.visibility = 'visible'; - } -} - -function showHide(action) { - var obj = GetElementsWithClassName('*','hideme')[0]; - switch (action) { - case 's': obj.style.visibility = 'visible'; break; - case 'h': obj.style.visibility = 'hidden'; break; - case 'k': - if (obj.style.visibility != 'visible') { - obj.style.visibility = 'visible'; - } else { - obj.style.visibility = 'hidden'; - } - break; - } -} - -// 'keys' code adapted from MozPoint (http://mozpoint.mozdev.org/) -function keys(key) { - if (!key) { - key = event; - key.which = key.keyCode; - } - if (key.which == 84) { - toggle(); - return; - } - if (s5mode) { - switch (key.which) { - case 10: // return - case 13: // enter - if (window.event && isParentOrSelf(window.event.srcElement, 'controls')) return; - if (key.target && isParentOrSelf(key.target, 'controls')) return; - if(number != undef) { - goTo(number); - break; - } - case 32: // spacebar - case 34: // page down - case 39: // rightkey - case 40: // downkey - if(number != undef) { - go(number); - } else if (!incrementals[snum] || incpos >= incrementals[snum].length) { - go(1); - } else { - subgo(1); - } - break; - case 33: // page up - case 37: // leftkey - case 38: // upkey - if(number != undef) { - go(-1 * number); - } else if (!incrementals[snum] || incpos <= 0) { - go(-1); - } else { - subgo(-1); - } - break; - case 36: // home - goTo(0); - break; - case 35: // end - goTo(smax-1); - break; - case 67: // c - showHide('k'); - break; - } - if (key.which < 48 || key.which > 57) { - number = undef; - } else { - if (window.event && isParentOrSelf(window.event.srcElement, 'controls')) return; - if (key.target && isParentOrSelf(key.target, 'controls')) return; - number = (((number != undef) ? number : 0) * 10) + (key.which - 48); - } - } - return false; -} - -function clicker(e) { - number = undef; - var target; - if (window.event) { - target = window.event.srcElement; - e = window.event; - } else target = e.target; - if (target.href != null || hasValue(target.rel, 'external') || isParentOrSelf(target, 'controls') || isParentOrSelf(target,'embed') || isParentOrSelf(target, 'object')) return true; - if (!e.which || e.which == 1) { - if (!incrementals[snum] || incpos >= incrementals[snum].length) { - go(1); - } else { - subgo(1); - } - } -} - -function findSlide(hash) { - var target = document.getElementById(hash); - if (target) { - for (var i = 0; i < slideIDs.length; i++) { - if (target.id == slideIDs[i]) return i; - } - } - return null; -} - -function slideJump() { - if (window.location.hash == null || window.location.hash == '') { - currentSlide(); - return; - } - if (window.location.hash == null) return; - var dest = null; - dest = findSlide(window.location.hash.slice(1)); - if (dest == null) { - dest = 0; - } - go(dest - snum); -} - -function fixLinks() { - var thisUri = window.location.href; - thisUri = thisUri.slice(0, thisUri.length - window.location.hash.length); - var aelements = document.getElementsByTagName('A'); - for (var i = 0; i < aelements.length; i++) { - var a = aelements[i].href; - var slideID = a.match('\#.+'); - if ((slideID) && (slideID[0].slice(0,1) == '#')) { - var dest = findSlide(slideID[0].slice(1)); - if (dest != null) { - if (aelements[i].addEventListener) { - aelements[i].addEventListener("click", new Function("e", - "if (document.getElementById('slideProj').disabled) return;" + - "go("+dest+" - snum); " + - "if (e.preventDefault) e.preventDefault();"), true); - } else if (aelements[i].attachEvent) { - aelements[i].attachEvent("onclick", new Function("", - "if (document.getElementById('slideProj').disabled) return;" + - "go("+dest+" - snum); " + - "event.returnValue = false;")); - } - } - } - } -} - -function externalLinks() { - if (!document.getElementsByTagName) return; - var anchors = document.getElementsByTagName('a'); - for (var i=0; i<anchors.length; i++) { - var anchor = anchors[i]; - if (anchor.getAttribute('href') && hasValue(anchor.rel, 'external')) { - anchor.target = '_blank'; - addClass(anchor,'external'); - } - } -} - -function createControls() { - var controlsDiv = document.getElementById("controls"); - if (!controlsDiv) return; - var hider = ' onmouseover="showHide(\'s\');" onmouseout="showHide(\'h\');"'; - var hideDiv, hideList = ''; - if (controlVis == 'hidden') { - hideDiv = hider; - } else { - hideList = hider; - } - controlsDiv.innerHTML = '<form action="#" id="controlForm"' + hideDiv + '>' + - '<div id="navLinks">' + - '<a accesskey="t" id="toggle" href="javascript:toggle();">Ø<\/a>' + - '<a accesskey="z" id="prev" href="javascript:go(-1);">«<\/a>' + - '<a accesskey="x" id="next" href="javascript:go(1);">»<\/a>' + - '<div id="navList"' + hideList + '><select id="jumplist" onchange="go(\'j\');"><\/select><\/div>' + - '<\/div><\/form>'; - if (controlVis == 'hidden') { - var hidden = document.getElementById('navLinks'); - } else { - var hidden = document.getElementById('jumplist'); - } - addClass(hidden,'hideme'); -} - -function fontScale() { // causes layout problems in FireFox that get fixed if browser's Reload is used; same may be true of other Gecko-based browsers - if (!s5mode) return false; - var vScale = 22; // both yield 32 (after rounding) at 1024x768 - var hScale = 32; // perhaps should auto-calculate based on theme's declared value? - if (window.innerHeight) { - var vSize = window.innerHeight; - var hSize = window.innerWidth; - } else if (document.documentElement.clientHeight) { - var vSize = document.documentElement.clientHeight; - var hSize = document.documentElement.clientWidth; - } else if (document.body.clientHeight) { - var vSize = document.body.clientHeight; - var hSize = document.body.clientWidth; - } else { - var vSize = 700; // assuming 1024x768, minus chrome and such - var hSize = 1024; // these do not account for kiosk mode or Opera Show - } - var newSize = Math.min(Math.round(vSize/vScale),Math.round(hSize/hScale)); - fontSize(newSize + 'px'); - if (isGe) { // hack to counter incremental reflow bugs - var obj = document.getElementsByTagName('body')[0]; - obj.style.display = 'none'; - obj.style.display = 'block'; - } -} - -function fontSize(value) { - if (!(s5ss = document.getElementById('s5ss'))) { - if (!isIE) { - document.getElementsByTagName('head')[0].appendChild(s5ss = document.createElement('style')); - s5ss.setAttribute('media','screen, projection'); - s5ss.setAttribute('id','s5ss'); - } else { - document.createStyleSheet(); - document.s5ss = document.styleSheets[document.styleSheets.length - 1]; - } - } - if (!isIE) { - while (s5ss.lastChild) s5ss.removeChild(s5ss.lastChild); - s5ss.appendChild(document.createTextNode('body {font-size: ' + value + ' !important;}')); - } else { - document.s5ss.addRule('body','font-size: ' + value + ' !important;'); - } -} - -function notOperaFix() { - slideCSS = document.getElementById('slideProj').href; - var slides = document.getElementById('slideProj'); - var outline = document.getElementById('outlineStyle'); - slides.setAttribute('media','screen'); - outline.disabled = true; - if (isGe) { - slides.setAttribute('href','null'); // Gecko fix - slides.setAttribute('href',slideCSS); // Gecko fix - } - if (isIE && document.styleSheets && document.styleSheets[0]) { - document.styleSheets[0].addRule('img', 'behavior: url(ui/small-black/iepngfix.htc)'); - document.styleSheets[0].addRule('div', 'behavior: url(ui/small-black/iepngfix.htc)'); - document.styleSheets[0].addRule('.slide', 'behavior: url(ui/small-black/iepngfix.htc)'); - } -} - -function getIncrementals(obj) { - var incrementals = new Array(); - if (!obj) - return incrementals; - var children = obj.childNodes; - for (var i = 0; i < children.length; i++) { - var child = children[i]; - if (hasClass(child, 'incremental')) { - if (child.nodeName == 'OL' || child.nodeName == 'UL') { - removeClass(child, 'incremental'); - for (var j = 0; j < child.childNodes.length; j++) { - if (child.childNodes[j].nodeType == 1) { - addClass(child.childNodes[j], 'incremental'); - } - } - } else { - incrementals[incrementals.length] = child; - removeClass(child,'incremental'); - } - } - if (hasClass(child, 'show-first')) { - if (child.nodeName == 'OL' || child.nodeName == 'UL') { - removeClass(child, 'show-first'); - if (child.childNodes[isGe].nodeType == 1) { - removeClass(child.childNodes[isGe], 'incremental'); - } - } else { - incrementals[incrementals.length] = child; - } - } - incrementals = incrementals.concat(getIncrementals(child)); - } - return incrementals; -} - -function createIncrementals() { - var incrementals = new Array(); - for (var i = 0; i < smax; i++) { - incrementals[i] = getIncrementals(document.getElementById(slideIDs[i])); - } - return incrementals; -} - -function defaultCheck() { - var allMetas = document.getElementsByTagName('meta'); - for (var i = 0; i< allMetas.length; i++) { - if (allMetas[i].name == 'defaultView') { - defaultView = allMetas[i].content; - } - if (allMetas[i].name == 'controlVis') { - controlVis = allMetas[i].content; - } - } -} - -// Key trap fix, new function body for trap() -function trap(e) { - if (!e) { - e = event; - e.which = e.keyCode; - } - try { - modifierKey = e.ctrlKey || e.altKey || e.metaKey; - } - catch(e) { - modifierKey = false; - } - return modifierKey || e.which == 0; -} - -function startup() { - defaultCheck(); - if (!isOp) createControls(); - slideLabel(); - fixLinks(); - externalLinks(); - fontScale(); - if (!isOp) { - notOperaFix(); - incrementals = createIncrementals(); - slideJump(); - if (defaultView == 'outline') { - toggle(); - } - document.onkeyup = keys; - document.onkeypress = trap; - document.onclick = clicker; - } -} - -window.onload = startup; -window.onresize = function(){setTimeout('fontScale()', 50);} diff --git a/docutils/test/functional/input/compact_lists.txt b/docutils/test/functional/input/compact_lists.txt deleted file mode 100644 index ec13a97be..000000000 --- a/docutils/test/functional/input/compact_lists.txt +++ /dev/null @@ -1,39 +0,0 @@ -* This is an ordinary simple bullet list. -* It should be made compact (<p> & </p> tags omitted). - -********** - -* This is a bullet list that is not simple. - - There are multiple paragraphs in some items. - -* It should not be made compact. - -* Even though some items may have only one paragraph. - -********** - -.. class:: open - -* This is a simple bullet list, but class="open" is set. -* It should not be made compact. - -********** - -.. class:: compact - -* This is a bullet list that is not simple. - - There are multiple paragraphs in some items. - -* However, the class="compact" setting will cause - all first paragraph's <p> & </p> tags to be omitted. - -* Items with multiple paragraphs will not appear changed. - -* Items may have one paragraph, or multiple. - - Items with multiple paragraphs will still be followed - by vertical whitespace because of the later paragraphs. - -* The effect is interesting. diff --git a/docutils/test/functional/input/dangerous.txt b/docutils/test/functional/input/dangerous.txt deleted file mode 100644 index 8f75386c8..000000000 --- a/docutils/test/functional/input/dangerous.txt +++ /dev/null @@ -1,16 +0,0 @@ -Potentially dangerous features (security holes): - -.. include:: /etc/passwd -.. raw:: html - :file: /etc/passwd -.. raw:: html - :url: file:///etc/passwd -.. raw:: html - - <script> - that does something really nasty - </script> -.. csv-table:: :file: /etc/passwd -.. csv-table:: :url: file:///etc/passwd -.. figure:: picture.png - :figwidth: image diff --git a/docutils/test/functional/input/data/custom_roles.txt b/docutils/test/functional/input/data/custom_roles.txt deleted file mode 100644 index 0f209d61e..000000000 --- a/docutils/test/functional/input/data/custom_roles.txt +++ /dev/null @@ -1,6 +0,0 @@ -Custom Roles ------------- - -.. role:: custom(literal) - -:custom:`one` :custom:`two` :custom:`three` diff --git a/docutils/test/functional/input/data/errors.txt b/docutils/test/functional/input/data/errors.txt deleted file mode 100644 index 557f479d3..000000000 --- a/docutils/test/functional/input/data/errors.txt +++ /dev/null @@ -1,9 +0,0 @@ -Error Handling -============== - -Any errors caught during processing will generate system messages. - -There should be five messages in the following, auto-generated -section, "Docutils System Messages": - -.. section should be added by Docutils automatically diff --git a/docutils/test/functional/input/data/header_footer.txt b/docutils/test/functional/input/data/header_footer.txt deleted file mode 100644 index 875c9fac0..000000000 --- a/docutils/test/functional/input/data/header_footer.txt +++ /dev/null @@ -1,2 +0,0 @@ -.. header:: Document header -.. footer:: Document footer diff --git a/docutils/test/functional/input/data/latex.txt b/docutils/test/functional/input/data/latex.txt deleted file mode 100644 index 20d59db1e..000000000 --- a/docutils/test/functional/input/data/latex.txt +++ /dev/null @@ -1,201 +0,0 @@ -Some Tests for the LaTeX Writer -=============================== - -These tests have been written to exercise some unusual combinations of -syntax elements which may cause trouble for the LaTeX writer but do -not need to be tested with other writers (e.g. the HTML writer). - -This file is not yet used by any automated test. It is currently only -used to control the visual appearance of the output. - - -Block Quotes ------------- - - This block quote comes directly after the section heading and is - followed by a paragraph. - - This is the second paragraph of the block quote and it contains - some more text filling up some space which would otherwise be - empty. - - -- Attribution - -This is a paragraph. - - This block quote does not have an attribution. - -This is another paragraph. - - Another block quote at the end of the section. - - -More Block Quotes ------------------ - - Block quote followed by a transition. - ----------- - - Another block quote. - - -Sidebars --------- - -This paragraph precedes the sidebar. This is some text. This is some -text. This is some text. This is some text. This is some text. -This is some text. This is some text. This is some text. - -.. sidebar:: Sidebar Title - - These are the sidebar contents. These are the sidebar contents. - - These are the sidebar contents. These are the sidebar contents. - - These are the sidebar contents. These are the sidebar contents. - These are the sidebar contents. These are the sidebar contents. - -This paragraph follows the sidebar. This is some text. This is some -text. This is some text. - -This is some text. This is some text. This is some text. This is -some text. This is some text. This is some text. This is some text. - - -Next Section ------------- - -This section comes after the sidebar, and this text should float -around the sidebar as well. This is some text. This is some text. -This is some text. This is some text. This is some text. This is -some text. This is some text. This is some text. This is some text. -This is some text. This is some text. This is some text. This is -some text. This is some text. - -This is some text. This is some text. This is some text. This is -some text. This is some text. This is some text. This is some text. -This is some text. This is some text. This is some text. - - -Nested Elements ---------------- - -:Field list: | Line - | Block -:Field 2: * Bullet - * list -:Another (longer) field: * Bullet - * list -:Yet another long field: - * .. comment - - Bullet - - .. comment - - * .. comment - - list - - .. comment - -:Field: * This - - is - - a - - * bullet - - list - -:Field: * | This is - | a bullet - * | list with - | line blocks -:Last field: Last field. - -* * * * * * * * Deeply nested list. - -1. 2. 3. 4. 5. 6. 7. 8. Deeply nested list. - -+-----------------+ -| | Line block | -| | -| * Bullet list | -| | -| :: | -| | -| Literal | -| block | -+-----------------+ -| :Field 1: | -| Text. | -| :Field 2: | -| More text. | -+-----------------+ -| +-------+-----+ | -| | A |* foo| | -| | nested| | | -| | table.|* bar| | -| +-------+-----+ | -+-----------------+ -| This is a | -| paragraph. | -| | -| +-------+-----+ | -| | A |* foo| | -| | nested| | | -| | table.|* bar| | -| +-------+-----+ | -| | -| Another longer | -| paragraph. | -+-----------------+ -| * A list. | -| * A list. | -| | -| +-------+-----+ | -| | A |* foo| | -| | nested| | | -| | table.|* bar| | -| +-------+-----+ | -| | -| * Another list. | -| * Another list. | -+-----------------+ -| Foo | -| | -| Bar | -+-----------------+ -| * Foo | -| | -| * Bar | -+-----------------+ -| * This is a | -| paragraph. | -| | -| This is a | -| paragraph. | -| | -| * This is a | -| paragraph. | -| | -| This is a | -| paragraph. | -+-----------------+ - - -Images -====== - -Image with 20% width: - -.. image:: ../../../docs/user/rst/images/title.png - :width: 20% - -Image with 100% width: - -.. image:: ../../../docs/user/rst/images/title.png - :width: 100% diff --git a/docutils/test/functional/input/data/list_table.txt b/docutils/test/functional/input/data/list_table.txt deleted file mode 100644 index 632285e36..000000000 --- a/docutils/test/functional/input/data/list_table.txt +++ /dev/null @@ -1,24 +0,0 @@ -List Tables ------------ - -Here's a list table exercising all features: - -.. list-table:: list table with integral header - :class: test - :widths: 10 20 30 - :header-rows: 1 - :stub-columns: 1 - - * - Treat - - Quantity - - Description - * - Albatross - - 2.99 - - On a stick! - * - Crunchy Frog - - 1.49 - - If we took the bones out, it wouldn't be - crunchy, now would it? - * - Gannet Ripple - - 1.99 - - On a stick! diff --git a/docutils/test/functional/input/data/nonalphanumeric.txt b/docutils/test/functional/input/data/nonalphanumeric.txt deleted file mode 100644 index 4c4ee7343..000000000 --- a/docutils/test/functional/input/data/nonalphanumeric.txt +++ /dev/null @@ -1,13 +0,0 @@ -Monospaced non-alphanumeric characters --------------------------------------- - -These are all ASCII characters except a-zA-Z0-9 and space: - -``!!!"""###$$$%%%&&&'''((()))***+++,,,---...///:::`` - -``;;;<<<===>>>???@@@[[[\\\]]]^^^___```{{{|||}}}~~~`` - -``xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`` - -The two lines of non-alphanumeric characters should both have the same -width as the third line. diff --git a/docutils/test/functional/input/data/standard.txt b/docutils/test/functional/input/data/standard.txt deleted file mode 100644 index a0d1570ed..000000000 --- a/docutils/test/functional/input/data/standard.txt +++ /dev/null @@ -1,753 +0,0 @@ -.. This is a comment. Note how any initial comments are moved by - transforms to after the document title, subtitle, and docinfo. - -.. _doctitle: - -================================ - reStructuredText Test Document -================================ - -.. Above is the document title, and below is the subtitle. - They are transformed from section titles after parsing. - -.. _subtitle: - --------------------------------- - Examples of Syntax Constructs --------------------------------- - -.. bibliographic fields (which also require a transform): - -:Author: David Goodger -:Address: 123 Example Street - Example, EX Canada - A1B 2C3 -:Contact: goodger@users.sourceforge.net -:Authors: Me; Myself; I -:organization: humankind -:date: Now, or yesterday. Or maybe even *before* yesterday. -:status: This is a "work in progress" -:revision: is managed by a version control system. -:version: 1 -:copyright: This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. -:field name: This is a "generic bibliographic field". -:field name "2": - Generic bibliographic fields may contain multiple body elements. - - Like this. - -:Dedication: - - For Docutils users & co-developers. - -:abstract: - - This is a test document, containing at least one example of each - reStructuredText construct. - -.. meta:: - :keywords: reStructuredText, test, parser - :description lang=en: A test document, containing at least one - example of each reStructuredText construct. - -.. contents:: Table of Contents -.. section-numbering:: - - -Structural Elements -=================== - -Section Title -------------- -Section Subtitle -```````````````` - -That's it, the text just above this line. - -Empty Section -------------- - -Transitions ------------ - -Here's a transition: - ---------- - -It divides the section. Transitions may also occur between sections: - ---------- - -Body Elements -============= - -Paragraphs ----------- - -A paragraph. - -Inline Markup -````````````` - -Paragraphs contain text and may contain inline markup: *emphasis*, -**strong emphasis**, ``inline literals``, standalone hyperlinks -(http://www.python.org), external hyperlinks (Python_), internal -cross-references (example_), external hyperlinks with embedded URIs -(`Python web site <http://www.python.org>`__), `anonymous hyperlink -references`__ (`a second reference`__), footnote references (manually -numbered [1]_, anonymous auto-numbered [#]_, labeled auto-numbered -[#label]_, or symbolic [*]_), citation references ([CIT2002]_), -substitution references (|example|), and _`inline hyperlink targets` -(see Targets_ below for a reference back to here). Character-level -inline markup is also possible (although exceedingly ugly!) in *re*\ -``Structured``\ *Text*. Problems are indicated by |problematic| text -(generated by processing errors; this one is intentional). Here is a -reference to the doctitle_ and the subtitle_. - -__ http://www.python.org/ -__ http://docutils.sourceforge.net/ - -The default role for interpreted text is `Title Reference`. Here are -some explicit interpreted text roles: a PEP reference (:PEP:`287`); an -RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; -and explicit roles for :emphasis:`standard` :strong:`inline` -:literal:`markup`. - -.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! - -Let's test wrapping and whitespace significance in inline literals: -``This is an example of --inline-literal --text, --including some-- -strangely--hyphenated-words. Adjust-the-width-of-your-browser-window -to see how the text is wrapped. -- ---- -------- Now note the -spacing between the words of this sentence (words -should be grouped in pairs).`` - -If the ``--pep-references`` option was supplied, there should be a -live link to PEP 258 here. - -Bullet Lists ------------- - -- A bullet list - - + Nested bullet list. - + Nested item 2. - -- Item 2. - - Paragraph 2 of item 2. - - * Nested bullet list. - * Nested item 2. - - - Third level. - - Item 2. - - * Nested item 3. - - * This nested list should be compacted by the HTML writer. - - .. _target: - - .. Even if this item contains a target and a comment. - -Enumerated Lists ----------------- - -1. Arabic numerals. - - a) lower alpha) - - (i) (lower roman) - - A. upper alpha. - - I) upper roman) - -2. Lists that don't start at 1: - - 3. Three - - 4. Four - - C. C - - D. D - - iii. iii - - iv. iv - -Definition Lists ----------------- - -Term - Definition -Term : classifier - Definition paragraph 1. - - Definition paragraph 2. -Term - Definition -Term : classifier one : classifier two - Definition - -Field Lists ------------ - -:what: Field lists map field names to field bodies, like database - records. They are often part of an extension syntax. They are - an unambiguous variant of RFC 2822 fields. - -:how arg1 arg2: - - The field marker is a colon, the field name, and a colon. - - The field body may contain one or more body elements, indented - relative to the field marker. - -:credits: - - .. class:: credits - - This paragraph has the `credits` class set. (This is actually not - about credits but just for ensuring that the class attribute - doesn't get stripped away.) - -Option Lists ------------- - -For listing command-line options: - --a command-line option "a" --b file options can have arguments - and long descriptions ---long options can be long also ---input=file long options can also have - arguments - ---very-long-option - The description can also start on the next line. - - The description may contain multiple body elements, - regardless of where it starts. - --x, -y, -z Multiple options are an "option group". --v, --verbose Commonly-seen: short & long options. --1 file, --one=file, --two file - Multiple options with arguments. -/V DOS/VMS-style options too - -There must be at least two spaces between the option and the -description. - -Literal Blocks --------------- - -Literal blocks are indicated with a double-colon ("::") at the end of -the preceding paragraph (over there ``-->``). They can be indented:: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -Or they can be quoted without indentation:: - ->> Great idea! -> -> Why didn't I think of that? - -Line Blocks ------------ - -This section tests line blocks. Line blocks are body elements which -consist of lines and other line blocks. Nested line blocks cause -indentation. - -| This is a line block. It ends with a blank line. -| New lines begin with a vertical bar ("|"). -| Line breaks and initial indent are significant, and preserved. -| Continuation lines are also possible. A long line that is intended - to wrap should begin with a space in place of the vertical bar. -| The left edge of a continuation line need not be aligned with - the left edge of the text above it. - -| This is a second line block. -| -| Blank lines are permitted internally, but they must begin with a "|". - -Another line block, surrounded by paragraphs: - -| And it's no good waiting by the window -| It's no good waiting for the sun -| Please believe me, the things you dream of -| They don't fall in the lap of no-one - -Take it away, Eric the Orchestra Leader! - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -Block Quotes ------------- - -Block quotes consist of indented body elements: - - My theory by A. Elk. Brackets Miss, brackets. This theory goes - as follows and begins now. All brontosauruses are thin at one - end, much much thicker in the middle and then thin again at the - far end. That is my theory, it is mine, and belongs to me and I - own it, and what it is too. - - -- Anne Elk (Miss) - -Doctest Blocks --------------- - ->>> print 'Python-specific usage examples; begun with ">>>"' -Python-specific usage examples; begun with ">>>" ->>> print '(cut and pasted from interactive Python sessions)' -(cut and pasted from interactive Python sessions) - -Footnotes ---------- - -.. [1] A footnote contains body elements, consistently indented by at - least 3 spaces. - - This is the footnote's second paragraph. - -.. [#label] Footnotes may be numbered, either manually (as in [1]_) or - automatically using a "#"-prefixed label. This footnote has a - label so it can be referred to from multiple places, both as a - footnote reference ([#label]_) and as a hyperlink reference - (label_). - -.. [#] This footnote is numbered automatically and anonymously using a - label of "#" only. - - This is the second paragraph. - - And this is the third paragraph. - -.. [*] Footnotes may also use symbols, specified with a "*" label. - Here's a reference to the next footnote: [*]_. - -.. [*] This footnote shows the next symbol in the sequence. - -.. [4] Here's an unreferenced footnote, with a reference to a - nonexistent footnote: [5]_. - -Citations ---------- - -.. [CIT2002] Citations are text-labeled footnotes. They may be - rendered separately and differently from footnotes. - -Here's a reference to the above, [CIT2002]_, and a [nonexistent]_ -citation. - -.. _Another Target: - -Targets -------- - -.. _example: - -This paragraph is pointed to by the explicit "example" target. A -reference can be found under `Inline Markup`_, above. `Inline -hyperlink targets`_ are also possible. - -Section headers are implicit targets, referred to by name. See -Targets_, which is a subsection of `Body Elements`_. - -Explicit external targets are interpolated into references such as -"Python_". - -.. _Python: http://www.python.org/ - -Targets may be indirect and anonymous. Thus `this phrase`__ may also -refer to the Targets_ section. - -__ Targets_ - -Here's a `hyperlink reference without a target`_, which generates an -error. - -Duplicate Target Names -`````````````````````` - -Duplicate names in section headers or other implicit targets will -generate "info" (level-1) system messages. Duplicate names in -explicit targets will generate "warning" (level-2) system messages. - -Duplicate Target Names -`````````````````````` - -Since there are two "Duplicate Target Names" section headers, we -cannot uniquely refer to either of them by name. If we try to (like -this: `Duplicate Target Names`_), an error is generated. - -Directives ----------- - -.. contents:: :local: - -These are just a sample of the many reStructuredText Directives. For -others, please see -http://docutils.sourceforge.net/docs/ref/rst/directives.html. - -Document Parts -`````````````` - -An example of the "contents" directive can be seen above this section -(a local, untitled table of contents_) and at the beginning of the -document (a document-wide `table of contents`_). - -Images -`````` - -An image directive (also clickable -- a hyperlink reference): - -.. image:: ../../../docs/user/rst/images/title.png - :class: class1 class2 - :target: directives_ - -Image with multiple IDs: - -.. _image target 1: -.. _image target 2: -.. _image target 3: -.. image:: ../../../docs/user/rst/images/title.png - -A centered image: - -.. image:: ../../../docs/user/rst/images/biohazard.png - :align: center - -A left-aligned image: - -.. image:: ../../../docs/user/rst/images/biohazard.png - :align: left - -A right-aligned image: - -.. image:: ../../../docs/user/rst/images/biohazard.png - :align: right - -A figure directive: - -.. figure:: ../../../docs/user/rst/images/biohazard.png - :figclass: figclass1 figclass2 - :class: class1 class2 - :alt: reStructuredText, the markup syntax - :align: right - :width: 50 - - A figure is an image with a caption and/or a legend: - - +------------+-----------------------------------------------+ - | re | Revised, revisited, based on 're' module. | - +------------+-----------------------------------------------+ - | Structured | Structure-enhanced text, structuredtext. | - +------------+-----------------------------------------------+ - | Text | Well it is, isn't it? | - +------------+-----------------------------------------------+ - - This paragraph is also part of the legend. - -.. figure:: ../../../docs/user/rst/images/biohazard.png - :figclass: figclass1 figclass2 - :class: class1 class2 - :alt: reStructuredText, the markup syntax - :align: left - :width: 50 - - A left-aligned figure. - - This is the legend. - -This paragraph might flow around the figure... - -A centered figure: - -.. figure:: ../../../docs/user/rst/images/biohazard.png - :align: center - :width: 50 - - This is the caption. - - This is the legend. - - The legend may consist of several paragraphs. - -This paragraph might flow around the figure... - -A left-aligned figure: - -.. figure:: ../../../docs/user/rst/images/biohazard.png - :align: left - :width: 50 - - This is the caption. - - This is the legend. - - The legend may consist of several paragraphs. - -This paragraph might flow around the figure... - -Now widths: - -An image 2 em wide: - -.. image:: ../../../docs/user/rst/images/biohazard.png - :width: 2 em - -An image 2 em wide and 30 pixel high: - -.. image:: ../../../docs/user/rst/images/biohazard.png - :width: 2em - :height: 30 px - -An image occupying 70% of the line width: - -.. image:: ../../../docs/user/rst/images/biohazard.png - :width: 70% - -An image 3 cm high: - -.. image:: ../../../docs/user/rst/images/biohazard.png - :height: 3 cm - - -Admonitions -``````````` - -.. Attention:: Directives at large. - -.. Caution:: - - Don't take any wooden nickels. - -.. DANGER:: Mad scientist at work! - -.. Error:: Does not compute. - -.. Hint:: It's bigger than a bread box. - -.. Important:: - - Wash behind your ears. - - Clean up your room. - - Call your mother. - - Back up your data. - -.. Note:: This is a note. - -.. Tip:: 15% if the service is good. - -.. WARNING:: Strong prose may provoke extreme mental exertion. - Reader discretion is strongly advised. - -.. admonition:: And, by the way... - - You can make up your own admonition too. - - .. _Docutils: http://docutils.sourceforge.net/ - -Topics, Sidebars, and Rubrics -````````````````````````````` - -.. sidebar:: Sidebar Title - :subtitle: Optional Subtitle - - This is a sidebar. It is for text outside the flow of the main - text. - - .. rubric:: This is a rubric inside a sidebar - - Sidebars often appears beside the main text with a border and - background color. - -.. topic:: Topic Title - - This is a topic. - -.. rubric:: This is a rubric - -Target Footnotes -```````````````` - -.. target-notes:: - - -Replacement Text -```````````````` - -I recommend you try |Python|_. - -.. |Python| replace:: Python, *the* best language around - -Compound Paragraph -`````````````````` - -.. compound:: - :class: some-class - - Compound 1, paragraph 1. - - Compound 1, paragraph 2. - - * Compound 1, list item one. - * Compound 1, list item two. - -Another compound statement: - -.. compound:: - - Compound 2, a literal block:: - - Compound 2, literal. - - Compound 2, this is a test. - -.. compound:: - - Compound 3, only consisting of one paragraph. - -.. compound:: - - :: - - Compound 4. - This one starts with a literal block. - - Compound 4, a paragraph. - -Now something *really* perverted -- a nested compound block. This is -just to test that it works at all; the results don't have to be -meaningful. - -.. compound:: - - Compound 5, block 1 (a paragraph). - - .. compound:: - - Compound 6, block 2 in compound 5. - - Compound 6, another paragraph. - - Compound 5, block 3 (a paragraph). - -.. compound:: - - Compound 7, with a table inside: - - +--------------------+--------------------+--------------------+ - | Left cell, first | Middle cell, | Right cell. | - | paragraph. | consisting of | | - | | exactly one | Paragraph 2. | - | Left cell, second | paragraph. | | - | paragraph. | | Paragraph 3. | - +--------------------+--------------------+--------------------+ - - Compound 7, a paragraph after the table. - - Compound 7, another paragraph. - -Parsed Literal Blocks -````````````````````` - -.. parsed-literal:: - - This is a parsed literal block. - This line is indented. The next line is blank. - - Inline markup is supported, e.g. *emphasis*, **strong**, ``literal - text``, footnotes [1]_, _`targets`, and `references - <http://www.python.org/>`_. - -Substitution Definitions ------------------------- - -An inline image (|example|) example: - -.. |EXAMPLE| image:: ../../../docs/user/rst/images/biohazard.png - -(Substitution definitions are not visible in the HTML source.) - -Comments --------- - -Here's one: - -.. Comments begin with two dots and a space. Anything may - follow, except for the syntax of footnotes, hyperlink - targets, directives, or substitution definitions. - - Double-dashes -- "--" -- must be escaped somehow in HTML output. - -(View the HTML source to see the comment.) - -Raw text --------- - -This does not necessarily look nice, because there may be missing white space. - -It's just there to freeze the behavior. - -.. raw:: html latex - - A test. - -.. raw:: html latex - - Second test. - -.. class:: myclass - -.. raw:: html latex - - Another test with myclass set. - -.. role:: raw-role(raw) - :format: html latex - :class: myrawroleclass - -This is the :raw-role:`fourth test` with myrawroleclass set. - -.. raw:: html - - Fifth test in HTML.<br />Line two. - -.. raw:: latex - - Fifth test in LaTeX.\\Line two. - -Container ---------- - -.. container:: custom - - paragraph 1 - - paragraph 2 diff --git a/docutils/test/functional/input/data/table_colspan.txt b/docutils/test/functional/input/data/table_colspan.txt deleted file mode 100644 index 54294fdd2..000000000 --- a/docutils/test/functional/input/data/table_colspan.txt +++ /dev/null @@ -1,15 +0,0 @@ -Colspanning tables ------------------- - -This table has a cell spanning two columns: - -===== ===== ====== - Inputs Output ------------- ------ - A B A or B -===== ===== ====== -False False False -True False True -False True True -True True True -===== ===== ====== diff --git a/docutils/test/functional/input/data/table_complex.txt b/docutils/test/functional/input/data/table_complex.txt deleted file mode 100644 index 8ff37180e..000000000 --- a/docutils/test/functional/input/data/table_complex.txt +++ /dev/null @@ -1,21 +0,0 @@ -Complex tables --------------- - -Here's a complex table, which should test all features. - -+------------------------+------------+----------+----------+ -| Header row, column 1 | Header 2 | Header 3 | Header 4 | -| (header rows optional) | | | | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | Cells may span columns. | -+------------------------+------------+---------------------+ -| body row 3 | Cells may | - Table cells | -+------------------------+ span rows. | - contain | -| body row 4 | | - body elements. | -| | Paragraph. | | -+------------------------+------------+----------+----------+ -| body row 5 | Cells may also be | | -| | empty: ``-->`` | | -+------------------------+-----------------------+----------+ diff --git a/docutils/test/functional/input/data/table_rowspan.txt b/docutils/test/functional/input/data/table_rowspan.txt deleted file mode 100644 index 5df3109c4..000000000 --- a/docutils/test/functional/input/data/table_rowspan.txt +++ /dev/null @@ -1,15 +0,0 @@ -Rowspanning tables ------------------- - -Here's a table with cells spanning several rows: - -+------------------------+------------+------------------+ -| Header row, column 1 | Header 2 | Header 3 | -| (header rows optional) | | | -+========================+============+==================+ -| body row 1, column 1 | column 2 | column 3 | -+------------------------+------------+------------------+ -| body row 2 | Cells may | Another | -+------------------------+ span rows. | rowspanning | -| body row 3 | | cell. | -+------------------------+------------+------------------+ diff --git a/docutils/test/functional/input/data/unicode.txt b/docutils/test/functional/input/data/unicode.txt deleted file mode 100644 index 4bdd57653..000000000 --- a/docutils/test/functional/input/data/unicode.txt +++ /dev/null @@ -1,27 +0,0 @@ -Various non-ASCII characters ----------------------------- - -= =================================== -© copyright sign -® registered sign -« left pointing guillemet -» right pointing guillemet -– en-dash -— em-dash -‘ single turned comma quotation mark -’ single comma quotation mark -‚ low single comma quotation mark -“ double turned comma quotation mark -†double comma quotation mark -„ low double comma quotation mark -†dagger -‡ double dagger -… ellipsis -â„¢ trade mark sign -⇔ left-right double arrow -= =================================== - -The following line should not be wrapped, because it uses -non-breakable spaces: - -X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X diff --git a/docutils/test/functional/input/field_list.txt b/docutils/test/functional/input/field_list.txt deleted file mode 100644 index fa04ba6ca..000000000 --- a/docutils/test/functional/input/field_list.txt +++ /dev/null @@ -1,5 +0,0 @@ -:short: This field's name is short. -:medium-length: This field's name is medium-length. -:long field name: This field's name is long. -:very very long field name: - This field's name is quite long. diff --git a/docutils/test/functional/input/latex_docinfo.txt b/docutils/test/functional/input/latex_docinfo.txt deleted file mode 100644 index f6c9ba2e4..000000000 --- a/docutils/test/functional/input/latex_docinfo.txt +++ /dev/null @@ -1,10 +0,0 @@ -:Author: Foo Fred -:Organization: Food Foomatics & Friends -:Contact: foo@food.example.info -:Address: Fox St 13 - Foowood -:Author: Bar Barney -:Organization: Bar-BQ Bar -:Contact: 1-800-BARBQBAR -:Address: Barbara St 16 - South Barwell diff --git a/docutils/test/functional/input/pep_html.txt b/docutils/test/functional/input/pep_html.txt deleted file mode 100644 index 483077131..000000000 --- a/docutils/test/functional/input/pep_html.txt +++ /dev/null @@ -1,32 +0,0 @@ -PEP: 100 -Title: Test PEP -Version: 42 -Last-Modified: A long time ago. -Author: John Doe <john@example.org> -Discussions-To: <devnull@example.org> -Status: Draft -Type: Standards Track -Content-Type: text/x-rst -Created: 01-Jun-2001 -Post-History: 13-Jun-2001 - - -Abstract -======== - -This is just a test [#]_. See the `PEP repository`_ for the real -thing. - -.. _PEP repository: http://www.python.org/peps/ - - -Copyright -========= - -This document has been placed in the public domain. - - -References and Footnotes -======================== - -.. [#] PEP editors: peps@python.org diff --git a/docutils/test/functional/input/simple.txt b/docutils/test/functional/input/simple.txt deleted file mode 100644 index 492e4233b..000000000 --- a/docutils/test/functional/input/simple.txt +++ /dev/null @@ -1 +0,0 @@ -simple input diff --git a/docutils/test/functional/input/standalone_rst_html4css1.txt b/docutils/test/functional/input/standalone_rst_html4css1.txt deleted file mode 100644 index 3c2cf80c6..000000000 --- a/docutils/test/functional/input/standalone_rst_html4css1.txt +++ /dev/null @@ -1,8 +0,0 @@ -.. include:: data/standard.txt -.. include:: data/header_footer.txt -.. include:: data/table_colspan.txt -.. include:: data/table_rowspan.txt -.. include:: data/table_complex.txt -.. include:: data/list_table.txt -.. include:: data/custom_roles.txt -.. include:: data/errors.txt diff --git a/docutils/test/functional/input/standalone_rst_latex.txt b/docutils/test/functional/input/standalone_rst_latex.txt deleted file mode 100644 index 09a4f8890..000000000 --- a/docutils/test/functional/input/standalone_rst_latex.txt +++ /dev/null @@ -1,12 +0,0 @@ -.. include:: data/standard.txt -.. include:: data/table_colspan.txt -.. include:: data/table_rowspan.txt - - -Tests for the LaTeX writer -========================== - -.. include:: data/nonalphanumeric.txt -.. include:: data/unicode.txt - -.. include:: data/errors.txt diff --git a/docutils/test/functional/input/standalone_rst_newlatex.txt b/docutils/test/functional/input/standalone_rst_newlatex.txt deleted file mode 100644 index 81b4e5ea6..000000000 --- a/docutils/test/functional/input/standalone_rst_newlatex.txt +++ /dev/null @@ -1,12 +0,0 @@ -.. include:: data/standard.txt -.. include:: data/table_colspan.txt -.. include:: data/latex.txt - - -Tests for the LaTeX writer -========================== - -.. include:: data/nonalphanumeric.txt -.. include:: data/unicode.txt - -.. include:: data/errors.txt diff --git a/docutils/test/functional/input/standalone_rst_pseudoxml.txt b/docutils/test/functional/input/standalone_rst_pseudoxml.txt deleted file mode 100644 index 05f0287d0..000000000 --- a/docutils/test/functional/input/standalone_rst_pseudoxml.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. include:: data/standard.txt -.. include:: data/header_footer.txt -.. include:: data/table_colspan.txt -.. include:: data/table_rowspan.txt -.. include:: data/table_complex.txt -.. include:: data/list_table.txt -.. include:: data/errors.txt diff --git a/docutils/test/functional/input/standalone_rst_s5_html.txt b/docutils/test/functional/input/standalone_rst_s5_html.txt deleted file mode 100644 index 863cc77b6..000000000 --- a/docutils/test/functional/input/standalone_rst_s5_html.txt +++ /dev/null @@ -1,126 +0,0 @@ -.. include:: <s5defs.txt> - -============= - Slide Shows -============= - -:Author: David Goodger -:Date: 2005-11-28 - -.. contents:: - :class: handout - -.. class:: handout - - This is a test. This is only a test. If this were a real slide - show, there would be a projector handy. - -Let's test the S5/HTML writer! - -.. class:: small - -* Use the arrow keys to navigate. - -* Click the "|mode|" button to switch between presentation & - handout/outline modes. - -.. container:: handout - - In presentation mode, mouse over to the lower right-hand corner to - display the controls. - -.. |bullet| unicode:: U+02022 -.. |mode| unicode:: U+00D8 .. capital o with stroke -.. footer:: Location |bullet| Date - - -Introduction -============ - -.. class:: compact - -* reStructuredText - - .. class:: handout - - Uses normal reStructuredText as input. - -* One section per slide - - .. class:: handout - - Each first-level section is converted into a single slide. - -* (X)HTML output - - .. class:: handout - - Presentations can be viewed using any modern graphical web browser. - The browser must support CSS, JavaScript, and XHTML. S5 even works - with IE! - -* Themes - - .. class:: handout - - A variety of themes are available. - -* ``rst2s5.py`` - - .. class:: handout - - The front-end tool to generate S5 slide shows. - - -Features (1) -============ - -.. class:: left - -A flush-left paragraph - -.. class:: center - -A centered paragraph - -.. class:: right - -A flush-right paragraph - -Some colours: :black:`black` [black], :gray:`gray`, :silver:`silver`, -:white:`white` [white], :maroon:`maroon`, :red:`red`, -:magenta:`magenta`, :fuchsia:`fuchsia`, :pink:`pink`, -:orange:`orange`, :yellow:`yellow`, :lime:`lime`, :green:`green`, -:olive:`olive`, :teal:`teal`, :cyan:`cyan`, :aqua:`aqua`, -:blue:`blue`, :navy:`navy`, :purple:`purple` - -Features (2) -============ - -`Some` `incremental` `text.` - -.. class:: incremental open - - * :tiny:`tiny` (class & role name: "tiny", e.g. "``:tiny:`text```") - * :small:`small` ("small") - * normal (unstyled) - * :big:`big` ("big") - * :huge:`huge` ("huge") - - -Checklist -========= - -* The document title should be duplicated on each slide in the footer - (except for the first slide, ``slide0``, where the entire footer is - disabled). - -* The footer also contains a second line, "Location |bullet| Date" - -* There's no table of contents on the first slide, although it does - appear in the handout/outline. - -* Handout material is not displayed in presentation mode. - -* The theme directories should be created, and the theme files copied - over. diff --git a/docutils/test/functional/output/README.txt b/docutils/test/functional/output/README.txt deleted file mode 100644 index ce6dc9861..000000000 --- a/docutils/test/functional/output/README.txt +++ /dev/null @@ -1,3 +0,0 @@ -This is the directory where the actual output is stored. - -This README.txt is just a placeholder to make CVS create the directory. diff --git a/docutils/test/functional/tests/_default.py b/docutils/test/functional/tests/_default.py deleted file mode 100644 index 2835c5b2e..000000000 --- a/docutils/test/functional/tests/_default.py +++ /dev/null @@ -1,7 +0,0 @@ -# Default settings for all tests. - -settings_overrides['report_level'] = 2 -settings_overrides['halt_level'] = 5 -settings_overrides['warning_stream'] = '' -settings_overrides['input_encoding'] = 'utf-8' -settings_overrides['embed_stylesheet'] = 0 diff --git a/docutils/test/functional/tests/_standalone_rst_defaults.py b/docutils/test/functional/tests/_standalone_rst_defaults.py deleted file mode 100644 index b51704929..000000000 --- a/docutils/test/functional/tests/_standalone_rst_defaults.py +++ /dev/null @@ -1,6 +0,0 @@ -# Keyword parameters passed to publish_file. -reader_name = "standalone" -parser_name = "rst" - -# Settings. -settings_overrides['sectsubtitle_xform'] = 1 diff --git a/docutils/test/functional/tests/compact_lists.py b/docutils/test/functional/tests/compact_lists.py deleted file mode 100644 index 3ac4c3f8b..000000000 --- a/docutils/test/functional/tests/compact_lists.py +++ /dev/null @@ -1,11 +0,0 @@ -# Source and destination file names. -test_source = "compact_lists.txt" -test_destination = "compact_lists.html" - -# Keyword parameters passed to publish_file. -reader_name = "standalone" -parser_name = "rst" -writer_name = "html" - -# Settings -#settings_overrides['key'] = diff --git a/docutils/test/functional/tests/dangerous.py b/docutils/test/functional/tests/dangerous.py deleted file mode 100644 index 620a927ba..000000000 --- a/docutils/test/functional/tests/dangerous.py +++ /dev/null @@ -1,12 +0,0 @@ -# Source and destination file names. -test_source = "dangerous.txt" -test_destination = "dangerous.html" - -# Keyword parameters passed to publish_file. -reader_name = "standalone" -parser_name = "rst" -writer_name = "html" - -# Settings -settings_overrides['file_insertion_enabled'] = 0 -settings_overrides['raw_enabled'] = 0 diff --git a/docutils/test/functional/tests/field_name_limit.py b/docutils/test/functional/tests/field_name_limit.py deleted file mode 100644 index db79d4c67..000000000 --- a/docutils/test/functional/tests/field_name_limit.py +++ /dev/null @@ -1,12 +0,0 @@ -# Source and destination file names. -test_source = "field_list.txt" -test_destination = "field_name_limit.html" - -# Keyword parameters passed to publish_file. -reader_name = "standalone" -parser_name = "rst" -writer_name = "html" - -# Settings -settings_overrides['field_name_limit'] = 0 # no limit -settings_overrides['docinfo_xform'] = 0 diff --git a/docutils/test/functional/tests/latex_docinfo.py b/docutils/test/functional/tests/latex_docinfo.py deleted file mode 100644 index 3f9c34455..000000000 --- a/docutils/test/functional/tests/latex_docinfo.py +++ /dev/null @@ -1,12 +0,0 @@ -# Source and destination file names. -test_source = "latex_docinfo.txt" -test_destination = "latex_docinfo.tex" - -# Keyword parameters passed to publish_file. -reader_name = "standalone" -parser_name = "rst" -writer_name = "latex" - -# Extra setting we need - -settings_overrides['use_latex_docinfo'] = 1 diff --git a/docutils/test/functional/tests/misc_rst_html4css1.py b/docutils/test/functional/tests/misc_rst_html4css1.py deleted file mode 100644 index 861a9e9c5..000000000 --- a/docutils/test/functional/tests/misc_rst_html4css1.py +++ /dev/null @@ -1,14 +0,0 @@ -# Source and destination file names. -test_source = "simple.txt" -test_destination = "misc_rst_html4css1.html" - -# Keyword parameters passed to publish_file. -reader_name = "standalone" -parser_name = "rst" -writer_name = "html4css1" - -# Settings -# test for encoded attribute value: -settings_overrides['stylesheet'] = 'foo&bar.css' -settings_overrides['stylesheet_path'] = '' -settings_overrides['embed_stylesheet'] = 0 diff --git a/docutils/test/functional/tests/pep_html.py b/docutils/test/functional/tests/pep_html.py deleted file mode 100644 index 00e127ba7..000000000 --- a/docutils/test/functional/tests/pep_html.py +++ /dev/null @@ -1,14 +0,0 @@ -# Source and destination file names. -test_source = "pep_html.txt" -test_destination = "pep_html.html" - -# Keyword parameters passed to publish_file. -reader_name = "pep" -parser_name = "rst" -writer_name = "pep_html" - -# Settings -settings_overrides['python_home'] = "http://www.python.org" -settings_overrides['pep_home'] = "http://www.python.org/peps" -settings_overrides['no_random'] = 1 -settings_overrides['cloak_email_addresses'] = 1 diff --git a/docutils/test/functional/tests/standalone_rst_html4css1.py b/docutils/test/functional/tests/standalone_rst_html4css1.py deleted file mode 100644 index c34298eab..000000000 --- a/docutils/test/functional/tests/standalone_rst_html4css1.py +++ /dev/null @@ -1,10 +0,0 @@ -execfile('functional/tests/_standalone_rst_defaults.py') - -# Source and destination file names. -test_source = "standalone_rst_html4css1.txt" -test_destination = "standalone_rst_html4css1.html" - -# Keyword parameters passed to publish_file. -writer_name = "html4css1" - -# Settings: settings_overrides['setting'] = value diff --git a/docutils/test/functional/tests/standalone_rst_latex.py b/docutils/test/functional/tests/standalone_rst_latex.py deleted file mode 100644 index f0c40b75a..000000000 --- a/docutils/test/functional/tests/standalone_rst_latex.py +++ /dev/null @@ -1,8 +0,0 @@ -execfile('functional/tests/_standalone_rst_defaults.py') - -# Source and destination file names. -test_source = "standalone_rst_latex.txt" -test_destination = "standalone_rst_latex.tex" - -# Keyword parameters passed to publish_file. -writer_name = "latex" diff --git a/docutils/test/functional/tests/standalone_rst_pseudoxml.py b/docutils/test/functional/tests/standalone_rst_pseudoxml.py deleted file mode 100644 index b9b2df309..000000000 --- a/docutils/test/functional/tests/standalone_rst_pseudoxml.py +++ /dev/null @@ -1,8 +0,0 @@ -execfile('functional/tests/_standalone_rst_defaults.py') - -# Source and destination file names. -test_source = "standalone_rst_pseudoxml.txt" -test_destination = "standalone_rst_pseudoxml.txt" - -# Keyword parameters passed to publish_file. -writer_name = "pseudoxml" diff --git a/docutils/test/functional/tests/standalone_rst_s5_html_1.py b/docutils/test/functional/tests/standalone_rst_s5_html_1.py deleted file mode 100755 index ce27f687a..000000000 --- a/docutils/test/functional/tests/standalone_rst_s5_html_1.py +++ /dev/null @@ -1,56 +0,0 @@ -execfile('functional/tests/_standalone_rst_defaults.py') - -# Source and destination file names: -test_source = 'standalone_rst_s5_html.txt' -test_destination = 'standalone_rst_s5_html_1.html' - -# Keyword parameters passed to publish_file: -writer_name = 's5_html' - -# Settings: -settings_overrides['theme'] = 'small-black' - - -# Extra functional tests. -# Prefix all names with '_' to avoid confusing `docutils.core.publish_file`. - -import filecmp as _filecmp - -def _test_more(expected_dir, output_dir, test_case, parameters): - """Compare ``ui/<theme>`` directories.""" - theme = settings_overrides.get('theme', 'default') - expected = '%s/%s/%s' % (expected_dir, 'ui', theme) - output = '%s/%s/%s' % (output_dir, 'ui', theme) - differences, uniques = _compare_directories(expected, output) - parts = [] - if differences: - parts.append('The following files differ from the expected output:') - parts.extend(differences) - expected = [path.replace('functional/output/', 'functional/expected/') - for path in differences] - parts.append('Please compare the expected and actual output files:') - parts.extend([' diff %s %s' % tup - for tup in zip(expected, differences)]) - parts.append('If the actual output is correct, please replace the ' - 'expected output files:') - parts.extend([' mv %s %s' % tup - for tup in zip(differences, expected)]) - parts.append('and check them in to Subversion:') - parts.extend([' svn commit -m "<comment>" %s' % path - for path in expected]) - if uniques: - parts.append('The following paths are unique:') - parts.extend(uniques) - test_case.assert_(not parts, '\n'.join(parts)) - -def _compare_directories(expected, output): - dircmp = _filecmp.dircmp(expected, output, ['.svn', 'CVS']) - differences = ['%s/%s' % (output, name) for name in dircmp.diff_files] - uniques = (['%s/%s' % (expected, name) for name in dircmp.left_only] - + ['%s/%s' % (output, name) for name in dircmp.right_only]) - for subdir in dircmp.common_dirs: - diffs, uniqs = _compare_directories('%s/%s' % (expected, subdir), - '%s/%s' % (output, subdir)) - differences.extend(diffs) - uniques.extend(uniqs) - return differences, uniques diff --git a/docutils/test/functional/tests/standalone_rst_s5_html_2.py b/docutils/test/functional/tests/standalone_rst_s5_html_2.py deleted file mode 100755 index aea7a9207..000000000 --- a/docutils/test/functional/tests/standalone_rst_s5_html_2.py +++ /dev/null @@ -1,7 +0,0 @@ -# initialize with the settings & definitions from test 1: -execfile('functional/tests/standalone_rst_s5_html_1.py') - -# overrides specific to this test: -test_destination = 'standalone_rst_s5_html_2.html' -del settings_overrides['theme'] # use the default -settings_overrides['current_slide'] = 1 diff --git a/docutils/test/package_unittest.py b/docutils/test/package_unittest.py deleted file mode 100644 index 43d724cd1..000000000 --- a/docutils/test/package_unittest.py +++ /dev/null @@ -1,161 +0,0 @@ -#! /usr/bin/env python - -# Author: Garth Kidd -# Contact: garth@deadlybloodyserious.com -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This module extends unittest.py with `loadTestModules()`, by loading multiple -test modules from a directory. Optionally, test packages are also loaded, -recursively. -""" - -import sys -import os -import getopt -import types -import unittest -import re - - -# So that individual test modules can share a bit of state, -# `package_unittest` acts as an intermediary for the following -# variables: -debug = 0 -verbosity = 1 - -USAGE = """\ -Usage: test_whatever [options] - -Options: - -h, --help Show this message - -v, --verbose Verbose output - -q, --quiet Minimal output - -d, --debug Debug mode -""" - -def usageExit(msg=None): - """Print usage and exit.""" - if msg: - print msg - print USAGE - sys.exit(2) - -def parseArgs(argv=sys.argv): - """Parse command line arguments and set TestFramework state. - - State is to be acquired by test_* modules by a grotty hack: - ``from TestFramework import *``. For this stylistic - transgression, I expect to be first up against the wall - when the revolution comes. --Garth""" - global verbosity, debug - try: - options, args = getopt.getopt(argv[1:], 'hHvqd', - ['help', 'verbose', 'quiet', 'debug']) - for opt, value in options: - if opt in ('-h', '-H', '--help'): - usageExit() - if opt in ('-q', '--quiet'): - verbosity = 0 - if opt in ('-v', '--verbose'): - verbosity = 2 - if opt in ('-d', '--debug'): - debug =1 - if len(args) != 0: - usageExit("No command-line arguments supported yet.") - except getopt.error, msg: - usageExit(msg) - -def loadTestModules(path, name='', packages=None): - """ - Return a test suite composed of all the tests from modules in a directory. - - Search for modules in directory `path`, beginning with `name`. If - `packages` is true, search subdirectories (also beginning with `name`) - recursively. Subdirectories must be Python packages; they must contain an - '__init__.py' module. - """ - testLoader = unittest.defaultTestLoader - testSuite = unittest.TestSuite() - testModules = [] - path = os.path.abspath(path) # current working dir if `path` empty - paths = [path] - while paths: - p = paths.pop(0) - files = os.listdir(p) - for filename in files: - if filename.startswith(name): - fullpath = os.path.join(p, filename) - if filename.endswith('.py'): - fullpath = fullpath[len(path)+1:] - testModules.append(path2mod(fullpath)) - elif packages and os.path.isdir(fullpath) and \ - os.path.isfile(os.path.join(fullpath, '__init__.py')): - paths.append(fullpath) - # Import modules and add their tests to the suite. - sys.path.insert(0, path) - for mod in testModules: - if debug: - print >>sys.stderr, "importing %s" % mod - try: - module = import_module(mod) - except ImportError: - print >>sys.stderr, "ERROR: Can't import %s, skipping its tests:" % mod - sys.excepthook(*sys.exc_info()) - else: - # if there's a suite defined, incorporate its contents - try: - suite = getattr(module, 'suite') - except AttributeError: - # Look for individual tests - moduleTests = testLoader.loadTestsFromModule(module) - # unittest.TestSuite.addTests() doesn't work as advertised, - # as it can't load tests from another TestSuite, so we have - # to cheat: - testSuite.addTest(moduleTests) - continue - if type(suite) == types.FunctionType: - testSuite.addTest(suite()) - elif type(suite) == types.InstanceType \ - and isinstance(suite, unittest.TestSuite): - testSuite.addTest(suite) - else: - raise AssertionError, "don't understand suite (%s)" % mod - sys.path.pop(0) - return testSuite - -def path2mod(path): - """Convert a file path to a dotted module name.""" - return path[:-3].replace(os.sep, '.') - -def import_module(name): - """Import a dotted-path module name, and return the final component.""" - mod = __import__(name) - components = name.split('.') - for comp in components[1:]: - mod = getattr(mod, comp) - return mod - -def main(suite=None): - """ - Shared `main` for any individual test_* file. - - suite -- TestSuite to run. If not specified, look for any globally defined - tests and run them. - """ - parseArgs() - if suite is None: - # Load any globally defined tests. - suite = unittest.defaultTestLoader.loadTestsFromModule( - __import__('__main__')) - if debug: - print >>sys.stderr, "Debug: Suite=%s" % suite - testRunner = unittest.TextTestRunner(verbosity=verbosity) - # run suites (if we were called from test_all) or suite... - if type(suite) == type([]): - for s in suite: - testRunner.run(s) - else: - testRunner.run(suite) diff --git a/docutils/test/test_dependencies.py b/docutils/test/test_dependencies.py deleted file mode 100755 index 46e8ff846..000000000 --- a/docutils/test/test_dependencies.py +++ /dev/null @@ -1,78 +0,0 @@ -#! /usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for the --record-dependencies option. -""" - -import os.path -import unittest -import sys -import DocutilsTestSupport # must be imported before docutils -import docutils.core -import docutils.utils - - -class RecordDependenciesTests(unittest.TestCase): - - def setUp(self): - os.chdir(os.path.join(DocutilsTestSupport.testroot, 'data')) - - def get_record(self, inputfile=None, **settings): - - recordfile = 'record.txt' - settings.setdefault('source_path', 'dependencies.txt') - settings.setdefault('settings_overrides', {}) - settings['settings_overrides'] = settings['settings_overrides'].copy() - settings['settings_overrides']['_disable_config'] = 1 - if not settings['settings_overrides'].has_key('record_dependencies'): - settings['settings_overrides']['record_dependencies'] = \ - docutils.utils.DependencyList(recordfile) - docutils.core.publish_file(destination=DocutilsTestSupport.DevNull(), - **settings) - settings['settings_overrides']['record_dependencies'].close() - return open(recordfile).read().splitlines() - - def test_dependencies(self): - self.assertEqual(self.get_record(), - ['include.txt', - 'raw.txt']) - self.assertEqual(self.get_record(writer_name='latex'), - ['include.txt', - 'raw.txt', - 'some_image.png']) - - def test_csv_dependencies(self): - try: - import csv - self.assertEqual(self.get_record(source_path='csv_dep.txt'), - ['csv_data.txt']) - except ImportError: - pass - - def test_stylesheet_dependencies(self): - # Parameters to publish_file. - s = {'settings_overrides': {}} - so = s['settings_overrides'] - so['embed_stylesheet'] = 0 - so['stylesheet_path'] = 'stylesheet.txt' - so['stylesheet'] = None - s['writer_name'] = 'html' - self.assert_('stylesheet.txt' not in - self.get_record(**s)) - so['embed_stylesheet'] = 1 - self.assert_('stylesheet.txt' in - self.get_record(**s)) - del so['embed_stylesheet'] - s['writer_name'] = 'latex' - self.assert_('stylesheet.txt' in - self.get_record(**s)) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_functional.py b/docutils/test/test_functional.py deleted file mode 100755 index dcec9cf45..000000000 --- a/docutils/test/test_functional.py +++ /dev/null @@ -1,167 +0,0 @@ -#!/usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Perform tests with the data in the functional/ directory. - -Read README.txt for details on how this is done. -""" - -import sys -import os -import os.path -import shutil -import unittest -import difflib -import DocutilsTestSupport # must be imported before docutils -import docutils -import docutils.core - - -datadir = 'functional' -"""The directory to store the data needed for the functional tests.""" - - -def join_path(*args): - return '/'.join(args) or '.' - - -class FunctionalTestSuite(DocutilsTestSupport.CustomTestSuite): - - """Test suite containing test cases for all config files.""" - - def __init__(self): - """Process all config files in functional/tests/.""" - DocutilsTestSupport.CustomTestSuite.__init__(self) - os.chdir(DocutilsTestSupport.testroot) - self.clear_output_directory() - self.added = 0 - os.path.walk(join_path(datadir, 'tests'), self.walker, None) - assert self.added, 'No functional tests found.' - - def clear_output_directory(self): - files = os.listdir(os.path.join('functional', 'output')) - for f in files: - if f in ('README.txt', '.svn', 'CVS'): - continue # don't touch the infrastructure - path = os.path.join('functional', 'output', f) - if os.path.isdir(path): - shutil.rmtree(path) - else: - os.remove(path) - - def walker(self, dummy, dirname, names): - """ - Process all config files among `names` in `dirname`. - - This is a helper function for os.path.walk. A config file is - a Python file (*.py) which sets several variables. - """ - for name in names: - if name.endswith('.py') and not name.startswith('_'): - config_file_full_path = join_path(dirname, name) - self.addTestCase(FunctionalTestCase, 'test', None, None, - id=config_file_full_path, - configfile=config_file_full_path) - self.added += 1 - - -class FunctionalTestCase(DocutilsTestSupport.CustomTestCase): - - """Test case for one config file.""" - - def __init__(self, *args, **kwargs): - """Set self.configfile, pass arguments to parent __init__.""" - self.configfile = kwargs['configfile'] - del kwargs['configfile'] - DocutilsTestSupport.CustomTestCase.__init__(self, *args, **kwargs) - - def shortDescription(self): - return 'test_functional.py: ' + self.configfile - - def test(self): - """Process self.configfile.""" - os.chdir(DocutilsTestSupport.testroot) - # Keyword parameters for publish_file: - namespace = {} - # Initialize 'settings_overrides' for test settings scripts, - # and disable configuration files: - namespace['settings_overrides'] = {'_disable_config': 1} - # Read the variables set in the default config file and in - # the current config file into namespace: - execfile(join_path(datadir, 'tests', '_default.py'), namespace) - execfile(self.configfile, namespace) - # Check for required settings: - assert namespace.has_key('test_source'),\ - "No 'test_source' supplied in " + self.configfile - assert namespace.has_key('test_destination'),\ - "No 'test_destination' supplied in " + self.configfile - # Set source_path and destination_path if not given: - namespace.setdefault('source_path', - join_path(datadir, 'input', - namespace['test_source'])) - # Path for actual output: - namespace.setdefault('destination_path', - join_path(datadir, 'output', - namespace['test_destination'])) - # Path for expected output: - expected_path = join_path(datadir, 'expected', - namespace['test_destination']) - # shallow copy of namespace to minimize: - params = namespace.copy() - # remove unneeded parameters: - del params['test_source'] - del params['test_destination'] - # Delete private stuff like params['__builtins__']: - for key in params.keys(): - if key.startswith('_'): - del params[key] - # Get output (automatically written to the output/ directory - # by publish_file): - output = docutils.core.publish_file(**params) - # Get the expected output *after* writing the actual output. - self.assert_(os.access(expected_path, os.R_OK),\ - 'Cannot find expected output at\n' + expected_path) - f = open(expected_path, 'rU') - expected = f.read() - f.close() - diff = ('The expected and actual output differs.\n' - 'Please compare the expected and actual output files:\n' - ' diff %s %s\n' - 'If the actual output is correct, please replace the\n' - 'expected output and check it in to Subversion:\n' - ' mv %s %s\n' - ' svn commit -m "<comment>" %s' - % (expected_path, params['destination_path'], - params['destination_path'], expected_path, expected_path)) - try: - self.assertEquals(output, expected, diff) - except AssertionError: - if hasattr(difflib, 'unified_diff'): - # Generate diff if unified_diff available: - diff = ''.join( - difflib.unified_diff(expected.splitlines(1), - output.splitlines(1), - expected_path, - params['destination_path'])) - print >>sys.stderr, '\n%s:' % (self,) - print >>sys.stderr, diff - raise - # Execute optional function containing extra tests: - if namespace.has_key('_test_more'): - namespace['_test_more'](join_path(datadir, 'expected'), - join_path(datadir, 'output'), - self, namespace) - - -def suite(): - return FunctionalTestSuite() - - -if __name__ == '__main__': - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_io.py b/docutils/test/test_io.py deleted file mode 100755 index b82911e44..000000000 --- a/docutils/test/test_io.py +++ /dev/null @@ -1,32 +0,0 @@ -#! /usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for io.py. -""" - -import unittest -import DocutilsTestSupport # must be imported before docutils -from docutils import io - - -class InputTests(unittest.TestCase): - - def test_bom(self): - input = io.StringInput(source='\xef\xbb\xbf foo \xef\xbb\xbf bar', - encoding='utf8') - # Assert BOMs are gone. - self.assertEquals(input.read(), u' foo bar') - # With unicode input: - input = io.StringInput(source=u'\ufeff foo \ufeff bar') - # Assert BOMs are still there. - self.assertEquals(input.read(), u'\ufeff foo \ufeff bar') - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_language.py b/docutils/test/test_language.py deleted file mode 100755 index 0571275e7..000000000 --- a/docutils/test/test_language.py +++ /dev/null @@ -1,211 +0,0 @@ -#!/usr/bin/env python - -# Authors: Engelbert Gruber; David Goodger -# Contact: grubert@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for language module completeness. - -Specify a language code (e.g. "de") as a command-line parameter to test only -that language. -""" - -import sys -import os -import re -from types import UnicodeType -import DocutilsTestSupport # must be imported before docutils -import docutils.languages -import docutils.parsers.rst.languages -from docutils.parsers.rst import states, directives, roles - - -reference_language = 'en' - - -class LanguageTestSuite(DocutilsTestSupport.CustomTestSuite): - - language_module_pattern = re.compile('^([a-z]{2,3}(_[a-z]{2,8})*)\.py$') - - def __init__(self, languages=None): - DocutilsTestSupport.CustomTestSuite.__init__(self) - if languages: - self.languages = languages - else: - self.get_languages() - - def get_languages(self): - """ - Get installed language translations from docutils.languages and from - docutils.parsers.rst.languages. - """ - languages = {} - for mod in (os.listdir(docutils.languages.__path__[0]) - + os.listdir(docutils.parsers.rst.languages.__path__[0])): - match = self.language_module_pattern.match(mod) - if match: - languages[match.group(1)] = 1 - self.languages = languages.keys() - - def generateTests(self): - for language in self.languages: - for method in LanguageTestCase.test_methods: - self.addTestCase(LanguageTestCase, method, None, None, - id=language+'.py', language=language) - - -class LanguageTestCase(DocutilsTestSupport.CustomTestCase): - - test_methods = ['test_labels', 'test_bibliographic_fields', - 'test_directives', 'test_roles'] - """Names of methods used to test each language.""" - - def __init__(self, *args, **kwargs): - self.ref = docutils.languages.get_language(reference_language) - self.language = kwargs['language'] - del kwargs['language'] # only wanted here - DocutilsTestSupport.CustomTestCase.__init__(self, *args, **kwargs) - - def _xor(self, ref_dict, l_dict): - """ - Returns entries that are only in one dictionary. - (missing_in_lang, more_than_in_ref). - """ - missing = [] # in ref but not in l. - too_much = [] # in l but not in ref. - for label in ref_dict.keys(): - if not l_dict.has_key(label): - missing.append(label) - for label in l_dict.keys(): - if not ref_dict.has_key(label): - too_much.append(label) - return (missing, too_much) - - def _invert(self, adict): - """Return an inverted (keys & values swapped) dictionary.""" - inverted = {} - for key, value in adict.items(): - inverted[value] = key - return inverted - - def test_labels(self): - try: - module = docutils.languages.get_language(self.language) - if not module: - raise ImportError - except ImportError: - self.fail('No docutils.languages.%s module.' % self.language) - missed, unknown = self._xor(self.ref.labels, module.labels) - if missed or unknown: - self.fail('Module docutils.languages.%s.labels:\n' - ' Missed: %s; Unknown: %s' - % (self.language, str(missed), str(unknown))) - - def test_bibliographic_fields(self): - try: - module = docutils.languages.get_language(self.language) - if not module: - raise ImportError - except ImportError: - self.fail('No docutils.languages.%s module.' % self.language) - missed, unknown = self._xor( - self._invert(self.ref.bibliographic_fields), - self._invert(module.bibliographic_fields)) - if missed or unknown: - self.fail('Module docutils.languages.%s.bibliographic_fields:\n' - ' Missed: %s; Unknown: %s' - % (self.language, str(missed), str(unknown))) - - def test_directives(self): - try: - module = docutils.parsers.rst.languages.get_language( - self.language) - if not module: - raise ImportError - except ImportError: - self.fail('No docutils.parsers.rst.languages.%s module.' - % self.language) - failures = [] - for d in module.directives.keys(): - try: - func, msg = directives.directive(d, module, None) - if not func: - failures.append('"%s": unknown directive' % d) - except Exception, error: - failures.append('"%s": %s' % (d, error)) - inverted = self._invert(module.directives) - canonical = directives._directive_registry.keys() - canonical.sort() - canonical.remove('restructuredtext-test-directive') - for name in canonical: - if not inverted.has_key(name): - failures.append('"%s": translation missing' % name) - if failures: - text = ('Module docutils.parsers.rst.languages.%s:\n %s' - % (self.language, '\n '.join(failures))) - if type(text) == UnicodeType: - text = text.encode('raw_unicode_escape') - self.fail(text) - - def test_roles(self): - try: - module = docutils.parsers.rst.languages.get_language( - self.language) - if not module: - raise ImportError - module.roles - except ImportError: - self.fail('No docutils.parsers.rst.languages.%s module.' - % self.language) - except AttributeError: - self.fail('No "roles" mapping in docutils.parsers.rst.languages.' - '%s module.' % self.language) - failures = [] - for d in module.roles.values(): - try: - method = roles._role_registry[d] - #if not method: - # failures.append('"%s": unknown role' % d) - except KeyError, error: - failures.append('"%s": %s' % (d, error)) - inverted = self._invert(module.roles) - canonical = roles._role_registry.keys() - canonical.sort() - canonical.remove('restructuredtext-unimplemented-role') - for name in canonical: - if not inverted.has_key(name): - failures.append('"%s": translation missing' % name) - if failures: - text = ('Module docutils.parsers.rst.languages.%s:\n %s' - % (self.language, '\n '.join(failures))) - if type(text) == UnicodeType: - text = text.encode('raw_unicode_escape') - self.fail(text) - - -languages_to_test = [] - -def suite(): - s = LanguageTestSuite(languages_to_test) - s.generateTests() - return s - -def get_language_arguments(): - while len(sys.argv) > 1: - last = sys.argv[-1] - if last.startswith('-'): - break - languages_to_test.append(last) - sys.argv.pop() - languages_to_test.reverse() - - -if __name__ == '__main__': - get_language_arguments() - import unittest - unittest.main(defaultTest='suite') - -# vim: set et ts=4 ai : diff --git a/docutils/test/test_nodes.py b/docutils/test/test_nodes.py deleted file mode 100755 index 5467c5490..000000000 --- a/docutils/test/test_nodes.py +++ /dev/null @@ -1,338 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for nodes.py. -""" - -import unittest -from types import ClassType -import DocutilsTestSupport # must be imported before docutils -from DocutilsTestSupport import nodes, utils - -debug = 0 - - -class TextTests(unittest.TestCase): - - def setUp(self): - self.text = nodes.Text('Line 1.\nLine 2.') - - def test_repr(self): - self.assertEquals(repr(self.text), r"<#text: 'Line 1.\nLine 2.'>") - - def test_str(self): - self.assertEquals(str(self.text), 'Line 1.\nLine 2.') - - def test_astext(self): - self.assertEquals(self.text.astext(), 'Line 1.\nLine 2.') - - def test_pformat(self): - self.assertEquals(self.text.pformat(), 'Line 1.\nLine 2.\n') - - -class ElementTests(unittest.TestCase): - - def test_empty(self): - element = nodes.Element() - self.assertEquals(repr(element), '<Element: >') - self.assertEquals(str(element), '<Element/>') - dom = element.asdom() - self.assertEquals(dom.toxml(), '<Element/>') - dom.unlink() - element['attr'] = '1' - self.assertEquals(repr(element), '<Element: >') - self.assertEquals(str(element), '<Element attr="1"/>') - dom = element.asdom() - self.assertEquals(dom.toxml(), '<Element attr="1"/>') - dom.unlink() - self.assertEquals(element.pformat(), '<Element attr="1">\n') - del element['attr'] - element['mark'] = u'\u2022' - self.assertEquals(repr(element), '<Element: >') - self.assertEquals(str(element), '<Element mark="\\u2022"/>') - dom = element.asdom() - self.assertEquals(dom.toxml(), u'<Element mark="\u2022"/>') - dom.unlink() - - def test_withtext(self): - element = nodes.Element('text\nmore', nodes.Text('text\nmore')) - self.assertEquals(repr(element), r"<Element: <#text: 'text\nmore'>>") - self.assertEquals(str(element), '<Element>text\nmore</Element>') - dom = element.asdom() - self.assertEquals(dom.toxml(), '<Element>text\nmore</Element>') - dom.unlink() - element['attr'] = '1' - self.assertEquals(repr(element), r"<Element: <#text: 'text\nmore'>>") - self.assertEquals(str(element), - '<Element attr="1">text\nmore</Element>') - dom = element.asdom() - self.assertEquals(dom.toxml(), - '<Element attr="1">text\nmore</Element>') - dom.unlink() - self.assertEquals(element.pformat(), - '<Element attr="1">\n text\n more\n') - - def test_clear(self): - element = nodes.Element() - element += nodes.Element() - self.assert_(len(element)) - element.clear() - self.assert_(not len(element)) - - def test_normal_attributes(self): - element = nodes.Element() - self.assert_(not element.has_key('foo')) - self.assertRaises(KeyError, element.__getitem__, 'foo') - element['foo'] = 'sometext' - self.assertEquals(element['foo'], 'sometext') - del element['foo'] - self.assertRaises(KeyError, element.__getitem__, 'foo') - - def test_default_attributes(self): - element = nodes.Element() - self.assertEquals(element['ids'], []) - self.assertEquals(element.non_default_attributes(), {}) - self.assert_(not element.is_not_default('ids')) - self.assert_(element['ids'] is not nodes.Element()['ids']) - element['ids'].append('someid') - self.assertEquals(element['ids'], ['someid']) - self.assertEquals(element.non_default_attributes(), - {'ids': ['someid']}) - self.assert_(element.is_not_default('ids')) - - def test_update_basic_atts(self): - element1 = nodes.Element(ids=['foo', 'bar'], test=['test1']) - element2 = nodes.Element(ids=['baz', 'qux'], test=['test2']) - element1.update_basic_atts(element2) - # 'ids' are appended because 'ids' is a basic attribute. - self.assertEquals(element1['ids'], ['foo', 'bar', 'baz', 'qux']) - # 'test' is not overwritten because it is not a basic attribute. - self.assertEquals(element1['test'], ['test1']) - - def test_replace_self(self): - parent = nodes.Element(ids=['parent']) - child1 = nodes.Element(ids=['child1']) - grandchild = nodes.Element(ids=['grandchild']) - child1 += grandchild - child2 = nodes.Element(ids=['child2']) - twins = [nodes.Element(ids=['twin%s' % i]) for i in (1, 2)] - child2 += twins - child3 = nodes.Element(ids=['child3']) - child4 = nodes.Element(ids=['child4']) - parent += [child1, child2, child3, child4] - self.assertEquals(parent.pformat(), """\ -<Element ids="parent"> - <Element ids="child1"> - <Element ids="grandchild"> - <Element ids="child2"> - <Element ids="twin1"> - <Element ids="twin2"> - <Element ids="child3"> - <Element ids="child4"> -""") - # Replace child1 with the grandchild. - child1.replace_self(child1[0]) - self.assertEquals(parent[0], grandchild) - # Assert that 'ids' have been updated. - self.assertEquals(grandchild['ids'], ['grandchild', 'child1']) - # Replace child2 with its children. - child2.replace_self(child2[:]) - self.assertEquals(parent[1:3], twins) - # Assert that 'ids' have been propagated to first child. - self.assertEquals(twins[0]['ids'], ['twin1', 'child2']) - self.assertEquals(twins[1]['ids'], ['twin2']) - # Replace child3 with new child. - newchild = nodes.Element(ids=['newchild']) - child3.replace_self(newchild) - self.assertEquals(parent[3], newchild) - self.assertEquals(newchild['ids'], ['newchild', 'child3']) - # Crazy but possible case: Substitute child4 for itself. - child4.replace_self(child4) - # Make sure the 'child4' ID hasn't been duplicated. - self.assertEquals(child4['ids'], ['child4']) - self.assertEquals(len(parent), 5) - - -class MiscTests(unittest.TestCase): - - def test_node_class_names(self): - node_class_names = [] - for x in dir(nodes): - c = getattr(nodes, x) - if isinstance(c, ClassType) and issubclass(c, nodes.Node) \ - and len(c.__bases__) > 1: - node_class_names.append(x) - node_class_names.sort() - nodes.node_class_names.sort() - self.assertEquals(node_class_names, nodes.node_class_names) - - ids = [('a', 'a'), ('A', 'a'), ('', ''), ('a b \n c', 'a-b-c'), - ('a.b.c', 'a-b-c'), (' - a - b - c - ', 'a-b-c'), (' - ', ''), - (u'\u2020\u2066', ''), (u'a \xa7 b \u2020 c', 'a-b-c'), - ('1', ''), ('1abc', 'abc')] - - def test_make_id(self): - for input, output in self.ids: - normed = nodes.make_id(input) - self.assertEquals(normed, output) - - def test_traverse(self): - e = nodes.Element() - e += nodes.Element() - e[0] += nodes.Element() - e[0] += nodes.TextElement() - e[0][1] += nodes.Text('some text') - e += nodes.Element() - e += nodes.Element() - self.assertEquals(list(e.traverse()), - [e, e[0], e[0][0], e[0][1], e[0][1][0], e[1], e[2]]) - self.assertEquals(list(e.traverse(include_self=0)), - [e[0], e[0][0], e[0][1], e[0][1][0], e[1], e[2]]) - self.assertEquals(list(e.traverse(descend=0)), - [e]) - self.assertEquals(list(e[0].traverse(descend=0, ascend=1)), - [e[0], e[1], e[2]]) - self.assertEquals(list(e[0][0].traverse(descend=0, ascend=1)), - [e[0][0], e[0][1], e[1], e[2]]) - self.assertEquals(list(e[0][0].traverse(descend=0, siblings=1)), - [e[0][0], e[0][1]]) - self.testlist = e[0:2] - self.assertEquals(list(e.traverse(condition=self.not_in_testlist)), - [e, e[0][0], e[0][1], e[0][1][0], e[2]]) - # Return siblings despite siblings=0 because ascend is true. - self.assertEquals(list(e[1].traverse(ascend=1, siblings=0)), - [e[1], e[2]]) - self.assertEquals(list(e[0].traverse()), - [e[0], e[0][0], e[0][1], e[0][1][0]]) - self.testlist = [e[0][0], e[0][1]] - self.assertEquals(list(e[0].traverse(condition=self.not_in_testlist)), - [e[0], e[0][1][0]]) - self.testlist.append(e[0][1][0]) - self.assertEquals(list(e[0].traverse(condition=self.not_in_testlist)), - [e[0]]) - self.assertEquals(list(e.traverse(nodes.TextElement)), [e[0][1]]) - - def test_next_node(self): - e = nodes.Element() - e += nodes.Element() - e[0] += nodes.Element() - e[0] += nodes.TextElement() - e[0][1] += nodes.Text('some text') - e += nodes.Element() - e += nodes.Element() - self.testlist = [e[0], e[0][1], e[1]] - compare = [(e, e[0][0]), - (e[0], e[0][0]), - (e[0][0], e[0][1][0]), - (e[0][1], e[0][1][0]), - (e[0][1][0], e[2]), - (e[1], e[2]), - (e[2], None)] - for node, next_node in compare: - self.assertEquals(node.next_node(self.not_in_testlist, ascend=1), - next_node) - self.assertEquals(e[0][0].next_node(ascend=1), e[0][1]) - self.assertEquals(e[2].next_node(), None) - - def not_in_testlist(self, x): - return x not in self.testlist - - def test_copy(self): - grandchild = nodes.Text('rawsource') - child = nodes.emphasis('rawsource', grandchild, att='child') - e = nodes.Element('rawsource', child, att='e') - # Shallow copy: - e_copy = e.copy() - self.assert_(e is not e_copy) - # Internal attributes (like `rawsource`) are not copied. - self.assertEquals(e.rawsource, 'rawsource') - self.assertEquals(e_copy.rawsource, '') - self.assertEquals(e_copy['att'], 'e') - # Children are not copied. - self.assertEquals(len(e_copy), 0) - # Deep copy: - e_deepcopy = e.deepcopy() - self.assertEquals(e_deepcopy.rawsource, '') - self.assertEquals(e_deepcopy['att'], 'e') - # Children are copied recursively. - self.assertEquals(e_deepcopy[0][0], grandchild) - self.assert_(e_deepcopy[0][0] is not grandchild) - self.assertEquals(e_deepcopy[0]['att'], 'child') - - -class TreeCopyVisitorTests(unittest.TestCase): - - def setUp(self): - document = utils.new_document('test data') - document += nodes.paragraph('', 'Paragraph 1.') - blist = nodes.bullet_list() - for i in range(1, 6): - item = nodes.list_item() - for j in range(1, 4): - item += nodes.paragraph('', 'Item %s, paragraph %s.' % (i, j)) - blist += item - document += blist - self.document = document - - def compare_trees(self, one, two): - self.assertEquals(one.__class__, two.__class__) - self.assertNotEquals(id(one), id(two)) - self.assertEquals(len(one.children), len(two.children)) - for i in range(len(one.children)): - self.compare_trees(one.children[i], two.children[i]) - - def test_copy_whole(self): - visitor = nodes.TreeCopyVisitor(self.document) - self.document.walkabout(visitor) - newtree = visitor.get_tree_copy() - self.assertEquals(self.document.pformat(), newtree.pformat()) - self.compare_trees(self.document, newtree) - - -class MiscFunctionTests(unittest.TestCase): - - names = [('a', 'a'), ('A', 'a'), ('A a A', 'a a a'), - ('A a A a', 'a a a a'), - (' AaA\n\r\naAa\tAaA\t\t', 'aaa aaa aaa')] - - def test_normalize_name(self): - for input, output in self.names: - normed = nodes.fully_normalize_name(input) - self.assertEquals(normed, output) - - def test_set_id_default(self): - # Default prefixes. - document = utils.new_document('test') - # From name. - element = nodes.Element(names=['test']) - document.set_id(element) - self.assertEquals(element['ids'], ['test']) - # Auto-generated. - element = nodes.Element() - document.set_id(element) - self.assertEquals(element['ids'], ['id1']) - - def test_set_id_custom(self): - # Custom prefixes. - document = utils.new_document('test') - # Change settings. - document.settings.id_prefix = 'prefix' - document.settings.auto_id_prefix = 'auto' - # From name. - element = nodes.Element(names=['test']) - document.set_id(element) - self.assertEquals(element['ids'], ['prefixtest']) - # Auto-generated. - element = nodes.Element() - document.set_id(element) - self.assertEquals(element['ids'], ['prefixauto1']) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_parsers/__init__.py b/docutils/test/test_parsers/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_parsers/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_parsers/test_rst/__init__.py b/docutils/test/test_parsers/test_rst/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_parsers/test_rst/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_parsers/test_rst/includes/include9.txt b/docutils/test/test_parsers/test_rst/includes/include9.txt deleted file mode 100644 index 9164722b3..000000000 --- a/docutils/test/test_parsers/test_rst/includes/include9.txt +++ /dev/null @@ -1,3 +0,0 @@ -In ../includes/include9.txt. - -.. include:: ../test_directives/include2.txt diff --git a/docutils/test/test_parsers/test_rst/test_SimpleTableParser.py b/docutils/test/test_parsers/test_rst/test_SimpleTableParser.py deleted file mode 100755 index aee037206..000000000 --- a/docutils/test/test_parsers/test_rst/test_SimpleTableParser.py +++ /dev/null @@ -1,123 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.SimpleTableParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['simple_tables'] = [ -["""\ -============ ============ -A table with two columns. -============ ============ -""", -([12, 12], - [], - [[[0, 0, 1, ['A table with']], - [0, 0, 1, ['two columns.']]]])], -["""\ -============ ============ -A table with two columns -and two rows. -============ ============ -""", -([12, 12], - [], - [[[0, 0, 1, ['A table with']], - [0, 0, 1, ['two columns']]], - [[0, 0, 2, ['and']], - [0, 0, 2, ['two rows.']]]])], -["""\ -========== =========== -A table with four rows, ------------------------ -and two columns. -First and last rows -contain column spans. -======================= -""", -([10, 11], - [], - [[[0, 1, 1, ['A table with four rows,']]], - [[0, 0, 3, ['and two']], - [0, 0, 3, ['columns.']]], - [[0, 0, 4, ['First and']], - [0, 0, 4, ['last rows']]], - [[0, 1, 5, ['contain column spans.']]]])], -["""\ -======= ===== ====== -A bad table cell 2 -cell 3 cell 4 -============ ====== -""", -'TableMarkupError: Text in column margin at line offset 1.'], -["""\ -=========== ================ -A table with two header rows, ------------------------------ -the first with a span. -=========== ================ -Two body rows, -the second with a span. -============================= -""", -([11, 16], - [[[0, 1, 1, ['A table with two header rows,']]], - [[0, 0, 3, ['the first']], - [0, 0, 3, ['with a span.']]]], - [[[0, 0, 5, ['Two body']], - [0, 0, 5, ['rows,']]], - [[0, 1, 6, ['the second with a span.']]]])], -["""\ -============ ============= -A table with two head/body -============ ============= -row separators. -============ ============= -That's bad. -============ ============= -""", -'TableMarkupError: Multiple head/body row separators in table ' -'(at line offset 2 and 4); only one allowed.'], -["""\ -============ ============ -============ ============ -""", -([12, 12], - [], - [[[0, 0, 1, []], - [0, 0, 1, []]]])], -# ["""\ -# ============== ========== -# Table with row separators -# ============== ========== -# and blank -# -------------- ---------- -# entries -# -------------- ---------- -# in first -# -------------- ---------- -# columns. -# ============== ========== -# """, -# ''] -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_TableParser.py b/docutils/test/test_parsers/test_rst/test_TableParser.py deleted file mode 100755 index 84e4b7563..000000000 --- a/docutils/test/test_parsers/test_rst/test_TableParser.py +++ /dev/null @@ -1,207 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.GridTableParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['grid_tables'] = [ -["""\ -+-------------------------------------+ -| A table with one cell and one line. | -+-------------------------------------+ -""", -[(0, 0, 2, 38, ['A table with one cell and one line.'])], -([37], - [], - [[(0, 0, 1, ['A table with one cell and one line.'])]])], -["""\ -+--------------+--------------+ -| A table with | two columns. | -+--------------+--------------+ -""", -[(0, 0, 2, 15, ['A table with']), - (0, 15, 2, 30, ['two columns.'])], -([14, 14], - [], - [[(0, 0, 1, ['A table with']), - (0, 0, 1, ['two columns.'])]])], -["""\ -+--------------+-------------+ -| A table with | two columns | -+--------------+-------------+ -| and | two rows. | -+--------------+-------------+ -""", -[(0, 0, 2, 15, ['A table with']), - (0, 15, 2, 29, ['two columns']), - (2, 0, 4, 15, ['and']), - (2, 15, 4, 29, ['two rows.'])], -([14, 13], - [], - [[(0, 0, 1, ['A table with']), - (0, 0, 1, ['two columns'])], - [(0, 0, 3, ['and']), - (0, 0, 3, ['two rows.'])]])], -["""\ -+--------------------------+ -| A table with three rows, | -+------------+-------------+ -| and two | columns. | -+------------+-------------+ -| First and last rows | -| contain column spans. | -+--------------------------+ -""", -[(0, 0, 2, 27, ['A table with three rows,']), - (2, 0, 4, 13, ['and two']), - (2, 13, 4, 27, ['columns.']), - (4, 0, 7, 27, ['First and last rows', 'contain column spans.'])], -([12, 13], - [], - [[(0, 1, 1, ['A table with three rows,']), - None], - [(0, 0, 3, ['and two']), - (0, 0, 3, ['columns.'])], - [(0, 1, 5, ['First and last rows', 'contain column spans.']), - None]])], -["""\ -+------------+-------------+---------------+ -| A table | two rows in | and row spans | -| with three +-------------+ to left and | -| columns, | the middle, | right. | -+------------+-------------+---------------+ -""", -[(0, 0, 4, 13, ['A table', 'with three', 'columns,']), - (0, 13, 2, 27, ['two rows in']), - (0, 27, 4, 43, ['and row spans', 'to left and', 'right.']), - (2, 13, 4, 27, ['the middle,'])], -([12, 13, 15], - [], - [[(1, 0, 1, ['A table', 'with three', 'columns,']), - (0, 0, 1, ['two rows in']), - (1, 0, 1, ['and row spans', 'to left and', 'right.'])], - [None, - (0, 0, 3, ['the middle,']), - None]])], -["""\ -+------------+-------------+---------------+ -| A table | | two rows in | and funny | -| with 3 +--+-------------+-+ stuff. | -| columns, | the middle, | | | -+------------+-------------+---------------+ -""", -[(0, 0, 4, 13, ['A table |', 'with 3 +--', 'columns,']), - (0, 13, 2, 27, ['two rows in']), - (0, 27, 4, 43, [' and funny', '-+ stuff.', ' |']), - (2, 13, 4, 27, ['the middle,'])], -([12, 13, 15], - [], - [[(1, 0, 1, ['A table |', 'with 3 +--', 'columns,']), - (0, 0, 1, ['two rows in']), - (1, 0, 1, [' and funny', '-+ stuff.', ' |'])], - [None, - (0, 0, 3, ['the middle,']), - None]])], -["""\ -+-----------+-------------------------+ -| W/NW cell | N/NE cell | -| +-------------+-----------+ -| | Middle cell | E/SE cell | -+-----------+-------------+ | -| S/SE cell | | -+-------------------------+-----------+ -""", -[(0, 0, 4, 12, ['W/NW cell', '', '']), - (0, 12, 2, 38, ['N/NE cell']), - (2, 12, 4, 26, ['Middle cell']), - (2, 26, 6, 38, ['E/SE cell', '', '']), - (4, 0, 6, 26, ['S/SE cell'])], -([11, 13, 11], - [], - [[(1, 0, 1, ['W/NW cell', '', '']), - (0, 1, 1, ['N/NE cell']), - None], - [None, - (0, 0, 3, ['Middle cell']), - (1, 0, 3, ['E/SE cell', '', ''])], - [(0, 1, 5, ['S/SE cell']), - None, - None]])], -["""\ -+--------------+-------------+ -| A bad table. | | -+--------------+ | -| Cells must be rectangles. | -+----------------------------+ -""", -'TableMarkupError: Malformed table; parse incomplete.', -'TableMarkupError: Malformed table; parse incomplete.'], -["""\ -+-------------------------------+ -| A table with two header rows, | -+------------+------------------+ -| the first | with a span. | -+============+==================+ -| Two body | rows, | -+------------+------------------+ -| the second with a span. | -+-------------------------------+ -""", -[(0, 0, 2, 32, ['A table with two header rows,']), - (2, 0, 4, 13, ['the first']), - (2, 13, 4, 32, ['with a span.']), - (4, 0, 6, 13, ['Two body']), - (4, 13, 6, 32, ['rows,']), - (6, 0, 8, 32, ['the second with a span.'])], -([12, 18], - [[(0, 1, 1, ['A table with two header rows,']), - None], - [(0, 0, 3, ['the first']), - (0, 0, 3, ['with a span.'])]], - [[(0, 0, 5, ['Two body']), - (0, 0, 5, ['rows,'])], - [(0, 1, 7, ['the second with a span.']), - None]])], -["""\ -+-------------------------------+ -| A table with two head/body | -+=============+=================+ -| row | separators. | -+=============+=================+ -| That's bad. | | -+-------------+-----------------+ -""", -'TableMarkupError: Multiple head/body row separators in table ' -'(at line offset 2 and 4); only one allowed.', -'TableMarkupError: Multiple head/body row separators in table ' -'(at line offset 2 and 4); only one allowed.'], -["""\ -+-------------------------------------+ -| | -+-------------------------------------+ -""", -[(0, 0, 2, 38, [''])], -([37], - [], - [[(0, 0, 1, [''])]])], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_block_quotes.py b/docutils/test/test_parsers/test_rst/test_block_quotes.py deleted file mode 100755 index dd7561723..000000000 --- a/docutils/test/test_parsers/test_rst/test_block_quotes.py +++ /dev/null @@ -1,273 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['block_quotes'] = [ -["""\ -Line 1. -Line 2. - - Indented. -""", -"""\ -<document source="test data"> - <paragraph> - Line 1. - Line 2. - <block_quote> - <paragraph> - Indented. -"""], -["""\ -Line 1. -Line 2. - - Indented 1. - - Indented 2. -""", -"""\ -<document source="test data"> - <paragraph> - Line 1. - Line 2. - <block_quote> - <paragraph> - Indented 1. - <block_quote> - <paragraph> - Indented 2. -"""], -["""\ -Line 1. -Line 2. - Unexpectedly indented. -""", -"""\ -<document source="test data"> - <paragraph> - Line 1. - Line 2. - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Unexpected indentation. - <block_quote> - <paragraph> - Unexpectedly indented. -"""], -["""\ -Line 1. -Line 2. - - Indented. -no blank line -""", -"""\ -<document source="test data"> - <paragraph> - Line 1. - Line 2. - <block_quote> - <paragraph> - Indented. - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Block quote ends without a blank line; unexpected unindent. - <paragraph> - no blank line -"""], -["""\ -Here is a paragraph. - - Indent 8 spaces. - - Indent 4 spaces. - -Is this correct? Should it generate a warning? -Yes, it is correct, no warning necessary. -""", -"""\ -<document source="test data"> - <paragraph> - Here is a paragraph. - <block_quote> - <block_quote> - <paragraph> - Indent 8 spaces. - <paragraph> - Indent 4 spaces. - <paragraph> - Is this correct? Should it generate a warning? - Yes, it is correct, no warning necessary. -"""], -["""\ -Paragraph. - - Block quote. - - -- Attribution - -Paragraph. - - Block quote. - - --Attribution -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <block_quote> - <paragraph> - Block quote. - <attribution> - Attribution - <paragraph> - Paragraph. - <block_quote> - <paragraph> - Block quote. - <attribution> - Attribution -"""], -[u"""\ -Alternative: true em-dash. - - Block quote. - - \u2014 Attribution - -Alternative: three hyphens. - - Block quote. - - --- Attribution -""", -"""\ -<document source="test data"> - <paragraph> - Alternative: true em-dash. - <block_quote> - <paragraph> - Block quote. - <attribution> - Attribution - <paragraph> - Alternative: three hyphens. - <block_quote> - <paragraph> - Block quote. - <attribution> - Attribution -"""], -["""\ -Paragraph. - - Block quote. - - -- Attribution line one - and line two - -Paragraph. - - Block quote. - - -- Attribution line one - and line two - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <block_quote> - <paragraph> - Block quote. - <attribution> - Attribution line one - and line two - <paragraph> - Paragraph. - <block_quote> - <paragraph> - Block quote. - <attribution> - Attribution line one - and line two - <paragraph> - Paragraph. -"""], -["""\ -Paragraph. - - -- Not an attribution - -Paragraph. - - Block quote. - - \-- Not an attribution - -Paragraph. - - Block quote. - - -- Not an attribution line one - and line two - and line three -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <block_quote> - <paragraph> - -- Not an attribution - <paragraph> - Paragraph. - <block_quote> - <paragraph> - Block quote. - <paragraph> - -- Not an attribution - <paragraph> - Paragraph. - <block_quote> - <paragraph> - Block quote. - <definition_list> - <definition_list_item> - <term> - -- Not an attribution line one - <definition> - <definition_list> - <definition_list_item> - <term> - and line two - <definition> - <paragraph> - and line three -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_bullet_lists.py b/docutils/test/test_parsers/test_rst/test_bullet_lists.py deleted file mode 100755 index 12ede6cf1..000000000 --- a/docutils/test/test_parsers/test_rst/test_bullet_lists.py +++ /dev/null @@ -1,181 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['bullet_lists'] = [ -["""\ -- item -""", -"""\ -<document source="test data"> - <bullet_list bullet="-"> - <list_item> - <paragraph> - item -"""], -["""\ -* item 1 - -* item 2 -""", -"""\ -<document source="test data"> - <bullet_list bullet="*"> - <list_item> - <paragraph> - item 1 - <list_item> - <paragraph> - item 2 -"""], -["""\ -No blank line between: - -+ item 1 -+ item 2 -""", -"""\ -<document source="test data"> - <paragraph> - No blank line between: - <bullet_list bullet="+"> - <list_item> - <paragraph> - item 1 - <list_item> - <paragraph> - item 2 -"""], -["""\ -- item 1, para 1. - - item 1, para 2. - -- item 2 -""", -"""\ -<document source="test data"> - <bullet_list bullet="-"> - <list_item> - <paragraph> - item 1, para 1. - <paragraph> - item 1, para 2. - <list_item> - <paragraph> - item 2 -"""], -["""\ -- item 1, line 1 - item 1, line 2 -- item 2 -""", -"""\ -<document source="test data"> - <bullet_list bullet="-"> - <list_item> - <paragraph> - item 1, line 1 - item 1, line 2 - <list_item> - <paragraph> - item 2 -"""], -["""\ -Different bullets: - -- item 1 - -+ item 2 - -* item 3 -- item 4 -""", -"""\ -<document source="test data"> - <paragraph> - Different bullets: - <bullet_list bullet="-"> - <list_item> - <paragraph> - item 1 - <bullet_list bullet="+"> - <list_item> - <paragraph> - item 2 - <bullet_list bullet="*"> - <list_item> - <paragraph> - item 3 - <system_message level="2" line="8" source="test data" type="WARNING"> - <paragraph> - Bullet list ends without a blank line; unexpected unindent. - <bullet_list bullet="-"> - <list_item> - <paragraph> - item 4 -"""], -["""\ -- item -no blank line -""", -"""\ -<document source="test data"> - <bullet_list bullet="-"> - <list_item> - <paragraph> - item - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Bullet list ends without a blank line; unexpected unindent. - <paragraph> - no blank line -"""], -["""\ -- - -empty item above -""", -"""\ -<document source="test data"> - <bullet_list bullet="-"> - <list_item> - <paragraph> - empty item above -"""], -["""\ -- -empty item above, no blank line -""", -"""\ -<document source="test data"> - <bullet_list bullet="-"> - <list_item> - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Bullet list ends without a blank line; unexpected unindent. - <paragraph> - empty item above, no blank line -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_citations.py b/docutils/test/test_parsers/test_rst/test_citations.py deleted file mode 100755 index c50e28e0b..000000000 --- a/docutils/test/test_parsers/test_rst/test_citations.py +++ /dev/null @@ -1,139 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['citations'] = [ -["""\ -.. [citation] This is a citation. -""", -"""\ -<document source="test data"> - <citation ids="citation" names="citation"> - <label> - citation - <paragraph> - This is a citation. -"""], -["""\ -.. [citation1234] This is a citation with year. -""", -"""\ -<document source="test data"> - <citation ids="citation1234" names="citation1234"> - <label> - citation1234 - <paragraph> - This is a citation with year. -"""], -["""\ -.. [citation] This is a citation - on multiple lines. -""", -"""\ -<document source="test data"> - <citation ids="citation" names="citation"> - <label> - citation - <paragraph> - This is a citation - on multiple lines. -"""], -["""\ -.. [citation1] This is a citation - on multiple lines with more space. - -.. [citation2] This is a citation - on multiple lines with less space. -""", -"""\ -<document source="test data"> - <citation ids="citation1" names="citation1"> - <label> - citation1 - <paragraph> - This is a citation - on multiple lines with more space. - <citation ids="citation2" names="citation2"> - <label> - citation2 - <paragraph> - This is a citation - on multiple lines with less space. -"""], -["""\ -.. [citation] - This is a citation on multiple lines - whose block starts on line 2. -""", -"""\ -<document source="test data"> - <citation ids="citation" names="citation"> - <label> - citation - <paragraph> - This is a citation on multiple lines - whose block starts on line 2. -"""], -["""\ -.. [citation] - -That was an empty citation. -""", -"""\ -<document source="test data"> - <citation ids="citation" names="citation"> - <label> - citation - <paragraph> - That was an empty citation. -"""], -["""\ -.. [citation] -No blank line. -""", -"""\ -<document source="test data"> - <citation ids="citation" names="citation"> - <label> - citation - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - No blank line. -"""], -["""\ -.. [citation label with spaces] this isn't a citation - -.. [*citationlabelwithmarkup*] this isn't a citation -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - [citation label with spaces] this isn't a citation - <comment xml:space="preserve"> - [*citationlabelwithmarkup*] this isn't a citation -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_comments.py b/docutils/test/test_parsers/test_rst/test_comments.py deleted file mode 100755 index a90135ec5..000000000 --- a/docutils/test/test_parsers/test_rst/test_comments.py +++ /dev/null @@ -1,319 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['comments'] = [ -["""\ -.. A comment - -Paragraph. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment - <paragraph> - Paragraph. -"""], -["""\ -.. A comment - block. - -Paragraph. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment - block. - <paragraph> - Paragraph. -"""], -["""\ -.. - A comment consisting of multiple lines - starting on the line after the - explicit markup start. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment consisting of multiple lines - starting on the line after the - explicit markup start. -"""], -["""\ -.. A comment. -.. Another. - -Paragraph. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment. - <comment xml:space="preserve"> - Another. - <paragraph> - Paragraph. -"""], -["""\ -.. A comment -no blank line - -Paragraph. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - no blank line - <paragraph> - Paragraph. -"""], -["""\ -.. A comment. -.. Another. -no blank line - -Paragraph. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment. - <comment xml:space="preserve"> - Another. - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - no blank line - <paragraph> - Paragraph. -"""], -["""\ -.. A comment:: - -Paragraph. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment:: - <paragraph> - Paragraph. -"""], -["""\ -.. - comment:: - -The extra newline before the comment text prevents -the parser from recognizing a directive. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - comment:: - <paragraph> - The extra newline before the comment text prevents - the parser from recognizing a directive. -"""], -["""\ -.. - _comment: http://example.org - -The extra newline before the comment text prevents -the parser from recognizing a hyperlink target. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - _comment: http://example.org - <paragraph> - The extra newline before the comment text prevents - the parser from recognizing a hyperlink target. -"""], -["""\ -.. - [comment] Not a citation. - -The extra newline before the comment text prevents -the parser from recognizing a citation. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - [comment] Not a citation. - <paragraph> - The extra newline before the comment text prevents - the parser from recognizing a citation. -"""], -["""\ -.. - |comment| image:: bogus.png - -The extra newline before the comment text prevents -the parser from recognizing a substitution definition. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - |comment| image:: bogus.png - <paragraph> - The extra newline before the comment text prevents - the parser from recognizing a substitution definition. -"""], -["""\ -.. Next is an empty comment, which serves to end this comment and - prevents the following block quote being swallowed up. - -.. - - A block quote. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - Next is an empty comment, which serves to end this comment and - prevents the following block quote being swallowed up. - <comment xml:space="preserve"> - <block_quote> - <paragraph> - A block quote. -"""], -["""\ -term 1 - definition 1 - - .. a comment - -term 2 - definition 2 -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term 1 - <definition> - <paragraph> - definition 1 - <comment xml:space="preserve"> - a comment - <definition_list_item> - <term> - term 2 - <definition> - <paragraph> - definition 2 -"""], -["""\ -term 1 - definition 1 - -.. a comment - -term 2 - definition 2 -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term 1 - <definition> - <paragraph> - definition 1 - <comment xml:space="preserve"> - a comment - <definition_list> - <definition_list_item> - <term> - term 2 - <definition> - <paragraph> - definition 2 -"""], -["""\ -+ bullet paragraph 1 - - bullet paragraph 2 - - .. comment between bullet paragraphs 2 and 3 - - bullet paragraph 3 -""", -"""\ -<document source="test data"> - <bullet_list bullet="+"> - <list_item> - <paragraph> - bullet paragraph 1 - <paragraph> - bullet paragraph 2 - <comment xml:space="preserve"> - comment between bullet paragraphs 2 and 3 - <paragraph> - bullet paragraph 3 -"""], -["""\ -+ bullet paragraph 1 - - .. comment between bullet paragraphs 1 (leader) and 2 - - bullet paragraph 2 -""", -"""\ -<document source="test data"> - <bullet_list bullet="+"> - <list_item> - <paragraph> - bullet paragraph 1 - <comment xml:space="preserve"> - comment between bullet paragraphs 1 (leader) and 2 - <paragraph> - bullet paragraph 2 -"""], -["""\ -+ bullet - - .. trailing comment -""", -"""\ -<document source="test data"> - <bullet_list bullet="+"> - <list_item> - <paragraph> - bullet - <comment xml:space="preserve"> - trailing comment -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_definition_lists.py b/docutils/test/test_parsers/test_rst/test_definition_lists.py deleted file mode 100755 index d9f3211c0..000000000 --- a/docutils/test/test_parsers/test_rst/test_definition_lists.py +++ /dev/null @@ -1,395 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['definition_lists'] = [ -["""\ -term - definition -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term - <definition> - <paragraph> - definition -"""], -["""\ -term - definition - -paragraph -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term - <definition> - <paragraph> - definition - <paragraph> - paragraph -"""], -["""\ -term - definition -no blank line -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term - <definition> - <paragraph> - definition - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Definition list ends without a blank line; unexpected unindent. - <paragraph> - no blank line -"""], -["""\ -A paragraph:: - A literal block without a blank line first? -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - A paragraph:: - <definition> - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - Blank line missing before literal block (after the "::")? Interpreted as a definition list item. - <paragraph> - A literal block without a blank line first? -"""], -["""\ -this is not a term; -a term may only be one line long - this is not a definition -""", -"""\ -<document source="test data"> - <paragraph> - this is not a term; - a term may only be one line long - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Unexpected indentation. - <block_quote> - <paragraph> - this is not a definition -"""], -["""\ -term 1 - definition 1 - -term 2 - definition 2 -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term 1 - <definition> - <paragraph> - definition 1 - <definition_list_item> - <term> - term 2 - <definition> - <paragraph> - definition 2 -"""], -["""\ -term 1 - definition 1 (no blank line below) -term 2 - definition 2 -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term 1 - <definition> - <paragraph> - definition 1 (no blank line below) - <definition_list_item> - <term> - term 2 - <definition> - <paragraph> - definition 2 -"""], -["""\ -term 1 - definition 1 (no blank line below) -term 2 - definition 2 -No blank line after the definition list. -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term 1 - <definition> - <paragraph> - definition 1 (no blank line below) - <definition_list_item> - <term> - term 2 - <definition> - <paragraph> - definition 2 - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Definition list ends without a blank line; unexpected unindent. - <paragraph> - No blank line after the definition list. -"""], -["""\ -term 1 - definition 1 - - term 1a - definition 1a - - term 1b - definition 1b - -term 2 - definition 2 - -paragraph -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - term 1 - <definition> - <paragraph> - definition 1 - <definition_list> - <definition_list_item> - <term> - term 1a - <definition> - <paragraph> - definition 1a - <definition_list_item> - <term> - term 1b - <definition> - <paragraph> - definition 1b - <definition_list_item> - <term> - term 2 - <definition> - <paragraph> - definition 2 - <paragraph> - paragraph -"""], -["""\ -Term : classifier - The ' : ' indicates a classifier in - definition list item terms only. -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - Term - <classifier> - classifier - <definition> - <paragraph> - The ' : ' indicates a classifier in - definition list item terms only. -"""], -["""\ -Term: not a classifier - Because there's no space before the colon. -Term :not a classifier - Because there's no space after the colon. -Term \: not a classifier - Because the colon is escaped. -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - Term: not a classifier - <definition> - <paragraph> - Because there's no space before the colon. - <definition_list_item> - <term> - Term :not a classifier - <definition> - <paragraph> - Because there's no space after the colon. - <definition_list_item> - <term> - Term : not a classifier - <definition> - <paragraph> - Because the colon is escaped. -"""], -["""\ -``Term : not a classifier`` - Because the ' : ' is inside an inline literal. -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - <literal> - Term : not a classifier - <definition> - <paragraph> - Because the ' : ' is inside an inline literal. -"""], -["""\ -Term `with *inline ``text **errors : classifier `with *errors ``too - Definition `with *inline ``text **markup errors. -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - Term \n\ - <problematic ids="id2" refid="id1"> - ` - with \n\ - <problematic ids="id4" refid="id3"> - * - inline \n\ - <problematic ids="id6" refid="id5"> - `` - text \n\ - <problematic ids="id8" refid="id7"> - ** - errors - <classifier> - classifier \n\ - <problematic ids="id10" refid="id9"> - ` - with \n\ - <problematic ids="id12" refid="id11"> - * - errors \n\ - <problematic ids="id14" refid="id13"> - `` - too - <definition> - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline interpreted text or phrase reference start-string without end-string. - <system_message backrefs="id4" ids="id3" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message backrefs="id6" ids="id5" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. - <system_message backrefs="id8" ids="id7" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. - <system_message backrefs="id10" ids="id9" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline interpreted text or phrase reference start-string without end-string. - <system_message backrefs="id12" ids="id11" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message backrefs="id14" ids="id13" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. - <paragraph> - Definition \n\ - <problematic ids="id16" refid="id15"> - ` - with \n\ - <problematic ids="id18" refid="id17"> - * - inline \n\ - <problematic ids="id20" refid="id19"> - `` - text \n\ - <problematic ids="id22" refid="id21"> - ** - markup errors. - <system_message backrefs="id16" ids="id15" level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Inline interpreted text or phrase reference start-string without end-string. - <system_message backrefs="id18" ids="id17" level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message backrefs="id20" ids="id19" level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. - <system_message backrefs="id22" ids="id21" level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. -"""], -["""\ -Term : classifier one : classifier two - Definition -""", -"""\ -<document source="test data"> - <definition_list> - <definition_list_item> - <term> - Term - <classifier> - classifier one - <classifier> - classifier two - <definition> - <paragraph> - Definition -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/__init__.py b/docutils/test/test_parsers/test_rst/test_directives/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_parsers/test_rst/test_directives/empty.txt b/docutils/test/test_parsers/test_rst/test_directives/empty.txt deleted file mode 100644 index e69de29bb..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/empty.txt +++ /dev/null diff --git a/docutils/test/test_parsers/test_rst/test_directives/include 11.txt b/docutils/test/test_parsers/test_rst/test_directives/include 11.txt deleted file mode 100644 index 7b57bd29e..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/include 11.txt +++ /dev/null @@ -1 +0,0 @@ -some text diff --git a/docutils/test/test_parsers/test_rst/test_directives/include1.txt b/docutils/test/test_parsers/test_rst/test_directives/include1.txt deleted file mode 100644 index 82f605320..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/include1.txt +++ /dev/null @@ -1,4 +0,0 @@ -Inclusion 1 ------------ - -This file is used by ``test_include.py``. diff --git a/docutils/test/test_parsers/test_rst/test_directives/include10.txt b/docutils/test/test_parsers/test_rst/test_directives/include10.txt deleted file mode 100644 index 8eb5b1720..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/include10.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. |bad| unicode:: 0xFFFFFFFFF - -hi ------ - -hi ------ diff --git a/docutils/test/test_parsers/test_rst/test_directives/include2.txt b/docutils/test/test_parsers/test_rst/test_directives/include2.txt deleted file mode 100644 index 3149a7bf6..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/include2.txt +++ /dev/null @@ -1,5 +0,0 @@ -Here are some paragraphs -that can appear at any level. - -This file (include2.txt) is used by -``test_include.py``. diff --git a/docutils/test/test_parsers/test_rst/test_directives/include3.txt b/docutils/test/test_parsers/test_rst/test_directives/include3.txt deleted file mode 100644 index 9996a4452..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/include3.txt +++ /dev/null @@ -1,3 +0,0 @@ -In include3.txt - -.. include:: includes/include4.txt diff --git a/docutils/test/test_parsers/test_rst/test_directives/include8.txt b/docutils/test/test_parsers/test_rst/test_directives/include8.txt deleted file mode 100644 index e7fc57a3d..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/include8.txt +++ /dev/null @@ -1,3 +0,0 @@ -In include8.txt - -.. include:: ../includes/include9.txt diff --git a/docutils/test/test_parsers/test_rst/test_directives/includes/include4.txt b/docutils/test/test_parsers/test_rst/test_directives/includes/include4.txt deleted file mode 100644 index 384772a77..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/includes/include4.txt +++ /dev/null @@ -1,3 +0,0 @@ -In includes/include4.txt - -.. include:: include5.txt diff --git a/docutils/test/test_parsers/test_rst/test_directives/includes/include5.txt b/docutils/test/test_parsers/test_rst/test_directives/includes/include5.txt deleted file mode 100644 index 64b3e3aa2..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/includes/include5.txt +++ /dev/null @@ -1,3 +0,0 @@ -In includes/include5.txt - -.. include:: more/include6.txt diff --git a/docutils/test/test_parsers/test_rst/test_directives/includes/more/include6.txt b/docutils/test/test_parsers/test_rst/test_directives/includes/more/include6.txt deleted file mode 100644 index 8ac403b01..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/includes/more/include6.txt +++ /dev/null @@ -1,3 +0,0 @@ -In includes/more/include6.txt - -.. include:: ../sibling/include7.txt diff --git a/docutils/test/test_parsers/test_rst/test_directives/includes/sibling/include7.txt b/docutils/test/test_parsers/test_rst/test_directives/includes/sibling/include7.txt deleted file mode 100644 index fe85aa963..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/includes/sibling/include7.txt +++ /dev/null @@ -1 +0,0 @@ -In includes/sibling/include7.txt diff --git a/docutils/test/test_parsers/test_rst/test_directives/raw1.txt b/docutils/test/test_parsers/test_rst/test_directives/raw1.txt deleted file mode 100644 index 7ea03651b..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/raw1.txt +++ /dev/null @@ -1 +0,0 @@ -<p>This file is used by <tt>test_raw.py</tt>.</p> diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py b/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py deleted file mode 100755 index aaa5aa8d3..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py +++ /dev/null @@ -1,184 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for admonitions.py directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['admonitions'] = [ -["""\ -.. Attention:: Directives at large. - -.. Note:: This is a note. - -.. Tip:: 15% if the - service is good. - -.. Hint:: It's bigger than a bread box. - -- .. WARNING:: Strong prose may provoke extreme mental exertion. - Reader discretion is strongly advised. -- .. Error:: Does not compute. - -.. Caution:: - - Don't take any wooden nickels. - -.. DANGER:: Mad scientist at work! - -.. Important:: - - Wash behind your ears. - - Clean up your room. - - Call your mother. - - Back up your data. -""", -"""\ -<document source="test data"> - <attention> - <paragraph> - Directives at large. - <note> - <paragraph> - This is a note. - <tip> - <paragraph> - 15% if the - service is good. - <hint> - <paragraph> - It's bigger than a bread box. - <bullet_list bullet="-"> - <list_item> - <warning> - <paragraph> - Strong prose may provoke extreme mental exertion. - Reader discretion is strongly advised. - <list_item> - <error> - <paragraph> - Does not compute. - <caution> - <paragraph> - Don't take any wooden nickels. - <danger> - <paragraph> - Mad scientist at work! - <important> - <bullet_list bullet="-"> - <list_item> - <paragraph> - Wash behind your ears. - <list_item> - <paragraph> - Clean up your room. - <list_item> - <paragraph> - Call your mother. - <list_item> - <paragraph> - Back up your data. -"""], -["""\ -.. note:: One-line notes. -.. note:: One after the other. -.. note:: No blank lines in-between. -""", -"""\ -<document source="test data"> - <note> - <paragraph> - One-line notes. - <note> - <paragraph> - One after the other. - <note> - <paragraph> - No blank lines in-between. -"""], -["""\ -.. note:: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - The "note" admonition is empty; content required. - <literal_block xml:space="preserve"> - .. note:: -"""], -["""\ -.. admonition:: Admonition - - This is a generic admonition. -""", -"""\ -<document source="test data"> - <admonition classes="admonition-admonition"> - <title> - Admonition - <paragraph> - This is a generic admonition. -"""], -["""\ -.. admonition:: And, by the way... - - You can make up your own admonition too. -""", -"""\ -<document source="test data"> - <admonition classes="admonition-and-by-the-way"> - <title> - And, by the way... - <paragraph> - You can make up your own admonition too. -"""], -["""\ -.. admonition:: Admonition - :class: emergency - - Test the "class" override. -""", -"""\ -<document source="test data"> - <admonition classes="emergency"> - <title> - Admonition - <paragraph> - Test the "class" override. -"""], -["""\ -.. admonition:: - - Generic admonitions require a title. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "admonition" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. admonition:: - - Generic admonitions require a title. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_compound.py b/docutils/test/test_parsers/test_rst/test_directives/test_compound.py deleted file mode 100755 index eea4dd53b..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_compound.py +++ /dev/null @@ -1,106 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the 'compound' directive from body.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['compound'] = [ -["""\ -.. compound:: - - Compound paragraphs are single logical paragraphs - which contain embedded - - * lists - * tables - * literal blocks - * and other body elements - - and are split into multiple physical paragraphs. -""", -"""\ -<document source="test data"> - <compound> - <paragraph> - Compound paragraphs are single logical paragraphs - which contain embedded - <bullet_list bullet="*"> - <list_item> - <paragraph> - lists - <list_item> - <paragraph> - tables - <list_item> - <paragraph> - literal blocks - <list_item> - <paragraph> - and other body elements - <paragraph> - and are split into multiple physical paragraphs. -"""], -["""\ -.. compound:: - - This is an extremely interesting compound paragraph containing a - simple paragraph, a literal block with some useless log messages:: - - Connecting... OK - Transmitting data... OK - Disconnecting... OK - - and another simple paragraph which is actually just a continuation - of the first simple paragraph, with the literal block in between. -""", -"""\ -<document source="test data"> - <compound> - <paragraph> - This is an extremely interesting compound paragraph containing a - simple paragraph, a literal block with some useless log messages: - <literal_block xml:space="preserve"> - Connecting... OK - Transmitting data... OK - Disconnecting... OK - <paragraph> - and another simple paragraph which is actually just a continuation - of the first simple paragraph, with the literal block in between. -"""], -["""\ -.. compound:: arg1 arg2 - - text -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "compound" directive: - no arguments permitted; blank line required before content block. - <literal_block xml:space="preserve"> - .. compound:: arg1 arg2 - \n\ - text -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_container.py b/docutils/test/test_parsers/test_rst/test_directives/test_container.py deleted file mode 100755 index 3c740611a..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_container.py +++ /dev/null @@ -1,76 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the 'container' directive from body.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['container'] = [ -["""\ -.. container:: - - "container" is a generic element, an extension mechanism for - users & applications. - - Containers may contain arbitrary body elements. -""", -"""\ -<document source="test data"> - <container> - <paragraph> - "container" is a generic element, an extension mechanism for - users & applications. - <paragraph> - Containers may contain arbitrary body elements. -"""], -["""\ -.. container:: custom - - Some text. -""", -"""\ -<document source="test data"> - <container classes="custom"> - <paragraph> - Some text. -"""], -["""\ -.. container:: one two three - four - - Multiple classes. - - Multi-line argument. - - Multiple paragraphs in the container. -""", -"""\ -<document source="test data"> - <container classes="one two three four"> - <paragraph> - Multiple classes. - <paragraph> - Multi-line argument. - <paragraph> - Multiple paragraphs in the container. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_contents.py b/docutils/test/test_parsers/test_rst/test_directives/test_contents.py deleted file mode 100755 index cb7bbec0f..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_contents.py +++ /dev/null @@ -1,241 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for parts.py contents directive. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['contents'] = [ -["""\ -.. contents:: -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="contents" names="contents"> - <title> - Contents - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: -"""], -["""\ -.. contents:: Table of Contents -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="table-of-contents" names="table\ of\ contents"> - <title> - Table of Contents - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: -"""], -["""\ -.. contents:: - Table of Contents -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="table-of-contents" names="table\ of\ contents"> - <title> - Table of Contents - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: -"""], -["""\ -.. contents:: Table - of - Contents -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="table-of-contents" names="table\ of\ contents"> - <title> - Table - of - Contents - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: -"""], -["""\ -.. contents:: *Table* of ``Contents`` -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="table-of-contents" names="table\ of\ contents"> - <title> - <emphasis> - Table - of - <literal> - Contents - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: -"""], -["""\ -.. contents:: - :depth: 2 - :local: -""", -"""\ -<document source="test data"> - <topic classes="contents local" ids="contents" names="contents"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - depth: 2 - local: None -"""], -["""\ -.. contents:: - :local: arg -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "contents" directive: - invalid option value: (option: "local"; value: 'arg') - no argument is allowed; "arg" supplied. - <literal_block xml:space="preserve"> - .. contents:: - :local: arg -"""], -["""\ -.. contents:: Table of Contents - :local: - :depth: 2 - :backlinks: none -""", -"""\ -<document source="test data"> - <topic classes="contents local" ids="table-of-contents" names="table\ of\ contents"> - <title> - Table of Contents - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - backlinks: None - depth: 2 - local: None -"""], -["""\ -.. contents:: - :depth: two -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "contents" directive: - invalid option value: (option: "depth"; value: 'two') - invalid literal for int(): two. - <literal_block xml:space="preserve"> - .. contents:: - :depth: two -"""], -["""\ -.. contents:: - :width: 2 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "contents" directive: - unknown option: "width". - <literal_block xml:space="preserve"> - .. contents:: - :width: 2 -"""], -["""\ -.. contents:: - :backlinks: no way! -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "contents" directive: - invalid option value: (option: "backlinks"; value: 'no way!') - "no way!" unknown; choose from "top", "entry", or "none". - <literal_block xml:space="preserve"> - .. contents:: - :backlinks: no way! -"""], -["""\ -.. contents:: - :backlinks: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "contents" directive: - invalid option value: (option: "backlinks"; value: None) - must supply an argument; choose from "top", "entry", or "none". - <literal_block xml:space="preserve"> - .. contents:: - :backlinks: -"""], -["""\ -* .. contents:: -""", -"""\ -<document source="test data"> - <bullet_list bullet="*"> - <list_item> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - The "contents" directive may not be used within topics or body elements. - <literal_block xml:space="preserve"> - .. contents:: -"""], -["""\ -.. sidebar:: containing contents - - .. contents:: -""", -"""\ -<document source="test data"> - <sidebar> - <title> - containing contents - <topic classes="contents" ids="contents" names="contents"> - <title> - Contents - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_date.py b/docutils/test/test_parsers/test_rst/test_directives/test_date.py deleted file mode 100755 index 0364331b1..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_date.py +++ /dev/null @@ -1,53 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the misc.py "date" directive. -""" - -from __init__ import DocutilsTestSupport -import time - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['date'] = [ -["""\ -.. |date| date:: - -Today's date is |date|. -""", -"""\ -<document source="test data"> - <substitution_definition names="date"> - %s - <paragraph> - Today's date is \n\ - <substitution_reference refname="date"> - date - . -""" % time.strftime('%Y-%m-%d')], -["""\ -.. |date| date:: %a, %d %b %Y -""", -"""\ -<document source="test data"> - <substitution_definition names="date"> - %s -""" % time.strftime('%a, %d %b %Y')], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_decorations.py b/docutils/test/test_parsers/test_rst/test_directives/test_decorations.py deleted file mode 100755 index c770c6a49..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_decorations.py +++ /dev/null @@ -1,93 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the "header" & "footer" directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['headers'] = [ -["""\ -.. header:: a paragraph for the header -""", -"""\ -<document source="test data"> - <decoration> - <header> - <paragraph> - a paragraph for the header -"""], -["""\ -.. header:: -""", -"""\ -<document source="test data"> - <decoration> - <header> - <paragraph> - Problem with the "header" directive: no content supplied. - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Content block expected for the "header" directive; none found. - <literal_block xml:space="preserve"> - .. header:: -"""], -["""\ -.. header:: first part of the header -.. header:: second part of the header -""", -"""\ -<document source="test data"> - <decoration> - <header> - <paragraph> - first part of the header - <paragraph> - second part of the header -"""], -] - -totest['footers'] = [ -["""\ -.. footer:: a paragraph for the footer -""", -"""\ -<document source="test data"> - <decoration> - <footer> - <paragraph> - a paragraph for the footer -"""], -["""\ -.. footer:: even if a footer is declared first -.. header:: the header appears first -""", -"""\ -<document source="test data"> - <decoration> - <header> - <paragraph> - the header appears first - <footer> - <paragraph> - even if a footer is declared first -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_default_role.py b/docutils/test/test_parsers/test_rst/test_directives/test_default_role.py deleted file mode 100755 index fc9343247..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_default_role.py +++ /dev/null @@ -1,84 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for misc.py "default-role" directive. -""" - -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['default-role'] = [ -["""\ -.. default-role:: subscript - -This is a `subscript`. -""", -"""\ -<document source="test data"> - <paragraph> - This is a \n\ - <subscript> - subscript - . -"""], -["""\ -Must define a custom role before using it. - -.. default-role:: custom -""", -"""\ -<document source="test data"> - <paragraph> - Must define a custom role before using it. - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - No role entry for "custom" in module "docutils.parsers.rst.languages.en". - Trying "custom" as canonical role name. - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Unknown interpreted text role "custom". - <literal_block xml:space="preserve"> - .. default-role:: custom -"""], -["""\ -.. role:: custom -.. default-role:: custom - -This text uses the `default role`. - -.. default-role:: - -Returned the `default role` to its standard default. -""", -"""\ -<document source="test data"> - <paragraph> - This text uses the \n\ - <inline classes="custom"> - default role - . - <paragraph> - Returned the \n\ - <title_reference> - default role - to its standard default. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_figures.py b/docutils/test/test_parsers/test_rst/test_directives/test_figures.py deleted file mode 100755 index 91fd91596..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_figures.py +++ /dev/null @@ -1,294 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for images.py figure directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['figures'] = [ -["""\ -.. figure:: picture.png -""", -"""\ -<document source="test data"> - <figure> - <image uri="picture.png"> -"""], -["""\ -.. figure:: picture.png - - A picture with a caption. -""", -"""\ -<document source="test data"> - <figure> - <image uri="picture.png"> - <caption> - A picture with a caption. -"""], -["""\ -.. figure:: picture.png - - - A picture with an invalid caption. -""", -"""\ -<document source="test data"> - <figure> - <image uri="picture.png"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Figure caption must be a paragraph or empty comment. - <literal_block xml:space="preserve"> - .. figure:: picture.png - \n\ - - A picture with an invalid caption. -"""], -["""\ -.. figure:: picture.png - - .. - - A picture with a legend but no caption. -""", -"""\ -<document source="test data"> - <figure> - <image uri="picture.png"> - <legend> - <paragraph> - A picture with a legend but no caption. -"""], -["""\ -.. Figure:: picture.png - :height: 100 - :width: 200 - :scale: 50 - - A picture with image options and a caption. -""", -"""\ -<document source="test data"> - <figure> - <image height="100" scale="50" uri="picture.png" width="200"> - <caption> - A picture with image options and a caption. -"""], -["""\ -.. Figure:: picture.png - :height: 100 - :alt: alternate text - :width: 200 - :scale: 50 - :figwidth: 300 - :figclass: class1 class2 - - A picture with image options on individual lines, and this caption. -""", -"""\ -<document source="test data"> - <figure classes="class1 class2" width="300"> - <image alt="alternate text" height="100" scale="50" uri="picture.png" width="200"> - <caption> - A picture with image options on individual lines, and this caption. -"""], -["""\ -.. figure:: picture.png - :align: center - - A figure with explicit alignment. -""", -"""\ -<document source="test data"> - <figure align="center"> - <image uri="picture.png"> - <caption> - A figure with explicit alignment. -"""], -["""\ -.. figure:: picture.png - :align: top - - A figure with wrong alignment. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "figure" directive: - invalid option value: (option: "align"; value: 'top') - "top" unknown; choose from "left", "center", or "right". - <literal_block xml:space="preserve"> - .. figure:: picture.png - :align: top - - A figure with wrong alignment. -"""], -["""\ -This figure lacks a caption. It may still have a -"Figure 1."-style caption appended in the output. - -.. figure:: picture.png -""", -"""\ -<document source="test data"> - <paragraph> - This figure lacks a caption. It may still have a - "Figure 1."-style caption appended in the output. - <figure> - <image uri="picture.png"> -"""], -["""\ -.. figure:: picture.png - - A picture with a caption and a legend. - - +-----------------------+-----------------------+ - | Symbol | Meaning | - +=======================+=======================+ - | .. image:: tent.png | Campground | - +-----------------------+-----------------------+ - | .. image:: waves.png | Lake | - +-----------------------+-----------------------+ - | .. image:: peak.png | Mountain | - +-----------------------+-----------------------+ -""", -"""\ -<document source="test data"> - <figure> - <image uri="picture.png"> - <caption> - A picture with a caption and a legend. - <legend> - <table> - <tgroup cols="2"> - <colspec colwidth="23"> - <colspec colwidth="23"> - <thead> - <row> - <entry> - <paragraph> - Symbol - <entry> - <paragraph> - Meaning - <tbody> - <row> - <entry> - <image uri="tent.png"> - <entry> - <paragraph> - Campground - <row> - <entry> - <image uri="waves.png"> - <entry> - <paragraph> - Lake - <row> - <entry> - <image uri="peak.png"> - <entry> - <paragraph> - Mountain -"""], -["""\ -.. figure:: picture.png - - .. - - A picture with a legend but no caption. - (The empty comment replaces the caption, which must - be a single paragraph.) -""", -"""\ -<document source="test data"> - <figure> - <image uri="picture.png"> - <legend> - <paragraph> - A picture with a legend but no caption. - (The empty comment replaces the caption, which must - be a single paragraph.) -"""], -["""\ -Testing for line-leaks: - -.. figure:: picture.png - - A picture with a caption. -.. figure:: picture.png - - A picture with a caption. -.. figure:: picture.png - - A picture with a caption. -.. figure:: picture.png -.. figure:: picture.png -.. figure:: picture.png -.. figure:: picture.png - - A picture with a caption. - -.. figure:: picture.png - -.. figure:: picture.png - - A picture with a caption. - -.. figure:: picture.png -""", -"""\ -<document source="test data"> - <paragraph> - Testing for line-leaks: - <figure> - <image uri="picture.png"> - <caption> - A picture with a caption. - <figure> - <image uri="picture.png"> - <caption> - A picture with a caption. - <figure> - <image uri="picture.png"> - <caption> - A picture with a caption. - <figure> - <image uri="picture.png"> - <figure> - <image uri="picture.png"> - <figure> - <image uri="picture.png"> - <figure> - <image uri="picture.png"> - <caption> - A picture with a caption. - <figure> - <image uri="picture.png"> - <figure> - <image uri="picture.png"> - <caption> - A picture with a caption. - <figure> - <image uri="picture.png"> -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_images.py b/docutils/test/test_parsers/test_rst/test_directives/test_images.py deleted file mode 100755 index 50f555ba1..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_images.py +++ /dev/null @@ -1,413 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for images.py image directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['images'] = [ -["""\ -.. image:: picture.png -""", -"""\ -<document source="test data"> - <image uri="picture.png"> -"""], -["""\ -.. image:: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. image:: -"""], -["""\ -.. image:: one two three.png -""", -"""\ -<document source="test data"> - <image uri="onetwothree.png"> -"""], -["""\ -.. image:: picture.png - :height: 100 - :width: 200 - :scale: 50 -""", -"""\ -<document source="test data"> - <image height="100" scale="50" uri="picture.png" width="200"> -"""], -["""\ -.. image:: - picture.png - :height: 100 - :width: 200 - :scale: 50 -""", -"""\ -<document source="test data"> - <image height="100" scale="50" uri="picture.png" width="200"> -"""], -["""\ -.. image:: - :height: 100 - :width: 200 - :scale: 50 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. image:: - :height: 100 - :width: 200 - :scale: 50 -"""], -["""\ -.. image:: a/very/long/path/to/ - picture.png - :height: 100 - :width: 200 - :scale: 50 -""", -"""\ -<document source="test data"> - <image height="100" scale="50" uri="a/very/long/path/to/picture.png" width="200"> -"""], -["""\ -.. image:: picture.png - :width: 200px - :height: 100 em -""", -"""\ -<document source="test data"> - <image height="100em" uri="picture.png" width="200px"> -"""], -["""\ -.. image:: picture.png - :width: 50% - :height: 10mm -""", -"""\ -<document source="test data"> - <image height="10mm" uri="picture.png" width="50%"> -"""], -["""\ -.. image:: picture.png - :width: 50% - :height: 40% -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option value: (option: "height"; value: \'40%\') - not a positive measure of one of the following units: - "em" "ex" "px" "in" "cm" "mm" "pt" "pc" "". - <literal_block xml:space="preserve"> - .. image:: picture.png - :width: 50% - :height: 40% -"""], -["""\ -.. image:: picture.png - :height: 100 - :width: 200 - :scale: 50 - :alt: Alternate text for the picture -""", -"""\ -<document source="test data"> - <image alt="Alternate text for the picture" height="100" scale="50" uri="picture.png" width="200"> -"""], -["""\ -.. image:: picture.png - :scale: - 50 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option value: (option: "scale"; value: '- 50') - negative value; must be positive or zero. - <literal_block xml:space="preserve"> - .. image:: picture.png - :scale: - 50 -"""], -["""\ -.. image:: picture.png - :scale: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option value: (option: "scale"; value: None) - %s. - <literal_block xml:space="preserve"> - .. image:: picture.png - :scale: -""" % DocutilsTestSupport.exception_data('int(None)')[1][0]], -["""\ -.. image:: picture.png - :scale 50 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option block. - <literal_block xml:space="preserve"> - .. image:: picture.png - :scale 50 -"""], -["""\ -.. image:: picture.png - scale: 50 -""", -"""\ -<document source="test data"> - <image uri="picture.pngscale:50"> -"""], -["""\ -.. image:: picture.png - :: 50 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option block. - <literal_block xml:space="preserve"> - .. image:: picture.png - :: 50 -"""], -["""\ -.. image:: picture.png - :sale: 50 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - unknown option: "sale". - <literal_block xml:space="preserve"> - .. image:: picture.png - :sale: 50 -"""], -["""\ -.. image:: picture.png - :scale is: 50 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option data: extension option field name may not contain multiple words. - <literal_block xml:space="preserve"> - .. image:: picture.png - :scale is: 50 -"""], -["""\ -.. image:: picture.png - :scale: fifty -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option value: (option: "scale"; value: 'fifty') - invalid literal for int(): fifty. - <literal_block xml:space="preserve"> - .. image:: picture.png - :scale: fifty -"""], -["""\ -.. image:: picture.png - :scale: 50 - :scale: 50 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option data: duplicate option "scale". - <literal_block xml:space="preserve"> - .. image:: picture.png - :scale: 50 - :scale: 50 -"""], -["""\ -.. image:: picture.png - :alt: - -(Empty "alt" option.) -""", -"""\ -<document source="test data"> - <image alt="" uri="picture.png"> - <paragraph> - (Empty "alt" option.) -"""], -["""\ -.. image:: picture.png - :target: bigpicture.png -""", -"""\ -<document source="test data"> - <reference refuri="bigpicture.png"> - <image uri="picture.png"> -"""], -["""\ -.. image:: picture.png - :target: indirect_ -""", -"""\ -<document source="test data"> - <reference name="indirect" refname="indirect"> - <image uri="picture.png"> -"""], -["""\ -.. image:: picture.png - :target: a/multi/ - line/uri - -.. image:: picture.png - :target: `a multi line - internal reference`_ -""", -"""\ -<document source="test data"> - <reference refuri="a/multi/line/uri"> - <image uri="picture.png"> - <reference name="a multi line internal reference" refname="a multi line internal reference"> - <image uri="picture.png"> -"""], -["""\ -.. image:: picture.png - :target: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option value: (option: "target"; value: None) - argument required but none supplied. - <literal_block xml:space="preserve"> - .. image:: picture.png - :target: -"""], -["""\ -.. image:: picture.png - :align: left -""", -"""\ -<document source="test data"> - <image align="left" uri="picture.png"> -"""], -["""\ -.. image:: picture.png - :align: top -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: "top" is not a valid value for the "align" option. Valid values for "align" are: "left", "center", "right". - <literal_block xml:space="preserve"> - .. image:: picture.png - :align: top -"""], -["""\ -.. |img| image:: picture.png - :align: top -""", -"""\ -<document source="test data"> - <substitution_definition names="img"> - <image align="top" alt="img" uri="picture.png"> -"""], -["""\ -.. |img| image:: picture.png - :align: left -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: "left" is not a valid value for the "align" option within a substitution definition. Valid values for "align" are: "top", "middle", "bottom". - <literal_block xml:space="preserve"> - image:: picture.png - :align: left - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Substitution definition "img" empty or invalid. - <literal_block xml:space="preserve"> - .. |img| image:: picture.png - :align: left -"""], -[u"""\ -.. image:: picture.png - :align: \xe4 -""", -u"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - invalid option value: (option: "align"; value: u\'\\xe4\') - "\xe4" unknown; choose from "top", "middle", "bottom", "left", "center", or "right". - <literal_block xml:space="preserve"> - .. image:: picture.png - :align: \xe4 -"""], -[""" -.. image:: test.png - :target: Uppercase_ - -.. _Uppercase: http://docutils.sourceforge.net/ -""", -"""\ -<document source="test data"> - <reference name="Uppercase" refname="uppercase"> - <image uri="test.png"> - <target ids="uppercase" names="uppercase" refuri="http://docutils.sourceforge.net/"> -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_include.py b/docutils/test/test_parsers/test_rst/test_directives/test_include.py deleted file mode 100755 index c9b5f7378..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_include.py +++ /dev/null @@ -1,412 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for misc.py "include" directive. -""" - -import os.path -import sys -from __init__ import DocutilsTestSupport -from docutils.parsers.rst import states - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -mydir = 'test_parsers/test_rst/test_directives/' -include1 = os.path.join(mydir, 'include1.txt') -include1rel = DocutilsTestSupport.utils.relative_path(None, include1) -include2 = os.path.join(mydir, 'include2.txt') -include3 = os.path.join(mydir, 'include3.txt') -include8 = os.path.join(mydir, 'include8.txt') -include10 = os.path.join(mydir, 'include10.txt') -include10rel = DocutilsTestSupport.utils.relative_path(None, include10) -include11 = os.path.join(mydir, 'include 11.txt') -include11rel = DocutilsTestSupport.utils.relative_path(None, include11) -utf_16_file = os.path.join(mydir, 'utf-16.csv') -utf_16_file_rel = DocutilsTestSupport.utils.relative_path(None, utf_16_file) -nonexistent = os.path.join(os.path.dirname(states.__file__), - 'include', 'nonexistent') -nonexistent_rel = DocutilsTestSupport.utils.relative_path( - os.path.join(DocutilsTestSupport.testroot, 'dummy'), nonexistent) - -totest = {} - -totest['include'] = [ -["""\ -Include Test -============ - -.. include:: %s - -A paragraph. -""" % include1, -"""\ -<document source="test data"> - <section ids="include-test" names="include\ test"> - <title> - Include Test - <section ids="inclusion-1" names="inclusion\ 1"> - <title> - Inclusion 1 - <paragraph> - This file is used by \n\ - <literal> - test_include.py - . - <paragraph> - A paragraph. -"""], -["""\ -Include Test -============ - -.. include:: %s - :literal: - -A paragraph. -""" % include1, -"""\ -<document source="test data"> - <section ids="include-test" names="include\ test"> - <title> - Include Test - <literal_block source="%s" xml:space="preserve"> - Inclusion 1 - ----------- - \n\ - This file is used by ``test_include.py``. - <paragraph> - A paragraph. -""" % include1rel], -["""\ -Let's test the parse context. - - This paragraph is in a block quote. - - .. include:: %s - -The included paragraphs should also be in the block quote. -""" % include2, -"""\ -<document source="test data"> - <paragraph> - Let's test the parse context. - <block_quote> - <paragraph> - This paragraph is in a block quote. - <paragraph> - Here are some paragraphs - that can appear at any level. - <paragraph> - This file (include2.txt) is used by - <literal> - test_include.py - . - <paragraph> - The included paragraphs should also be in the block quote. -"""], -["""\ -Include Test -============ - -.. include:: nonexistent.txt - -A paragraph. -""", -"""\ -<document source="test data"> - <section ids="include-test" names="include\ test"> - <title> - Include Test - <system_message level="4" line="4" source="test data" type="SEVERE"> - <paragraph> - Problems with "include" directive path: - IOError: [Errno 2] No such file or directory: 'nonexistent.txt'. - <literal_block xml:space="preserve"> - .. include:: nonexistent.txt - <paragraph> - A paragraph. -"""], -["""\ -Include Test -============ - -.. include:: %s - -.. include:: %s - -A paragraph. -""" % (include1, include1), -"""\ -<document source="test data"> - <section ids="include-test" names="include\ test"> - <title> - Include Test - <section dupnames="inclusion\ 1" ids="inclusion-1"> - <title> - Inclusion 1 - <paragraph> - This file is used by - <literal> - test_include.py - . - <section dupnames="inclusion\ 1" ids="id1"> - <title> - Inclusion 1 - <system_message backrefs="id1" level="1" line="2" source="%s" type="INFO"> - <paragraph> - Duplicate implicit target name: "inclusion 1". - <paragraph> - This file is used by - <literal> - test_include.py - . - <paragraph> - A paragraph. -""" % include1rel], -["""\ -Include Test -============ - -.. include:: %s - ----------- - -.. include:: %s - -A paragraph. -""" % (include1, include1), -"""\ -<document source="test data"> - <section ids="include-test" names="include\ test"> - <title> - Include Test - <section dupnames="inclusion\ 1" ids="inclusion-1"> - <title> - Inclusion 1 - <paragraph> - This file is used by \n\ - <literal> - test_include.py - . - <transition> - <section dupnames="inclusion\ 1" ids="id1"> - <title> - Inclusion 1 - <system_message backrefs="id1" level="1" line="2" source="%s" type="INFO"> - <paragraph> - Duplicate implicit target name: "inclusion 1". - <paragraph> - This file is used by \n\ - <literal> - test_include.py - . - <paragraph> - A paragraph. -""" % include1rel], -["""\ -In test data - -.. include:: %s -""" % include3, -"""\ -<document source="test data"> - <paragraph> - In test data - <paragraph> - In include3.txt - <paragraph> - In includes/include4.txt - <paragraph> - In includes/include5.txt - <paragraph> - In includes/more/include6.txt - <paragraph> - In includes/sibling/include7.txt -"""], -["""\ -In test data - -Section -======= - -(Section contents in nested parse; slice of input_lines ViewList.) - -.. include:: %s -""" % include3, -"""\ -<document source="test data"> - <paragraph> - In test data - <section ids="section" names="section"> - <title> - Section - <paragraph> - (Section contents in nested parse; slice of input_lines ViewList.) - <paragraph> - In include3.txt - <paragraph> - In includes/include4.txt - <paragraph> - In includes/include5.txt - <paragraph> - In includes/more/include6.txt - <paragraph> - In includes/sibling/include7.txt -"""], -["""\ -Testing relative includes: - -.. include:: %s -""" % include8, -"""\ -<document source="test data"> - <paragraph> - Testing relative includes: - <paragraph> - In include8.txt - <paragraph> - In ../includes/include9.txt. - <paragraph> - Here are some paragraphs - that can appear at any level. - <paragraph> - This file (include2.txt) is used by - <literal> - test_include.py - . -"""], -["""\ -Encoding: - -.. include:: %s - :encoding: utf-16 -""" % utf_16_file_rel, -u"""\ -<document source="test data"> - <paragraph> - Encoding: - <paragraph> - "Treat", "Quantity", "Description" - "Albatr\xb0\xdf", 2.99, "\xa1On a \\u03c3\\u03c4\\u03b9\\u03ba!" - "Crunchy Frog", 1.49, "If we took the b\xf6nes out, it wouldn\\u2019t be - crunchy, now would it?" - "Gannet Ripple", 1.99, "\xbfOn a \\u03c3\\u03c4\\u03b9\\u03ba?" -"""], -["""\ -Include file is UTF-16-encoded, and is not valid ASCII. - -.. include:: %s - :encoding: ascii -""" % utf_16_file_rel, -"""\ -<document source="test data"> - <paragraph> - Include file is UTF-16-encoded, and is not valid ASCII. - <system_message level="4" line="3" source="test data" type="SEVERE"> - <paragraph> - Problem with "include" directive: - UnicodeError: Unable to decode input data. Tried the following encodings: 'ascii'. - (UnicodeDecodeError: 'ascii' codec can't decode byte 0xfe in position 0: ordinal not in range(128)) - <literal_block xml:space="preserve"> - .. include:: %s - :encoding: ascii -""" % utf_16_file_rel], -# @@@ BUG with errors reported with incorrect "source" & "line": -# ["""\ -# Testing bad charent includes: -# -# .. include:: %s -# """ % include10, -# """\ -# <document source="test data"> -# <paragraph> -# Testing bad charent includes: -# <system_message level="3" line="1" source="%s" type="ERROR"> -# <paragraph> -# Invalid character code: 0xFFFFFFFFF -# int() literal too large: FFFFFFFFF -# <literal_block xml:space="preserve"> -# unicode:: 0xFFFFFFFFF -# <system_message level="2" line="1" source="%s" type="WARNING"> -# <paragraph> -# Substitution definition "bad" empty or invalid. -# <literal_block xml:space="preserve"> -# .. |bad| unicode:: 0xFFFFFFFFF -# """ % (include10rel, include10rel)], -["""\ -Include file with whitespace in the path: - -.. include:: %s -""" % include11rel, -"""\ -<document source="test data"> - <paragraph> - Include file with whitespace in the path: - <paragraph> - some text -"""], -["""\ -Standard include data file: - -.. include:: <isogrk4.txt> -""", -"""\ -<document source="test data"> - <paragraph> - Standard include data file: - <comment xml:space="preserve"> - This data file has been placed in the public domain. - <comment xml:space="preserve"> - Derived from the Unicode character mappings available from - <http://www.w3.org/2003/entities/xml/>. - Processed by unicode2rstsubs.py, part of Docutils: - <http://docutils.sourceforge.net>. - <substitution_definition names="b.Gammad"> - \\u03dc - <substitution_definition names="b.gammad"> - \\u03dd -"""], -["""\ -Nonexistent standard include data file: - -.. include:: <nonexistent> -""", -"""\ -<document source="test data"> - <paragraph> - Nonexistent standard include data file: - <system_message level="4" line="3" source="test data" type="SEVERE"> - <paragraph> - Problems with "include" directive path: - IOError: [Errno 2] No such file or directory: '%s'. - <literal_block xml:space="preserve"> - .. include:: <nonexistent> -""" % nonexistent_rel], -] - - -# Skip tests whose output contains "UnicodeDecodeError" if we are not -# using Python 2.3 or higher. -if sys.version_info < (2, 3): - for i in range(len(totest['include'])): - if totest['include'][i][1].find('UnicodeDecodeError') != -1: - del totest['include'][i] - print ("Test totest['include'][%s] skipped; " - "Python 2.3+ required for expected output." % i) - # Assume we have only one of these tests. - break - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_line_blocks.py b/docutils/test/test_parsers/test_rst/test_directives/test_line_blocks.py deleted file mode 100755 index 131ceaa05..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_line_blocks.py +++ /dev/null @@ -1,81 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the body.py 'line-block' directive. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['line_blocks'] = [ -["""\ -.. line-block:: - - This is a line block. - Newlines are *preserved*. - As is initial whitespace. -""", -"""\ -<document source="test data"> - <line_block> - <line> - This is a line block. - <line> - Newlines are \n\ - <emphasis> - preserved - . - <line_block> - <line> - As is initial whitespace. -"""], -["""\ -.. line-block:: - - Inline markup *may not span - multiple lines* of a line block. -""", -"""\ -<document source="test data"> - <line_block> - <line> - Inline markup \n\ - <problematic ids="id2" refid="id1"> - * - may not span - <line_block> - <line> - multiple lines* of a line block. - <system_message backrefs="id2" ids="id1" level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. -"""], -["""\ -.. line-block:: -""", -"""\ -<document source="test data"> - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Content block expected for the "line-block" directive; none found. - <literal_block xml:space="preserve"> - .. line-block:: -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_meta.py b/docutils/test/test_parsers/test_rst/test_directives/test_meta.py deleted file mode 100755 index 7c8b34002..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_meta.py +++ /dev/null @@ -1,232 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for html meta directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['meta'] = [ -["""\ -.. meta:: - :description: The reStructuredText plaintext markup language - :keywords: plaintext,markup language -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="The reStructuredText plaintext markup language" name="description"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="plaintext,markup language" name="keywords"> -"""], -["""\ -.. meta:: - :description lang=en: An amusing story - :description lang=fr: Un histoire amusant -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="An amusing story" lang="en" name="description"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="Un histoire amusant" lang="fr" name="description"> -"""], -["""\ -.. meta:: - :http-equiv=Content-Type: text/html; charset=ISO-8859-1 -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type"> -"""], -["""\ -.. meta:: - :name: content - over multiple lines -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="content over multiple lines" name="name"> -"""], -["""\ -Paragraph - -.. meta:: - :name: content -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="content" name="name"> -"""], -["""\ -.. meta:: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Empty meta directive. - <literal_block xml:space="preserve"> - .. meta:: -"""], -["""\ -.. meta:: - :empty: -""", -"""\ -<document source="test data"> - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - No content for meta tag "empty". - <literal_block xml:space="preserve"> - :empty: -"""], -["""\ -.. meta:: - not a field list -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Invalid meta directive. - <literal_block xml:space="preserve"> - .. meta:: - not a field list -"""], -["""\ -.. meta:: - :name: content - not a field - :name: content -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="content" name="name"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Invalid meta directive. - <literal_block xml:space="preserve"> - .. meta:: - :name: content - not a field - :name: content -"""], -["""\ -.. meta:: - :name: content - :name: content - not a field -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="content" name="name"> - <pending> - .. internal attributes: - .transform: docutils.transforms.components.Filter - .details: - component: 'writer' - format: 'html' - nodes: - <meta content="content" name="name"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Invalid meta directive. - <literal_block xml:space="preserve"> - .. meta:: - :name: content - :name: content - not a field -"""], -["""\ -.. meta:: - :name notattval: content -""", -"""\ -<document source="test data"> - <system_message level="3" line="2" source="test data" type="ERROR"> - <paragraph> - Error parsing meta tag attribute "notattval": missing "=". - <literal_block xml:space="preserve"> - :name notattval: content -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_raw.py b/docutils/test/test_parsers/test_rst/test_directives/test_raw.py deleted file mode 100755 index 9e1a17974..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_raw.py +++ /dev/null @@ -1,154 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for misc.py "raw" directive. -""" - -import os.path -import sys -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -mydir = 'test_parsers/test_rst/test_directives/' -raw1 = os.path.join(mydir, 'raw1.txt') -utf_16_file = os.path.join(mydir, 'utf-16.csv') -utf_16_file_rel = DocutilsTestSupport.utils.relative_path(None, utf_16_file) - -totest = {} - -totest['raw'] = [ -["""\ -.. raw:: html - - <span>This is some plain old raw text.</span> -""", -"""\ -<document source="test data"> - <raw format="html" xml:space="preserve"> - <span>This is some plain old raw text.</span> -"""], -["""\ -.. raw:: html - :file: %s -""" % raw1, -"""\ -<document source="test data"> - <raw format="html" source="%s" xml:space="preserve"> - <p>This file is used by <tt>test_raw.py</tt>.</p> -""" % DocutilsTestSupport.utils.relative_path(None, raw1)], -["""\ -.. raw:: html - :file: rawfile.html - :url: http://example.org/ -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - The "file" and "url" options may not be simultaneously specified for the "raw" directive. - <literal_block xml:space="preserve"> - .. raw:: html - :file: rawfile.html - :url: http://example.org/ -"""], -["""\ -.. raw:: html - :file: rawfile.html - - <p>Can't have both content and file attribute.</p> -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - "raw" directive may not both specify an external file and have content. - <literal_block xml:space="preserve"> - .. raw:: html - :file: rawfile.html - - <p>Can't have both content and file attribute.</p> -"""], -[r""" -.. raw:: latex html - - \[ \sum_{n=1}^\infty \frac{1}{n} \text{ etc.} \] -""", -"""\ -<document source="test data"> - <raw format="latex html" xml:space="preserve"> - \\[ \\sum_{n=1}^\\infty \\frac{1}{n} \\text{ etc.} \\] -"""], -["""\ -.. raw:: html - :file: %s - :encoding: utf-16 -""" % utf_16_file_rel, -"""\ -<document source="test data"> - <raw format="html" source="%s" xml:space="preserve"> - "Treat", "Quantity", "Description" - "Albatr\xb0\xdf", 2.99, "\xa1On a \\u03c3\\u03c4\\u03b9\\u03ba!" - "Crunchy Frog", 1.49, "If we took the b\xf6nes out, it wouldn\\u2019t be - crunchy, now would it?" - "Gannet Ripple", 1.99, "\xbfOn a \\u03c3\\u03c4\\u03b9\\u03ba?" -""" % utf_16_file_rel], -["""\ -Raw input file is UTF-16-encoded, and is not valid ASCII. - -.. raw:: html - :file: %s - :encoding: ascii -""" % utf_16_file_rel, -"""\ -<document source="test data"> - <paragraph> - Raw input file is UTF-16-encoded, and is not valid ASCII. - <system_message level="4" line="3" source="test data" type="SEVERE"> - <paragraph> - Problem with "raw" directive: - UnicodeError: Unable to decode input data. Tried the following encodings: \'ascii\'. - (UnicodeDecodeError: 'ascii' codec can't decode byte 0xfe in position 0: ordinal not in range(128)) - <literal_block xml:space="preserve"> - .. raw:: html - :file: %s - :encoding: ascii -""" % utf_16_file_rel], -["""\ -.. raw:: html - :encoding: utf-8 - - Should the parser complain becau\xdfe there is no :file:? BUG? -""", -"""\ -<document source="test data"> - <raw format="html" xml:space="preserve"> - Should the parser complain becau\xdfe there is no :file:? BUG? -"""], -] - -# Skip tests whose output contains "UnicodeDecodeError" if we are not -# using Python 2.3 or higher. -if sys.version_info < (2, 3): - for i in range(len(totest['raw'])): - if totest['raw'][i][1].find('UnicodeDecodeError') != -1: - del totest['raw'][i] - print ("Test totest['raw'][%s] skipped; " - "Python 2.3+ required for expected output." % i) - # Assume we have only one of these tests. - break - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_replace.py b/docutils/test/test_parsers/test_rst/test_directives/test_replace.py deleted file mode 100755 index f5fd2495b..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_replace.py +++ /dev/null @@ -1,135 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for misc.py "replace" directive. -""" - -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['replace'] = [ -["""\ -Test the |name| directive. - -.. |name| replace:: "**replace**" -""", -"""\ -<document source="test data"> - <paragraph> - Test the \n\ - <substitution_reference refname="name"> - name - directive. - <substitution_definition names="name"> - " - <strong> - replace - " -"""], -["""\ -.. |name| replace:: paragraph 1 - - paragraph 2 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "replace" directive: may contain a single paragraph only. - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Substitution definition "name" empty or invalid. - <literal_block xml:space="preserve"> - .. |name| replace:: paragraph 1 - - paragraph 2 -"""], -["""\ -.. |name| replace:: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - The "replace" directive is empty; content required. - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Substitution definition "name" empty or invalid. - <literal_block xml:space="preserve"> - .. |name| replace:: -"""], -["""\ -.. |Python| replace:: Python, *the* best language around - -.. _Python: http://www.python.org/ - -I recommend you try |Python|_. -""", -"""\ -<document source="test data"> - <substitution_definition names="Python"> - Python, - <emphasis> - the - best language around - <target ids="python" names="python" refuri="http://www.python.org/"> - <paragraph> - I recommend you try - <reference refname="python"> - <substitution_reference refname="Python"> - Python - . -"""], -["""\ -.. |name| replace:: *error in **inline ``markup -""", -"""\ -<document source="test data"> - <system_message ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message ids="id3" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. - <system_message ids="id5" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "replace" directive: may contain a single paragraph only. - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Substitution definition "name" empty or invalid. - <literal_block xml:space="preserve"> - .. |name| replace:: *error in **inline ``markup -"""], -["""\ -.. replace:: not valid outside of a substitution definition -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Invalid context: the "replace" directive can only be used within a substitution definition. - <literal_block xml:space="preserve"> - .. replace:: not valid outside of a substitution definition -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_role.py b/docutils/test/test_parsers/test_rst/test_directives/test_role.py deleted file mode 100755 index 0cd10c967..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_role.py +++ /dev/null @@ -1,230 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for misc.py "role" directive. -""" - -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['role'] = [ -["""\ -.. role:: custom -.. role:: special - -:custom:`interpreted` and :special:`interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <inline classes="custom"> - interpreted - and \n\ - <inline classes="special"> - interpreted -"""], -["""\ -.. role:: custom - :class: custom-class -.. role:: special - :class: special-class - -:custom:`interpreted` and :special:`interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <inline classes="custom-class"> - interpreted - and \n\ - <inline classes="special-class"> - interpreted -"""], -["""\ -Must define :custom:`interpreted` before using it. - -.. role:: custom - -Now that it's defined, :custom:`interpreted` works. -""", -"""\ -<document source="test data"> - <paragraph> - Must define - <problematic ids="id2" refid="id1"> - :custom:`interpreted` - before using it. - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - No role entry for "custom" in module "docutils.parsers.rst.languages.en". - Trying "custom" as canonical role name. - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown interpreted text role "custom". - <paragraph> - Now that it's defined, \n\ - <inline classes="custom"> - interpreted - works. -"""], -["""\ -.. role:: custom(emphasis) - -:custom:`text` -""", -"""\ -<document source="test data"> - <paragraph> - <emphasis classes="custom"> - text -"""], -["""\ -.. role:: custom ( emphasis ) - -:custom:`text` -""", -"""\ -<document source="test data"> - <paragraph> - <emphasis classes="custom"> - text -"""], -["""\ -.. role:: custom(emphasis) - :class: special - -:custom:`text` -""", -"""\ -<document source="test data"> - <paragraph> - <emphasis classes="special"> - text -"""], -["""\ -.. role:: custom(unknown-role) -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - No role entry for "unknown-role" in module "docutils.parsers.rst.languages.en". - Trying "unknown-role" as canonical role name. - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown interpreted text role "unknown-role". - <literal_block xml:space="preserve"> - .. role:: custom(unknown-role) -"""], -["""\ -.. role:: custom - :class: 1 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "role" directive: - invalid option value: (option: "class"; value: '1') - cannot make "1" into a class name. - <literal_block xml:space="preserve"> - .. role:: custom - :class: 1 -"""], -["""\ -.. role:: 1 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Invalid argument for "role" directive: - cannot make "1" into a class name. - <literal_block xml:space="preserve"> - .. role:: 1 -"""], -["""\ -Test ----- - -.. role:: fileref(emphasis) - -Testing a :fileref:`role` in a nested parse. -""", -"""\ -<document source="test data"> - <section ids="test" names="test"> - <title> - Test - <paragraph> - Testing a \n\ - <emphasis classes="fileref"> - role - in a nested parse. -"""], -] - -totest['raw_role'] = [ -["""\ -.. role:: html(raw) - :format: html - -Here's some :html:`<i>raw HTML data</i>`. -""", -"""\ -<document source="test data"> - <paragraph> - Here's some \n\ - <raw classes="html" format="html" xml:space="preserve"> - <i>raw HTML data</i> - . -"""], -["""\ -.. role:: itex(raw) - :format: latex html - -Here's some itex markup: :itex:`$x^\\infty$`. -""", -"""\ -<document source="test data"> - <paragraph> - Here's some itex markup: \n\ - <raw classes="itex" format="latex html" xml:space="preserve"> - $x^\\infty$ - . -"""], -["""\ -Can't use the :raw:`role` directly. -""", -"""\ -<document source="test data"> - <paragraph> - Can't use the \n\ - <problematic ids="id2" refid="id1"> - :raw:`role` - directly. - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - No format (Writer name) is associated with this role: "raw". - The "raw" role cannot be used directly. - Instead, use the "role" directive to create a new role with an associated format. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_rubrics.py b/docutils/test/test_parsers/test_rst/test_directives/test_rubrics.py deleted file mode 100755 index 271802736..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_rubrics.py +++ /dev/null @@ -1,74 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the "rubric" directive. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['rubrics'] = [ -["""\ -.. rubric:: This is a rubric -""", -"""\ -<document source="test data"> - <rubric> - This is a rubric -"""], -["""\ -.. rubric:: -.. rubric:: A rubric has no content - - Invalid content -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "rubric" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. rubric:: - <system_message level="3" line="2" source="test data" type="ERROR"> - <paragraph> - Error in "rubric" directive: - no content permitted. - <literal_block xml:space="preserve"> - .. rubric:: A rubric has no content - \n\ - Invalid content -"""], -["""\ -.. rubric:: A rubric followed by a block quote -.. - - Block quote -""", -"""\ -<document source="test data"> - <rubric> - A rubric followed by a block quote - <comment xml:space="preserve"> - <block_quote> - <paragraph> - Block quote -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_sidebars.py b/docutils/test/test_parsers/test_rst/test_directives/test_sidebars.py deleted file mode 100755 index a84fc248d..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_sidebars.py +++ /dev/null @@ -1,73 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the "sidebar" directive. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['sidebars'] = [ -["""\ -.. sidebar:: Outer - - .. sidebar:: Nested - - Body. -""", -"""\ -<document source="test data"> - <sidebar> - <title> - Outer - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - The "sidebar" directive may not be used within a sidebar element. - <literal_block xml:space="preserve"> - .. sidebar:: Nested - \n\ - Body. -"""], -["""\ -.. sidebar:: Outer - - .. topic:: Topic - - .. sidebar:: Inner - - text -""", -"""\ -<document source="test data"> - <sidebar> - <title> - Outer - <topic> - <title> - Topic - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - The "sidebar" directive may not be used within topics or body elements. - <literal_block xml:space="preserve"> - .. sidebar:: Inner - \n\ - text -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_tables.py b/docutils/test/test_parsers/test_rst/test_directives/test_tables.py deleted file mode 100755 index da88510e7..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_tables.py +++ /dev/null @@ -1,997 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for tables.py directives. -""" - -from __init__ import DocutilsTestSupport - -import os -try: - import csv -except ImportError: - csv = None - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -mydir = 'test_parsers/test_rst/test_directives/' -utf_16_csv = os.path.join(mydir, 'utf-16.csv') -utf_16_csv_rel = DocutilsTestSupport.utils.relative_path(None, utf_16_csv) -empty_txt = os.path.join(mydir, 'empty.txt') - -totest = {} - -totest['table'] = [ -["""\ -.. table:: Truth table for "not" - :class: custom - - ===== ===== - A not A - ===== ===== - False True - True False - ===== ===== -""", -"""\ -<document source="test data"> - <table classes="custom"> - <title> - Truth table for "not" - <tgroup cols="2"> - <colspec colwidth="5"> - <colspec colwidth="5"> - <thead> - <row> - <entry> - <paragraph> - A - <entry> - <paragraph> - not A - <tbody> - <row> - <entry> - <paragraph> - False - <entry> - <paragraph> - True - <row> - <entry> - <paragraph> - True - <entry> - <paragraph> - False -"""], -["""\ -.. table:: title with an *error - - ====== ===== - Simple table - ====== ===== -""", -"""\ -<document source="test data"> - <table> - <title> - title with an \n\ - <problematic ids="id2" refid="id1"> - * - error - <tgroup cols="2"> - <colspec colwidth="6"> - <colspec colwidth="5"> - <tbody> - <row> - <entry> - <paragraph> - Simple - <entry> - <paragraph> - table - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. -"""], -] - -if not csv: - print ('Tests of "csv-table" directive skipped; ' - 'Python 2.3 or higher required.') -else: - totest['csv-table'] = [ -["""\ -.. csv-table:: inline with integral header - :widths: 10, 20, 30 - :header-rows: 1 - :stub-columns: 1 - - "Treat", "Quantity", "Description" - "Albatross", 2.99, "On a stick!" - "Crunchy Frog", 1.49, "If we took the bones out, it wouldn\'t be - crunchy, now would it?" - "Gannet Ripple", 1.99, "On a stick!" -""", -"""\ -<document source="test data"> - <table> - <title> - inline with integral header - <tgroup cols="3"> - <colspec colwidth="10" stub="1"> - <colspec colwidth="20"> - <colspec colwidth="30"> - <thead> - <row> - <entry> - <paragraph> - Treat - <entry> - <paragraph> - Quantity - <entry> - <paragraph> - Description - <tbody> - <row> - <entry> - <paragraph> - Albatross - <entry> - <paragraph> - 2.99 - <entry> - <paragraph> - On a stick! - <row> - <entry> - <paragraph> - Crunchy Frog - <entry> - <paragraph> - 1.49 - <entry> - <paragraph> - If we took the bones out, it wouldn't be - crunchy, now would it? - <row> - <entry> - <paragraph> - Gannet Ripple - <entry> - <paragraph> - 1.99 - <entry> - <paragraph> - On a stick! -"""], -["""\ -.. csv-table:: inline with separate header - :header: "Treat", Quantity, "Description" - :widths: 10,20,30 - - "Albatross", 2.99, "On a stick!" -""", -"""\ -<document source="test data"> - <table> - <title> - inline with separate header - <tgroup cols="3"> - <colspec colwidth="10"> - <colspec colwidth="20"> - <colspec colwidth="30"> - <thead> - <row> - <entry> - <paragraph> - Treat - <entry> - <paragraph> - Quantity - <entry> - <paragraph> - Description - <tbody> - <row> - <entry> - <paragraph> - Albatross - <entry> - <paragraph> - 2.99 - <entry> - <paragraph> - On a stick! -"""], -["""\ -.. csv-table:: complex internal structure - :header: "Treat", Quantity, " - * Description, - * Definition, or - * Narrative" - - " - * Ice cream - * Sorbet - * Albatross", 2.99, "On a stick!" -""", -"""\ -<document source="test data"> - <table> - <title> - complex internal structure - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <thead> - <row> - <entry> - <paragraph> - Treat - <entry> - <paragraph> - Quantity - <entry> - <bullet_list bullet="*"> - <list_item> - <paragraph> - Description, - <list_item> - <paragraph> - Definition, or - <list_item> - <paragraph> - Narrative - <tbody> - <row> - <entry> - <bullet_list bullet="*"> - <list_item> - <paragraph> - Ice cream - <list_item> - <paragraph> - Sorbet - <list_item> - <paragraph> - Albatross - <entry> - <paragraph> - 2.99 - <entry> - <paragraph> - On a stick! -"""], -["""\ -.. csv-table:: short rows - - one, 2, three - 4, five -""", -"""\ -<document source="test data"> - <table> - <title> - short rows - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <tbody> - <row> - <entry> - <paragraph> - one - <entry> - <paragraph> - 2 - <entry> - <paragraph> - three - <row> - <entry> - <paragraph> - 4 - <entry> - <paragraph> - five - <entry> -"""], -["""\ -.. csv-table:: short rows - :header-rows: 1 - - header col 1, header col 2 - one, 2, three - 4 -""", -"""\ -<document source="test data"> - <table> - <title> - short rows - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <thead> - <row> - <entry> - <paragraph> - header col 1 - <entry> - <paragraph> - header col 2 - <entry> - <tbody> - <row> - <entry> - <paragraph> - one - <entry> - <paragraph> - 2 - <entry> - <paragraph> - three - <row> - <entry> - <paragraph> - 4 - <entry> - <entry> -"""], -[u"""\ -.. csv-table:: non-ASCII characters - - Heiz\xf6lr\xfccksto\xdfabd\xe4mpfung -""", -u"""\ -<document source="test data"> - <table> - <title> - non-ASCII characters - <tgroup cols="1"> - <colspec colwidth="100"> - <tbody> - <row> - <entry> - <paragraph> - Heiz\xf6lr\xfccksto\xdfabd\xe4mpfung -"""], -["""\ -.. csv-table:: empty -""", -"""\ -<document source="test data"> - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - The "csv-table" directive requires content; none supplied. - <literal_block xml:space="preserve"> - .. csv-table:: empty -"""], -["""\ -.. csv-table:: insufficient header row data - :header-rows: 2 - - some, csv, data -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - 2 header row(s) specified but only 1 row(s) of data supplied ("csv-table" directive). - <literal_block xml:space="preserve"> - .. csv-table:: insufficient header row data - :header-rows: 2 - \n\ - some, csv, data -"""], -["""\ -.. csv-table:: insufficient body data - :header-rows: 1 - - some, csv, data -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Insufficient data supplied (1 row(s)); no data remaining for table body, required by "csv-table" directive. - <literal_block xml:space="preserve"> - .. csv-table:: insufficient body data - :header-rows: 1 - \n\ - some, csv, data -"""], -["""\ -.. csv-table:: content and external - :file: bogus.csv - - some, csv, data -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - "csv-table" directive may not both specify an external file and have content. - <literal_block xml:space="preserve"> - .. csv-table:: content and external - :file: bogus.csv - \n\ - some, csv, data -"""], -["""\ -.. csv-table:: external file and url - :file: bogus.csv - :url: http://example.org/bogus.csv -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - The "file" and "url" options may not be simultaneously specified for the "csv-table" directive. - <literal_block xml:space="preserve"> - .. csv-table:: external file and url - :file: bogus.csv - :url: http://example.org/bogus.csv -"""], -["""\ -.. csv-table:: error in the *title - - some, csv, data -""", -"""\ -<document source="test data"> - <table> - <title> - error in the \n\ - <problematic ids="id2" refid="id1"> - * - title - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <tbody> - <row> - <entry> - <paragraph> - some - <entry> - <paragraph> - csv - <entry> - <paragraph> - data - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. -"""], -["""\ -.. csv-table:: no such file - :file: bogus.csv -""", -"""\ -<document source="test data"> - <system_message level="4" line="1" source="test data" type="SEVERE"> - <paragraph> - Problems with "csv-table" directive path: - [Errno 2] No such file or directory: 'bogus.csv'. - <literal_block xml:space="preserve"> - .. csv-table:: no such file - :file: bogus.csv -"""], -["""\ -.. csv-table:: bad URL - :url: bogus.csv -""", -"""\ -<document source="test data"> - <system_message level="4" line="1" source="test data" type="SEVERE"> - <paragraph> - Problems with "csv-table" directive URL "bogus.csv": - unknown url type: bogus.csv. - <literal_block xml:space="preserve"> - .. csv-table:: bad URL - :url: bogus.csv -"""], -["""\ -.. csv-table:: column mismatch - :widths: 10,20 - - some, csv, data -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - "csv-table" widths do not match the number of columns in table (3). - <literal_block xml:space="preserve"> - .. csv-table:: column mismatch - :widths: 10,20 - \n\ - some, csv, data -"""], -["""\ -.. csv-table:: bad column widths - :widths: 10,y,z - - some, csv, data - -.. csv-table:: bad column widths - :widths: 0 0 0 - - some, csv, data -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "csv-table" directive: - invalid option value: (option: "widths"; value: '10,y,z') - invalid literal for int(): y. - <literal_block xml:space="preserve"> - .. csv-table:: bad column widths - :widths: 10,y,z - \n\ - some, csv, data - <system_message level="3" line="6" source="test data" type="ERROR"> - <paragraph> - Error in "csv-table" directive: - invalid option value: (option: "widths"; value: '0 0 0') - negative or zero value; must be positive. - <literal_block xml:space="preserve"> - .. csv-table:: bad column widths - :widths: 0 0 0 - \n\ - some, csv, data -"""], -["""\ -.. csv-table:: good delimiter - :delim: / - - some/csv/data - -.. csv-table:: good delimiter - :delim: \\ - - some\\csv\\data - -.. csv-table:: good delimiter - :delim: 0x5c - - some\\csv\\data - -.. csv-table:: good delimiter - :delim: space - - some csv data -""", -"""\ -<document source="test data"> - <table> - <title> - good delimiter - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <tbody> - <row> - <entry> - <paragraph> - some - <entry> - <paragraph> - csv - <entry> - <paragraph> - data - <table> - <title> - good delimiter - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <tbody> - <row> - <entry> - <paragraph> - some - <entry> - <paragraph> - csv - <entry> - <paragraph> - data - <table> - <title> - good delimiter - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <tbody> - <row> - <entry> - <paragraph> - some - <entry> - <paragraph> - csv - <entry> - <paragraph> - data - <table> - <title> - good delimiter - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <tbody> - <row> - <entry> - <paragraph> - some - <entry> - <paragraph> - csv - <entry> - <paragraph> - data -"""], -["""\ -.. csv-table:: bad delimiter - :delim: multiple - -.. csv-table:: bad delimiter - :delim: U+9999999999999 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "csv-table" directive: - invalid option value: (option: "delim"; value: 'multiple') - 'multiple' invalid; must be a single character or a Unicode code. - <literal_block xml:space="preserve"> - .. csv-table:: bad delimiter - :delim: multiple - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Error in "csv-table" directive: - invalid option value: (option: "delim"; value: 'U+9999999999999') - code too large (long int too large to convert to int). - <literal_block xml:space="preserve"> - .. csv-table:: bad delimiter - :delim: U+9999999999999 -"""], -["""\ -.. csv-table:: bad CSV data - - "bad", \"csv, data -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error with CSV data in "csv-table" directive: - newline inside string - <literal_block xml:space="preserve"> - .. csv-table:: bad CSV data - \n\ - "bad", \"csv, data -"""], -["""\ -.. csv-table:: bad CSV header data - :header: "bad", \"csv, data - - good, csv, data -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error with CSV data in "csv-table" directive: - newline inside string - <literal_block xml:space="preserve"> - .. csv-table:: bad CSV header data - :header: "bad", \"csv, data - \n\ - good, csv, data -"""], -["""\ -.. csv-table:: bad encoding - :file: %s - :encoding: latin-1 - -(7- and 8-bit text encoded as UTF-16 has lots of null/zero bytes.) -""" % utf_16_csv, -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error with CSV data in "csv-table" directive: - string with NUL bytes - <literal_block xml:space="preserve"> - .. csv-table:: bad encoding - :file: %s - :encoding: latin-1 - <paragraph> - (7- and 8-bit text encoded as UTF-16 has lots of null/zero bytes.) -""" % utf_16_csv], -["""\ -.. csv-table:: good encoding - :file: %s - :encoding: utf-16 - :header-rows: 1 -""" % utf_16_csv, -u"""\ -<document source="test data"> - <table> - <title> - good encoding - <tgroup cols="3"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <colspec colwidth="33"> - <thead> - <row> - <entry> - <paragraph> - Treat - <entry> - <paragraph> - Quantity - <entry> - <paragraph> - Description - <tbody> - <row> - <entry> - <paragraph> - Albatr\u00b0\u00df - <entry> - <paragraph> - 2.99 - <entry> - <paragraph> - \u00a1On a \u03c3\u03c4\u03b9\u03ba! - <row> - <entry> - <paragraph> - Crunchy Frog - <entry> - <paragraph> - 1.49 - <entry> - <paragraph> - If we took the b\u00f6nes out, it wouldn\u2019t be - crunchy, now would it? - <row> - <entry> - <paragraph> - Gannet Ripple - <entry> - <paragraph> - 1.99 - <entry> - <paragraph> - \u00bfOn a \u03c3\u03c4\u03b9\u03ba? -"""], -["""\ -.. csv-table:: no CSV data - :file: %s -""" % empty_txt, -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - No table data detected in CSV file. - <literal_block xml:space="preserve"> - .. csv-table:: no CSV data - :file: %s -""" % empty_txt], -] - -totest['list-table'] = [ -["""\ -.. list-table:: list table with integral header - :widths: 10 20 30 - :header-rows: 1 - :stub-columns: 1 - - * - Treat - - Quantity - - Description - * - Albatross - - 2.99 - - On a stick! - * - Crunchy Frog - - 1.49 - - If we took the bones out, it wouldn\'t be - crunchy, now would it? - * - Gannet Ripple - - 1.99 - - On a stick! -""", -"""\ -<document source="test data"> - <table> - <title> - list table with integral header - <tgroup cols="3"> - <colspec colwidth="10" stub="1"> - <colspec colwidth="20"> - <colspec colwidth="30"> - <thead> - <row> - <entry> - <paragraph> - Treat - <entry> - <paragraph> - Quantity - <entry> - <paragraph> - Description - <tbody> - <row> - <entry> - <paragraph> - Albatross - <entry> - <paragraph> - 2.99 - <entry> - <paragraph> - On a stick! - <row> - <entry> - <paragraph> - Crunchy Frog - <entry> - <paragraph> - 1.49 - <entry> - <paragraph> - If we took the bones out, it wouldn\'t be - crunchy, now would it? - <row> - <entry> - <paragraph> - Gannet Ripple - <entry> - <paragraph> - 1.99 - <entry> - <paragraph> - On a stick! -"""], -["""\ -.. list-table:: - - not a bullet list -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error parsing content block for the "list-table" directive: exactly one bullet list expected. - <literal_block xml:space="preserve"> - .. list-table:: - \n\ - not a bullet list -"""], -["""\ -.. list-table:: - - * not a second-level bullet list -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error parsing content block for the "list-table" directive: two-level bullet list expected, but row 1 does not contain a second-level bullet list. - <literal_block xml:space="preserve"> - .. list-table:: - \n\ - * not a second-level bullet list -"""], -["""\ -.. list-table:: - - * - columns not uniform - * - first row has one, - - second row has two -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error parsing content block for the "list-table" directive: uniform two-level bullet list expected, but row 2 does not contain the same number of items as row 1 (2 vs 1). - <literal_block xml:space="preserve"> - .. list-table:: - \n\ - * - columns not uniform - * - first row has one, - - second row has two -"""], -["""\ -.. list-table:: - :widths: 10 20 - - * - ":widths:" option doesn't match columns -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - "list-table" widths do not match the number of columns in table (1). - <literal_block xml:space="preserve"> - .. list-table:: - :widths: 10 20 - \n\ - * - ":widths:" option doesn\'t match columns -"""], -["""\ -.. list-table:: - :stub-columns: 3 - - * - column 1 - - column 2 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - 3 stub column(s) specified but only 2 columns(s) of data supplied ("list-table" directive). - <literal_block xml:space="preserve"> - .. list-table:: - :stub-columns: 3 - \n\ - * - column 1 - - column 2 -"""], -["""\ -.. list-table:: - :stub-columns: 2 - - * - column 1 - - column 2 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Insufficient data supplied (2 columns(s)); no data remaining for table body, required by "list-table" directive. - <literal_block xml:space="preserve"> - .. list-table:: - :stub-columns: 2 - \n\ - * - column 1 - - column 2 -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_target_notes.py b/docutils/test/test_parsers/test_rst/test_directives/test_target_notes.py deleted file mode 100755 index 18dc1d207..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_target_notes.py +++ /dev/null @@ -1,64 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the target-notes directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['target-notes'] = [ -["""\ -.. target-notes:: -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.references.TargetNotes - .details: -"""], -["""\ -.. target-notes:: :class: custom -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.references.TargetNotes - .details: - class: ['custom'] -"""], -["""\ -.. target-notes:: - :class: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "target-notes" directive: - invalid option value: (option: "class"; value: None) - argument required but none supplied. - <literal_block xml:space="preserve"> - .. target-notes:: - :class: -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_test_directives.py b/docutils/test/test_parsers/test_rst/test_directives/test_test_directives.py deleted file mode 100755 index b90b26473..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_test_directives.py +++ /dev/null @@ -1,208 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for misc.py test directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['test_directives'] = [ -["""\ -.. reStructuredText-test-directive:: - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=[], options={}, content: None - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive :: - -An optional space before the "::". -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=[], options={}, content: None - <paragraph> - An optional space before the "::". -"""], -["""\ -.. reStructuredText-test-directive:: argument - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=['argument'], options={}, content: None - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: argument - :option: value - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=['argument'], options={'option': 'value'}, content: None - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: :option: value - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=[], options={'option': 'value'}, content: None - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: :option: - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "reStructuredText-test-directive" directive: - invalid option value: (option: "option"; value: None) - argument required but none supplied. - <literal_block xml:space="preserve"> - .. reStructuredText-test-directive:: :option: - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: - - Directive block contains one paragraph, with a blank line before. - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=[], options={}, content: - <literal_block xml:space="preserve"> - Directive block contains one paragraph, with a blank line before. - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: - - - Directive block contains one paragraph, with two blank lines before. - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=[], options={}, content: - <literal_block xml:space="preserve"> - Directive block contains one paragraph, with two blank lines before. - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: - Directive block contains one paragraph, no blank line before. - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=['Directive block contains one paragraph, no blank line before.'], options={}, content: None - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: - block -no blank line. - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=['block'], options={}, content: None - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - no blank line. - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: argument - :option: * value1 - * value2 - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=['argument'], options={'option': '* value1\\n* value2'}, content: None - <paragraph> - Paragraph. -"""], -["""\ -.. reStructuredText-test-directive:: - - Directive \\block \\*contains* \\\\backslashes. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Directive processed. Type="reStructuredText-test-directive", arguments=[], options={}, content: - <literal_block xml:space="preserve"> - Directive \\block \\*contains* \\\\backslashes. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_topics.py b/docutils/test/test_parsers/test_rst/test_directives/test_topics.py deleted file mode 100755 index 4d0fae27b..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_topics.py +++ /dev/null @@ -1,240 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for the "topic" directive. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['topics'] = [ -["""\ -.. topic:: -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "topic" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. topic:: -"""], -["""\ -.. topic:: Title -""", -"""\ -<document source="test data"> - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Content block expected for the "topic" directive; none found. - <literal_block xml:space="preserve"> - .. topic:: Title -"""], -["""\ -.. topic:: Title - - Body. -""", -"""\ -<document source="test data"> - <topic> - <title> - Title - <paragraph> - Body. -"""], -["""\ -.. topic:: - - Title - - Body. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "topic" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. topic:: - \n\ - Title - \n\ - Body. -"""], -["""\ -.. topic:: Title - Body. -""", -"""\ -<document source="test data"> - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Content block expected for the "topic" directive; none found. - <literal_block xml:space="preserve"> - .. topic:: Title - Body. -"""], -["""\ -.. topic:: - - Title - Body. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "topic" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. topic:: - \n\ - Title - Body. -"""], -["""\ -.. topic:: Title - - .. topic:: Nested - - Body. -""", -"""\ -<document source="test data"> - <topic> - <title> - Title - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - The "topic" directive may not be used within topics or body elements. - <literal_block xml:space="preserve"> - .. topic:: Nested - \n\ - Body. -"""], -["""\ -.. topic:: Title - - .. topic:: Nested - - Body. - More. -""", -"""\ -<document source="test data"> - <topic> - <title> - Title - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - The "topic" directive may not be used within topics or body elements. - <literal_block xml:space="preserve"> - .. topic:: Nested - \n\ - Body. - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - More. -"""], -["""\ -.. topic:: Title - - .. topic:: Nested - - Body. - - More. - -More. -""", -"""\ -<document source="test data"> - <topic> - <title> - Title - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - The "topic" directive may not be used within topics or body elements. - <literal_block xml:space="preserve"> - .. topic:: Nested - \n\ - Body. - <paragraph> - More. - <paragraph> - More. -"""], -["""\ -.. topic:: First - - Body - -.. topic:: Second - - Body. -""", -"""\ -<document source="test data"> - <topic> - <title> - First - <paragraph> - Body - <topic> - <title> - Second - <paragraph> - Body. -"""], -["""\ -.. sidebar:: Title - :subtitle: Outer - - .. topic:: Nested - - Body. - - More. - -More. -""", -"""\ -<document source="test data"> - <sidebar> - <title> - Title - <subtitle> - Outer - <topic> - <title> - Nested - <paragraph> - Body. - <paragraph> - More. - <paragraph> - More. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py b/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py deleted file mode 100755 index bd028cf42..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py +++ /dev/null @@ -1,172 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for misc.py "unicode" directive. -""" - -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['unicode'] = [ -[""" -Insert an em-dash (|mdash|), a copyright symbol (|copy|), a non-breaking -space (|nbsp|), a backwards-not-equals (|bne|), and a captial omega (|Omega|). - -.. |mdash| unicode:: 0x02014 -.. |copy| unicode:: \\u00A9 -.. |nbsp| unicode::   -.. |bne| unicode:: U0003D U020E5 -.. |Omega| unicode:: U+003A9 -""", -u"""\ -<document source="test data"> - <paragraph> - Insert an em-dash ( - <substitution_reference refname="mdash"> - mdash - ), a copyright symbol ( - <substitution_reference refname="copy"> - copy - ), a non-breaking - space ( - <substitution_reference refname="nbsp"> - nbsp - ), a backwards-not-equals ( - <substitution_reference refname="bne"> - bne - ), and a captial omega ( - <substitution_reference refname="Omega"> - Omega - ). - <substitution_definition names="mdash"> - \u2014 - <substitution_definition names="copy"> - \u00A9 - <substitution_definition names="nbsp"> - \u00A0 - <substitution_definition names="bne"> - = - \u20e5 - <substitution_definition names="Omega"> - \u03a9 -"""], -[""" -Bad input: - -.. |empty| unicode:: -.. |empty too| unicode:: .. comment doesn't count as content -.. |not hex| unicode:: 0xHEX -.. |not all hex| unicode:: UABCX -.. unicode:: not in a substitution definition -""", -"""\ -<document source="test data"> - <paragraph> - Bad input: - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Error in "unicode" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - unicode:: - <system_message level="2" line="4" source="test data" type="WARNING"> - <paragraph> - Substitution definition "empty" empty or invalid. - <literal_block xml:space="preserve"> - .. |empty| unicode:: - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Substitution definition "empty too" empty or invalid. - <literal_block xml:space="preserve"> - .. |empty too| unicode:: .. comment doesn't count as content - <substitution_definition names="not\ hex"> - 0xHEX - <substitution_definition names="not\ all\ hex"> - UABCX - <system_message level="3" line="8" source="test data" type="ERROR"> - <paragraph> - Invalid context: the "unicode" directive can only be used within a substitution definition. - <literal_block xml:space="preserve"> - .. unicode:: not in a substitution definition -"""], -[""" -Testing comments and extra text. - -Copyright |copy| 2003, |BogusMegaCorp (TM)|. - -.. |copy| unicode:: 0xA9 .. copyright sign -.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign -""", -u"""\ -<document source="test data"> - <paragraph> - Testing comments and extra text. - <paragraph> - Copyright - <substitution_reference refname="copy"> - copy - 2003, - <substitution_reference refname="BogusMegaCorp (TM)"> - BogusMegaCorp (TM) - . - <substitution_definition names="copy"> - \u00A9 - <substitution_definition names="BogusMegaCorp\ (TM)"> - BogusMegaCorp - \u2122 -"""], -[""" -.. |too big for int| unicode:: 0x111111111111111111 -.. |too big for unicode| unicode:: 0x11111111 -""", -"""\ -<document source="test data"> - <system_message level="3" line="2" source="test data" type="ERROR"> - <paragraph> - Invalid character code: 0x111111111111111111 - ValueError: %s - <literal_block xml:space="preserve"> - unicode:: 0x111111111111111111 - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Substitution definition "too big for int" empty or invalid. - <literal_block xml:space="preserve"> - .. |too big for int| unicode:: 0x111111111111111111 - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Invalid character code: 0x11111111 - %s - <literal_block xml:space="preserve"> - unicode:: 0x11111111 - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Substitution definition "too big for unicode" empty or invalid. - <literal_block xml:space="preserve"> - .. |too big for unicode| unicode:: 0x11111111 -""" % ([DocutilsTestSupport.exception_data( - 'unichr(int("111111111111111111", 16))')[0], - 'code too large (%s)' % DocutilsTestSupport.exception_data( - 'unichr(int("111111111111111111", 16))')[0]] - [isinstance(DocutilsTestSupport.exception_data( - 'unichr(int("111111111111111111", 16))')[0], OverflowError)], - DocutilsTestSupport.exception_data('unichr(int("11111111", 16))')[2])] -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_unknown.py b/docutils/test/test_parsers/test_rst/test_directives/test_unknown.py deleted file mode 100755 index 3c859faa3..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_unknown.py +++ /dev/null @@ -1,67 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for unknown directives. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['unknown'] = [ -["""\ -.. reStructuredText-unknown-directive:: - -.. reStructuredText-unknown-directive:: argument - -.. reStructuredText-unknown-directive:: - block -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - No directive entry for "reStructuredText-unknown-directive" in module "docutils.parsers.rst.languages.en". - Trying "reStructuredText-unknown-directive" as canonical directive name. - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown directive type "reStructuredText-unknown-directive". - <literal_block xml:space="preserve"> - .. reStructuredText-unknown-directive:: - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - No directive entry for "reStructuredText-unknown-directive" in module "docutils.parsers.rst.languages.en". - Trying "reStructuredText-unknown-directive" as canonical directive name. - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Unknown directive type "reStructuredText-unknown-directive". - <literal_block xml:space="preserve"> - .. reStructuredText-unknown-directive:: argument - <system_message level="1" line="5" source="test data" type="INFO"> - <paragraph> - No directive entry for "reStructuredText-unknown-directive" in module "docutils.parsers.rst.languages.en". - Trying "reStructuredText-unknown-directive" as canonical directive name. - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Unknown directive type "reStructuredText-unknown-directive". - <literal_block xml:space="preserve"> - .. reStructuredText-unknown-directive:: - block -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_directives/utf-16.csv b/docutils/test/test_parsers/test_rst/test_directives/utf-16.csv Binary files differdeleted file mode 100644 index ba60d155e..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/utf-16.csv +++ /dev/null diff --git a/docutils/test/test_parsers/test_rst/test_doctest_blocks.py b/docutils/test/test_parsers/test_rst/test_doctest_blocks.py deleted file mode 100755 index c9637c6d6..000000000 --- a/docutils/test/test_parsers/test_rst/test_doctest_blocks.py +++ /dev/null @@ -1,74 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['doctest_blocks'] = [ -["""\ -Paragraph. - ->>> print "Doctest block." -Doctest block. - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <doctest_block xml:space="preserve"> - >>> print "Doctest block." - Doctest block. - <paragraph> - Paragraph. -"""], -["""\ -Paragraph. - ->>> print " Indented output." - Indented output. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <doctest_block xml:space="preserve"> - >>> print " Indented output." - Indented output. -"""], -["""\ -Paragraph. - - >>> print " Indented block & output." - Indented block & output. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <block_quote> - <doctest_block xml:space="preserve"> - >>> print " Indented block & output." - Indented block & output. -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_east_asian_text.py b/docutils/test/test_parsers/test_rst/test_east_asian_text.py deleted file mode 100755 index 1ac27743e..000000000 --- a/docutils/test/test_parsers/test_rst/test_east_asian_text.py +++ /dev/null @@ -1,324 +0,0 @@ -#! /usr/bin/env python -# -*- coding: utf-8 -*- - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for East Asian text with double-width characters. -""" - -from __init__ import DocutilsTestSupport - -import unicodedata -try: - east_asian_width = unicodedata.east_asian_width -except AttributeError: - east_asian_width = None - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -if not east_asian_width: - print ('test_east_asian_text.py tests skipped; ' - 'Python 2.4 or higher required.') -else: - totest['double-width'] = [ -[u"""\ -タイトル1 -========= - -タイトル2 -======== -""", -u"""\ -<document source="test data"> - <section ids="id1" names="タイトル1"> - <title> - タイトル1 - <section ids="id2" names="タイトル2"> - <title> - タイトル2 - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Title underline too short. - <literal_block xml:space="preserve"> - タイトル2 - ======== -"""], -[ur""" -+-----------------------+ -| * ヒョウ:ダイ1ギョウ | -| * ダイ2ギョウ | -+-----------------------+ -| \* ダイ1ギョウ | -| * ダイ2ギョウ | -+-----------------------+ -""", -u"""\ -<document source="test data"> - <table> - <tgroup cols="1"> - <colspec colwidth="23"> - <tbody> - <row> - <entry> - <bullet_list bullet="*"> - <list_item> - <paragraph> - ヒョウ:ダイ1ギョウ - <list_item> - <paragraph> - ダイ2ギョウ - <row> - <entry> - <paragraph> - * ダイ1ギョウ - * ダイ2ギョウ -"""], -[u"""\ -Complex spanning pattern (no edge knows all rows/cols): - -+--------+---------------------+ -| 北西・ | 北・北æ±ã‚»ãƒ« | -| 西セル +--------------+------+ -| | 真んä¸ã®ã‚»ãƒ« | æ±ãƒ» | -+--------+--------------+ å—æ± | -| å—西・å—セル | セル | -+-----------------------+------+ -""", -u"""\ -<document source="test data"> - <paragraph> - Complex spanning pattern (no edge knows all rows/cols): - <table> - <tgroup cols="3"> - <colspec colwidth="8"> - <colspec colwidth="14"> - <colspec colwidth="6"> - <tbody> - <row> - <entry morerows="1"> - <paragraph> - 北西・ - 西セル - <entry morecols="1"> - <paragraph> - 北・北æ±ã‚»ãƒ« - <row> - <entry> - <paragraph> - 真んä¸ã®ã‚»ãƒ« - <entry morerows="1"> - <paragraph> - æ±ãƒ» - å—æ± - セル - <row> - <entry morecols="1"> - <paragraph> - å—西・å—セル -"""], -[u"""\ -========= ========= -ダイ1ラン ダイ2ラン -========= ========= - -======== ========= -ダイ1ラン ダイ2ラン -======== ========= -""", -u"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="9"> - <colspec colwidth="9"> - <tbody> - <row> - <entry> - <paragraph> - ダイ1ラン - <entry> - <paragraph> - ダイ2ラン - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Malformed table. - Text in column margin at line offset 1. - <literal_block xml:space="preserve"> - ======== ========= - ダイ1ラン ダイ2ラン - ======== ========= -"""], -[u"""\ -Some ambiguous-width characters: - -= =================================== -© copyright sign -® registered sign -« left pointing guillemet -» right pointing guillemet -– en-dash -— em-dash -‘ single turned comma quotation mark -’ single comma quotation mark -‚ low single comma quotation mark -“ double turned comma quotation mark -†double comma quotation mark -„ low double comma quotation mark -†dagger -‡ double dagger -… ellipsis -â„¢ trade mark sign -⇔ left-right double arrow -= =================================== -""", -u"""\ -<document source="test data"> - <paragraph> - Some ambiguous-width characters: - <table> - <tgroup cols="2"> - <colspec colwidth="1"> - <colspec colwidth="35"> - <tbody> - <row> - <entry> - <paragraph> - \xa9 - <entry> - <paragraph> - copyright sign - <row> - <entry> - <paragraph> - \xae - <entry> - <paragraph> - registered sign - <row> - <entry> - <paragraph> - \xab - <entry> - <paragraph> - left pointing guillemet - <row> - <entry> - <paragraph> - \xbb - <entry> - <paragraph> - right pointing guillemet - <row> - <entry> - <paragraph> - \\u2013 - <entry> - <paragraph> - en-dash - <row> - <entry> - <paragraph> - \\u2014 - <entry> - <paragraph> - em-dash - <row> - <entry> - <paragraph> - \\u2018 - <entry> - <paragraph> - single turned comma quotation mark - <row> - <entry> - <paragraph> - \\u2019 - <entry> - <paragraph> - single comma quotation mark - <row> - <entry> - <paragraph> - \\u201a - <entry> - <paragraph> - low single comma quotation mark - <row> - <entry> - <paragraph> - \\u201c - <entry> - <paragraph> - double turned comma quotation mark - <row> - <entry> - <paragraph> - \\u201d - <entry> - <paragraph> - double comma quotation mark - <row> - <entry> - <paragraph> - \\u201e - <entry> - <paragraph> - low double comma quotation mark - <row> - <entry> - <paragraph> - \\u2020 - <entry> - <paragraph> - dagger - <row> - <entry> - <paragraph> - \\u2021 - <entry> - <paragraph> - double dagger - <row> - <entry> - <paragraph> - \\u2026 - <entry> - <paragraph> - ellipsis - <row> - <entry> - <paragraph> - \\u2122 - <entry> - <paragraph> - trade mark sign - <row> - <entry> - <paragraph> - \\u21d4 - <entry> - <paragraph> - left-right double arrow -"""], -] -''' -[u"""\ -""", -u"""\ -"""], -''' - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_enumerated_lists.py b/docutils/test/test_parsers/test_rst/test_enumerated_lists.py deleted file mode 100755 index 0375b33e9..000000000 --- a/docutils/test/test_parsers/test_rst/test_enumerated_lists.py +++ /dev/null @@ -1,908 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['enumerated_lists'] = [ -["""\ -1. Item one. - -2. Item two. - -3. Item three. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. -"""], -["""\ -No blank lines betwen items: - -1. Item one. -2. Item two. -3. Item three. -""", -"""\ -<document source="test data"> - <paragraph> - No blank lines betwen items: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. -"""], -["""\ -1. -empty item above, no blank line -""", -"""\ -<document source="test data"> - <paragraph> - 1. - empty item above, no blank line -"""], -["""\ -Scrambled: - -3. Item three. - -2. Item two. - -1. Item one. - -3. Item three. -2. Item two. -1. Item one. -""", -"""\ -<document source="test data"> - <paragraph> - Scrambled: - <enumerated_list enumtype="arabic" prefix="" start="3" suffix="."> - <list_item> - <paragraph> - Item three. - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "3" (ordinal 3) - <enumerated_list enumtype="arabic" prefix="" start="2" suffix="."> - <list_item> - <paragraph> - Item two. - <system_message level="1" line="5" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "2" (ordinal 2) - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <paragraph> - 3. Item three. - 2. Item two. - 1. Item one. -"""], -["""\ -Skipping item 3: - -1. Item 1. -2. Item 2. -4. Item 4. -""", -"""\ -<document source="test data"> - <paragraph> - Skipping item 3: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item 1. - <system_message level="2" line="4" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <paragraph> - 2. Item 2. - 4. Item 4. -"""], -["""\ -Start with non-ordinal-1: - -0. Item zero. -1. Item one. -2. Item two. -3. Item three. - -And again: - -2. Item two. -3. Item three. -""", -"""\ -<document source="test data"> - <paragraph> - Start with non-ordinal-1: - <enumerated_list enumtype="arabic" prefix="" start="0" suffix="."> - <list_item> - <paragraph> - Item zero. - <list_item> - <paragraph> - Item one. - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "0" (ordinal 0) - <paragraph> - And again: - <enumerated_list enumtype="arabic" prefix="" start="2" suffix="."> - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. - <system_message level="1" line="10" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "2" (ordinal 2) -"""], -["""\ -1. Item one: line 1, - line 2. -2. Item two: line 1, - line 2. -3. Item three: paragraph 1, line 1, - line 2. - - Paragraph 2. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one: line 1, - line 2. - <list_item> - <paragraph> - Item two: line 1, - line 2. - <list_item> - <paragraph> - Item three: paragraph 1, line 1, - line 2. - <paragraph> - Paragraph 2. -"""], -["""\ -Different enumeration sequences: - -1. Item 1. -2. Item 2. -3. Item 3. - -A. Item A. -B. Item B. -C. Item C. - -a. Item a. -b. Item b. -c. Item c. - -I. Item I. -II. Item II. -III. Item III. - -i. Item i. -ii. Item ii. -iii. Item iii. -""", -"""\ -<document source="test data"> - <paragraph> - Different enumeration sequences: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item 1. - <list_item> - <paragraph> - Item 2. - <list_item> - <paragraph> - Item 3. - <enumerated_list enumtype="upperalpha" prefix="" suffix="."> - <list_item> - <paragraph> - Item A. - <list_item> - <paragraph> - Item B. - <list_item> - <paragraph> - Item C. - <enumerated_list enumtype="loweralpha" prefix="" suffix="."> - <list_item> - <paragraph> - Item a. - <list_item> - <paragraph> - Item b. - <list_item> - <paragraph> - Item c. - <enumerated_list enumtype="upperroman" prefix="" suffix="."> - <list_item> - <paragraph> - Item I. - <list_item> - <paragraph> - Item II. - <list_item> - <paragraph> - Item III. - <enumerated_list enumtype="lowerroman" prefix="" suffix="."> - <list_item> - <paragraph> - Item i. - <list_item> - <paragraph> - Item ii. - <list_item> - <paragraph> - Item iii. -"""], -["""\ -Bad Roman numerals: - -i. i - -ii. ii - -iii. iii - -iiii. iiii - second line - -(LCD) is an acronym made up of Roman numerals - -(livid) is a word made up of Roman numerals - -(CIVIL) is another such word - -(I) I - -(IVXLCDM) IVXLCDM -""", -"""\ -<document source="test data"> - <paragraph> - Bad Roman numerals: - <enumerated_list enumtype="lowerroman" prefix="" suffix="."> - <list_item> - <paragraph> - i - <list_item> - <paragraph> - ii - <list_item> - <paragraph> - iii - <definition_list> - <definition_list_item> - <term> - iiii. iiii - <definition> - <paragraph> - second line - <paragraph> - (LCD) is an acronym made up of Roman numerals - <paragraph> - (livid) is a word made up of Roman numerals - <paragraph> - (CIVIL) is another such word - <enumerated_list enumtype="upperroman" prefix="(" suffix=")"> - <list_item> - <paragraph> - I - <paragraph> - (IVXLCDM) IVXLCDM -"""], -["""\ -Potentially ambiguous cases: - -A. Item A. -B. Item B. -C. Item C. - -I. Item I. -II. Item II. -III. Item III. - -a. Item a. -b. Item b. -c. Item c. - -i. Item i. -ii. Item ii. -iii. Item iii. - -Phew! Safe! -""", -"""\ -<document source="test data"> - <paragraph> - Potentially ambiguous cases: - <enumerated_list enumtype="upperalpha" prefix="" suffix="."> - <list_item> - <paragraph> - Item A. - <list_item> - <paragraph> - Item B. - <list_item> - <paragraph> - Item C. - <enumerated_list enumtype="upperroman" prefix="" suffix="."> - <list_item> - <paragraph> - Item I. - <list_item> - <paragraph> - Item II. - <list_item> - <paragraph> - Item III. - <enumerated_list enumtype="loweralpha" prefix="" suffix="."> - <list_item> - <paragraph> - Item a. - <list_item> - <paragraph> - Item b. - <list_item> - <paragraph> - Item c. - <enumerated_list enumtype="lowerroman" prefix="" suffix="."> - <list_item> - <paragraph> - Item i. - <list_item> - <paragraph> - Item ii. - <list_item> - <paragraph> - Item iii. - <paragraph> - Phew! Safe! -"""], -["""\ -Definitely ambiguous: - -A. Item A. -B. Item B. -C. Item C. -D. Item D. -E. Item E. -F. Item F. -G. Item G. -H. Item H. -I. Item I. -II. Item II. -III. Item III. - -a. Item a. -b. Item b. -c. Item c. -d. Item d. -e. Item e. -f. Item f. -g. Item g. -h. Item h. -i. Item i. -ii. Item ii. -iii. Item iii. -""", -"""\ -<document source="test data"> - <paragraph> - Definitely ambiguous: - <enumerated_list enumtype="upperalpha" prefix="" suffix="."> - <list_item> - <paragraph> - Item A. - <list_item> - <paragraph> - Item B. - <list_item> - <paragraph> - Item C. - <list_item> - <paragraph> - Item D. - <list_item> - <paragraph> - Item E. - <list_item> - <paragraph> - Item F. - <list_item> - <paragraph> - Item G. - <list_item> - <paragraph> - Item H. - <system_message level="2" line="11" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <enumerated_list enumtype="upperroman" prefix="" suffix="."> - <list_item> - <paragraph> - Item I. - <list_item> - <paragraph> - Item II. - <list_item> - <paragraph> - Item III. - <enumerated_list enumtype="loweralpha" prefix="" suffix="."> - <list_item> - <paragraph> - Item a. - <list_item> - <paragraph> - Item b. - <list_item> - <paragraph> - Item c. - <list_item> - <paragraph> - Item d. - <list_item> - <paragraph> - Item e. - <list_item> - <paragraph> - Item f. - <list_item> - <paragraph> - Item g. - <list_item> - <paragraph> - Item h. - <system_message level="2" line="23" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <enumerated_list enumtype="lowerroman" prefix="" suffix="."> - <list_item> - <paragraph> - Item i. - <list_item> - <paragraph> - Item ii. - <list_item> - <paragraph> - Item iii. -"""], -["""\ -Different enumeration formats: - -1. Item 1. -2. Item 2. -3. Item 3. - -1) Item 1). -2) Item 2). -3) Item 3). - -(1) Item (1). -(2) Item (2). -(3) Item (3). -""", -"""\ -<document source="test data"> - <paragraph> - Different enumeration formats: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item 1. - <list_item> - <paragraph> - Item 2. - <list_item> - <paragraph> - Item 3. - <enumerated_list enumtype="arabic" prefix="" suffix=")"> - <list_item> - <paragraph> - Item 1). - <list_item> - <paragraph> - Item 2). - <list_item> - <paragraph> - Item 3). - <enumerated_list enumtype="arabic" prefix="(" suffix=")"> - <list_item> - <paragraph> - Item (1). - <list_item> - <paragraph> - Item (2). - <list_item> - <paragraph> - Item (3). -"""], -["""\ -Nested enumerated lists: - -1. Item 1. - - A) Item A). - B) Item B). - C) Item C). - -2. Item 2. - - (a) Item (a). - - I) Item I). - II) Item II). - III) Item III). - - (b) Item (b). - - (c) Item (c). - - (i) Item (i). - (ii) Item (ii). - (iii) Item (iii). - -3. Item 3. -""", -"""\ -<document source="test data"> - <paragraph> - Nested enumerated lists: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item 1. - <enumerated_list enumtype="upperalpha" prefix="" suffix=")"> - <list_item> - <paragraph> - Item A). - <list_item> - <paragraph> - Item B). - <list_item> - <paragraph> - Item C). - <list_item> - <paragraph> - Item 2. - <enumerated_list enumtype="loweralpha" prefix="(" suffix=")"> - <list_item> - <paragraph> - Item (a). - <enumerated_list enumtype="upperroman" prefix="" suffix=")"> - <list_item> - <paragraph> - Item I). - <list_item> - <paragraph> - Item II). - <list_item> - <paragraph> - Item III). - <list_item> - <paragraph> - Item (b). - <list_item> - <paragraph> - Item (c). - <enumerated_list enumtype="lowerroman" prefix="(" suffix=")"> - <list_item> - <paragraph> - Item (i). - <list_item> - <paragraph> - Item (ii). - <list_item> - <paragraph> - Item (iii). - <list_item> - <paragraph> - Item 3. -"""], -[u"""\ -A. Einstein was a great influence on -B. Physicist, who was a colleague of -C. Chemist. They all worked in -Princeton, NJ. - -Using a non-breaking space as a workaround: - -A.\u00a0Einstein was a great influence on -B. Physicist, who was a colleague of -C. Chemist. They all worked in -Princeton, NJ. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="upperalpha" prefix="" suffix="."> - <list_item> - <paragraph> - Einstein was a great influence on - <list_item> - <paragraph> - Physicist, who was a colleague of - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <paragraph> - C. Chemist. They all worked in - Princeton, NJ. - <paragraph> - Using a non-breaking space as a workaround: - <paragraph> - A.\xa0Einstein was a great influence on - B. Physicist, who was a colleague of - C. Chemist. They all worked in - Princeton, NJ. -"""], -["""\ -1. Item one: line 1, - line 2. -2. Item two: line 1, - line 2. -3. Item three: paragraph 1, line 1, - line 2. - - Paragraph 2. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one: line 1, - line 2. - <list_item> - <paragraph> - Item two: line 1, - <system_message level="2" line="4" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <block_quote> - <paragraph> - line 2. - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Block quote ends without a blank line; unexpected unindent. - <enumerated_list enumtype="arabic" prefix="" start="3" suffix="."> - <list_item> - <paragraph> - Item three: paragraph 1, line 1, - <system_message level="1" line="5" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "3" (ordinal 3) - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <block_quote> - <paragraph> - line 2. - <block_quote> - <paragraph> - Paragraph 2. -"""], -["""\ -1. Item one. - -#. Item two. - -#. Item three. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. -"""], -["""\ -a. Item one. -#. Item two. -#. Item three. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="loweralpha" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. -"""], -["""\ -i. Item one. -ii. Item two. -#. Item three. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="lowerroman" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. -"""], -["""\ -#. Item one. -#. Item two. -#. Item three. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. -"""], -["""\ -1. Item one. -#. Item two. -3. Item three. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item one. - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <paragraph> - #. Item two. - 3. Item three. -"""], -["""\ -z. -x -""", -"""\ -<document source="test data"> - <paragraph> - z. - x -"""], -["""\ -3-space indent, with a trailing space: - -1. \n\ - foo - -3-space indent, no trailing space: - -1. - foo - -2-space indent: - -1. - foo - -1-space indent: - -1. - foo - -0-space indent, not a list item: - -1. -foo - -No item content: - -1. -""", -"""\ -<document source="test data"> - <paragraph> - 3-space indent, with a trailing space: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - foo - <paragraph> - 3-space indent, no trailing space: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - foo - <paragraph> - 2-space indent: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - foo - <paragraph> - 1-space indent: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - foo - <paragraph> - 0-space indent, not a list item: - <paragraph> - 1. - foo - <paragraph> - No item content: - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_field_lists.py b/docutils/test/test_parsers/test_rst/test_field_lists.py deleted file mode 100755 index 2e715770c..000000000 --- a/docutils/test/test_parsers/test_rst/test_field_lists.py +++ /dev/null @@ -1,551 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['field_lists'] = [ -["""\ -One-liners: - -:Author: Me - -:Version: 1 - -:Date: 2001-08-11 - -:Parameter i: integer -""", -"""\ -<document source="test data"> - <paragraph> - One-liners: - <field_list> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - integer -"""], -["""\ -One-liners, no blank lines: - -:Author: Me -:Version: 1 -:Date: 2001-08-11 -:Parameter i: integer -""", -"""\ -<document source="test data"> - <paragraph> - One-liners, no blank lines: - <field_list> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - integer -"""], -["""\ -:field: -empty item above, no blank line -""", -"""\ -<document source="test data"> - <field_list> - <field> - <field_name> - field - <field_body> - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Field list ends without a blank line; unexpected unindent. - <paragraph> - empty item above, no blank line -"""], -["""\ -Field bodies starting on the next line: - -:Author: - Me -:Version: - 1 -:Date: - 2001-08-11 -:Parameter i: - integer -""", -"""\ -<document source="test data"> - <paragraph> - Field bodies starting on the next line: - <field_list> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - integer -"""], -["""\ -One-paragraph, multi-liners: - -:Authors: Me, - Myself, - and I -:Version: 1 - or so -:Date: 2001-08-11 - (Saturday) -:Parameter i: counter - (integer) -""", -"""\ -<document source="test data"> - <paragraph> - One-paragraph, multi-liners: - <field_list> - <field> - <field_name> - Authors - <field_body> - <paragraph> - Me, - Myself, - and I - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - or so - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - (Saturday) - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - counter - (integer) -"""], -["""\ -One-paragraph, multi-liners, not lined up: - -:Authors: Me, - Myself, - and I -:Version: 1 - or so -:Date: 2001-08-11 - (Saturday) -:Parameter i: counter - (integer) -""", -"""\ -<document source="test data"> - <paragraph> - One-paragraph, multi-liners, not lined up: - <field_list> - <field> - <field_name> - Authors - <field_body> - <paragraph> - Me, - Myself, - and I - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - or so - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - (Saturday) - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - counter - (integer) -"""], -["""\ -Multiple body elements: - -:Authors: - Me - - Myself - - I - -:Abstract: - This is a field list item's body, - containing multiple elements. - - Here's a literal block:: - - def f(x): - return x**2 + x - - Even nested field lists are possible: - - :Date: 2001-08-11 - :Day: Saturday - :Time: 15:07 -""", -"""\ -<document source="test data"> - <paragraph> - Multiple body elements: - <field_list> - <field> - <field_name> - Authors - <field_body> - <bullet_list bullet="-"> - <list_item> - <paragraph> - Me - <list_item> - <paragraph> - Myself - <list_item> - <paragraph> - I - <field> - <field_name> - Abstract - <field_body> - <paragraph> - This is a field list item's body, - containing multiple elements. - <paragraph> - Here's a literal block: - <literal_block xml:space="preserve"> - def f(x): - return x**2 + x - <paragraph> - Even nested field lists are possible: - <field_list> - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - <field> - <field_name> - Day - <field_body> - <paragraph> - Saturday - <field> - <field_name> - Time - <field_body> - <paragraph> - 15:07 -"""], -["""\ -Nested field lists on one line: - -:field1: :field2: :field3: body -:field4: :field5: :field6: body - :field7: body - :field8: body - :field9: body line 1 - body line 2 -""", -"""\ -<document source="test data"> - <paragraph> - Nested field lists on one line: - <field_list> - <field> - <field_name> - field1 - <field_body> - <field_list> - <field> - <field_name> - field2 - <field_body> - <field_list> - <field> - <field_name> - field3 - <field_body> - <paragraph> - body - <field> - <field_name> - field4 - <field_body> - <field_list> - <field> - <field_name> - field5 - <field_body> - <field_list> - <field> - <field_name> - field6 - <field_body> - <paragraph> - body - <field> - <field_name> - field7 - <field_body> - <paragraph> - body - <field> - <field_name> - field8 - <field_body> - <paragraph> - body - <field> - <field_name> - field9 - <field_body> - <paragraph> - body line 1 - body line 2 -"""], -["""\ -:Parameter i j k: multiple arguments -""", -"""\ -<document source="test data"> - <field_list> - <field> - <field_name> - Parameter i j k - <field_body> - <paragraph> - multiple arguments -"""], -["""\ -:Field *name* `with` **inline** ``markup``: inline markup in - field name is parsed. -""", -"""\ -<document source="test data"> - <field_list> - <field> - <field_name> - Field \n\ - <emphasis> - name - \n\ - <title_reference> - with - \n\ - <strong> - inline - \n\ - <literal> - markup - <field_body> - <paragraph> - inline markup in - field name is parsed. -"""], -["""\ -:Field name with *bad inline markup: should generate warning. -""", -"""\ -<document source="test data"> - <field_list> - <field> - <field_name> - Field name with \n\ - <problematic ids="id2" refid="id1"> - * - bad inline markup - <field_body> - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <paragraph> - should generate warning. -"""], -[r"""Some edge cases: - -:Empty: -:Author: Me -No blank line before this paragraph. - -: Field: marker must not begin with whitespace. - -:Field : marker must not end with whitespace. - -Field: marker is missing its open-colon. - -:Field marker is missing its close-colon. - -:Field\: names\: with\: colons\:: are possible. - -:\\Field\ names with backslashes\\: are possible, too. - -:\\: A backslash. - -:Not a\\\: field list. - -:Not a \: field list either. - -:\: Not a field list either. - -:\: - A definition list, not a field list. -""", -"""\ -<document source="test data"> - <paragraph> - Some edge cases: - <field_list> - <field> - <field_name> - Empty - <field_body> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Field list ends without a blank line; unexpected unindent. - <paragraph> - No blank line before this paragraph. - <paragraph> - : Field: marker must not begin with whitespace. - <paragraph> - :Field : marker must not end with whitespace. - <paragraph> - Field: marker is missing its open-colon. - <paragraph> - :Field marker is missing its close-colon. - <field_list> - <field> - <field_name> - Field: names: with: colons: - <field_body> - <paragraph> - are possible. - <field> - <field_name> - \\Field names with backslashes\\ - <field_body> - <paragraph> - are possible, too. - <field> - <field_name> - \\ - <field_body> - <paragraph> - A backslash. - <paragraph> - :Not a\\: field list. - <paragraph> - :Not a : field list either. - <paragraph> - :: Not a field list either. - <definition_list> - <definition_list_item> - <term> - :: - <definition> - <paragraph> - A definition list, not a field list. -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_footnotes.py b/docutils/test/test_parsers/test_rst/test_footnotes.py deleted file mode 100755 index cca255cbc..000000000 --- a/docutils/test/test_parsers/test_rst/test_footnotes.py +++ /dev/null @@ -1,332 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['footnotes'] = [ -["""\ -.. [1] This is a footnote. -""", -"""\ -<document source="test data"> - <footnote ids="id1" names="1"> - <label> - 1 - <paragraph> - This is a footnote. -"""], -["""\ -.. [1] This is a footnote - on multiple lines. -""", -"""\ -<document source="test data"> - <footnote ids="id1" names="1"> - <label> - 1 - <paragraph> - This is a footnote - on multiple lines. -"""], -["""\ -.. [1] This is a footnote - on multiple lines with more space. - -.. [2] This is a footnote - on multiple lines with less space. -""", -"""\ -<document source="test data"> - <footnote ids="id1" names="1"> - <label> - 1 - <paragraph> - This is a footnote - on multiple lines with more space. - <footnote ids="id2" names="2"> - <label> - 2 - <paragraph> - This is a footnote - on multiple lines with less space. -"""], -["""\ -.. [1] - This is a footnote on multiple lines - whose block starts on line 2. -""", -"""\ -<document source="test data"> - <footnote ids="id1" names="1"> - <label> - 1 - <paragraph> - This is a footnote on multiple lines - whose block starts on line 2. -"""], -["""\ -.. [1] - -That was an empty footnote. -""", -"""\ -<document source="test data"> - <footnote ids="id1" names="1"> - <label> - 1 - <paragraph> - That was an empty footnote. -"""], -["""\ -.. [1] -No blank line. -""", -"""\ -<document source="test data"> - <footnote ids="id1" names="1"> - <label> - 1 - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - No blank line. -"""], -] - -totest['auto_numbered_footnotes'] = [ -["""\ -[#]_ is the first auto-numbered footnote reference. -[#]_ is the second auto-numbered footnote reference. - -.. [#] Auto-numbered footnote 1. -.. [#] Auto-numbered footnote 2. -.. [#] Auto-numbered footnote 3. - -[#]_ is the third auto-numbered footnote reference. -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" ids="id1"> - is the first auto-numbered footnote reference. - <footnote_reference auto="1" ids="id2"> - is the second auto-numbered footnote reference. - <footnote auto="1" ids="id3"> - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" ids="id4"> - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" ids="id5"> - <paragraph> - Auto-numbered footnote 3. - <paragraph> - <footnote_reference auto="1" ids="id6"> - is the third auto-numbered footnote reference. -"""], -["""\ -[#third]_ is a reference to the third auto-numbered footnote. - -.. [#first] First auto-numbered footnote. -.. [#second] Second auto-numbered footnote. -.. [#third] Third auto-numbered footnote. - -[#second]_ is a reference to the second auto-numbered footnote. -[#first]_ is a reference to the first auto-numbered footnote. -[#third]_ is another reference to the third auto-numbered footnote. - -Here are some internal cross-references to the targets generated by -the footnotes: first_, second_, third_. -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" ids="id1" refname="third"> - is a reference to the third auto-numbered footnote. - <footnote auto="1" ids="first" names="first"> - <paragraph> - First auto-numbered footnote. - <footnote auto="1" ids="second" names="second"> - <paragraph> - Second auto-numbered footnote. - <footnote auto="1" ids="third" names="third"> - <paragraph> - Third auto-numbered footnote. - <paragraph> - <footnote_reference auto="1" ids="id2" refname="second"> - is a reference to the second auto-numbered footnote. - <footnote_reference auto="1" ids="id3" refname="first"> - is a reference to the first auto-numbered footnote. - <footnote_reference auto="1" ids="id4" refname="third"> - is another reference to the third auto-numbered footnote. - <paragraph> - Here are some internal cross-references to the targets generated by - the footnotes: \n\ - <reference name="first" refname="first"> - first - , \n\ - <reference name="second" refname="second"> - second - , \n\ - <reference name="third" refname="third"> - third - . -"""], -["""\ -Mixed anonymous and labelled auto-numbered footnotes: - -[#four]_ should be 4, [#]_ should be 1, -[#]_ should be 3, [#]_ is one too many, -[#two]_ should be 2, and [#six]_ doesn't exist. - -.. [#] Auto-numbered footnote 1. -.. [#two] Auto-numbered footnote 2. -.. [#] Auto-numbered footnote 3. -.. [#four] Auto-numbered footnote 4. -.. [#five] Auto-numbered footnote 5. -.. [#five] Auto-numbered footnote 5 again (duplicate). -""", -"""\ -<document source="test data"> - <paragraph> - Mixed anonymous and labelled auto-numbered footnotes: - <paragraph> - <footnote_reference auto="1" ids="id1" refname="four"> - should be 4, \n\ - <footnote_reference auto="1" ids="id2"> - should be 1, - <footnote_reference auto="1" ids="id3"> - should be 3, \n\ - <footnote_reference auto="1" ids="id4"> - is one too many, - <footnote_reference auto="1" ids="id5" refname="two"> - should be 2, and \n\ - <footnote_reference auto="1" ids="id6" refname="six"> - doesn't exist. - <footnote auto="1" ids="id7"> - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" ids="two" names="two"> - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" ids="id8"> - <paragraph> - Auto-numbered footnote 3. - <footnote auto="1" ids="four" names="four"> - <paragraph> - Auto-numbered footnote 4. - <footnote auto="1" dupnames="five" ids="five"> - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" dupnames="five" ids="id9"> - <system_message backrefs="id9" level="2" line="12" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "five". - <paragraph> - Auto-numbered footnote 5 again (duplicate). -"""], -["""\ -Mixed manually-numbered, anonymous auto-numbered, -and labelled auto-numbered footnotes: - -[#four]_ should be 4, [#]_ should be 2, -[1]_ is 1, [3]_ is 3, -[#]_ should be 6, [#]_ is one too many, -[#five]_ should be 5, and [#six]_ doesn't exist. - -.. [1] Manually-numbered footnote 1. -.. [#] Auto-numbered footnote 2. -.. [#four] Auto-numbered footnote 4. -.. [3] Manually-numbered footnote 3 -.. [#five] Auto-numbered footnote 5. -.. [#five] Auto-numbered footnote 5 again (duplicate). -.. [#] Auto-numbered footnote 6. -""", -"""\ -<document source="test data"> - <paragraph> - Mixed manually-numbered, anonymous auto-numbered, - and labelled auto-numbered footnotes: - <paragraph> - <footnote_reference auto="1" ids="id1" refname="four"> - should be 4, \n\ - <footnote_reference auto="1" ids="id2"> - should be 2, - <footnote_reference ids="id3" refname="1"> - 1 - is 1, \n\ - <footnote_reference ids="id4" refname="3"> - 3 - is 3, - <footnote_reference auto="1" ids="id5"> - should be 6, \n\ - <footnote_reference auto="1" ids="id6"> - is one too many, - <footnote_reference auto="1" ids="id7" refname="five"> - should be 5, and \n\ - <footnote_reference auto="1" ids="id8" refname="six"> - doesn't exist. - <footnote ids="id9" names="1"> - <label> - 1 - <paragraph> - Manually-numbered footnote 1. - <footnote auto="1" ids="id10"> - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" ids="four" names="four"> - <paragraph> - Auto-numbered footnote 4. - <footnote ids="id11" names="3"> - <label> - 3 - <paragraph> - Manually-numbered footnote 3 - <footnote auto="1" dupnames="five" ids="five"> - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" dupnames="five" ids="id12"> - <system_message backrefs="id12" level="2" line="14" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "five". - <paragraph> - Auto-numbered footnote 5 again (duplicate). - <footnote auto="1" ids="id13"> - <paragraph> - Auto-numbered footnote 6. -"""], -] - -totest['auto_symbol_footnotes'] = [ -["""\ -.. [*] This is an auto-symbol footnote. -""", -"""\ -<document source="test data"> - <footnote auto="*" ids="id1"> - <paragraph> - This is an auto-symbol footnote. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_functions.py b/docutils/test/test_parsers/test_rst/test_functions.py deleted file mode 100755 index e6694b2c5..000000000 --- a/docutils/test/test_parsers/test_rst/test_functions.py +++ /dev/null @@ -1,38 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -import unittest -from __init__ import DocutilsTestSupport -states = DocutilsTestSupport.states - - -class FuctionTests(unittest.TestCase): - - escaped = r'escapes: \*one, \\*two, \\\*three' - nulled = 'escapes: \x00*one, \x00\\*two, \x00\\\x00*three' - unescaped = r'escapes: *one, \*two, \*three' - - def test_escape2null(self): - nulled = states.escape2null(self.escaped) - self.assertEquals(nulled, self.nulled) - nulled = states.escape2null(self.escaped + '\\') - self.assertEquals(nulled, self.nulled + '\x00') - - def test_unescape(self): - unescaped = states.unescape(self.nulled) - self.assertEquals(unescaped, self.unescaped) - restored = states.unescape(self.nulled, 1) - self.assertEquals(restored, self.escaped) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_parsers/test_rst/test_inline_markup.py b/docutils/test/test_parsers/test_rst/test_inline_markup.py deleted file mode 100755 index 7185d723d..000000000 --- a/docutils/test/test_parsers/test_rst/test_inline_markup.py +++ /dev/null @@ -1,924 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for inline markup in docutils/parsers/rst/states.py. -Interpreted text tests are in a separate module, test_interpreted.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['emphasis'] = [ -["""\ -*emphasis* -""", -"""\ -<document source="test data"> - <paragraph> - <emphasis> - emphasis -"""], -["""\ -*emphasized sentence -across lines* -""", -"""\ -<document source="test data"> - <paragraph> - <emphasis> - emphasized sentence - across lines -"""], -["""\ -*emphasis without closing asterisk -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - * - emphasis without closing asterisk - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. -"""], -["""\ -'*emphasis*' and 1/*emphasis*/2 and 3-*emphasis*-4 and 5:*emphasis*:6 -but not '*' or '"*"' or x*2* or 2*x* or \\*args or * -or *the\\* *stars\\\\\\* *inside* - -(however, '*args' will trigger a warning and may be problematic) - -what about *this**? -""", -"""\ -<document source="test data"> - <paragraph> - ' - <emphasis> - emphasis - ' and 1/ - <emphasis> - emphasis - /2 and 3- - <emphasis> - emphasis - -4 and 5: - <emphasis> - emphasis - :6 - but not '*' or '"*"' or x*2* or 2*x* or *args or * - or \n\ - <emphasis> - the* *stars\* *inside - <paragraph> - (however, ' - <problematic ids="id2" refid="id1"> - * - args' will trigger a warning and may be problematic) - <system_message backrefs="id2" ids="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <paragraph> - what about \n\ - <emphasis> - this* - ? -"""], -["""\ -Emphasized asterisk: *\\** - -Emphasized double asterisk: *\\*** -""", -"""\ -<document source="test data"> - <paragraph> - Emphasized asterisk: \n\ - <emphasis> - * - <paragraph> - Emphasized double asterisk: \n\ - <emphasis> - ** -"""], -] - -totest['strong'] = [ -["""\ -**strong** -""", -"""\ -<document source="test data"> - <paragraph> - <strong> - strong -"""], -["""\ -(**strong**) but not (**) or '(** ' or x**2 or \\**kwargs or ** - -(however, '**kwargs' will trigger a warning and may be problematic) -""", -"""\ -<document source="test data"> - <paragraph> - ( - <strong> - strong - ) but not (**) or '(** ' or x**2 or **kwargs or ** - <paragraph> - (however, ' - <problematic ids="id2" refid="id1"> - ** - kwargs' will trigger a warning and may be problematic) - <system_message backrefs="id2" ids="id1" level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. -"""], -["""\ -Strong asterisk: ***** - -Strong double asterisk: ****** -""", -"""\ -<document source="test data"> - <paragraph> - Strong asterisk: \n\ - <strong> - * - <paragraph> - Strong double asterisk: \n\ - <strong> - ** -"""], -["""\ -**strong without closing asterisks -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - ** - strong without closing asterisks - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. -"""], -] - -totest['literal'] = [ -["""\ -``literal`` -""", -"""\ -<document source="test data"> - <paragraph> - <literal> - literal -"""], -["""\ -``\\literal`` -""", -"""\ -<document source="test data"> - <paragraph> - <literal> - \\literal -"""], -["""\ -``lite\\ral`` -""", -"""\ -<document source="test data"> - <paragraph> - <literal> - lite\\ral -"""], -["""\ -``literal\\`` -""", -"""\ -<document source="test data"> - <paragraph> - <literal> - literal\\ -"""], -["""\ -``literal ``TeX quotes'' & \\backslash`` but not "``" or `` - -(however, ``standalone TeX quotes'' will trigger a warning -and may be problematic) -""", -"""\ -<document source="test data"> - <paragraph> - <literal> - literal ``TeX quotes'' & \\backslash - but not "``" or `` - <paragraph> - (however, \n\ - <problematic ids="id2" refid="id1"> - `` - standalone TeX quotes'' will trigger a warning - and may be problematic) - <system_message backrefs="id2" ids="id1" level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. -"""], -["""\ -Find the ```interpreted text``` in this paragraph! -""", -"""\ -<document source="test data"> - <paragraph> - Find the \n\ - <literal> - `interpreted text` - in this paragraph! -"""], -["""\ -``literal without closing backquotes -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - `` - literal without closing backquotes - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. -"""], -["""\ -Python ``list``\\s use square bracket syntax. -""", -"""\ -<document source="test data"> - <paragraph> - Python \n\ - <literal> - list - s use square bracket syntax. -"""], -] - -totest['references'] = [ -["""\ -ref_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="ref" refname="ref"> - ref -"""], -["""\ -ref__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1" name="ref"> - ref -"""], -["""\ -ref_, r_, r_e-f_, -ref_, and anonymousref__, -but not _ref_ or __attr__ or object.__attr__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="ref" refname="ref"> - ref - , \n\ - <reference name="r" refname="r"> - r - , \n\ - <reference name="r_e-f" refname="r_e-f"> - r_e-f - , - - <reference name="ref" refname="ref"> - ref - , and \n\ - <reference anonymous="1" name="anonymousref"> - anonymousref - , - but not _ref_ or __attr__ or object.__attr__ -"""], -] - -totest['phrase_references'] = [ -["""\ -`phrase reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="phrase reference" refname="phrase reference"> - phrase reference -"""], -["""\ -`anonymous reference`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1" name="anonymous reference"> - anonymous reference -"""], -["""\ -`phrase reference -across lines`_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="phrase reference across lines" refname="phrase reference across lines"> - phrase reference - across lines -"""], -["""\ -`phrase\`_ reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="phrase`_ reference" refname="phrase`_ reference"> - phrase`_ reference -"""], -["""\ -Invalid phrase reference: - -:role:`phrase reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - Invalid phrase reference: - <paragraph> - <problematic ids="id2" refid="id1"> - :role:`phrase reference`_ - <system_message backrefs="id2" ids="id1" level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Mismatch: both interpreted text role prefix and reference suffix. -"""], -["""\ -Invalid phrase reference: - -`phrase reference`:role:_ -""", -"""\ -<document source="test data"> - <paragraph> - Invalid phrase reference: - <paragraph> - <problematic ids="id2" refid="id1"> - `phrase reference`:role:_ - <system_message backrefs="id2" ids="id1" level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Mismatch: both interpreted text role suffix and reference suffix. -"""], -["""\ -`phrase reference_ without closing backquote -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - ` - phrase \n\ - <reference name="reference" refname="reference"> - reference - without closing backquote - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline interpreted text or phrase reference start-string without end-string. -"""], -["""\ -`anonymous phrase reference__ without closing backquote -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - ` - anonymous phrase \n\ - <reference anonymous="1" name="reference"> - reference - without closing backquote - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline interpreted text or phrase reference start-string without end-string. -"""], -] - -totest['embedded_URIs'] = [ -["""\ -`phrase reference <http://example.com>`_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="phrase reference" refuri="http://example.com"> - phrase reference - <target ids="phrase-reference" names="phrase\ reference" refuri="http://example.com"> -"""], -["""\ -`anonymous reference <http://example.com>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="anonymous reference" refuri="http://example.com"> - anonymous reference -"""], -["""\ -`embedded URI on next line -<http://example.com>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="embedded URI on next line" refuri="http://example.com"> - embedded URI on next line -"""], -["""\ -`embedded URI across lines <http://example.com/ -long/path>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="embedded URI across lines" refuri="http://example.com/long/path"> - embedded URI across lines -"""], -["""\ -`embedded URI with whitespace <http://example.com/ -long/path /and /whitespace>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="embedded URI with whitespace" refuri="http://example.com/long/path/and/whitespace"> - embedded URI with whitespace -"""], -["""\ -`embedded email address <jdoe@example.com>`__ - -`embedded email address broken across lines <jdoe -@example.com>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="embedded email address" refuri="mailto:jdoe@example.com"> - embedded email address - <paragraph> - <reference name="embedded email address broken across lines" refuri="mailto:jdoe@example.com"> - embedded email address broken across lines -"""], -["""\ -`embedded URI with too much whitespace < http://example.com/ -long/path /and /whitespace >`__ - -`embedded URI with too much whitespace at end <http://example.com/ -long/path /and /whitespace >`__ - -`embedded URI with no preceding whitespace<http://example.com>`__ - -`escaped URI \\<http://example.com>`__ - -See `HTML Anchors: \\<a>`_. -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1" name="embedded URI with too much whitespace < http://example.com/ long/path /and /whitespace >"> - embedded URI with too much whitespace < http://example.com/ - long/path /and /whitespace > - <paragraph> - <reference anonymous="1" name="embedded URI with too much whitespace at end <http://example.com/ long/path /and /whitespace >"> - embedded URI with too much whitespace at end <http://example.com/ - long/path /and /whitespace > - <paragraph> - <reference anonymous="1" name="embedded URI with no preceding whitespace<http://example.com>"> - embedded URI with no preceding whitespace<http://example.com> - <paragraph> - <reference anonymous="1" name="escaped URI <http://example.com>"> - escaped URI <http://example.com> - <paragraph> - See \n\ - <reference name="HTML Anchors: <a>" refname="html anchors: <a>"> - HTML Anchors: <a> - . -"""], -["""\ -Relative URIs' reference text can be omitted: - -`<reference>`_ - -`<anonymous>`__ -""", -"""\ -<document source="test data"> - <paragraph> - Relative URIs' reference text can be omitted: - <paragraph> - <reference name="reference" refuri="reference"> - reference - <target ids="reference" names="reference" refuri="reference"> - <paragraph> - <reference name="anonymous" refuri="anonymous"> - anonymous -"""], -] - -totest['inline_targets'] = [ -["""\ -_`target` - -Here is _`another target` in some text. And _`yet -another target`, spanning lines. - -_`Here is a TaRgeT` with case and spacial difficulties. -""", -"""\ -<document source="test data"> - <paragraph> - <target ids="target" names="target"> - target - <paragraph> - Here is \n\ - <target ids="another-target" names="another\ target"> - another target - in some text. And \n\ - <target ids="yet-another-target" names="yet\ another\ target"> - yet - another target - , spanning lines. - <paragraph> - <target ids="here-is-a-target" names="here\ is\ a\ target"> - Here is a TaRgeT - with case and spacial difficulties. -"""], -["""\ -But this isn't a _target; targets require backquotes. - -And _`this`_ is just plain confusing. -""", -"""\ -<document source="test data"> - <paragraph> - But this isn't a _target; targets require backquotes. - <paragraph> - And \n\ - <problematic ids="id2" refid="id1"> - _` - this`_ is just plain confusing. - <system_message backrefs="id2" ids="id1" level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Inline target start-string without end-string. -"""], -["""\ -_`inline target without closing backquote -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - _` - inline target without closing backquote - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline target start-string without end-string. -"""], -] - -totest['footnote_reference'] = [ -["""\ -[1]_ -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference ids="id1" refname="1"> - 1 -"""], -["""\ -[#]_ -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" ids="id1"> -"""], -["""\ -[#label]_ -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" ids="id1" refname="label"> -"""], -["""\ -[*]_ -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="*" ids="id1"> -"""], -] - -totest['citation_reference'] = [ -["""\ -[citation]_ -""", -"""\ -<document source="test data"> - <paragraph> - <citation_reference ids="id1" refname="citation"> - citation -"""], -["""\ -[citation]_ and [cit-ation]_ and [cit.ation]_ and [CIT1]_ but not [CIT 1]_ -""", -"""\ -<document source="test data"> - <paragraph> - <citation_reference ids="id1" refname="citation"> - citation - and \n\ - <citation_reference ids="id2" refname="cit-ation"> - cit-ation - and \n\ - <citation_reference ids="id3" refname="cit.ation"> - cit.ation - and \n\ - <citation_reference ids="id4" refname="cit1"> - CIT1 - but not [CIT 1]_ -"""], -] - -totest['substitution_references'] = [ -["""\ -|subref| -""", -"""\ -<document source="test data"> - <paragraph> - <substitution_reference refname="subref"> - subref -"""], -["""\ -|subref|_ and |subref|__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference refname="subref"> - <substitution_reference refname="subref"> - subref - and \n\ - <reference anonymous="1"> - <substitution_reference refname="subref"> - subref -"""], -["""\ -|substitution reference| -""", -"""\ -<document source="test data"> - <paragraph> - <substitution_reference refname="substitution reference"> - substitution reference -"""], -["""\ -|substitution -reference| -""", -"""\ -<document source="test data"> - <paragraph> - <substitution_reference refname="substitution reference"> - substitution - reference -"""], -["""\ -|substitution reference without closing verbar -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - | - substitution reference without closing verbar - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline substitution_reference start-string without end-string. -"""], -["""\ -first | then || and finally ||| -""", -"""\ -<document source="test data"> - <paragraph> - first | then || and finally ||| -"""], -] - -totest['standalone_hyperlink'] = [ -["""\ -http://www.standalone.hyperlink.com - -http:/one-slash-only.absolute.path - -[http://example.com] - -(http://example.com) - -<http://example.com> - -http://[1080:0:0:0:8:800:200C:417A]/IPv6address.html - -http://[3ffe:2a00:100:7031::1] (the final "]" is ambiguous in text) - -http://[3ffe:2a00:100:7031::1]/ - -mailto:someone@somewhere.com - -news:comp.lang.python - -An email address in a sentence: someone@somewhere.com. - -ftp://ends.with.a.period. - -(a.question.mark@end?) -""", -"""\ -<document source="test data"> - <paragraph> - <reference refuri="http://www.standalone.hyperlink.com"> - http://www.standalone.hyperlink.com - <paragraph> - <reference refuri="http:/one-slash-only.absolute.path"> - http:/one-slash-only.absolute.path - <paragraph> - [ - <reference refuri="http://example.com"> - http://example.com - ] - <paragraph> - ( - <reference refuri="http://example.com"> - http://example.com - ) - <paragraph> - < - <reference refuri="http://example.com"> - http://example.com - > - <paragraph> - <reference refuri="http://[1080:0:0:0:8:800:200C:417A]/IPv6address.html"> - http://[1080:0:0:0:8:800:200C:417A]/IPv6address.html - <paragraph> - <reference refuri="http://[3ffe:2a00:100:7031::1"> - http://[3ffe:2a00:100:7031::1 - ] (the final "]" is ambiguous in text) - <paragraph> - <reference refuri="http://[3ffe:2a00:100:7031::1]/"> - http://[3ffe:2a00:100:7031::1]/ - <paragraph> - <reference refuri="mailto:someone@somewhere.com"> - mailto:someone@somewhere.com - <paragraph> - <reference refuri="news:comp.lang.python"> - news:comp.lang.python - <paragraph> - An email address in a sentence: \n\ - <reference refuri="mailto:someone@somewhere.com"> - someone@somewhere.com - . - <paragraph> - <reference refuri="ftp://ends.with.a.period"> - ftp://ends.with.a.period - . - <paragraph> - ( - <reference refuri="mailto:a.question.mark@end"> - a.question.mark@end - ?) -"""], -["""\ -Valid URLs with escaped markup characters: - -http://example.com/\\*content\\*/whatever - -http://example.com/\\*content*/whatever -""", -"""\ -<document source="test data"> - <paragraph> - Valid URLs with escaped markup characters: - <paragraph> - <reference refuri="http://example.com/*content*/whatever"> - http://example.com/*content*/whatever - <paragraph> - <reference refuri="http://example.com/*content*/whatever"> - http://example.com/*content*/whatever -"""], -["""\ -Valid URLs may end with punctuation inside "<>": - -<http://example.org/ends-with-dot.> -""", -"""\ -<document source="test data"> - <paragraph> - Valid URLs may end with punctuation inside "<>": - <paragraph> - < - <reference refuri="http://example.org/ends-with-dot."> - http://example.org/ends-with-dot. - > -"""], -["""\ -Valid URLs with interesting endings: - -http://example.org/ends-with-pluses++ -""", -"""\ -<document source="test data"> - <paragraph> - Valid URLs with interesting endings: - <paragraph> - <reference refuri="http://example.org/ends-with-pluses++"> - http://example.org/ends-with-pluses++ -"""], -["""\ -None of these are standalone hyperlinks (their "schemes" -are not recognized): signal:noise, a:b. -""", -"""\ -<document source="test data"> - <paragraph> - None of these are standalone hyperlinks (their "schemes" - are not recognized): signal:noise, a:b. -"""], -["""\ -Escaped email addresses are not recognized: test\@example.org -""", -"""\ -<document source="test data"> - <paragraph> - Escaped email addresses are not recognized: test@example.org -"""], -] - -totest['miscellaneous'] = [ -["""\ -__This__ should be left alone. -""", -"""\ -<document source="test data"> - <paragraph> - __This__ should be left alone. -"""], -[r""" -Character-level m\ *a*\ **r**\ ``k``\ `u`:title:\p -with backslash-escaped whitespace, including new\ -lines. -""", -"""\ -<document source="test data"> - <paragraph> - Character-level m - <emphasis> - a - <strong> - r - <literal> - k - <title_reference> - u - p - with backslash-escaped whitespace, including newlines. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_interpreted.py b/docutils/test/test_parsers/test_rst/test_interpreted.py deleted file mode 100755 index a5392d497..000000000 --- a/docutils/test/test_parsers/test_rst/test_interpreted.py +++ /dev/null @@ -1,305 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for interpreted text in docutils/parsers/rst/states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['basics'] = [ -["""\ -`interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - interpreted -"""], -["""\ -:title:`interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - interpreted -"""], -["""\ -`interpreted`:title: -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - interpreted -"""], -["""\ -`interpreted \`title`` -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - interpreted `title` -"""], -["""\ -:title:`:not-role: interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - :not-role: interpreted -"""], -["""\ -`interpreted` but not \\`interpreted` [`] or ({[`] or [`]}) or ` -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - interpreted - but not `interpreted` [`] or ({[`] or [`]}) or ` -"""], -["""\ -`interpreted`-text `interpreted`: text `interpreted`:text `text`'s interpreted -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - interpreted - -text \n\ - <title_reference> - interpreted - : text \n\ - <title_reference> - interpreted - :text \n\ - <title_reference> - text - 's interpreted -"""], -["""\ -`interpreted without closing backquote -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - ` - interpreted without closing backquote - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline interpreted text or phrase reference start-string without end-string. -"""], -["""\ -`interpreted`:not a role if it contains whitespace: -""", -"""\ -<document source="test data"> - <paragraph> - <title_reference> - interpreted - :not a role if it contains whitespace: -"""], -["""\ -:title:`` (empty interpteted text not recognized) -""", -"""\ -<document source="test data"> - <paragraph> - :title:`` (empty interpteted text not recognized) -"""], -["""\ -Explicit roles for standard inline markup: -:emphasis:`emphasis`, -:strong:`strong`, -:literal:`inline literal text`. -""", -"""\ -<document source="test data"> - <paragraph> - Explicit roles for standard inline markup: - <emphasis> - emphasis - , - <strong> - strong - , - <literal> - inline literal text - . -"""], -["""\ -Simple explicit roles: -:ab:`abbreviation`, -:ac:`acronym`, -:sup:`superscript`, -:sub:`subscript`, -:title:`title reference`. -""", -"""\ -<document source="test data"> - <paragraph> - Simple explicit roles: - <abbreviation> - abbreviation - , - <acronym> - acronym - , - <superscript> - superscript - , - <subscript> - subscript - , - <title_reference> - title reference - . -"""], -] - -totest['references'] = [ -["""\ -:PEP:`0` -""", -"""\ -<document source="test data"> - <paragraph> - <reference refuri="http://www.python.org/peps/pep-0000.html"> - PEP 0 -"""], -["""\ -:PEP:`-1` -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - :PEP:`-1` - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - PEP number must be a number from 0 to 9999; "-1" is invalid. -"""], -["""\ -:RFC:`2822` -""", -"""\ -<document source="test data"> - <paragraph> - <reference refuri="http://www.faqs.org/rfcs/rfc2822.html"> - RFC 2822 -"""], -["""\ -:RFC:`0` -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - :RFC:`0` - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - RFC number must be a number greater than or equal to 1; "0" is invalid. -"""], -] - -totest['unknown_roles'] = [ -["""\ -:role:`interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - :role:`interpreted` - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - No role entry for "role" in module "docutils.parsers.rst.languages.en". - Trying "role" as canonical role name. - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown interpreted text role "role". -"""], -["""\ -`interpreted`:role: -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - `interpreted`:role: - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - No role entry for "role" in module "docutils.parsers.rst.languages.en". - Trying "role" as canonical role name. - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown interpreted text role "role". -"""], -["""\ -:role:`interpreted`:role: -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - :role:`interpreted`:role: - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Multiple roles in interpreted text (both prefix and suffix present; only one allowed). -"""], -["""\ -:very.long-role_name:`interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - :very.long-role_name:`interpreted` - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - No role entry for "very.long-role_name" in module "docutils.parsers.rst.languages.en". - Trying "very.long-role_name" as canonical role name. - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown interpreted text role "very.long-role_name". -"""], -["""\ -:restructuredtext-unimplemented-role:`interpreted` -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - :restructuredtext-unimplemented-role:`interpreted` - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - No role entry for "restructuredtext-unimplemented-role" in module "docutils.parsers.rst.languages.en". - Trying "restructuredtext-unimplemented-role" as canonical role name. - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Interpreted text role "restructuredtext-unimplemented-role" not implemented. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_line_blocks.py b/docutils/test/test_parsers/test_rst/test_line_blocks.py deleted file mode 100755 index 10eaa8354..000000000 --- a/docutils/test/test_parsers/test_rst/test_line_blocks.py +++ /dev/null @@ -1,310 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['line_blocks'] = [ -["""\ -| This is a line block. -| Line breaks are *preserved*. - -| This is a second line block. - -| This is a third. -""", -"""\ -<document source="test data"> - <line_block> - <line> - This is a line block. - <line> - Line breaks are \n\ - <emphasis> - preserved - . - <line_block> - <line> - This is a second line block. - <line_block> - <line> - This is a third. -"""], -["""\ -| In line blocks, -| Initial indentation is *also* preserved. -""", -"""\ -<document source="test data"> - <line_block> - <line> - In line blocks, - <line_block> - <line> - Initial indentation is \n\ - <emphasis> - also - preserved. -"""], -["""\ -| Individual lines in line blocks - *may* wrap, as indicated by the lack of a vertical bar prefix. -| These are called "continuation lines". -""", -"""\ -<document source="test data"> - <line_block> - <line> - Individual lines in line blocks - <emphasis> - may - wrap, as indicated by the lack of a vertical bar prefix. - <line> - These are called "continuation lines". -"""], -["""\ -| Inline markup in line blocks may also wrap *to - continuation lines*. -| But not to following lines. -""", -"""\ -<document source="test data"> - <line_block> - <line> - Inline markup in line blocks may also wrap \n\ - <emphasis> - to - continuation lines - . - <line> - But not to following lines. -"""], -["""\ -\\| This is not a line block. -The vertical bar is simply part of a paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - | This is not a line block. - The vertical bar is simply part of a paragraph. -"""], -["""\ -| This line block is incomplete. -There should be a blank line before this paragraph. -""", -"""\ -<document source="test data"> - <line_block> - <line> - This line block is incomplete. - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Line block ends without a blank line. - <paragraph> - There should be a blank line before this paragraph. -"""], -["""\ -| This line block contains -| -| blank lines. -""", -"""\ -<document source="test data"> - <line_block> - <line> - This line block contains - <line> - <line> - blank lines. -"""], -["""\ -| The blank lines in this block -| \n\ -| \n\ -| have bogus spaces. -""", -"""\ -<document source="test data"> - <line_block> - <line> - The blank lines in this block - <line> - <line> - <line> - have bogus spaces. -"""], -["""\ -| Initial indentation is also significant and preserved: -| -| Indented 4 spaces -| Not indented -| Indented 2 spaces -| Indented 4 spaces -| Only one space -| -| Continuation lines may be indented less - than their base lines. -""", -"""\ -<document source="test data"> - <line_block> - <line> - Initial indentation is also significant and preserved: - <line> - <line_block> - <line> - Indented 4 spaces - <line> - Not indented - <line_block> - <line_block> - <line> - Indented 2 spaces - <line_block> - <line> - Indented 4 spaces - <line> - Only one space - <line> - <line_block> - <line> - Continuation lines may be indented less - than their base lines. -"""], -["""\ -| -| This block begins and ends with blank lines. -| -""", -"""\ -<document source="test data"> - <line_block> - <line> - <line> - This block begins and ends with blank lines. - <line> -"""], -["""\ -This is not -| a line block. -""", -"""\ -<document source="test data"> - <paragraph> - This is not - | a line block. -"""], -["""\ -| The first line is indented. -| The second line is more indented. -""", -"""\ -<document source="test data"> - <line_block> - <line> - The first line is indented. - <line_block> - <line> - The second line is more indented. -"""], -["""\ -| The first line is indented. -| The second line is less indented. -""", -"""\ -<document source="test data"> - <line_block> - <line_block> - <line> - The first line is indented. - <line> - The second line is less indented. -"""], -["""\ -|This is not -|a line block - -| This is an -|incomplete line block. -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - | - This is not - <problematic ids="id4" refid="id3"> - | - a line block - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline substitution_reference start-string without end-string. - <system_message backrefs="id4" ids="id3" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline substitution_reference start-string without end-string. - <line_block> - <line> - This is an - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Line block ends without a blank line. - <paragraph> - <problematic ids="id6" refid="id5"> - | - incomplete line block. - <system_message backrefs="id6" ids="id5" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Inline substitution_reference start-string without end-string. -"""], -["""\ -| Inline markup *may not -| wrap* over several lines. -""", -"""\ -<document source="test data"> - <line_block> - <line> - Inline markup \n\ - <problematic ids="id2" refid="id1"> - * - may not - <line> - wrap* over several lines. - <system_message backrefs="id2" ids="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. -"""], -["""\ -| * Block level markup -| * is not recognized. -""", -"""\ -<document source="test data"> - <line_block> - <line> - * Block level markup - <line> - * is not recognized. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_literal_blocks.py b/docutils/test/test_parsers/test_rst/test_literal_blocks.py deleted file mode 100755 index 332e0eb27..000000000 --- a/docutils/test/test_parsers/test_rst/test_literal_blocks.py +++ /dev/null @@ -1,371 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['indented_literal_blocks'] = [ -["""\ -A paragraph:: - - A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A literal block. -"""], -["""\ -A paragraph with a space after the colons:: \n\ - - A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph with a space after the colons: - <literal_block xml:space="preserve"> - A literal block. -"""], -["""\ -A paragraph:: - - A literal block. - -Another paragraph:: - - Another literal block. - With two blank lines following. - - -A final paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A literal block. - <paragraph> - Another paragraph: - <literal_block xml:space="preserve"> - Another literal block. - With two blank lines following. - <paragraph> - A final paragraph. -"""], -["""\ -A paragraph -on more than -one line:: - - A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph - on more than - one line: - <literal_block xml:space="preserve"> - A literal block. -"""], -["""\ -A paragraph -on more than -one line:: - A literal block - with no blank line above. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph - on more than - one line: - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Unexpected indentation. - <literal_block xml:space="preserve"> - A literal block - with no blank line above. -"""], -["""\ -A paragraph:: - - A literal block. -no blank line -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A literal block. - <system_message level="2" line="4" source="test data" type="WARNING"> - <paragraph> - Literal block ends without a blank line; unexpected unindent. - <paragraph> - no blank line -"""], -[r""" -A paragraph\\:: - - A literal block. - -A paragraph\:: - - Not a literal block. -""", -r"""<document source="test data"> - <paragraph> - A paragraph\: - <literal_block xml:space="preserve"> - A literal block. - <paragraph> - A paragraph:: - <block_quote> - <paragraph> - Not a literal block. -"""], -[r""" -\\:: - - A literal block. - -\:: - - Not a literal block. -""", -r"""<document source="test data"> - <paragraph> - \: - <literal_block xml:space="preserve"> - A literal block. - <paragraph> - :: - <block_quote> - <paragraph> - Not a literal block. -"""], -["""\ -A paragraph: :: - - A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A literal block. -"""], -["""\ -A paragraph: - -:: - - A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A literal block. -"""], -["""\ -A paragraph: -:: - - A literal block. -""", -"""\ -<document source="test data"> - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - Possible title underline, too short for the title. - Treating it as ordinary text because it's so short. - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A literal block. -"""], -["""\ -A paragraph: - -:: - - A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A literal block. -"""], -["""\ -A paragraph:: - -Not a literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Literal block expected; none found. - <paragraph> - Not a literal block. -"""], -["""\ -A paragraph:: - - A wonky literal block. - Literal line 2. - - Literal line 3. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - A wonky literal block. - Literal line 2. - \n\ - Literal line 3. -"""], -["""\ -EOF, even though a literal block is indicated:: -""", -"""\ -<document source="test data"> - <paragraph> - EOF, even though a literal block is indicated: - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Literal block expected; none found. -"""], -] - -totest['quoted_literal_blocks'] = [ -["""\ -A paragraph:: - -> A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - > A literal block. -"""], -["""\ -A paragraph:: - - -> A literal block. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - > A literal block. -"""], -["""\ -A paragraph:: - -> A literal block. -> Line 2. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - > A literal block. - > Line 2. -"""], -["""\ -A paragraph:: - -> A literal block. - Indented line. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - > A literal block. - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Unexpected indentation. - <block_quote> - <paragraph> - Indented line. -"""], -["""\ -A paragraph:: - -> A literal block. -Text. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - > A literal block. - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Inconsistent literal block quoting. - <paragraph> - Text. -"""], -["""\ -A paragraph:: - -> A literal block. -$ Inconsistent line. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph: - <literal_block xml:space="preserve"> - > A literal block. - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Inconsistent literal block quoting. - <paragraph> - $ Inconsistent line. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_option_lists.py b/docutils/test/test_parsers/test_rst/test_option_lists.py deleted file mode 100755 index a5afc498b..000000000 --- a/docutils/test/test_parsers/test_rst/test_option_lists.py +++ /dev/null @@ -1,756 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['option_lists'] = [ -["""\ -Short options: - --a option -a - --b file option -b - --c name option -c -""", -"""\ -<document source="test data"> - <paragraph> - Short options: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - option -a - <option_list_item> - <option_group> - <option> - <option_string> - -b - <option_argument delimiter=" "> - file - <description> - <paragraph> - option -b - <option_list_item> - <option_group> - <option> - <option_string> - -c - <option_argument delimiter=" "> - name - <description> - <paragraph> - option -c -"""], -["""\ -Long options: - ---aaaa option --aaaa ---bbbb=file option --bbbb ---cccc name option --cccc ---d-e-f-g option --d-e-f-g ---h_i_j_k option --h_i_j_k -""", -"""\ -<document source="test data"> - <paragraph> - Long options: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - --aaaa - <description> - <paragraph> - option --aaaa - <option_list_item> - <option_group> - <option> - <option_string> - --bbbb - <option_argument delimiter="="> - file - <description> - <paragraph> - option --bbbb - <option_list_item> - <option_group> - <option> - <option_string> - --cccc - <option_argument delimiter=" "> - name - <description> - <paragraph> - option --cccc - <option_list_item> - <option_group> - <option> - <option_string> - --d-e-f-g - <description> - <paragraph> - option --d-e-f-g - <option_list_item> - <option_group> - <option> - <option_string> - --h_i_j_k - <description> - <paragraph> - option --h_i_j_k -"""], -["""\ -Old GNU-style options: - -+a option +a - -+b file option +b - -+c name option +c -""", -"""\ -<document source="test data"> - <paragraph> - Old GNU-style options: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - +a - <description> - <paragraph> - option +a - <option_list_item> - <option_group> - <option> - <option_string> - +b - <option_argument delimiter=" "> - file - <description> - <paragraph> - option +b - <option_list_item> - <option_group> - <option> - <option_string> - +c - <option_argument delimiter=" "> - name - <description> - <paragraph> - option +c -"""], -["""\ -VMS/DOS-style options: - -/A option /A -/B file option /B -/CCC option /CCC -/DDD string option /DDD -/EEE=int option /EEE -""", -"""\ -<document source="test data"> - <paragraph> - VMS/DOS-style options: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - /A - <description> - <paragraph> - option /A - <option_list_item> - <option_group> - <option> - <option_string> - /B - <option_argument delimiter=" "> - file - <description> - <paragraph> - option /B - <option_list_item> - <option_group> - <option> - <option_string> - /CCC - <description> - <paragraph> - option /CCC - <option_list_item> - <option_group> - <option> - <option_string> - /DDD - <option_argument delimiter=" "> - string - <description> - <paragraph> - option /DDD - <option_list_item> - <option_group> - <option> - <option_string> - /EEE - <option_argument delimiter="="> - int - <description> - <paragraph> - option /EEE -"""], -["""\ -Mixed short, long, and VMS/DOS options: - --a option -a ---bbbb=file option -bbbb -/C option /C ---dddd name option --dddd --e string option -e -/F file option /F -""", -"""\ -<document source="test data"> - <paragraph> - Mixed short, long, and VMS/DOS options: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - option -a - <option_list_item> - <option_group> - <option> - <option_string> - --bbbb - <option_argument delimiter="="> - file - <description> - <paragraph> - option -bbbb - <option_list_item> - <option_group> - <option> - <option_string> - /C - <description> - <paragraph> - option /C - <option_list_item> - <option_group> - <option> - <option_string> - --dddd - <option_argument delimiter=" "> - name - <description> - <paragraph> - option --dddd - <option_list_item> - <option_group> - <option> - <option_string> - -e - <option_argument delimiter=" "> - string - <description> - <paragraph> - option -e - <option_list_item> - <option_group> - <option> - <option_string> - /F - <option_argument delimiter=" "> - file - <description> - <paragraph> - option /F -"""], -["""\ -Aliased options: - --a, --aaaa, /A option -a, --aaaa, /A --b file, --bbbb=file, /B file option -b, --bbbb, /B -""", -"""\ -<document source="test data"> - <paragraph> - Aliased options: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <option> - <option_string> - --aaaa - <option> - <option_string> - /A - <description> - <paragraph> - option -a, --aaaa, /A - <option_list_item> - <option_group> - <option> - <option_string> - -b - <option_argument delimiter=" "> - file - <option> - <option_string> - --bbbb - <option_argument delimiter="="> - file - <option> - <option_string> - /B - <option_argument delimiter=" "> - file - <description> - <paragraph> - option -b, --bbbb, /B -"""], -["""\ -Multiple lines in descriptions, aligned: - --a option -a, line 1 - line 2 --b file option -b, line 1 - line 2 -""", -"""\ -<document source="test data"> - <paragraph> - Multiple lines in descriptions, aligned: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - option -a, line 1 - line 2 - <option_list_item> - <option_group> - <option> - <option_string> - -b - <option_argument delimiter=" "> - file - <description> - <paragraph> - option -b, line 1 - line 2 -"""], -["""\ -Multiple lines in descriptions, not aligned: - --a option -a, line 1 - line 2 --b file option -b, line 1 - line 2 -""", -"""\ -<document source="test data"> - <paragraph> - Multiple lines in descriptions, not aligned: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - option -a, line 1 - line 2 - <option_list_item> - <option_group> - <option> - <option_string> - -b - <option_argument delimiter=" "> - file - <description> - <paragraph> - option -b, line 1 - line 2 -"""], -["""\ -Descriptions begin on next line: - --a - option -a, line 1 - line 2 --b file - option -b, line 1 - line 2 -""", -"""\ -<document source="test data"> - <paragraph> - Descriptions begin on next line: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - option -a, line 1 - line 2 - <option_list_item> - <option_group> - <option> - <option_string> - -b - <option_argument delimiter=" "> - file - <description> - <paragraph> - option -b, line 1 - line 2 -"""], -["""\ -Multiple body elements in descriptions: - --a option -a, para 1 - - para 2 --b file - option -b, para 1 - - para 2 -""", -"""\ -<document source="test data"> - <paragraph> - Multiple body elements in descriptions: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - option -a, para 1 - <paragraph> - para 2 - <option_list_item> - <option_group> - <option> - <option_string> - -b - <option_argument delimiter=" "> - file - <description> - <paragraph> - option -b, para 1 - <paragraph> - para 2 -"""], -["""\ ---option -empty item above, no blank line -""", -"""\ -<document source="test data"> - <paragraph> - --option - empty item above, no blank line -"""], -["""\ -An option list using equals: - ---long1=arg1 Description 1 ---long2=arg2 Description 2 - -An option list using spaces: - ---long1 arg1 Description 1 ---long2 arg2 Description 2 - -An option list using mixed delimiters: - ---long1=arg1 Description 1 ---long2 arg2 Description 2 - -An option list using mixed delimiters in one line: - ---long1=arg1, --long2 arg2 Description -""", -"""\ -<document source="test data"> - <paragraph> - An option list using equals: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - --long1 - <option_argument delimiter="="> - arg1 - <description> - <paragraph> - Description 1 - <option_list_item> - <option_group> - <option> - <option_string> - --long2 - <option_argument delimiter="="> - arg2 - <description> - <paragraph> - Description 2 - <paragraph> - An option list using spaces: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - --long1 - <option_argument delimiter=" "> - arg1 - <description> - <paragraph> - Description 1 - <option_list_item> - <option_group> - <option> - <option_string> - --long2 - <option_argument delimiter=" "> - arg2 - <description> - <paragraph> - Description 2 - <paragraph> - An option list using mixed delimiters: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - --long1 - <option_argument delimiter="="> - arg1 - <description> - <paragraph> - Description 1 - <option_list_item> - <option_group> - <option> - <option_string> - --long2 - <option_argument delimiter=" "> - arg2 - <description> - <paragraph> - Description 2 - <paragraph> - An option list using mixed delimiters in one line: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - --long1 - <option_argument delimiter="="> - arg1 - <option> - <option_string> - --long2 - <option_argument delimiter=" "> - arg2 - <description> - <paragraph> - Description -"""], -["""\ -Some edge cases: - ---option=arg arg too many arguments - ---option=arg,arg not supported (yet?) - ---option=arg=arg too many arguments - ---option arg arg too many arguments - --a letter arg2 too many arguments - -/A letter arg2 too many arguments - ---option= argument missing - ---=argument option missing - --- everything missing - -- this should be a bullet list item - -These next ones should be simple paragraphs: - --1 - ---option - ---1 - --1 and this one too. -""", -"""\ -<document source="test data"> - <paragraph> - Some edge cases: - <paragraph> - --option=arg arg too many arguments - <paragraph> - --option=arg,arg not supported (yet?) - <paragraph> - --option=arg=arg too many arguments - <paragraph> - --option arg arg too many arguments - <paragraph> - -a letter arg2 too many arguments - <paragraph> - /A letter arg2 too many arguments - <paragraph> - --option= argument missing - <paragraph> - --=argument option missing - <paragraph> - -- everything missing - <bullet_list bullet="-"> - <list_item> - <paragraph> - this should be a bullet list item - <paragraph> - These next ones should be simple paragraphs: - <paragraph> - -1 - <paragraph> - --option - <paragraph> - --1 - <paragraph> - -1 and this one too. -"""], -["""\ -Complex optargs: - ---source-url=<URL> Use the supplied <URL> verbatim. ---output-encoding=<name[:handler]>, -o<name[:handler]> - Specify the text encoding for output. --f <[path]filename> Send output to file. --d <src dest> Use diff from <src> to <dest>. ---bogus=<x y z> Bogus 3D coordinates. -""", -"""\ -<document source="test data"> - <paragraph> - Complex optargs: - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - --source-url - <option_argument delimiter="="> - <URL> - <description> - <paragraph> - Use the supplied <URL> verbatim. - <option_list_item> - <option_group> - <option> - <option_string> - --output-encoding - <option_argument delimiter="="> - <name[:handler]> - <option> - <option_string> - -o - <option_argument delimiter=""> - <name[:handler]> - <description> - <paragraph> - Specify the text encoding for output. - <option_list_item> - <option_group> - <option> - <option_string> - -f - <option_argument delimiter=" "> - <[path]filename> - <description> - <paragraph> - Send output to file. - <option_list_item> - <option_group> - <option> - <option_string> - -d - <option_argument delimiter=" "> - <src dest> - <description> - <paragraph> - Use diff from <src> to <dest>. - <option_list_item> - <option_group> - <option> - <option_string> - --bogus - <option_argument delimiter="="> - <x y z> - <description> - <paragraph> - Bogus 3D coordinates. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_outdenting.py b/docutils/test/test_parsers/test_rst/test_outdenting.py deleted file mode 100755 index 1522b7f30..000000000 --- a/docutils/test/test_parsers/test_rst/test_outdenting.py +++ /dev/null @@ -1,90 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['outdenting'] = [ -["""\ -Anywhere a paragraph would have an effect on the current -indentation level, a comment or list item should also. - -+ bullet - -This paragraph ends the bullet list item before a block quote. - - Block quote. -""", -"""\ -<document source="test data"> - <paragraph> - Anywhere a paragraph would have an effect on the current - indentation level, a comment or list item should also. - <bullet_list bullet="+"> - <list_item> - <paragraph> - bullet - <paragraph> - This paragraph ends the bullet list item before a block quote. - <block_quote> - <paragraph> - Block quote. -"""], -["""\ -+ bullet - -.. Comments swallow up all indented text following. - - (Therefore this is not a) block quote. - -- bullet - - If we want a block quote after this bullet list item, - we need to use an empty comment: - -.. - - Block quote. -""", -"""\ -<document source="test data"> - <bullet_list bullet="+"> - <list_item> - <paragraph> - bullet - <comment xml:space="preserve"> - Comments swallow up all indented text following. - \n\ - (Therefore this is not a) block quote. - <bullet_list bullet="-"> - <list_item> - <paragraph> - bullet - <paragraph> - If we want a block quote after this bullet list item, - we need to use an empty comment: - <comment xml:space="preserve"> - <block_quote> - <paragraph> - Block quote. -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_paragraphs.py b/docutils/test/test_parsers/test_rst/test_paragraphs.py deleted file mode 100755 index 8ec8cbbc5..000000000 --- a/docutils/test/test_parsers/test_rst/test_paragraphs.py +++ /dev/null @@ -1,89 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['paragraphs'] = [ -["""\ -A paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph. -"""], -["""\ -Paragraph 1. - -Paragraph 2. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph 1. - <paragraph> - Paragraph 2. -"""], -["""\ -Line 1. -Line 2. -Line 3. -""", -"""\ -<document source="test data"> - <paragraph> - Line 1. - Line 2. - Line 3. -"""], -["""\ -Paragraph 1, Line 1. -Line 2. -Line 3. - -Paragraph 2, Line 1. -Line 2. -Line 3. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph 1, Line 1. - Line 2. - Line 3. - <paragraph> - Paragraph 2, Line 1. - Line 2. - Line 3. -"""], -["""\ -A. Einstein was a really -smart dude. -""", -"""\ -<document source="test data"> - <paragraph> - A. Einstein was a really - smart dude. -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_section_headers.py b/docutils/test/test_parsers/test_rst/test_section_headers.py deleted file mode 100755 index 3c5a21170..000000000 --- a/docutils/test/test_parsers/test_rst/test_section_headers.py +++ /dev/null @@ -1,897 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -"""Tests for states.py.""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['section_headers'] = [ -["""\ -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <section ids="title" names="title"> - <title> - Title - <paragraph> - Paragraph. -"""], -["""\ -Title -===== -Paragraph (no blank line). -""", -"""\ -<document source="test data"> - <section ids="title" names="title"> - <title> - Title - <paragraph> - Paragraph (no blank line). -"""], -["""\ -Paragraph. - -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <section ids="title" names="title"> - <title> - Title - <paragraph> - Paragraph. -"""], -["""\ -Test unexpected section titles. - - Title - ===== - Paragraph. - - ----- - Title - ----- - Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Test unexpected section titles. - <block_quote> - <system_message level="4" line="4" source="test data" type="SEVERE"> - <paragraph> - Unexpected section title. - <literal_block xml:space="preserve"> - Title - ===== - <paragraph> - Paragraph. - <system_message level="4" line="7" source="test data" type="SEVERE"> - <paragraph> - Unexpected section title or transition. - <literal_block xml:space="preserve"> - ----- - <system_message level="4" line="9" source="test data" type="SEVERE"> - <paragraph> - Unexpected section title. - <literal_block xml:space="preserve"> - Title - ----- - <paragraph> - Paragraph. -"""], -["""\ -Title -==== - -Test short underline. -""", -"""\ -<document source="test data"> - <section ids="title" names="title"> - <title> - Title - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Title underline too short. - <literal_block xml:space="preserve"> - Title - ==== - <paragraph> - Test short underline. -"""], -["""\ -===== -Title -===== - -Test overline title. -""", -"""\ -<document source="test data"> - <section ids="title" names="title"> - <title> - Title - <paragraph> - Test overline title. -"""], -["""\ -======= - Title -======= - -Test overline title with inset. -""", -"""\ -<document source="test data"> - <section ids="title" names="title"> - <title> - Title - <paragraph> - Test overline title with inset. -"""], -["""\ -======================== - Test Missing Underline -""", -"""\ -<document source="test data"> - <system_message level="4" line="1" source="test data" type="SEVERE"> - <paragraph> - Incomplete section title. - <literal_block xml:space="preserve"> - ======================== - Test Missing Underline -"""], -["""\ -======================== - Test Missing Underline - -""", -"""\ -<document source="test data"> - <system_message level="4" line="1" source="test data" type="SEVERE"> - <paragraph> - Missing matching underline for section title overline. - <literal_block xml:space="preserve"> - ======================== - Test Missing Underline -"""], -["""\ -======= - Title - -Test missing underline, with paragraph. -""", -"""\ -<document source="test data"> - <system_message level="4" line="1" source="test data" type="SEVERE"> - <paragraph> - Missing matching underline for section title overline. - <literal_block xml:space="preserve"> - ======= - Title - <paragraph> - Test missing underline, with paragraph. -"""], -["""\ -======= - Long Title -======= - -Test long title and space normalization. -""", -"""\ -<document source="test data"> - <section ids="long-title" names="long\ title"> - <title> - Long Title - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Title overline too short. - <literal_block xml:space="preserve"> - ======= - Long Title - ======= - <paragraph> - Test long title and space normalization. -"""], -["""\ -======= - Title -------- - -Paragraph. -""", -"""\ -<document source="test data"> - <system_message level="4" line="1" source="test data" type="SEVERE"> - <paragraph> - Title overline & underline mismatch. - <literal_block xml:space="preserve"> - ======= - Title - ------- - <paragraph> - Paragraph. -"""], -["""\ -======================== - -======================== - -Test missing titles; blank line in-between. - -======================== - -======================== -""", -"""\ -<document source="test data"> - <transition> - <transition> - <paragraph> - Test missing titles; blank line in-between. - <transition> - <transition> -"""], -["""\ -======================== -======================== - -Test missing titles; nothing in-between. - -======================== -======================== -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Invalid section title or transition marker. - <literal_block xml:space="preserve"> - ======================== - ======================== - <paragraph> - Test missing titles; nothing in-between. - <system_message level="3" line="6" source="test data" type="ERROR"> - <paragraph> - Invalid section title or transition marker. - <literal_block xml:space="preserve"> - ======================== - ======================== -"""], -["""\ -.. Test return to existing, highest-level section (Title 3). - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -======= -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - Test return to existing, highest-level section (Title 3). - <section ids="title-1" names="title\ 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title> - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -Test return to existing, highest-level section (Title 3, with overlines). - -======= -Title 1 -======= -Paragraph 1. - -------- -Title 2 -------- -Paragraph 2. - -======= -Title 3 -======= -Paragraph 3. - -------- -Title 4 -------- -Paragraph 4. -""", -"""\ -<document source="test data"> - <paragraph> - Test return to existing, highest-level section (Title 3, with overlines). - <section ids="title-1" names="title\ 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title> - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -Test return to existing, higher-level section (Title 4). - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -"""\ -<document source="test data"> - <paragraph> - Test return to existing, higher-level section (Title 4). - <section ids="title-1" names="title\ 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title> - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -Test bad subsection order (Title 4). - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -======= -Paragraph 3. - -Title 4 -``````` -Paragraph 4. -""", -"""\ -<document source="test data"> - <paragraph> - Test bad subsection order (Title 4). - <section ids="title-1" names="title\ 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <system_message level="4" line="15" source="test data" type="SEVERE"> - <paragraph> - Title level inconsistent: - <literal_block xml:space="preserve"> - Title 4 - ``````` - <paragraph> - Paragraph 4. -"""], -["""\ -Test bad subsection order (Title 4, with overlines). - -======= -Title 1 -======= -Paragraph 1. - -------- -Title 2 -------- -Paragraph 2. - -======= -Title 3 -======= -Paragraph 3. - -``````` -Title 4 -``````` -Paragraph 4. -""", -"""\ -<document source="test data"> - <paragraph> - Test bad subsection order (Title 4, with overlines). - <section ids="title-1" names="title\ 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <system_message level="4" line="19" source="test data" type="SEVERE"> - <paragraph> - Title level inconsistent: - <literal_block xml:space="preserve"> - ``````` - Title 4 - ``````` - <paragraph> - Paragraph 4. -"""], -["""\ -Title containing *inline* ``markup`` -==================================== - -Paragraph. -""", -"""\ -<document source="test data"> - <section ids="title-containing-inline-markup" names="title\ containing\ inline\ markup"> - <title> - Title containing \n\ - <emphasis> - inline - \n\ - <literal> - markup - <paragraph> - Paragraph. -"""], -["""\ -1. Numbered Title -================= - -Paragraph. -""", -"""\ -<document source="test data"> - <section ids="numbered-title" names="1.\ numbered\ title"> - <title> - 1. Numbered Title - <paragraph> - Paragraph. -"""], -["""\ -1. Item 1. -2. Item 2. -3. Numbered Title -================= - -Paragraph. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item 1. - <list_item> - <paragraph> - Item 2. - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Enumerated list ends without a blank line; unexpected unindent. - <section ids="numbered-title" names="3.\ numbered\ title"> - <title> - 3. Numbered Title - <paragraph> - Paragraph. -"""], -["""\ -ABC -=== - -Short title. -""", -"""\ -<document source="test data"> - <section ids="abc" names="abc"> - <title> - ABC - <paragraph> - Short title. -"""], -["""\ -ABC -== - -Underline too short. -""", -"""\ -<document source="test data"> - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - Possible title underline, too short for the title. - Treating it as ordinary text because it's so short. - <paragraph> - ABC - == - <paragraph> - Underline too short. -"""], -["""\ -== -ABC -== - -Over & underline too short. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <paragraph> - == - ABC - == - <paragraph> - Over & underline too short. -"""], -["""\ -== -ABC - -Overline too short, no underline. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <paragraph> - == - ABC - <paragraph> - Overline too short, no underline. -"""], -["""\ -== -ABC -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <paragraph> - == - ABC -"""], -["""\ -== - Not a title: a definition list item. -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <definition_list> - <definition_list_item> - <term> - == - <definition> - <paragraph> - Not a title: a definition list item. -"""], -["""\ -== - Not a title: a definition list item. --- - Another definition list item. It's in a different list, - but that's an acceptable limitation given that this will - probably never happen in real life. - - The next line will trigger a warning: -== -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <definition_list> - <definition_list_item> - <term> - == - <definition> - <paragraph> - Not a title: a definition list item. - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Definition list ends without a blank line; unexpected unindent. - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <definition_list> - <definition_list_item> - <term> - -- - <definition> - <paragraph> - Another definition list item. It's in a different list, - but that's an acceptable limitation given that this will - probably never happen in real life. - <paragraph> - The next line will trigger a warning: - <system_message level="2" line="9" source="test data" type="WARNING"> - <paragraph> - Definition list ends without a blank line; unexpected unindent. - <paragraph> - == -"""], -["""\ -Paragraph - - == - ABC - == - - Over & underline too short. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph - <block_quote> - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - Unexpected possible title overline or transition. - Treating it as ordinary text because it's so short. - <paragraph> - == - ABC - == - <paragraph> - Over & underline too short. -"""], -["""\ -Paragraph - - ABC - == - - Underline too short. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph - <block_quote> - <paragraph> - ABC - == - <paragraph> - Underline too short. -"""], -["""\ -... -... - -... ---- - -... -... -... -""", -"""\ -<document source="test data"> - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <section dupnames="..." ids="id1"> - <title> - ... - <system_message level="1" line="4" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <section dupnames="..." ids="id2"> - <title> - ... - <system_message backrefs="id2" level="1" line="5" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "...". - <system_message level="1" line="7" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <system_message level="1" line="7" source="test data" type="INFO"> - <paragraph> - Possible incomplete section title. - Treating the overline as ordinary text because it's so short. - <section dupnames="..." ids="id3"> - <title> - ... - <system_message backrefs="id3" level="1" line="8" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "...". - <paragraph> - ... -"""], -["""\ -.. -Hi -.. - -... -Yo -... - -Ho -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <section ids="hi" names="hi"> - <title> - Hi - <section ids="yo" names="yo"> - <title> - Yo - <paragraph> - Ho -"""], -["""\ -Empty Section -============= -""", -"""\ -<document source="test data"> - <section ids="empty-section" names="empty\ section"> - <title> - Empty Section -"""], -["""\ -=== -One -=== - -The bubble-up parser strategy conflicts with short titles -(<= 3 char-long over- & underlines). - -=== -Two -=== - -The parser currently contains a work-around kludge. -Without it, the parser ends up in an infinite loop. -""", -"""\ -<document source="test data"> - <section ids="one" names="one"> - <title> - One - <paragraph> - The bubble-up parser strategy conflicts with short titles - (<= 3 char-long over- & underlines). - <section ids="two" names="two"> - <title> - Two - <paragraph> - The parser currently contains a work-around kludge. - Without it, the parser ends up in an infinite loop. -"""], -["""\ -""", -"""\ -<document source="test data"> -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_substitutions.py b/docutils/test/test_parsers/test_rst/test_substitutions.py deleted file mode 100755 index fb8af4c2d..000000000 --- a/docutils/test/test_parsers/test_rst/test_substitutions.py +++ /dev/null @@ -1,298 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['substitution_definitions'] = [ -["""\ -Here's an image substitution definition: - -.. |symbol| image:: symbol.png -""", -"""\ -<document source="test data"> - <paragraph> - Here's an image substitution definition: - <substitution_definition names="symbol"> - <image alt="symbol" uri="symbol.png"> -"""], -["""\ -Embedded directive starts on the next line: - -.. |symbol| - image:: symbol.png -""", -"""\ -<document source="test data"> - <paragraph> - Embedded directive starts on the next line: - <substitution_definition names="symbol"> - <image alt="symbol" uri="symbol.png"> -"""], -["""\ -Trailing spaces should not be significant: - -.. |symbol| image:: \n\ - symbol.png -""", -"""\ -<document source="test data"> - <paragraph> - Trailing spaces should not be significant: - <substitution_definition names="symbol"> - <image alt="symbol" uri="symbol.png"> -"""], -["""\ -Here's a series of substitution definitions: - -.. |symbol 1| image:: symbol1.png -.. |SYMBOL 2| image:: symbol2.png - :height: 50 - :width: 100 -.. |symbol 3| image:: symbol3.png -""", -"""\ -<document source="test data"> - <paragraph> - Here's a series of substitution definitions: - <substitution_definition names="symbol\ 1"> - <image alt="symbol 1" uri="symbol1.png"> - <substitution_definition names="SYMBOL\ 2"> - <image alt="SYMBOL 2" height="50" uri="symbol2.png" width="100"> - <substitution_definition names="symbol\ 3"> - <image alt="symbol 3" uri="symbol3.png"> -"""], -["""\ -.. |very long substitution text, - split across lines| image:: symbol.png -""", -"""\ -<document source="test data"> - <substitution_definition names="very\ long\ substitution\ text,\ split\ across\ lines"> - <image alt="very long substitution text, split across lines" uri="symbol.png"> -"""], -["""\ -.. |symbol 1| image:: symbol.png - - Followed by a block quote. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "image" directive: - no content permitted. - <literal_block xml:space="preserve"> - image:: symbol.png - \n\ - Followed by a block quote. - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Substitution definition "symbol 1" empty or invalid. - <literal_block xml:space="preserve"> - .. |symbol 1| image:: symbol.png - \n\ - Followed by a block quote. -"""], -["""\ -.. |symbol 1| image:: symbol.png - -Followed by a paragraph. - -.. |symbol 2| image:: symbol.png - -.. - - Followed by a block quote. -""", -"""\ -<document source="test data"> - <substitution_definition names="symbol\ 1"> - <image alt="symbol 1" uri="symbol.png"> - <paragraph> - Followed by a paragraph. - <substitution_definition names="symbol\ 2"> - <image alt="symbol 2" uri="symbol.png"> - <comment xml:space="preserve"> - <block_quote> - <paragraph> - Followed by a block quote. -"""], -[u"""\ -Substitutions support case differences: - -.. |eacute| replace:: \u00E9 -.. |Eacute| replace:: \u00C9 -""", -u"""\ -<document source="test data"> - <paragraph> - Substitutions support case differences: - <substitution_definition names="eacute"> - \u00E9 - <substitution_definition names="Eacute"> - \u00C9 -"""], -["""\ -Raw substitution, backslashes should be preserved: - -.. |alpha| raw:: latex - - $\\\\alpha$ -""", -"""\ -<document source="test data"> - <paragraph> - Raw substitution, backslashes should be preserved: - <substitution_definition names="alpha"> - <raw format="latex" xml:space="preserve"> - $\\\\alpha$ -"""], -["""\ -Here are some duplicate substitution definitions: - -.. |symbol| image:: symbol.png -.. |symbol| image:: symbol.png -""", -"""\ -<document source="test data"> - <paragraph> - Here are some duplicate substitution definitions: - <substitution_definition dupnames="symbol"> - <image alt="symbol" uri="symbol.png"> - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Duplicate substitution definition name: "symbol". - <substitution_definition names="symbol"> - <image alt="symbol" uri="symbol.png"> -"""], -["""\ -Here are some bad cases: - -.. |symbol| image:: symbol.png -No blank line after. - -.. |empty| - -.. |unknown| directive:: symbol.png - -.. |invalid 1| there's no directive here -.. |invalid 2| there's no directive here - With some block quote text, line 1. - And some more, line 2. - -.. |invalid 3| there's no directive here - -.. | bad name | bad data - -.. | -""", -"""\ -<document source="test data"> - <paragraph> - Here are some bad cases: - <substitution_definition names="symbol"> - <image alt="symbol" uri="symbol.png"> - <system_message level="2" line="4" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - No blank line after. - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Substitution definition "empty" missing contents. - <literal_block xml:space="preserve"> - .. |empty| - <system_message level="1" line="8" source="test data" type="INFO"> - <paragraph> - No directive entry for "directive" in module "docutils.parsers.rst.languages.en". - Trying "directive" as canonical directive name. - <system_message level="3" line="8" source="test data" type="ERROR"> - <paragraph> - Unknown directive type "directive". - <literal_block xml:space="preserve"> - directive:: symbol.png - <system_message level="2" line="8" source="test data" type="WARNING"> - <paragraph> - Substitution definition "unknown" empty or invalid. - <literal_block xml:space="preserve"> - .. |unknown| directive:: symbol.png - <system_message level="2" line="10" source="test data" type="WARNING"> - <paragraph> - Substitution definition "invalid 1" empty or invalid. - <literal_block xml:space="preserve"> - .. |invalid 1| there's no directive here - <system_message level="2" line="11" source="test data" type="WARNING"> - <paragraph> - Substitution definition "invalid 2" empty or invalid. - <literal_block xml:space="preserve"> - .. |invalid 2| there's no directive here - With some block quote text, line 1. - And some more, line 2. - <system_message level="2" line="15" source="test data" type="WARNING"> - <paragraph> - Substitution definition "invalid 3" empty or invalid. - <literal_block xml:space="preserve"> - .. |invalid 3| there's no directive here - <comment xml:space="preserve"> - | bad name | bad data - <comment xml:space="preserve"> - | -"""], -["""\ -Elements that are prohibited inside of substitution definitions: - -.. |target| replace:: _`target` -.. |reference| replace:: anonymous__ -.. |auto-numbered footnote| replace:: [#]_ -""", -"""\ -<document source="test data"> - <paragraph> - Elements that are prohibited inside of substitution definitions: - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Substitution definition contains illegal element: - <literal_block xml:space="preserve"> - <target ids="target" names="target"> - target - <literal_block xml:space="preserve"> - .. |target| replace:: _`target` - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Substitution definition contains illegal element: - <literal_block xml:space="preserve"> - <reference anonymous="1" name="anonymous"> - anonymous - <literal_block xml:space="preserve"> - .. |reference| replace:: anonymous__ - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Substitution definition contains illegal element: - <literal_block xml:space="preserve"> - <footnote_reference auto="1" ids="id1"> - <literal_block xml:space="preserve"> - .. |auto-numbered footnote| replace:: [#]_ -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_tables.py b/docutils/test/test_parsers/test_rst/test_tables.py deleted file mode 100755 index 81c423bc4..000000000 --- a/docutils/test/test_parsers/test_rst/test_tables.py +++ /dev/null @@ -1,1261 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -import os -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -mydir = 'test_parsers/test_rst/' -include2 = os.path.join(mydir, 'test_directives/include2.txt') - -totest = {} - -totest['grid_tables'] = [ -["""\ -+-------------------------------------+ -| A table with one cell and one line. | -+-------------------------------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="1"> - <colspec colwidth="37"> - <tbody> - <row> - <entry> - <paragraph> - A table with one cell and one line. -"""], -["""\ -+-----------------------+ -| A table with one cell | -| and two lines. | -+-----------------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="1"> - <colspec colwidth="23"> - <tbody> - <row> - <entry> - <paragraph> - A table with one cell - and two lines. -"""], -["""\ -+-----------------------+ -| A malformed table. | -+-----------------------+ -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - <literal_block xml:space="preserve"> - +-----------------------+ - | A malformed table. | - +-----------------------+ -"""], -["""\ -+------------------------+ -| A well-formed | table. | -+------------------------+ - -+------------------------+ -| This +----------+ too! | -+------------------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="1"> - <colspec colwidth="24"> - <tbody> - <row> - <entry> - <paragraph> - A well-formed | table. - <table> - <tgroup cols="1"> - <colspec colwidth="24"> - <tbody> - <row> - <entry> - <paragraph> - This +----------+ too! -"""], -["""\ -+--------------+--------------+ -| A table with | two columns. | -+--------------+--------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="14"> - <colspec colwidth="14"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - two columns. -"""], -["""\ -+--------------+ -| A table with | -+--------------+ -| two rows. | -+--------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="1"> - <colspec colwidth="14"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <row> - <entry> - <paragraph> - two rows. -"""], -["""\ -+--------------+-------------+ -| A table with | two columns | -+--------------+-------------+ -| and | two rows. | -+--------------+-------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="14"> - <colspec colwidth="13"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - two columns - <row> - <entry> - <paragraph> - and - <entry> - <paragraph> - two rows. -"""], -["""\ -+--------------+---------------+ -| A table with | two columns, | -+--------------+---------------+ -| two rows, and a column span. | -+------------------------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="14"> - <colspec colwidth="15"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - two columns, - <row> - <entry morecols="1"> - <paragraph> - two rows, and a column span. -"""], -["""\ -+--------------------------+ -| A table with three rows, | -+------------+-------------+ -| and two | columns. | -+------------+-------------+ -| First and last rows | -| contains column spans. | -+--------------------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="12"> - <colspec colwidth="13"> - <tbody> - <row> - <entry morecols="1"> - <paragraph> - A table with three rows, - <row> - <entry> - <paragraph> - and two - <entry> - <paragraph> - columns. - <row> - <entry morecols="1"> - <paragraph> - First and last rows - contains column spans. -"""], -["""\ -+--------------+--------------+ -| A table with | two columns, | -+--------------+ and a row | -| two rows, | span. | -+--------------+--------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="14"> - <colspec colwidth="14"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry morerows="1"> - <paragraph> - two columns, - and a row - span. - <row> - <entry> - <paragraph> - two rows, -"""], -["""\ -+------------+-------------+---------------+ -| A table | two rows in | and row spans | -| with three +-------------+ to left and | -| columns, | the middle, | right. | -+------------+-------------+---------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="3"> - <colspec colwidth="12"> - <colspec colwidth="13"> - <colspec colwidth="15"> - <tbody> - <row> - <entry morerows="1"> - <paragraph> - A table - with three - columns, - <entry> - <paragraph> - two rows in - <entry morerows="1"> - <paragraph> - and row spans - to left and - right. - <row> - <entry> - <paragraph> - the middle, -"""], -["""\ -Complex spanning pattern (no edge knows all rows/cols): - -+-----------+-------------------------+ -| W/NW cell | N/NE cell | -| +-------------+-----------+ -| | Middle cell | E/SE cell | -+-----------+-------------+ | -| S/SE cell | | -+-------------------------+-----------+ -""", -"""\ -<document source="test data"> - <paragraph> - Complex spanning pattern (no edge knows all rows/cols): - <table> - <tgroup cols="3"> - <colspec colwidth="11"> - <colspec colwidth="13"> - <colspec colwidth="11"> - <tbody> - <row> - <entry morerows="1"> - <paragraph> - W/NW cell - <entry morecols="1"> - <paragraph> - N/NE cell - <row> - <entry> - <paragraph> - Middle cell - <entry morerows="1"> - <paragraph> - E/SE cell - <row> - <entry morecols="1"> - <paragraph> - S/SE cell -"""], -["""\ -+------------------------+------------+----------+----------+ -| Header row, column 1 | Header 2 | Header 3 | Header 4 | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | Cells may span columns. | -+------------------------+------------+---------------------+ -| body row 3 | Cells may | - Table cells | -+------------------------+ span rows. | - contain | -| body row 4 | | - body elements. | -+------------------------+------------+---------------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="4"> - <colspec colwidth="24"> - <colspec colwidth="12"> - <colspec colwidth="10"> - <colspec colwidth="10"> - <thead> - <row> - <entry> - <paragraph> - Header row, column 1 - <entry> - <paragraph> - Header 2 - <entry> - <paragraph> - Header 3 - <entry> - <paragraph> - Header 4 - <tbody> - <row> - <entry> - <paragraph> - body row 1, column 1 - <entry> - <paragraph> - column 2 - <entry> - <paragraph> - column 3 - <entry> - <paragraph> - column 4 - <row> - <entry> - <paragraph> - body row 2 - <entry morecols="2"> - <paragraph> - Cells may span columns. - <row> - <entry> - <paragraph> - body row 3 - <entry morerows="1"> - <paragraph> - Cells may - span rows. - <entry morecols="1" morerows="1"> - <bullet_list bullet="-"> - <list_item> - <paragraph> - Table cells - <list_item> - <paragraph> - contain - <list_item> - <paragraph> - body elements. - <row> - <entry> - <paragraph> - body row 4 -"""], -["""\ -+-----------------+--------+ -| A simple table | cell 2 | -+-----------------+--------+ -| cell 3 | cell 4 | -+-----------------+--------+ -No blank line after table. -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="17"> - <colspec colwidth="8"> - <tbody> - <row> - <entry> - <paragraph> - A simple table - <entry> - <paragraph> - cell 2 - <row> - <entry> - <paragraph> - cell 3 - <entry> - <paragraph> - cell 4 - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Blank line required after table. - <paragraph> - No blank line after table. -"""], -["""\ -+-----------------+--------+ -| A simple table | cell 2 | -+-----------------+--------+ -| cell 3 | cell 4 | -+-----------------+--------+ - Unexpected indent and no blank line after table. -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="17"> - <colspec colwidth="8"> - <tbody> - <row> - <entry> - <paragraph> - A simple table - <entry> - <paragraph> - cell 2 - <row> - <entry> - <paragraph> - cell 3 - <entry> - <paragraph> - cell 4 - <system_message level="3" line="6" source="test data" type="ERROR"> - <paragraph> - Unexpected indentation. - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Blank line required after table. - <block_quote> - <paragraph> - Unexpected indent and no blank line after table. -"""], -["""\ -+--------------+-------------+ -| A bad table. | | -+--------------+ | -| Cells must be rectangles. | -+----------------------------+ -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - Malformed table; parse incomplete. - <literal_block xml:space="preserve"> - +--------------+-------------+ - | A bad table. | | - +--------------+ | - | Cells must be rectangles. | - +----------------------------+ -"""], -["""\ -+------------------------------+ -| This table contains another. | -| | -| +-------------------------+ | -| | A table within a table. | | -| +-------------------------+ | -+------------------------------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="1"> - <colspec colwidth="30"> - <tbody> - <row> - <entry> - <paragraph> - This table contains another. - <table> - <tgroup cols="1"> - <colspec colwidth="25"> - <tbody> - <row> - <entry> - <paragraph> - A table within a table. -"""], -["""\ -+------------------+--------+ -| A simple table | | -+------------------+--------+ -| with empty cells | | -+------------------+--------+ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="18"> - <colspec colwidth="8"> - <tbody> - <row> - <entry> - <paragraph> - A simple table - <entry> - <row> - <entry> - <paragraph> - with empty cells - <entry> -"""], -[("""\ -+------------------------------------------------------------------------------+ -| .. include:: | -%s -+------------------------------------------------------------------------------+ -| (The first cell of this table may expand | -| to accommodate long filesystem paths.) | -+------------------------------------------------------------------------------+ -""") % ('\n'.join(['| %-70s |' % include2[part * 70 : (part + 1) * 70] - for part in range(len(include2) / 70 + 1)])), -"""\ -<document source="test data"> - <table> - <tgroup cols="1"> - <colspec colwidth="78"> - <tbody> - <row> - <entry> - <paragraph> - Here are some paragraphs - that can appear at any level. - <paragraph> - This file (include2.txt) is used by - <literal> - test_include.py - . - <row> - <entry> - <paragraph> - (The first cell of this table may expand - to accommodate long filesystem paths.) -"""], -[("""\ -Something before. - -+------------------------------------------------------------------------------+ -| .. include:: | -%s -+------------------------------------------------------------------------------+ - -Something afterwards. - -And more. -""") % ('\n'.join(['| %-70s |' % include2[part * 70 : (part + 1) * 70] - for part in range(len(include2) / 70 + 1)])), -"""\ -<document source="test data"> - <paragraph> - Something before. - <table> - <tgroup cols="1"> - <colspec colwidth="78"> - <tbody> - <row> - <entry> - <paragraph> - Here are some paragraphs - that can appear at any level. - <paragraph> - This file (include2.txt) is used by - <literal> - test_include.py - . - <paragraph> - Something afterwards. - <paragraph> - And more. -"""], -] - -totest['simple_tables'] = [ -["""\ -============ ============ -A table with two columns. -============ ============ - -Paragraph. -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="12"> - <colspec colwidth="12"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - two columns. - <paragraph> - Paragraph. -"""], -["""\ -============ ============ -A table with two columns -and two rows. -============ ============ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="12"> - <colspec colwidth="12"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - two columns - <row> - <entry> - <paragraph> - and - <entry> - <paragraph> - two rows. -"""], -["""\ -============ ============== -A table with two columns, -two rows, and a column span. -============================ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="12"> - <colspec colwidth="14"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - two columns, - <row> - <entry morecols="1"> - <paragraph> - two rows, and a column span. -"""], -["""\ -== =========== =========== -1 A table with three rows, --- ------------------------ -2 and three columns. -3 First and third rows - contain column spans. - - This row is a multi-line row, and overflows to the right. --- ------------------------ -4 One last row. -== =========== =========== -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="3"> - <colspec colwidth="2"> - <colspec colwidth="11"> - <colspec colwidth="44"> - <tbody> - <row> - <entry> - <paragraph> - 1 - <entry morecols="1"> - <paragraph> - A table with three rows, - <row> - <entry> - <paragraph> - 2 - <entry> - <paragraph> - and three - <entry> - <paragraph> - columns. - <row> - <entry> - <paragraph> - 3 - <entry morecols="1"> - <paragraph> - First and third rows - contain column spans. - <paragraph> - This row is a multi-line row, and overflows to the right. - <row> - <entry> - <paragraph> - 4 - <entry> - <paragraph> - One last - <entry> - <paragraph> - row. -"""], -["""\ -======= ========= ======== -A table with three columns. -================== ======== -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="3"> - <colspec colwidth="7"> - <colspec colwidth="9"> - <colspec colwidth="8"> - <tbody> - <row> - <entry morecols="1"> - <paragraph> - A table with three - <entry> - <paragraph> - columns. -"""], -["""\ -============== ====== -A simple table with -no bottom border -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - No bottom table border found. - <literal_block xml:space="preserve"> - ============== ====== - A simple table with - no bottom border -"""], -["""\ -============== ====== -A simple table cell 2 -cell 3 cell 4 -============== ====== -No blank line after table. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - No bottom table border found or no blank line after table bottom. - <literal_block xml:space="preserve"> - ============== ====== - A simple table cell 2 - cell 3 cell 4 - ============== ====== - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Blank line required after table. - <paragraph> - No blank line after table. -"""], -["""\ -============== ====== -A simple table cell 2 -============== ====== -cell 3 cell 4 -============== ====== -No blank line after table. -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="14"> - <colspec colwidth="6"> - <thead> - <row> - <entry> - <paragraph> - A simple table - <entry> - <paragraph> - cell 2 - <tbody> - <row> - <entry> - <paragraph> - cell 3 - <entry> - <paragraph> - cell 4 - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Blank line required after table. - <paragraph> - No blank line after table. -"""], -["""\ -============== ====== -A simple table cell 2 -cell 3 cell 4 -============== ====== - Unexpected indent and no blank line after table. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - No bottom table border found or no blank line after table bottom. - <literal_block xml:space="preserve"> - ============== ====== - A simple table cell 2 - cell 3 cell 4 - ============== ====== - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Blank line required after table. - <block_quote> - <paragraph> - Unexpected indent and no blank line after table. -"""], -["""\ -============== ====== -A bad table cell 2 -cell 3 cell 4 -============ ======== -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - Column span alignment problem at line offset 3. - <literal_block xml:space="preserve"> - ============== ====== - A bad table cell 2 - cell 3 cell 4 - ============ ======== -"""], -["""\ -======== ========= -A bad table cell 2 -cell 3 cell 4 -======== ========= -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - Text in column margin at line offset 1. - <literal_block xml:space="preserve"> - ======== ========= - A bad table cell 2 - cell 3 cell 4 - ======== ========= -"""], -["""\ -== ============================ -1 This table contains another. -2 ======= ====== ======== - A table within a table. - ======= ====== ======== - - The outer table does have to - have at least two columns - though. -== ============================ -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="2"> - <colspec colwidth="28"> - <tbody> - <row> - <entry> - <paragraph> - 1 - <entry> - <paragraph> - This table contains another. - <row> - <entry> - <paragraph> - 2 - <entry> - <table> - <tgroup cols="3"> - <colspec colwidth="7"> - <colspec colwidth="6"> - <colspec colwidth="8"> - <tbody> - <row> - <entry> - <paragraph> - A table - <entry> - <paragraph> - within - <entry> - <paragraph> - a table. - <paragraph> - The outer table does have to - have at least two columns - though. -"""], -["""\ -================ ====== -A simple table -with empty cells -================ ====== -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="16"> - <colspec colwidth="6"> - <tbody> - <row> - <entry> - <paragraph> - A simple table - <entry> - <row> - <entry> - <paragraph> - with empty cells - <entry> -"""], -["""\ -============== ======== - A table with -============== ======== - centered cells. - -============== ======== -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="14"> - <colspec colwidth="8"> - <thead> - <row> - <entry> - <paragraph> - A table - <entry> - <paragraph> - with - <tbody> - <row> - <entry> - <paragraph> - centered - <entry> - <paragraph> - cells. -"""], -["""\ -============== ====== -A simple table this text extends to the right -cell 3 the bottom border below is too long -============== ======== -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - Bottom/header table border does not match top border. - <literal_block xml:space="preserve"> - ============== ====== - A simple table this text extends to the right - cell 3 the bottom border below is too long - ============== ======== -"""], -["""\ -============ ================= -A table with row separators. ------------- ----------------- - -Blank line before. ------------- ----------------- - -Blank lines before and after. - ------------- ----------------- -Blank line after. - -============ ================= -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="12"> - <colspec colwidth="17"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - row separators. - <row> - <entry> - <paragraph> - Blank line - <entry> - <paragraph> - before. - <row> - <entry> - <paragraph> - Blank lines - <entry> - <paragraph> - before and after. - <row> - <entry> - <paragraph> - Blank line - <entry> - <paragraph> - after. -"""], -["""\ -============ ==================== -A table with many row separators. ------------- -------------------- ------------- -------------------- - ------------- -------------------- -============ ==================== -""", -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="12"> - <colspec colwidth="20"> - <tbody> - <row> - <entry> - <paragraph> - A table with - <entry> - <paragraph> - many row separators. - <row> - <entry> - <entry> - <row> - <entry> - <entry> - <row> - <entry> - <entry> -"""], -["""\ -== =========== =========== -1 Span columns 2 & 3 --- ------------------------ -2 Span columns 2 & 3 - ------------------------ -3 -== =========== =========== - -== =========== =========== -1 Span cols 1&2 but not 3 ---------------- ----------- -2 Span cols 1&2 but not 3 ---------------- -3 no spans here -== =========== =========== - -== =========== =========== -1 Not a span Not a span - ----------- ----------- -2 -== =========== =========== -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Malformed table. - Text in column margin at line offset 3. - <literal_block xml:space="preserve"> - == =========== =========== - 1 Span columns 2 & 3 - -- ------------------------ - 2 Span columns 2 & 3 - ------------------------ - 3 - == =========== =========== - <system_message level="3" line="9" source="test data" type="ERROR"> - <paragraph> - Malformed table. - Column span incomplete at line offset 4. - <literal_block xml:space="preserve"> - == =========== =========== - 1 Span cols 1&2 but not 3 - --------------- ----------- - 2 Span cols 1&2 but not 3 - --------------- - 3 no spans here - == =========== =========== - <table> - <tgroup cols="3"> - <colspec colwidth="2"> - <colspec colwidth="11"> - <colspec colwidth="11"> - <tbody> - <row> - <entry> - <paragraph> - 1 - <entry> - <system_message level="4" line="20" source="test data" type="SEVERE"> - <paragraph> - Unexpected section title. - <literal_block xml:space="preserve"> - Not a span - ----------- - <entry> - <system_message level="4" line="20" source="test data" type="SEVERE"> - <paragraph> - Unexpected section title. - <literal_block xml:space="preserve"> - Not a span - ----------- - <row> - <entry> - <paragraph> - 2 - <entry> - <entry> -"""], -["""\ -========= ===================================================================== -Inclusion .. include:: -%s -Note The first row of this table may expand - to accommodate long filesystem paths. -========= ===================================================================== -""" % ('\n'.join([' %-65s' % include2[part * 65 : (part + 1) * 65] - for part in range(len(include2) / 65 + 1)])), -"""\ -<document source="test data"> - <table> - <tgroup cols="2"> - <colspec colwidth="9"> - <colspec colwidth="69"> - <tbody> - <row> - <entry> - <paragraph> - Inclusion - <entry> - <paragraph> - Here are some paragraphs - that can appear at any level. - <paragraph> - This file (include2.txt) is used by - <literal> - test_include.py - . - <row> - <entry> - <paragraph> - Note - <entry> - <paragraph> - The first row of this table may expand - to accommodate long filesystem paths. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_targets.py b/docutils/test/test_parsers/test_rst/test_targets.py deleted file mode 100755 index 362bf2cca..000000000 --- a/docutils/test/test_parsers/test_rst/test_targets.py +++ /dev/null @@ -1,440 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for states.py. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['targets'] = [ -["""\ -.. _target: - -(Internal hyperlink target.) -""", -"""\ -<document source="test data"> - <target ids="target" names="target"> - <paragraph> - (Internal hyperlink target.) -"""], -["""\ -.. _optional space before colon : -""", -"""\ -<document source="test data"> - <target ids="optional-space-before-colon" names="optional\ space\ before\ colon"> -"""], -["""\ -External hyperlink targets: - -.. _one-liner: http://structuredtext.sourceforge.net - -.. _starts-on-this-line: http:// - structuredtext. - sourceforge.net - -.. _entirely-below: - http://structuredtext. - sourceforge.net - -.. _not-indirect: uri\\_ -""", -"""\ -<document source="test data"> - <paragraph> - External hyperlink targets: - <target ids="one-liner" names="one-liner" refuri="http://structuredtext.sourceforge.net"> - <target ids="starts-on-this-line" names="starts-on-this-line" refuri="http://structuredtext.sourceforge.net"> - <target ids="entirely-below" names="entirely-below" refuri="http://structuredtext.sourceforge.net"> - <target ids="not-indirect" names="not-indirect" refuri="uri_"> -"""], -["""\ -Indirect hyperlink targets: - -.. _target1: reference_ - -.. _target2: `phrase-link reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - Indirect hyperlink targets: - <target ids="target1" names="target1" refname="reference"> - <target ids="target2" names="target2" refname="phrase-link reference"> -"""], -["""\ -.. _a long target name: - -.. _`a target name: including a colon (quoted)`: - -.. _a target name\: including a colon (escaped): -""", -"""\ -<document source="test data"> - <target ids="a-long-target-name" names="a\ long\ target\ name"> - <target ids="a-target-name-including-a-colon-quoted" names="a\ target\ name:\ including\ a\ colon\ (quoted)"> - <target ids="a-target-name-including-a-colon-escaped" names="a\ target\ name:\ including\ a\ colon\ (escaped)"> -"""], -["""\ -.. _a very long target name, - split across lines: -.. _`and another, - with backquotes`: -""", -"""\ -<document source="test data"> - <target ids="a-very-long-target-name-split-across-lines" names="a\ very\ long\ target\ name,\ split\ across\ lines"> - <target ids="and-another-with-backquotes" names="and\ another,\ with\ backquotes"> -"""], -["""\ -External hyperlink: - -.. _target: http://www.python.org/ -""", -"""\ -<document source="test data"> - <paragraph> - External hyperlink: - <target ids="target" names="target" refuri="http://www.python.org/"> -"""], -["""\ -.. _email: jdoe@example.com - -.. _multi-line email: jdoe - @example.com -""", -"""\ -<document source="test data"> - <target ids="email" names="email" refuri="mailto:jdoe@example.com"> - <target ids="multi-line-email" names="multi-line\ email" refuri="mailto:jdoe@example.com"> -"""], -["""\ -Duplicate external targets (different URIs): - -.. _target: first - -.. _target: second -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate external targets (different URIs): - <target dupnames="target" ids="target" refuri="first"> - <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <target dupnames="target" ids="id1" refuri="second"> -"""], -["""\ -Duplicate external targets (same URIs): - -.. _target: first - -.. _target: first -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate external targets (same URIs): - <target ids="target" names="target" refuri="first"> - <system_message backrefs="id1" level="1" line="5" source="test data" type="INFO"> - <paragraph> - Duplicate explicit target name: "target". - <target dupnames="target" ids="id1" refuri="first"> -"""], -["""\ -Duplicate implicit targets. - -Title -===== - -Paragraph. - -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate implicit targets. - <section dupnames="title" ids="title"> - <title> - Title - <paragraph> - Paragraph. - <section dupnames="title" ids="id1"> - <title> - Title - <system_message backrefs="id1" level="1" line="9" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "title". - <paragraph> - Paragraph. -"""], -["""\ -Duplicate implicit/explicit targets. - -Title -===== - -.. _title: - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate implicit/explicit targets. - <section dupnames="title" ids="title"> - <title> - Title - <system_message backrefs="id1" level="1" line="6" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "title". - <target ids="id1" names="title"> - <paragraph> - Paragraph. -"""], -["""\ -Duplicate explicit targets. - -.. _title: - -First. - -.. _title: - -Second. - -.. _title: - -Third. -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate explicit targets. - <target dupnames="title" ids="title"> - <paragraph> - First. - <system_message backrefs="id1" level="2" line="7" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "title". - <target dupnames="title" ids="id1"> - <paragraph> - Second. - <system_message backrefs="id2" level="2" line="11" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "title". - <target dupnames="title" ids="id2"> - <paragraph> - Third. -"""], -["""\ -Duplicate targets: - -Target -====== - -Implicit section header target. - -.. [target] Citation target. - -.. [#target] Autonumber-labeled footnote target. - -.. _target: - -Explicit internal target. - -.. _target: Explicit_external_target -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate targets: - <section dupnames="target" ids="target"> - <title> - Target - <paragraph> - Implicit section header target. - <citation dupnames="target" ids="id1"> - <label> - target - <system_message backrefs="id1" level="1" line="8" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "target". - <paragraph> - Citation target. - <footnote auto="1" dupnames="target" ids="id2"> - <system_message backrefs="id2" level="2" line="10" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <paragraph> - Autonumber-labeled footnote target. - <system_message backrefs="id3" level="2" line="12" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <target dupnames="target" ids="id3"> - <paragraph> - Explicit internal target. - <system_message backrefs="id4" level="2" line="16" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <target dupnames="target" ids="id4" refuri="Explicit_external_target"> -"""], -["""\ -.. _unescaped colon at end:: no good - -.. _:: no good either - -.. _escaped colon\:: OK - -.. _`unescaped colon, quoted:`: OK -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - _unescaped colon at end:: no good - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - malformed hyperlink target. - <comment xml:space="preserve"> - _:: no good either - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - malformed hyperlink target. - <target ids="escaped-colon" names="escaped\ colon:" refuri="OK"> - <target ids="unescaped-colon-quoted" names="unescaped\ colon,\ quoted:" refuri="OK"> -"""], -] - -totest['anonymous_targets'] = [ -["""\ -Anonymous external hyperlink target: - -.. __: http://w3c.org/ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous external hyperlink target: - <target anonymous="1" ids="id1" refuri="http://w3c.org/"> -"""], -["""\ -Anonymous external hyperlink target: - -__ http://w3c.org/ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous external hyperlink target: - <target anonymous="1" ids="id1" refuri="http://w3c.org/"> -"""], -["""\ -Anonymous indirect hyperlink target: - -.. __: reference_ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous indirect hyperlink target: - <target anonymous="1" ids="id1" refname="reference"> -"""], -["""\ -Anonymous external hyperlink target, not indirect: - -__ uri\\_ - -__ this URI ends with an underscore_ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous external hyperlink target, not indirect: - <target anonymous="1" ids="id1" refuri="uri_"> - <target anonymous="1" ids="id2" refuri="thisURIendswithanunderscore_"> -"""], -["""\ -Anonymous indirect hyperlink targets: - -__ reference_ -__ `a very long - reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous indirect hyperlink targets: - <target anonymous="1" ids="id1" refname="reference"> - <target anonymous="1" ids="id2" refname="a very long reference"> -"""], -["""\ -Mixed anonymous & named indirect hyperlink targets: - -__ reference_ -.. __: reference_ -__ reference_ -.. _target1: reference_ -no blank line - -.. _target2: reference_ -__ reference_ -.. __: reference_ -__ reference_ -no blank line -""", -"""\ -<document source="test data"> - <paragraph> - Mixed anonymous & named indirect hyperlink targets: - <target anonymous="1" ids="id1" refname="reference"> - <target anonymous="1" ids="id2" refname="reference"> - <target anonymous="1" ids="id3" refname="reference"> - <target ids="target1" names="target1" refname="reference"> - <system_message level="2" line="7" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - no blank line - <target ids="target2" names="target2" refname="reference"> - <target anonymous="1" ids="id4" refname="reference"> - <target anonymous="1" ids="id5" refname="reference"> - <target anonymous="1" ids="id6" refname="reference"> - <system_message level="2" line="13" source="test data" type="WARNING"> - <paragraph> - Explicit markup ends without a blank line; unexpected unindent. - <paragraph> - no blank line -"""], -["""\ -.. _ -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - _ -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_parsers/test_rst/test_transitions.py b/docutils/test/test_parsers/test_rst/test_transitions.py deleted file mode 100755 index c60a28e96..000000000 --- a/docutils/test/test_parsers/test_rst/test_transitions.py +++ /dev/null @@ -1,309 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for transition markers. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -# See DocutilsTestSupport.ParserTestSuite.generateTests for a -# description of the 'totest' data structure. -totest['transitions'] = [ -["""\ -Test transition markers. - --------- - -Paragraph -""", -"""\ -<document source="test data"> - <paragraph> - Test transition markers. - <transition> - <paragraph> - Paragraph -"""], -["""\ -Section 1 -========= -First text division of section 1. - --------- - -Second text division of section 1. - -Section 2 ---------- -Paragraph 2 in section 2. -""", -"""\ -<document source="test data"> - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <paragraph> - First text division of section 1. - <transition> - <paragraph> - Second text division of section 1. - <section ids="section-2" names="section\ 2"> - <title> - Section 2 - <paragraph> - Paragraph 2 in section 2. -"""], -["""\ --------- - -A section or document may not begin with a transition. - -The DTD specifies that two transitions may not -be adjacent: - --------- - --------- - --------- - -The DTD also specifies that a section or document -may not end with a transition. - --------- -""", -"""\ -<document source="test data"> - <transition> - <paragraph> - A section or document may not begin with a transition. - <paragraph> - The DTD specifies that two transitions may not - be adjacent: - <transition> - <transition> - <transition> - <paragraph> - The DTD also specifies that a section or document - may not end with a transition. - <transition> -"""], -["""\ -Test unexpected transition markers. - - Block quote. - - -------- - - Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Test unexpected transition markers. - <block_quote> - <paragraph> - Block quote. - <system_message level="4" line="5" source="test data" type="SEVERE"> - <paragraph> - Unexpected section title or transition. - <literal_block xml:space="preserve"> - -------- - <paragraph> - Paragraph. -"""], -["""\ -Short transition marker. - ---- - -Paragraph -""", -"""\ -<document source="test data"> - <paragraph> - Short transition marker. - <paragraph> - --- - <paragraph> - Paragraph -"""], -["""\ -Sections with transitions at beginning and end. - -Section 1 -========= - ----------- - -The next transition is legal: - ----------- - -Section 2 -========= - ----------- -""", -"""\ -<document source="test data"> - <paragraph> - Sections with transitions at beginning and end. - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <transition> - <paragraph> - The next transition is legal: - <transition> - <section ids="section-2" names="section\ 2"> - <title> - Section 2 - <transition> -"""], -["""\ -A paragraph, two transitions, and a blank line. - ----------- - ----------- - -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph, two transitions, and a blank line. - <transition> - <transition> -"""], -["""\ -A paragraph and two transitions. - ----------- - ----------- -""", # the same: -"""\ -<document source="test data"> - <paragraph> - A paragraph and two transitions. - <transition> - <transition> -"""], -["""\ ----------- - -Document beginning with a transition. -""", -"""\ -<document source="test data"> - <transition> - <paragraph> - Document beginning with a transition. -"""], -["""\ -Section 1 -========= - -Subsection 1 ------------- - -Some text. - ----------- - -Section 2 -========= - -Some text. -""", -"""\ -<document source="test data"> - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <section ids="subsection-1" names="subsection\ 1"> - <title> - Subsection 1 - <paragraph> - Some text. - <transition> - <section ids="section-2" names="section\ 2"> - <title> - Section 2 - <paragraph> - Some text. -"""], -["""\ -Section 1 -========= - ----------- - ----------- - ----------- - -Section 2 -========= - -Some text. -""", -"""\ -<document source="test data"> - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <transition> - <transition> - <transition> - <section ids="section-2" names="section\ 2"> - <title> - Section 2 - <paragraph> - Some text. -"""], -["""\ ----------- - ----------- - ----------- -""", -"""\ -<document source="test data"> - <transition> - <transition> - <transition> -"""], -["""\ -A paragraph. - ----------- - -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph. - <transition> -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_publisher.py b/docutils/test/test_publisher.py deleted file mode 100755 index 708c3ef87..000000000 --- a/docutils/test/test_publisher.py +++ /dev/null @@ -1,143 +0,0 @@ -#!/usr/bin/env python - -# Author: Martin Blais -# Contact: blais@furius.ca -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test the `Publisher` facade and the ``publish_*`` convenience functions. -""" - -import pickle -from types import StringType, DictType -import DocutilsTestSupport # must be imported before docutils -import docutils -from docutils import core, nodes, io - - -test_document = """\ -Test Document -============= - -This is a test document with a broken reference: nonexistent_ -""" -pseudoxml_output = """\ -<document ids="test-document" names="test\ document" source="<string>" title="Test Document"> - <title> - Test Document - <paragraph> - This is a test document with a broken reference: \n\ - <problematic ids="id2" refid="id1"> - nonexistent_ - <section classes="system-messages"> - <title> - Docutils System Messages - <system_message backrefs="id2" ids="id1" level="3" line="4" source="<string>" type="ERROR"> - <paragraph> - Unknown target name: "nonexistent". -""" -exposed_pseudoxml_output = """\ -<document ids="test-document" internal:refnames="{u\'nonexistent\': [<reference: <#text: u\'nonexistent\'>>]}" names="test\ document" source="<string>" title="Test Document"> - <title> - Test Document - <paragraph> - This is a test document with a broken reference: \n\ - <problematic ids="id2" refid="id1"> - nonexistent_ - <section classes="system-messages"> - <title> - Docutils System Messages - <system_message backrefs="id2" ids="id1" level="3" line="4" source="<string>" type="ERROR"> - <paragraph> - Unknown target name: "nonexistent". -""" - - -class PublishDoctreeTestCase(DocutilsTestSupport.StandardTestCase, docutils.SettingsSpec): - - settings_default_overrides = { - '_disable_config': 1, - 'warning_stream': io.NullOutput()} - - def test_publish_doctree(self): - # Test `publish_doctree` and `publish_from_doctree`. - - # Produce the document tree. - doctree = core.publish_doctree( - source=test_document, reader_name='standalone', - parser_name='restructuredtext', settings_spec=self, - settings_overrides={'expose_internals': - ['refnames', 'do_not_expose'], - 'report_level': 5}) - self.assert_(isinstance(doctree, nodes.document)) - - # Confirm that transforms have been applied (in this case, the - # DocTitle transform): - self.assert_(isinstance(doctree[0], nodes.title)) - self.assert_(isinstance(doctree[1], nodes.paragraph)) - # Confirm that the Messages transform has not yet been applied: - self.assertEquals(len(doctree), 2) - - # The `do_not_expose` attribute may not show up in the - # pseudoxml output because the expose_internals transform may - # not be applied twice. - doctree.do_not_expose = 'test' - # Write out the document: - output = core.publish_from_doctree( - doctree, writer_name='pseudoxml', - settings_spec=self, - settings_overrides={'expose_internals': - ['refnames', 'do_not_expose'], - 'report_level': 1}) - self.assertEquals(output, exposed_pseudoxml_output) - - # Test publishing parts using document as the source. - parts = core.publish_parts( - reader_name='doctree', source_class=io.DocTreeInput, - source=doctree, source_path='test', writer_name='html', - settings_spec=self) - self.assert_(isinstance(parts, DictType)) - - def test_publish_pickle(self): - # Test publishing a document tree with pickling and unpickling. - - # Produce the document tree. - doctree = core.publish_doctree( - source=test_document, - reader_name='standalone', - parser_name='restructuredtext', - settings_spec=self) - self.assert_(isinstance(doctree, nodes.document)) - - # Pickle the document. Note: if this fails, some unpickleable - # reference has been added somewhere within the document tree. - # If so, you need to fix that. - # - # Note: Please do not remove this test, this is an important - # requirement, applications will be built on the assumption - # that we can pickle the document. - - # Remove the reporter and the transformer before pickling. - doctree.reporter = None - doctree.transformer = None - - doctree_pickled = pickle.dumps(doctree) - self.assert_(isinstance(doctree_pickled, StringType)) - del doctree - - # Unpickle the document. - doctree_zombie = pickle.loads(doctree_pickled) - self.assert_(isinstance(doctree_zombie, nodes.document)) - - # Write out the document: - output = core.publish_from_doctree( - doctree_zombie, writer_name='pseudoxml', - settings_spec=self) - self.assertEquals(output, pseudoxml_output) - - -if __name__ == '__main__': - import unittest - unittest.main() diff --git a/docutils/test/test_readers/__init__.py b/docutils/test/test_readers/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_readers/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_readers/test_pep/__init__.py b/docutils/test/test_readers/test_pep/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_readers/test_pep/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_readers/test_pep/test_inline_markup.py b/docutils/test/test_readers/test_pep/test_inline_markup.py deleted file mode 100755 index 4965af3d1..000000000 --- a/docutils/test/test_readers/test_pep/test_inline_markup.py +++ /dev/null @@ -1,140 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for inline markup in PEPs (readers/pep.py). -""" - -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.PEPParserTestSuite() - s.generateTests(totest) - return s - - -totest = {} - -totest['standalone_references'] = [ -["""\ -See PEP 287 (pep-0287.txt), -and RFC 2822 (which obsoletes RFC822 and RFC-733). -""", -"""\ -<document source="test data"> - <paragraph> - See \n\ - <reference refuri="http://www.python.org/peps/pep-0287.html"> - PEP 287 - ( - <reference refuri="http://www.python.org/peps/pep-0287.html"> - pep-0287.txt - ), - and \n\ - <reference refuri="http://www.faqs.org/rfcs/rfc2822.html"> - RFC 2822 - (which obsoletes \n\ - <reference refuri="http://www.faqs.org/rfcs/rfc822.html"> - RFC822 - and \n\ - <reference refuri="http://www.faqs.org/rfcs/rfc733.html"> - RFC-733 - ). -"""], -["""\ -References split across lines: - -PEP -287 - -RFC -2822 -""", -"""\ -<document source="test data"> - <paragraph> - References split across lines: - <paragraph> - <reference refuri="http://www.python.org/peps/pep-0287.html"> - PEP - 287 - <paragraph> - <reference refuri="http://www.faqs.org/rfcs/rfc2822.html"> - RFC - 2822 -"""], -["""\ -Test PEP-specific implicit references before a URL: - -PEP 287 (http://www.python.org/peps/pep-0287.html), RFC 2822. -""", -"""\ -<document source="test data"> - <paragraph> - Test PEP-specific implicit references before a URL: - <paragraph> - <reference refuri="http://www.python.org/peps/pep-0287.html"> - PEP 287 - ( - <reference refuri="http://www.python.org/peps/pep-0287.html"> - http://www.python.org/peps/pep-0287.html - ), \n\ - <reference refuri="http://www.faqs.org/rfcs/rfc2822.html"> - RFC 2822 - . -"""], -] - -totest['miscellaneous'] = [ -["""\ -For *completeness*, _`let's` ``test`` **other** forms_ -|of| `inline markup` [*]_. - -.. [*] See http://docutils.sf.net/docs/ref/rst/restructuredtext.html. -""", -"""\ -<document source="test data"> - <paragraph> - For \n\ - <emphasis> - completeness - , \n\ - <target ids="let-s" names="let's"> - let's - \n\ - <literal> - test - \n\ - <strong> - other - \n\ - <reference name="forms" refname="forms"> - forms - \n\ - <substitution_reference refname="of"> - of - \n\ - <title_reference> - inline markup - \n\ - <footnote_reference auto="*" ids="id1"> - . - <footnote auto="*" ids="id2"> - <paragraph> - See \n\ - <reference refuri="http://docutils.sf.net/docs/ref/rst/restructuredtext.html"> - http://docutils.sf.net/docs/ref/rst/restructuredtext.html - . -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_readers/test_pep/test_rfc2822.py b/docutils/test/test_readers/test_pep/test_rfc2822.py deleted file mode 100755 index 82fa27543..000000000 --- a/docutils/test/test_readers/test_pep/test_rfc2822.py +++ /dev/null @@ -1,291 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for RFC-2822 headers in PEPs (readers/pep.py). -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.PEPParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['rfc2822'] = [ -["""\ -Author: Me -Version: 1 -Date: 2002-04-23 -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2002-04-23 -"""], -["""\ - - -Author: Me -Version: 1 -Date: 2002-04-23 - -.. Leading blank lines don't affect RFC-2822 header parsing. -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2002-04-23 - <comment xml:space="preserve"> - Leading blank lines don't affect RFC-2822 header parsing. -"""], -["""\ -.. A comment should prevent RFC-2822 header parsing. - -Author: Me -Version: 1 -Date: 2002-04-23 -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - A comment should prevent RFC-2822 header parsing. - <paragraph> - Author: Me - Version: 1 - Date: 2002-04-23 -"""], -["""\ -Author: Me - -Version: 1 -Date: 2002-04-23 -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <paragraph> - Version: 1 - Date: 2002-04-23 -"""], -["""\ -field: -empty item above, no blank line -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - field - <field_body> - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - RFC2822-style field list ends without a blank line; unexpected unindent. - <paragraph> - empty item above, no blank line -"""], -["""\ -Author: - Me -Version: - 1 -Date: - 2002-04-23 -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2002-04-23 -"""], -["""\ -Authors: Me, - Myself, - and I -Version: 1 - or so -Date: 2002-04-23 - (Tuesday) -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Authors - <field_body> - <paragraph> - Me, - Myself, - and I - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - or so - <field> - <field_name> - Date - <field_body> - <paragraph> - 2002-04-23 - (Tuesday) -"""], -["""\ -Authors: Me, - Myself, - and I -Version: 1 - or so -Date: 2002-04-23 - (Tuesday) -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Authors - <field_body> - <paragraph> - Me, - Myself, - and I - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - or so - <field> - <field_name> - Date - <field_body> - <paragraph> - 2002-04-23 - (Tuesday) -"""], -["""\ -Authors: - Me - - Myself - - I -Version: -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Authors - <field_body> - <bullet_list bullet="-"> - <list_item> - <paragraph> - Me - <list_item> - <paragraph> - Myself - <list_item> - <paragraph> - I - <field> - <field_name> - Version - <field_body> -"""], -["""\ -Authors: Me - - Myself and I -Version: -""", -"""\ -<document source="test data"> - <field_list classes="rfc2822"> - <field> - <field_name> - Authors - <field_body> - <paragraph> - Me - <block_quote> - <paragraph> - Myself and I - <system_message level="2" line="4" source="test data" type="WARNING"> - <paragraph> - Block quote ends without a blank line; unexpected unindent. - <paragraph> - Version: -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_readers/test_python/__init__.py b/docutils/test/test_readers/test_python/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_readers/test_python/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_readers/test_python/showast b/docutils/test/test_readers/test_python/showast deleted file mode 100755 index e7d846307..000000000 --- a/docutils/test/test_readers/test_python/showast +++ /dev/null @@ -1,57 +0,0 @@ -#! /usr/bin/env python - -""" -This is a tool for exploring abstract syntax trees generated by -``compiler.parse()`` from test data in -docutils/test/test_readers/test_python/test_parser or stdin. - -Usage:: - - showast <key> <index> - - showast < <module.py> - -Where ``<key>`` is the key to the ``totest`` dictionary, and ``<index>`` is -the index of the list ``totest[key]``. If no arguments are given, stdin is -used for input. -""" - -import sys -import compiler -from compiler.ast import Node -import test_parser - -def pformat(ast, indent=' ', level=0): - assert isinstance(ast, Node), 'ast is not a Node: %r' % (ast,) - atts = {} - for name, value in vars(ast).items(): - if not value or isinstance(value, Node): - continue - if isinstance(value, list): - if isinstance(value[0], Node): - continue - if isinstance(value[0], tuple) and value[0] \ - and isinstance(value[0][0], Node): - continue - atts[name] = str(value).encode('unicode-escape') - attlist = atts.items() - attlist.sort() - parts = [ast.__class__.__name__] - for name, value in attlist: - parts.append('%s="%s"' % (name, value)) - result = ['%s<%s>\n' % (indent * level, ' '.join(parts))] - for node in ast.getChildNodes(): - result.extend(pformat(node, level=level+1)) - return result - -if len(sys.argv) > 1: - key, caseno = sys.argv[1:] - print 'totest["%s"][%s][0]:\n' % (key, caseno) - input_text = test_parser.totest[key][int(caseno)][0] -else: - input_text = sys.stdin.read() -print input_text -module = compiler.parse(input_text) -print module -print -print ''.join(pformat(module)), diff --git a/docutils/test/test_readers/test_python/showdoc b/docutils/test/test_readers/test_python/showdoc deleted file mode 100755 index 6461960f8..000000000 --- a/docutils/test/test_readers/test_python/showdoc +++ /dev/null @@ -1,33 +0,0 @@ -#! /usr/bin/env python - -""" -This is a tool for exploring module documentation trees generated by -``docutils.readers.python.moduleparser.parse_module()`` from test data in -docutils/test/test_readers/test_python/test_parser or stdin. - -Usage:: - - showdoc <key> <index> - - showdoc < <module.py> - -Where ``<key>`` is the key to the ``totest`` dictionary, and ``<index>`` is -the index of the list ``totest[key]``. If no arguments are given, stdin is -used for input. -""" - -import sys -from docutils.readers.python.moduleparser import parse_module -import test_parser - -if len(sys.argv) > 1: - key, caseno = sys.argv[1:] - print 'totest["%s"][%s][0]:\n' % (key, caseno) - input_text = test_parser.totest[key][int(caseno)][0] - input_source = "test_parser.totest['%s'][%s][0]" % (key, caseno) -else: - input_text = sys.stdin.read() - input_source = '<stdin>' -print input_text -module = parse_module(input_text, input_source) -print module, diff --git a/docutils/test/test_readers/test_python/showparse b/docutils/test/test_readers/test_python/showparse deleted file mode 100755 index 8144256d6..000000000 --- a/docutils/test/test_readers/test_python/showparse +++ /dev/null @@ -1,48 +0,0 @@ -#! /usr/bin/env python - -""" -This is a tool for exploring abstract syntax trees generated by -``parser.suite()`` from test data in -docutils/test/test_readers/test_python/test_parser or stdin. - -Usage:: - - showparse <key> <index> - - showparse < <module.py> - -Where ``<key>`` is the key to the ``totest`` dictionary, and ``<index>`` is -the index of the list ``totest[key]``. If no arguments are given, stdin is -used for input. -""" - -import sys -import types -import parser -import token -import symbol -import pprint -import test_parser - -names = token.tok_name.copy() -names.update(symbol.sym_name) - -def name_elements(ast): - if ast: - name = names[ast[0]] - ast[0] = '%s (%s)' % (name, ast[0]) - for node in ast[1:]: - if type(node) == types.ListType: - name_elements(node) - -if len(sys.argv) > 1: - key, caseno = sys.argv[1:] - print 'totest["%s"][%s][0]:\n' % (key, caseno) - input_text = test_parser.totest[key][int(caseno)][0] -else: - input_text = sys.stdin.read() -print input_text -module = parser.suite(input_text) -ast = parser.ast2list(module, line_info=1) -name_elements(ast) -pprint.pprint(ast) diff --git a/docutils/test/test_readers/test_python/showtok b/docutils/test/test_readers/test_python/showtok deleted file mode 100755 index efd250ce1..000000000 --- a/docutils/test/test_readers/test_python/showtok +++ /dev/null @@ -1,40 +0,0 @@ -#! /usr/bin/env python - - -""" -This is a tool for exploring token lists generated by -``tokenize.generate_tokens()`` from test data in -docutils/test/test_readers/test_python/test_parser or stdin. - -Usage:: - - showtok <key> <index> - - showtok < <module.py> - -Where ``<key>`` is the key to the ``totest`` dictionary, and ``<index>`` is -the index of the list ``totest[key]``. If no arguments are given, stdin is -used for input. -""" - -import sys -import tokenize -import pprint -from token import tok_name -import test_parser - -def name_tokens(tokens): - for i in range(len(tokens)): - tup = tokens[i] - tokens[i] = (tok_name[tup[0]], tup) - -if len(sys.argv) > 1: - key, caseno = sys.argv[1:] - print 'totest["%s"][%s][0]:\n' % (key, caseno) - input_text = test_parser.totest[key][int(caseno)][0] -else: - input_text = sys.stdin.read() -print input_text -tokens = list(tokenize.generate_tokens(iter(input_text.splitlines(1)).next)) -name_tokens(tokens) -pprint.pprint(tokens) diff --git a/docutils/test/test_readers/test_python/test_functions.py b/docutils/test/test_readers/test_python/test_functions.py deleted file mode 100755 index d521b2203..000000000 --- a/docutils/test/test_readers/test_python/test_functions.py +++ /dev/null @@ -1,56 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for PySource Reader functions. -""" - -import unittest -from __init__ import DocutilsTestSupport -from docutils.readers.python.moduleparser import trim_docstring - - -class MiscTests(unittest.TestCase): - - docstrings = ( - ("""""", """"""), # empty - ("""Begins on the first line. - - Middle line indented. - - Last line unindented. - """, - """\ -Begins on the first line. - - Middle line indented. - -Last line unindented."""), - (""" - Begins on the second line. - - Middle line indented. - - Last line unindented.""", - """\ -Begins on the second line. - - Middle line indented. - -Last line unindented."""), - ("""All on one line.""", """All on one line.""")) - - def test_trim_docstring(self): - for docstring, expected in self.docstrings: - self.assertEquals(trim_docstring(docstring), expected) - self.assertEquals(trim_docstring('\n ' + docstring), - expected) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_readers/test_python/test_parser.py b/docutils/test/test_readers/test_python/test_parser.py deleted file mode 100755 index 1ccfbdc10..000000000 --- a/docutils/test/test_readers/test_python/test_parser.py +++ /dev/null @@ -1,989 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils/readers/python/moduleparser.py. -""" - -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.PythonModuleParserTestSuite() - s.generateTests(totest) - return s - -totest = {} - -totest['module'] = [ -['''\ -''', -'''\ -<module_section filename="test data"> -'''], -['''\ -"""docstring""" -''', -'''\ -<module_section filename="test data"> - <docstring> - docstring -'''], -['''\ -u"""Unicode docstring""" -''', -'''\ -<module_section filename="test data"> - <docstring> - Unicode docstring -'''], -['''\ -"""docstring""" -"""additional docstring""" -''', -'''\ -<module_section filename="test data"> - <docstring> - docstring - <docstring lineno="2"> - additional docstring -'''], -['''\ -"""docstring""" -# comment -"""additional docstring""" -''', -'''\ -<module_section filename="test data"> - <docstring> - docstring - <docstring lineno="3"> - additional docstring -'''], -['''\ -"""docstring""" -1 -"""not an additional docstring""" -''', -'''\ -<module_section filename="test data"> - <docstring> - docstring -'''], -] - -totest['import'] = [ -['''\ -import module -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_name> - module -'''], -['''\ -import module as local -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_name> - module - <import_alias> - local -'''], -['''\ -import module.name -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_name> - module.name -'''], -['''\ -import module.name as local -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_name> - module.name - <import_alias> - local -'''], -['''\ -import module -"""not documentable""" -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_name> - module -'''], -] - -totest['from'] = [ -['''\ -from module import name -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_from> - module - <import_name> - name -'''], -['''\ -from module import name as local -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_from> - module - <import_name> - name - <import_alias> - local -'''], -['''\ -from module import name1, name2 as local2 -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_from> - module - <import_name> - name1 - <import_name> - name2 - <import_alias> - local2 -'''], -['''\ -from module.sub import name -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_from> - module.sub - <import_name> - name -'''], -['''\ -from module.sub import name as local -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_from> - module.sub - <import_name> - name - <import_alias> - local -'''], -['''\ -from module import * -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_from> - module - <import_name> - * -'''], -['''\ -from __future__ import division -''', -'''\ -<module_section filename="test data"> - <import_group lineno="1"> - <import_from> - __future__ - <import_name> - division -'''], -] - -totest['assign'] = [ -['''\ -a = 1 -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - 1 -'''], -['''a = 1''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - 1 -'''], -['''\ -a = 1 -"""a docstring""" -''', #" -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - 1 - <docstring lineno="2"> - a docstring -'''], -['''\ -a = 1 -"""a docstring""" -"""additional docstring""" -''', #" -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - 1 - <docstring lineno="2"> - a docstring - <docstring lineno="3"> - additional docstring -'''], #' -['''\ -a = 1 + 2 * 3 / 4 ** 5 -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - 1 + 2 * 3 / 4 ** 5 -'''], -['''\ -a = 1 \\ - + 2 -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - 1 + 2 -'''], -['''\ -a = not 1 and 2 or 3 -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - not 1 and 2 or 3 -'''], -['''\ -a = ~ 1 & 2 | 3 ^ 4 -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - ~ 1 & 2 | 3 ^ 4 -'''], -['''\ -a = `1 & 2` -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - `1 & 2` -'''], -['''\ -very_long_name = \\ - x -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - very_long_name - <expression_value> - x -'''], -['''\ -very_long_name \\ - = x -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - very_long_name - <expression_value> - x -'''], -['''\ -very_long_name = \\ - another_long_name = \\ - x -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - very_long_name - <expression_value> - x - <attribute lineno="2"> - <object_name> - another_long_name - <expression_value> - x -'''], -['''\ -a = (1 - + 2) -b = a.b[1 + - fn(x, y, - z, {'key': (1 + 2 - + 3)})][4] -c = """first line -second line - third""" -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - (1 + 2) - <attribute lineno="3"> - <object_name> - b - <expression_value> - a.b[1 + fn(x, y, z, {'key': (1 + 2 + 3)})][4] - <attribute lineno="7"> - <object_name> - c - <expression_value> - """first line - second line - third""" -'''], -['''\ -a, b, c = range(3) -(d, e, - f) = a, b, c -g, h, i = j = a, b, c -k.a, k.b.c, k.d.e.f = a, b, c -''', -'''\ -<module_section filename="test data"> - <attribute_tuple lineno="1"> - <attribute lineno="1"> - <object_name> - a - <attribute lineno="1"> - <object_name> - b - <attribute lineno="1"> - <object_name> - c - <expression_value> - range(3) - <attribute_tuple lineno="2"> - <attribute lineno="2"> - <object_name> - d - <attribute lineno="2"> - <object_name> - e - <attribute lineno="3"> - <object_name> - f - <expression_value> - a, b, c - <attribute_tuple lineno="4"> - <attribute lineno="4"> - <object_name> - g - <attribute lineno="4"> - <object_name> - h - <attribute lineno="4"> - <object_name> - i - <expression_value> - a, b, c - <attribute lineno="4"> - <object_name> - j - <expression_value> - a, b, c - <attribute_tuple lineno="5"> - <attribute lineno="5"> - <object_name> - k.a - <attribute lineno="5"> - <object_name> - k.b.c - <attribute lineno="5"> - <object_name> - k.d.e.f - <expression_value> - a, b, c -'''], -['''\ -a = 1 ; b = 2 -print ; c = 3 -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - 1 - <attribute lineno="1"> - <object_name> - b - <expression_value> - 2 - <attribute lineno="2"> - <object_name> - c - <expression_value> - 3 -'''], -['''\ -a.b = 1 -"""This assignment is noted but ignored unless ``a`` is a function.""" -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a.b - <expression_value> - 1 - <docstring lineno="2"> - This assignment is noted but ignored unless ``a`` is a function. -'''], -['''\ -a[b] = 1 -"""Subscript assignments are ignored.""" -''', -'''\ -<module_section filename="test data"> -'''], -['''\ -a = foo(b=1) -''', -'''\ -<module_section filename="test data"> - <attribute lineno="1"> - <object_name> - a - <expression_value> - foo(b=1) -'''], -# ['''\ -# a = 1 -# -# """Because of the blank above, this is a module docstring.""" -# ''', -# '''\ -# <module_section filename="test data"> -# <attribute lineno="1"> -# <object_name> -# a -# <expression_value> -# 1 -# <docstring lineno="3"> -# Because of the blank above, this is a module docstring. -# '''], -] - -totest['def'] = [ -['''\ -def f(): - """Function f docstring""" - """Additional docstring""" - local = 1 - """Not a docstring, since ``local`` is local.""" -''', # " -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <docstring lineno="1"> - Function f docstring - <docstring lineno="3"> - Additional docstring -'''], # ' -['''\ -def f(a, b): - local = 1 -''', -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <parameter_list> - <parameter> - <object_name> - a - <parameter> - <object_name> - b -'''], -['''\ -def f(a=None, b=1): - local = 1 -''', -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <parameter_list> - <parameter> - <object_name> - a - <parameter_default> - None - <parameter> - <object_name> - b - <parameter_default> - 1 -'''], -['''\ -def f(a, (b, c, d)=range(3), - e=None): - local = 1 -''', -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <parameter_list> - <parameter> - <object_name> - a - <parameter_tuple> - <parameter> - <object_name> - b - <parameter> - <object_name> - c - <parameter> - <object_name> - d - <parameter_default> - range(3) - <parameter> - <object_name> - e - <parameter_default> - None -'''], -['''\ -def f(*args): - local = 1 -''', -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <parameter_list> - <parameter excess_positional="1"> - <object_name> - args -'''], -['''\ -def f(**kwargs): - local = 1 -''', -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <parameter_list> - <parameter excess_keyword="1"> - <object_name> - kwargs -'''], -['''\ -def f(a, b=None, *args, **kwargs): - local = 1 -''', -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <parameter_list> - <parameter> - <object_name> - a - <parameter> - <object_name> - b - <parameter_default> - None - <parameter excess_positional="1"> - <object_name> - args - <parameter excess_keyword="1"> - <object_name> - kwargs -'''], -['''\ -def f(): - pass -f.attrib = 1 -"""f.attrib docstring""" -''', # " -# @@@ When should the attribute move inside the Function? -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f - <attribute lineno="3"> - <object_name> - f.attrib - <expression_value> - 1 - <docstring lineno="4"> - f.attrib docstring -'''], -['''\ -def f(): - def g(): - pass - """Not a docstring""" - local = 1 -''', -'''\ -<module_section filename="test data"> - <function_section lineno="1"> - <object_name> - f -'''], -] - -totest['class'] = [ -['''\ -class C: - """class C docstring""" -''', -'''\ -<module_section filename="test data"> - <class_section lineno="1"> - <object_name> - C - <docstring lineno="1"> - class C docstring -'''], -['''\ -class C(Super): - pass - -class D(SuperD, package.module.SuperD): - pass -''', -'''\ -<module_section filename="test data"> - <class_section lineno="1"> - <object_name> - C - <class_base> - <object_name> - Super - <class_section lineno="4"> - <object_name> - D - <class_base> - <object_name> - SuperD - <class_base> - <object_name> - package.module.SuperD -'''], -['''\ -class C: - class D: - pass - """Not a docstring""" -''', -'''\ -<module_section filename="test data"> - <class_section lineno="1"> - <object_name> - C -'''], -['''\ -class C: - def f(self): - self.local = 1 - local = 1 -''', -'''\ -<module_section filename="test data"> - <class_section lineno="1"> - <object_name> - C - <method_section lineno="2"> - <object_name> - f - <parameter_list> - <parameter> - <object_name> - self -'''], -['''\ -class C: - def __init__(self): - self.local = 1 - local = 1 -''', -'''\ -<module_section filename="test data"> - <class_section lineno="1"> - <object_name> - C - <method_section lineno="2"> - <object_name> - __init__ - <parameter_list> - <parameter> - <object_name> - self - <attribute lineno="3"> - <object_name> - self.local - <expression_value> - 1 - <attribute lineno="4"> - <object_name> - local - <expression_value> - 1 -'''], -['''\ -class C: - def __init__(self): - local = foo(a=1) -''', -'''\ -<module_section filename="test data"> - <class_section lineno="1"> - <object_name> - C - <method_section lineno="2"> - <object_name> - __init__ - <parameter_list> - <parameter> - <object_name> - self - <attribute lineno="3"> - <object_name> - local - <expression_value> - foo(a=1) -'''], -] - -totest['ignore'] = [ -['''\ -1 + 2 -''', -'''\ -<module_section filename="test data"> -'''], -['''\ -del a -''', -'''\ -<module_section filename="test data"> -'''], -] - -totest['comments'] = [ -# ['''\ -# # Comment -# ''', -# '''\ -# <module_section filename="test data"> -# <Comment lineno="1"> -# # Comment -# '''], -] - -# @@@ we don't parse comments yet -totest['everything'] = [ -['''\ -# comment - -"""Docstring""" - -"""Additional docstring""" - -__docformat__ = 'reStructuredText' - -a = 1 -"""Attribute docstring""" - -class C(Super): - - """C docstring""" - - class_attribute = 1 - """class_attribute docstring""" - - def __init__(self, text=None): - """__init__ docstring""" - - self.instance_attribute = (text * 7 - + ' whaddyaknow') - """instance_attribute docstring""" - - -def f(x, # parameter x - y=a*5, # parameter y - *args): # parameter args - """f docstring""" - return [x + item for item in args] - -f.function_attribute = 1 -"""f.function_attribute docstring""" -''', -'''\ -<module_section filename="test data"> - <docstring> - Docstring - <docstring lineno="5"> - Additional docstring - <attribute lineno="7"> - <object_name> - __docformat__ - <expression_value> - 'reStructuredText' - <attribute lineno="9"> - <object_name> - a - <expression_value> - 1 - <docstring lineno="10"> - Attribute docstring - <class_section lineno="12"> - <object_name> - C - <class_base> - <object_name> - Super - <docstring lineno="12"> - C docstring - <attribute lineno="16"> - <object_name> - class_attribute - <expression_value> - 1 - <docstring lineno="17"> - class_attribute docstring - <method_section lineno="19"> - <object_name> - __init__ - <docstring lineno="19"> - __init__ docstring - <parameter_list> - <parameter> - <object_name> - self - <parameter> - <object_name> - text - <parameter_default> - None - <attribute lineno="22"> - <object_name> - self.instance_attribute - <expression_value> - (text * 7 + ' whaddyaknow') - <docstring lineno="24"> - instance_attribute docstring - <function_section lineno="27"> - <object_name> - f - <docstring lineno="27"> - f docstring - <parameter_list> - <parameter> - <object_name> - x - <parameter> - <object_name> - y - <parameter_default> - a * 5 - <parameter excess_positional="1"> - <object_name> - args - <attribute lineno="33"> - <object_name> - f.function_attribute - <expression_value> - 1 - <docstring lineno="34"> - f.function_attribute docstring -'''], -] - -""" -['''\ -''', -'''\ -'''], -""" - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_readers/test_python/test_token_parser.py b/docutils/test/test_readers/test_python/test_token_parser.py deleted file mode 100755 index 23015a7dc..000000000 --- a/docutils/test/test_readers/test_python/test_token_parser.py +++ /dev/null @@ -1,46 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils/readers/python/moduleparser.py. -""" - -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.PythonModuleParserTestSuite() - s.generateTests(totest, testmethod='test_token_parser_rhs') - return s - -totest = {} - -totest['expressions'] = [ -['''a = 1''', '''1'''], -['''a = b = 1''', '''1'''], -['''\ -a = ( - 1 + 2 - + 3 - ) -''', -'''(1 + 2 + 3)'''], -['''\ -a = """\\ -line one -line two""" -''', -'''"""\\\nline one\nline two"""'''], -['''a = `1`''', '''`1`'''], -['''a = `1`+`2`''', '''`1` + `2`'''], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_settings.py b/docutils/test/test_settings.py deleted file mode 100755 index c18d613de..000000000 --- a/docutils/test/test_settings.py +++ /dev/null @@ -1,167 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests of runtime settings. -""" - -import sys -import os -import docutils_difflib -import pprint -import warnings -import unittest -from types import StringType -import DocutilsTestSupport # must be imported before docutils -from docutils import frontend, utils -from docutils.writers import html4css1, pep_html -from docutils.parsers import rst - - -warnings.filterwarnings(action='ignore', - category=frontend.ConfigDeprecationWarning) - -def fixpath(path): - return os.path.abspath(os.path.join(*(path.split('/')))) - - -class ConfigFileTests(unittest.TestCase): - - config_files = {'old': fixpath('data/config_old.txt'), - 'one': fixpath('data/config_1.txt'), - 'two': fixpath('data/config_2.txt'), - 'list': fixpath('data/config_list.txt'), - 'list2': fixpath('data/config_list_2.txt'), - 'error': fixpath('data/config_error_handler.txt')} - - settings = { - 'old': {'datestamp': '%Y-%m-%d %H:%M UTC', - 'generator': 1, - 'no_random': 1, - 'python_home': 'http://www.python.org', - 'source_link': 1, - 'stylesheet': None, - 'stylesheet_path': fixpath('data/stylesheets/pep.css'), - 'template': fixpath('data/pep-html-template')}, - 'one': {'datestamp': '%Y-%m-%d %H:%M UTC', - 'generator': 1, - 'no_random': 1, - 'python_home': 'http://www.python.org', - 'record_dependencies': utils.DependencyList(), - 'source_link': 1, - 'stylesheet': None, - 'stylesheet_path': fixpath('data/stylesheets/pep.css'), - 'tab_width': 8, - 'template': fixpath('data/pep-html-template'), - 'trim_footnote_reference_space': 1}, - 'two': {'footnote_references': 'superscript', - 'generator': 0, - 'record_dependencies': utils.DependencyList(), - 'stylesheet': None, - 'stylesheet_path': fixpath('data/test.css'), - 'trim_footnote_reference_space': None}, - 'list': {'expose_internals': ['a', 'b', 'c', 'd', 'e']}, - 'list2': {'expose_internals': ['a', 'b', 'c', 'd', 'e', 'f']}, - 'error': {'error_encoding': 'ascii', - 'error_encoding_error_handler': 'strict'}, - } - - compare = docutils_difflib.Differ().compare - """Comparison method shared by all tests.""" - - def setUp(self): - self.option_parser = frontend.OptionParser( - components=(pep_html.Writer, rst.Parser), read_config_files=None) - - def files_settings(self, *names): - settings = frontend.Values() - for name in names: - settings.update(self.option_parser.get_config_file_settings( - self.config_files[name]), self.option_parser) - return settings.__dict__ - - def expected_settings(self, *names): - expected = {} - for name in names: - expected.update(self.settings[name]) - return expected - - def compare_output(self, result, expected): - """`result` and `expected` should both be dicts.""" - self.assert_(result.has_key('record_dependencies')) - if not expected.has_key('record_dependencies'): - # Delete it if we don't want to test it. - del result['record_dependencies'] - result = pprint.pformat(result) + '\n' - expected = pprint.pformat(expected) + '\n' - try: - self.assertEquals(result, expected) - except AssertionError: - print >>sys.stderr, '\n%s\n' % (self,) - print >>sys.stderr, '-: expected\n+: result' - print >>sys.stderr, ''.join(self.compare(expected.splitlines(1), - result.splitlines(1))) - raise - - def test_nofiles(self): - self.compare_output(self.files_settings(), - self.expected_settings()) - - def test_old(self): - self.compare_output(self.files_settings('old'), - self.expected_settings('old')) - - def test_one(self): - self.compare_output(self.files_settings('one'), - self.expected_settings('one')) - - def test_multiple(self): - self.compare_output(self.files_settings('one', 'two'), - self.expected_settings('one', 'two')) - - def test_old_and_new(self): - self.compare_output(self.files_settings('old', 'two'), - self.expected_settings('old', 'two')) - - def test_list(self): - self.compare_output(self.files_settings('list'), - self.expected_settings('list')) - - def test_list2(self): - self.compare_output(self.files_settings('list', 'list2'), - self.expected_settings('list2')) - - def test_error_handler(self): - self.compare_output(self.files_settings('error'), - self.expected_settings('error')) - - -class ConfigEnvVarFileTests(ConfigFileTests): - - """ - Repeats the tests of `ConfigFileTests` using the ``DOCUTILSCONFIG`` - environment variable and the standard Docutils config file mechanism. - """ - - def setUp(self): - ConfigFileTests.setUp(self) - self.orig_environ = os.environ - os.environ = os.environ.copy() - - def files_settings(self, *names): - files = [self.config_files[name] for name in names] - os.environ['DOCUTILSCONFIG'] = os.pathsep.join(files) - settings = self.option_parser.get_standard_config_settings() - return settings.__dict__ - - def tearDown(self): - os.environ = self.orig_environ - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_statemachine.py b/docutils/test/test_statemachine.py deleted file mode 100755 index 4ca2a0144..000000000 --- a/docutils/test/test_statemachine.py +++ /dev/null @@ -1,283 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for statemachine.py. -""" - -import unittest -import sys -import re -from DocutilsTestSupport import statemachine - - -debug = 0 -testtext = statemachine.string2lines("""\ -First paragraph. - -- This is a bullet list. First list item. - Second line of first para. - - Second para. - - block quote - -- Second list item. Example:: - - a - literal - block - -Last paragraph.""") -expected = ('StateMachine1 text1 blank1 bullet1 known_indent1 ' - 'StateMachine2 text2 text2 blank2 text2 blank2 indent2 ' - 'StateMachine3 text3 blank3 finished3 finished2 ' - 'bullet1 known_indent1 ' - 'StateMachine2 text2 blank2 literalblock2(4) finished2 ' - 'text1 finished1').split() -para1 = testtext[:2] -item1 = [line[2:] for line in testtext[2:9]] -item2 = [line[2:] for line in testtext[9:-1]] -lbindent = 6 -literalblock = [line[lbindent:] for line in testtext[11:-1]] -para2 = testtext[-1] - - -class MockState(statemachine.StateWS): - - patterns = {'bullet': re.compile(r'- '), - 'text': ''} - initial_transitions = ['bullet', ['text']] - levelholder = [0] - - def bof(self, context): - self.levelholder[0] += 1 - self.level = self.levelholder[0] - if self.debug: print >>sys.stderr, 'StateMachine%s' % self.level - return [], ['StateMachine%s' % self.level] - - def blank(self, match, context, next_state): - result = ['blank%s' % self.level] - if self.debug: print >>sys.stderr, 'blank%s' % self.level - if context and context[-1] and context[-1][-2:] == '::': - result.extend(self.literalblock()) - return [], None, result - - def indent(self, match, context, next_state): - if self.debug: print >>sys.stderr, 'indent%s' % self.level - context, next_state, result = statemachine.StateWS.indent( - self, match, context, next_state) - return context, next_state, ['indent%s' % self.level] + result - - def known_indent(self, match, context, next_state): - if self.debug: print >>sys.stderr, 'known_indent%s' % self.level - context, next_state, result = statemachine.StateWS.known_indent( - self, match, context, next_state) - return context, next_state, ['known_indent%s' % self.level] + result - - def bullet(self, match, context, next_state): - if self.debug: print >>sys.stderr, 'bullet%s' % self.level - context, next_state, result \ - = self.known_indent(match, context, next_state) - return [], next_state, ['bullet%s' % self.level] + result - - def text(self, match, context, next_state): - if self.debug: print >>sys.stderr, 'text%s' % self.level - return [match.string], next_state, ['text%s' % self.level] - - def literalblock(self): - indented, indent, offset, good = self.state_machine.get_indented() - if self.debug: print >>sys.stderr, 'literalblock%s(%s)' % (self.level, - indent) - return ['literalblock%s(%s)' % (self.level, indent)] - - def eof(self, context): - self.levelholder[0] -= 1 - if self.debug: print >>sys.stderr, 'finished%s' % self.level - return ['finished%s' % self.level] - - -class EmptySMTests(unittest.TestCase): - - def setUp(self): - self.sm = statemachine.StateMachine( - state_classes=[], initial_state='State') - self.sm.debug = debug - - def test_add_state(self): - self.sm.add_state(statemachine.State) - self.assert_(len(self.sm.states) == 1) - self.assertRaises(statemachine.DuplicateStateError, self.sm.add_state, - statemachine.State) - self.sm.add_state(statemachine.StateWS) - self.assert_(len(self.sm.states) == 2) - - def test_add_states(self): - self.sm.add_states((statemachine.State, statemachine.StateWS)) - self.assertEqual(len(self.sm.states), 2) - - def test_get_state(self): - self.assertRaises(statemachine.UnknownStateError, self.sm.get_state) - self.sm.add_states((statemachine.State, statemachine.StateWS)) - self.assertRaises(statemachine.UnknownStateError, self.sm.get_state, - 'unknownState') - self.assert_(isinstance(self.sm.get_state('State'), - statemachine.State)) - self.assert_(isinstance(self.sm.get_state('StateWS'), - statemachine.State)) - self.assertEqual(self.sm.current_state, 'StateWS') - - -class EmptySMWSTests(EmptySMTests): - - def setUp(self): - self.sm = statemachine.StateMachineWS( - state_classes=[], initial_state='State') - self.sm.debug = debug - - -class SMWSTests(unittest.TestCase): - - def setUp(self): - self.sm = statemachine.StateMachineWS([MockState], 'MockState', - debug=debug) - self.sm.debug = debug - self.sm.states['MockState'].levelholder[0] = 0 - - def tearDown(self): - self.sm.unlink() - - def test___init__(self): - self.assertEquals(self.sm.states.keys(), ['MockState']) - self.assertEquals(len(self.sm.states['MockState'].transitions), 4) - - def test_get_indented(self): - self.sm.input_lines = statemachine.StringList(testtext) - self.sm.line_offset = -1 - self.sm.next_line(3) - indented, offset, good = self.sm.get_known_indented(2) - self.assertEquals(indented, item1) - self.assertEquals(offset, len(para1)) - self.failUnless(good) - self.sm.next_line() - indented, offset, good = self.sm.get_known_indented(2) - self.assertEquals(indented, item2) - self.assertEquals(offset, len(para1) + len(item1)) - self.failUnless(good) - self.sm.previous_line(3) - if self.sm.debug: - print '\ntest_get_indented: self.sm.line:\n', self.sm.line - indented, indent, offset, good = self.sm.get_indented() - if self.sm.debug: - print '\ntest_get_indented: indented:\n', indented - self.assertEquals(indent, lbindent) - self.assertEquals(indented, literalblock) - self.assertEquals(offset, (len(para1) + len(item1) + len(item2) - - len(literalblock))) - self.failUnless(good) - - def test_get_text_block(self): - self.sm.input_lines = statemachine.StringList(testtext) - self.sm.line_offset = -1 - self.sm.next_line() - textblock = self.sm.get_text_block() - self.assertEquals(textblock, testtext[:1]) - self.sm.next_line(2) - textblock = self.sm.get_text_block() - self.assertEquals(textblock, testtext[2:4]) - - def test_get_text_block_flush_left(self): - self.sm.input_lines = statemachine.StringList(testtext) - self.sm.line_offset = -1 - self.sm.next_line() - textblock = self.sm.get_text_block(flush_left=1) - self.assertEquals(textblock, testtext[:1]) - self.sm.next_line(2) - self.assertRaises(statemachine.UnexpectedIndentationError, - self.sm.get_text_block, flush_left=1) - - def test_run(self): - self.assertEquals(self.sm.run(testtext), expected) - - -class EmptyClass: - pass - - -class EmptyStateTests(unittest.TestCase): - - def setUp(self): - self.state = statemachine.State(EmptyClass(), debug=debug) - self.state.patterns = {'nop': 'dummy', - 'nop2': 'dummy', - 'nop3': 'dummy', - 'bogus': 'dummy'} - self.state.nop2 = self.state.nop3 = self.state.nop - - def test_add_transitions(self): - self.assertEquals(len(self.state.transitions), 0) - self.state.add_transitions(['None'], {'None': None}) - self.assertEquals(len(self.state.transitions), 1) - self.assertRaises(statemachine.UnknownTransitionError, - self.state.add_transitions, ['bogus'], {}) - self.assertRaises(statemachine.DuplicateTransitionError, - self.state.add_transitions, ['None'], - {'None': None}) - - def test_add_transition(self): - self.assertEquals(len(self.state.transitions), 0) - self.state.add_transition('None', None) - self.assertEquals(len(self.state.transitions), 1) - self.assertRaises(statemachine.DuplicateTransitionError, - self.state.add_transition, 'None', None) - - def test_remove_transition(self): - self.assertEquals(len(self.state.transitions), 0) - self.state.add_transition('None', None) - self.assertEquals(len(self.state.transitions), 1) - self.state.remove_transition('None') - self.assertEquals(len(self.state.transitions), 0) - self.assertRaises(statemachine.UnknownTransitionError, - self.state.remove_transition, 'None') - - def test_make_transition(self): - dummy = re.compile('dummy') - self.assertEquals(self.state.make_transition('nop', 'bogus'), - (dummy, self.state.nop, 'bogus')) - self.assertEquals(self.state.make_transition('nop'), - (dummy, self.state.nop, - self.state.__class__.__name__)) - self.assertRaises(statemachine.TransitionPatternNotFound, - self.state.make_transition, 'None') - self.assertRaises(statemachine.TransitionMethodNotFound, - self.state.make_transition, 'bogus') - - def test_make_transitions(self): - dummy = re.compile('dummy') - self.assertEquals(self.state.make_transitions(('nop', ['nop2'], - ('nop3', 'bogus'))), - (['nop', 'nop2', 'nop3'], - {'nop': (dummy, self.state.nop, - self.state.__class__.__name__), - 'nop2': (dummy, self.state.nop2, - self.state.__class__.__name__), - 'nop3': (dummy, self.state.nop3, 'bogus')})) - - -class MiscTests(unittest.TestCase): - - s2l_string = "hello\tthere\thow are\tyou?\n\tI'm fine\tthanks.\n" - s2l_expected = ['hello there how are you?', - " I'm fine thanks."] - def test_string2lines(self): - self.assertEquals(statemachine.string2lines(self.s2l_string), - self.s2l_expected) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_transforms/__init__.py b/docutils/test/test_transforms/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_transforms/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_transforms/test___init__.py b/docutils/test/test_transforms/test___init__.py deleted file mode 100755 index 30e60afd3..000000000 --- a/docutils/test/test_transforms/test___init__.py +++ /dev/null @@ -1,43 +0,0 @@ -#! /usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for transforms/__init__.py. -""" - -from __init__ import DocutilsTestSupport # must be imported before docutils -from docutils import transforms, utils -import unittest - - -class TestTransform(transforms.Transform): - - default_priority = 100 - - applied = 0 - - def apply(self, **kwargs): - self.applied += 1 - assert kwargs == {'foo': 42} - - -class KwargsTestCase(unittest.TestCase): - - def test_kwargs(self): - transformer = transforms.Transformer(utils.new_document('test data')) - transformer.add_transform(TestTransform, foo=42) - transformer.apply_transforms() - self.assertEqual(len(transformer.applied), 1) - self.assertEqual(len(transformer.applied[0]), 4) - transform_record = transformer.applied[0] - self.assertEqual(transform_record[1], TestTransform) - self.assertEqual(transform_record[3], {'foo': 42}) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_transforms/test_class.py b/docutils/test/test_transforms/test_class.py deleted file mode 100755 index 4cd874ea3..000000000 --- a/docutils/test/test_transforms/test_class.py +++ /dev/null @@ -1,191 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for `docutils.transforms.misc.ClassAttribute`. -""" - -from __init__ import DocutilsTestSupport -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['class'] = ((), [ -["""\ -.. class:: one - -paragraph -""", -"""\ -<document source="test data"> - <paragraph classes="one"> - paragraph -"""], -["""\ -.. class:: two -.. - - Block quote -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - <block_quote classes="two"> - <paragraph> - Block quote -"""], -["""\ - Block quote - - .. class:: three - -Paragraph -""", -"""\ -<document source="test data"> - <block_quote> - <paragraph> - Block quote - <paragraph classes="three"> - Paragraph -"""], -["""\ -.. class:: four - -Section Title -============= - -Paragraph -""", -"""\ -<document source="test data"> - <section classes="four" ids="section-title" names="section\ title"> - <title> - Section Title - <paragraph> - Paragraph -"""], -["""\ -.. class:: multiple - - paragraph 1 - - paragraph 2 -""", -"""\ -<document source="test data"> - <paragraph classes="multiple"> - paragraph 1 - <paragraph classes="multiple"> - paragraph 2 -"""], -["""\ -.. class:: multiple - - .. Just a comment. It's silly, but possible -""", -"""\ -<document source="test data"> - <comment classes="multiple" xml:space="preserve"> - Just a comment. It's silly, but possible -"""], -["""\ -.. class:: - -.. class:: 99 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Error in "class" directive: - 1 argument(s) required, 0 supplied. - <literal_block xml:space="preserve"> - .. class:: - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Invalid class attribute value for "class" directive: "99". - <literal_block xml:space="preserve"> - .. class:: 99 -"""], -["""\ -.. class:: one -.. class:: two - -multiple class values may be assigned to one element -""", -"""\ -<document source="test data"> - <paragraph classes="one two"> - multiple class values may be assigned to one element -"""], -["""\ -.. class:: one two - -multiple class values may be assigned to one element -""", -"""\ -<document source="test data"> - <paragraph classes="one two"> - multiple class values may be assigned to one element -"""], -["""\ -.. class:: fancy - -2. List starts at 2. -3. Class should apply to list, not to system message. -""", -"""\ -<document source="test data"> - <enumerated_list classes="fancy" enumtype="arabic" prefix="" start="2" suffix="."> - <list_item> - <paragraph> - List starts at 2. - <list_item> - <paragraph> - Class should apply to list, not to system message. - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "2" (ordinal 2) -"""], -["""\ -2. List starts at 2. -3. Class should apply to next paragraph, not to system message. - - .. class:: fancy - -A paragraph. -""", -"""\ -<document source="test data"> - <enumerated_list enumtype="arabic" prefix="" start="2" suffix="."> - <list_item> - <paragraph> - List starts at 2. - <list_item> - <paragraph> - Class should apply to next paragraph, not to system message. - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "2" (ordinal 2) - <paragraph classes="fancy"> - A paragraph. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_contents.py b/docutils/test/test_transforms/test_contents.py deleted file mode 100755 index 19705b5ba..000000000 --- a/docutils/test/test_transforms/test_contents.py +++ /dev/null @@ -1,434 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for `docutils.transforms.parts.Contents` (via -`docutils.transforms.universal.LastReaderPending`). -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.references import Substitutions -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['tables_of_contents'] = ((Substitutions,), [ -["""\ -.. contents:: - -Title 1 -======= -Paragraph 1. - -Title_ 2 --------- -Paragraph 2. - -_`Title` 3 -`````````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="contents" names="contents"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="title-1"> - Title 1 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id2" refid="title-2"> - Title - 2 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id3" refid="title-3"> - Title - 3 - <list_item> - <paragraph> - <reference ids="id4" refid="title-4"> - Title 4 - <section ids="title-1" names="title\ 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title> - <reference name="Title" refname="title"> - Title - 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title refid="id3"> - <target ids="title" names="title"> - Title - 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title refid="id4"> - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. contents:: Table of Contents - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="table-of-contents" names="table\ of\ contents"> - <title> - Table of Contents - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="title-1"> - Title 1 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id2" refid="title-2"> - Title 2 - <section ids="title-1" names="title\ 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title refid="id2"> - Title 2 - <paragraph> - Paragraph 2. -"""], -["""\ -.. contents:: There's an image in Title 2 - -Title 1 -======= -Paragraph 1. - -|Title 2| -========= -Paragraph 2. - -.. |Title 2| image:: title2.png -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="there-s-an-image-in-title-2" names="there's\ an\ image\ in\ title\ 2"> - <title> - There's an image in Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="title-1"> - Title 1 - <list_item> - <paragraph> - <reference ids="id2" refid="title-2"> - Title 2 - <section ids="title-1" names="title\ 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title refid="id2"> - <image alt="Title 2" uri="title2.png"> - <paragraph> - Paragraph 2. - <substitution_definition names="Title\ 2"> - <image alt="Title 2" uri="title2.png"> -"""], # emacs cruft: " -["""\ -.. contents:: - :depth: 2 - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="contents" names="contents"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="title-1"> - Title 1 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id2" refid="title-2"> - Title 2 - <list_item> - <paragraph> - <reference ids="id3" refid="title-4"> - Title 4 - <section ids="title-1" names="title\ 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title refid="id2"> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title refid="id3"> - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -Title 1 -======= - -.. contents:: - :local: - -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -"""\ -<document source="test data"> - <section ids="title-1" names="title\ 1"> - <title> - Title 1 - <topic classes="contents local" ids="contents" names="contents"> - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="title-2"> - Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id2" refid="title-3"> - Title 3 - <list_item> - <paragraph> - <reference ids="id3" refid="title-4"> - Title 4 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title refid="id1"> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title refid="id2"> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title refid="id3"> - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. contents:: - :local: - -Test duplicate name "Contents". - -Section --------- -Paragraph. -""", -"""\ -<document source="test data"> - <topic classes="contents local" ids="contents" names="contents"> - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="section"> - Section - <paragraph> - Test duplicate name "Contents". - <section ids="section" names="section"> - <title refid="id1"> - Section - <paragraph> - Paragraph. -"""], -["""\ -.. contents:: - :backlinks: top - -Section --------- -Paragraph. -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="contents" names="contents"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="section"> - Section - <section ids="section" names="section"> - <title refid="contents"> - Section - <paragraph> - Paragraph. -"""], -["""\ -.. contents:: - :backlinks: none - -Section --------- -Paragraph. -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="contents" names="contents"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="section"> - Section - <section ids="section" names="section"> - <title> - Section - <paragraph> - Paragraph. -"""], -["""\ -.. contents:: - -Degenerate case, no table of contents generated. -""", -"""\ -<document source="test data"> - <paragraph> - Degenerate case, no table of contents generated. -"""], -["""\ -Title 1 -======= - -Paragraph 1. - -.. sidebar:: Contents - - .. contents:: - :local: - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. -""", -"""\ -<document source="test data"> - <section ids="title-1" names="title\ 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <sidebar> - <title> - Contents - <topic classes="contents local" ids="contents" names="contents"> - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="title-2"> - Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id2" refid="title-3"> - Title 3 - <section ids="title-2" names="title\ 2"> - <title refid="id1"> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title refid="id2"> - Title 3 - <paragraph> - Paragraph 3. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_docinfo.py b/docutils/test/test_transforms/test_docinfo.py deleted file mode 100755 index 994d034ea..000000000 --- a/docutils/test/test_transforms/test_docinfo.py +++ /dev/null @@ -1,334 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.frontmatter.DocInfo. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.frontmatter import DocInfo -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['bibliographic_field_lists'] = ((DocInfo,), [ -["""\ -.. Bibliographic element extraction. - -:Abstract: - There can only be one abstract. - - It is automatically moved to the end of the other bibliographic elements. - -:Author: Me -:Version: 1 -:Date: 2001-08-11 -:Parameter i: integer -""", -"""\ -<document source="test data"> - <docinfo> - <author> - Me - <version> - 1 - <date> - 2001-08-11 - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - integer - <topic classes="abstract"> - <title> - Abstract - <paragraph> - There can only be one abstract. - <paragraph> - It is automatically moved to the end of the other bibliographic elements. - <comment xml:space="preserve"> - Bibliographic element extraction. -"""], -["""\ -.. Bibliographic element extraction. - -:Abstract: Abstract 1. -:Author: Me -:Address: 123 My Street - Example, EX -:Contact: me@my.org -:Version: 1 -:Abstract: Abstract 2 (should generate a warning). -:Date: 2001-08-11 -:Parameter i: integer -""", -"""\ -<document source="test data"> - <docinfo> - <author> - Me - <address xml:space="preserve"> - 123 My Street - Example, EX - <contact> - <reference refuri="mailto:me@my.org"> - me@my.org - <version> - 1 - <field> - <field_name> - Abstract - <field_body> - <paragraph> - Abstract 2 (should generate a warning). - <system_message level="2" line="9" source="test data" type="WARNING"> - <paragraph> - There can only be one "Abstract" field. - <date> - 2001-08-11 - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - integer - <topic classes="abstract"> - <title> - Abstract - <paragraph> - Abstract 1. - <comment xml:space="preserve"> - Bibliographic element extraction. -"""], -["""\ -:Author: - must be a paragraph -:Status: a *simple* paragraph -:Date: But only one - - paragraph. -:Version: - -.. and not empty either -""", -"""\ -<document source="test data"> - <docinfo> - <field> - <field_name> - Author - <field_body> - <bullet_list bullet="-"> - <list_item> - <paragraph> - must be a paragraph - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Cannot extract bibliographic field "Author" containing anything other than a single paragraph. - <status> - a \n\ - <emphasis> - simple - paragraph - <field> - <field_name> - Date - <field_body> - <paragraph> - But only one - <paragraph> - paragraph. - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Cannot extract compound bibliographic field "Date". - <field> - <field_name> - Version - <field_body> - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Cannot extract empty bibliographic field "Version". - <comment xml:space="preserve"> - and not empty either -"""], -["""\ -:Authors: Me, Myself, **I** -:Authors: PacMan; Ms. PacMan; PacMan, Jr. -:Authors: - Here - - There - - *Everywhere* -:Authors: - First - - Second - - Third -""", -"""\ -<document source="test data"> - <docinfo> - <authors> - <author> - Me - <author> - Myself - <author> - I - <authors> - <author> - PacMan - <author> - Ms. PacMan - <author> - PacMan, Jr. - <authors> - <author> - Here - <author> - There - <author> - <emphasis> - Everywhere - <authors> - <author> - First - <author> - Second - <author> - Third -"""], -["""\ -:Authors: Only One -:Authors: One, Only; -""", -"""\ -<document source="test data"> - <docinfo> - <authors> - <author> - Only One - <authors> - <author> - One, Only -"""], -["""\ -:Authors: - -:Authors: 1. One - 2. Two - -:Authors: - - - - - -:Authors: - - One - - Two - -:Authors: - - One - - Two -""", -"""\ -<document source="test data"> - <docinfo> - <field> - <field_name> - Authors - <field_body> - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Cannot extract empty bibliographic field "Authors". - <field> - <field_name> - Authors - <field_body> - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - One - <list_item> - <paragraph> - Two - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Bibliographic field "Authors" incompatible with extraction: it must contain either a single paragraph (with authors separated by one of ";,"), multiple paragraphs (one per author), or a bullet list with one paragraph (one author) per item. - <field> - <field_name> - Authors - <field_body> - <bullet_list bullet="-"> - <list_item> - <list_item> - <system_message level="2" line="6" source="test data" type="WARNING"> - <paragraph> - Bibliographic field "Authors" incompatible with extraction: it must contain either a single paragraph (with authors separated by one of ";,"), multiple paragraphs (one per author), or a bullet list with one paragraph (one author) per item. - <field> - <field_name> - Authors - <field_body> - <bullet_list bullet="-"> - <list_item> - <paragraph> - One - <paragraph> - Two - <system_message level="2" line="10" source="test data" type="WARNING"> - <paragraph> - Bibliographic field "Authors" incompatible with extraction: it must contain either a single paragraph (with authors separated by one of ";,"), multiple paragraphs (one per author), or a bullet list with one paragraph (one author) per item. - <field> - <field_name> - Authors - <field_body> - <bullet_list bullet="-"> - <list_item> - <paragraph> - One - <paragraph> - Two - <system_message level="2" line="15" source="test data" type="WARNING"> - <paragraph> - Bibliographic field "Authors" incompatible with extraction: it must contain either a single paragraph (with authors separated by one of ";,"), multiple paragraphs (one per author), or a bullet list with one paragraph (one author) per item. -"""], -["""\ -.. RCS keyword extraction. - -:Status: (some text) $""" + """RCSfile: test_docinfo.py,v $ (more text) -:Date: (some text) $""" + """Date: 2002/10/08 01:34:23 $ (more text) -:Date: (some text) $""" + """Date: 2005-03-26T16:21:28.693201Z $ (more text) -:Version: (some text) $""" + """Revision: 1.1 $ (more text) -""", -"""\ -<document source="test data"> - <docinfo> - <status> - (some text) test_docinfo.py (more text) - <date> - (some text) 2002-10-08 (more text) - <date> - (some text) 2005-03-26 (more text) - <version> - (some text) 1.1 (more text) - <comment xml:space="preserve"> - RCS keyword extraction. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_doctitle.py b/docutils/test/test_transforms/test_doctitle.py deleted file mode 100755 index 3000f53a5..000000000 --- a/docutils/test/test_transforms/test_doctitle.py +++ /dev/null @@ -1,231 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.frontmatter.DocTitle. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.frontmatter import DocTitle, SectionSubTitle -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['section_headers'] = ((DocTitle, SectionSubTitle), [ -["""\ -.. test title promotion - -Title -===== - -Paragraph. -""", -"""\ -<document ids="title" names="title" source="test data" title="Title"> - <title> - Title - <comment xml:space="preserve"> - test title promotion - <paragraph> - Paragraph. -"""], -["""\ -Title -===== -Paragraph (no blank line). -""", -"""\ -<document ids="title" names="title" source="test data" title="Title"> - <title> - Title - <paragraph> - Paragraph (no blank line). -"""], -["""\ -Paragraph. - -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <section ids="title" names="title"> - <title> - Title - <paragraph> - Paragraph. -"""], -["""\ -Title -===== - -Subtitle --------- - -.. title:: Another Title - -Test title, subtitle, and title metadata. -""", -"""\ -<document ids="title" names="title" source="test data" title="Another Title"> - <title> - Title - <subtitle ids="subtitle" names="subtitle"> - Subtitle - <paragraph> - Test title, subtitle, and title metadata. -"""], -["""\ -Title -==== - -Test short underline. -""", -"""\ -<document ids="title" names="title" source="test data" title="Title"> - <title> - Title - <system_message level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Title underline too short. - <literal_block xml:space="preserve"> - Title - ==== - <paragraph> - Test short underline. -"""], -["""\ -======= - Long Title -======= - -Test long title and space normalization. -The system_message should move after the document title -(it was before the beginning of the section). -""", -"""\ -<document ids="long-title" names="long\ title" source="test data" title="Long Title"> - <title> - Long Title - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Title overline too short. - <literal_block xml:space="preserve"> - ======= - Long Title - ======= - <paragraph> - Test long title and space normalization. - The system_message should move after the document title - (it was before the beginning of the section). -"""], -["""\ -.. Test multiple second-level titles. - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -------- -Paragraph 3. -""", -"""\ -<document ids="title-1" names="title\ 1" source="test data" title="Title 1"> - <title> - Title 1 - <comment xml:space="preserve"> - Test multiple second-level titles. - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. -"""], -["""\ -.. |foo| replace:: bar - -.. _invisible target: - -Title -===== -This title should be the document title despite the -substitution_definition. -""", -"""\ -<document ids="title" names="title" source="test data" title="Title"> - <title> - Title - <substitution_definition names="foo"> - bar - <target ids="invisible-target" names="invisible\ target"> - <paragraph> - This title should be the document title despite the - substitution_definition. -"""], -["""\ -(Because of this paragraph, the following is not a doc title.) - -=============== - Section Title -=============== - -Subtitle -======== - ------------------ - Another Section ------------------ - -Another Subtitle ----------------- - -""", -"""\ -<document source="test data"> - <paragraph> - (Because of this paragraph, the following is not a doc title.) - <section ids="section-title" names="section\ title"> - <title> - Section Title - <subtitle ids="subtitle" names="subtitle"> - Subtitle - <section ids="another-section" names="another\ section"> - <title> - Another Section - <subtitle ids="another-subtitle" names="another\ subtitle"> - Another Subtitle -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_expose_internals.py b/docutils/test/test_transforms/test_expose_internals.py deleted file mode 100755 index 69193246a..000000000 --- a/docutils/test/test_transforms/test_expose_internals.py +++ /dev/null @@ -1,42 +0,0 @@ -#! /usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for universal.ExposeInternals transform. -""" - - -from __init__ import DocutilsTestSupport # must be imported before docutils -from docutils.transforms.universal import ExposeInternals -from docutils.parsers.rst import Parser - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite( - parser, suite_settings={'expose_internals': ['rawsource', 'source']}) - s.generateTests(totest) - return s - - -totest = {} - -totest['transitions'] = ((ExposeInternals,), [ -["""\ -This is a test. -""", -"""\ -<document internal:rawsource="" source="test data"> - <paragraph internal:rawsource="This is a test." internal:source="test data"> - This is a test. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_filter.py b/docutils/test/test_transforms/test_filter.py deleted file mode 100755 index 009600d81..000000000 --- a/docutils/test/test_transforms/test_filter.py +++ /dev/null @@ -1,41 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.components.Filter. -""" - -from __init__ import DocutilsTestSupport -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['meta'] = ((), [ -["""\ -.. meta:: - :description: The reStructuredText plaintext markup language - :keywords: plaintext,markup language -""", -"""\ -<document source="test data"> - <meta content="The reStructuredText plaintext markup language" name="description"> - <meta content="plaintext,markup language" name="keywords"> -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_footnotes.py b/docutils/test/test_transforms/test_footnotes.py deleted file mode 100755 index 86cbd2110..000000000 --- a/docutils/test/test_transforms/test_footnotes.py +++ /dev/null @@ -1,545 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.references.Footnotes. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.references import Footnotes -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['footnotes'] = ((Footnotes,), [ -["""\ -[#autolabel]_ - -.. [#autolabel] text -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" ids="id1" refid="autolabel"> - 1 - <footnote auto="1" backrefs="id1" ids="autolabel" names="autolabel"> - <label> - 1 - <paragraph> - text -"""], -["""\ -autonumber: [#]_ - -.. [#] text -""", -"""\ -<document source="test data"> - <paragraph> - autonumber: \n\ - <footnote_reference auto="1" ids="id1" refid="id2"> - 1 - <footnote auto="1" backrefs="id1" ids="id2" names="1"> - <label> - 1 - <paragraph> - text -"""], -["""\ -[#]_ is the first auto-numbered footnote reference. -[#]_ is the second auto-numbered footnote reference. - -.. [#] Auto-numbered footnote 1. -.. [#] Auto-numbered footnote 2. -.. [#] Auto-numbered footnote 3. - -[#]_ is the third auto-numbered footnote reference. -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" ids="id1" refid="id3"> - 1 - is the first auto-numbered footnote reference. - <footnote_reference auto="1" ids="id2" refid="id4"> - 2 - is the second auto-numbered footnote reference. - <footnote auto="1" backrefs="id1" ids="id3" names="1"> - <label> - 1 - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" backrefs="id2" ids="id4" names="2"> - <label> - 2 - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" backrefs="id6" ids="id5" names="3"> - <label> - 3 - <paragraph> - Auto-numbered footnote 3. - <paragraph> - <footnote_reference auto="1" ids="id6" refid="id5"> - 3 - is the third auto-numbered footnote reference. -"""], -["""\ -[#third]_ is a reference to the third auto-numbered footnote. - -.. [#first] First auto-numbered footnote. -.. [#second] Second auto-numbered footnote. -.. [#third] Third auto-numbered footnote. - -[#second]_ is a reference to the second auto-numbered footnote. -[#first]_ is a reference to the first auto-numbered footnote. -[#third]_ is another reference to the third auto-numbered footnote. - -Here are some internal cross-references to the implicit targets -generated by the footnotes: first_, second_, third_. -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" ids="id1" refid="third"> - 3 - is a reference to the third auto-numbered footnote. - <footnote auto="1" backrefs="id3" ids="first" names="first"> - <label> - 1 - <paragraph> - First auto-numbered footnote. - <footnote auto="1" backrefs="id2" ids="second" names="second"> - <label> - 2 - <paragraph> - Second auto-numbered footnote. - <footnote auto="1" backrefs="id1 id4" ids="third" names="third"> - <label> - 3 - <paragraph> - Third auto-numbered footnote. - <paragraph> - <footnote_reference auto="1" ids="id2" refid="second"> - 2 - is a reference to the second auto-numbered footnote. - <footnote_reference auto="1" ids="id3" refid="first"> - 1 - is a reference to the first auto-numbered footnote. - <footnote_reference auto="1" ids="id4" refid="third"> - 3 - is another reference to the third auto-numbered footnote. - <paragraph> - Here are some internal cross-references to the implicit targets - generated by the footnotes: \n\ - <reference name="first" refname="first"> - first - , \n\ - <reference name="second" refname="second"> - second - , \n\ - <reference name="third" refname="third"> - third - . -"""], -["""\ -Mixed anonymous and labelled auto-numbered footnotes: - -[#four]_ should be 4, [#]_ should be 1, -[#]_ should be 3, [#]_ is one too many, -[#two]_ should be 2, and [#six]_ doesn't exist. - -.. [#] Auto-numbered footnote 1. -.. [#two] Auto-numbered footnote 2. -.. [#] Auto-numbered footnote 3. -.. [#four] Auto-numbered footnote 4. -.. [#five] Auto-numbered footnote 5. -.. [#five] Auto-numbered footnote 5 again (duplicate). -""", -"""\ -<document source="test data"> - <paragraph> - Mixed anonymous and labelled auto-numbered footnotes: - <paragraph> - <footnote_reference auto="1" ids="id1" refid="four"> - 4 - should be 4, \n\ - <footnote_reference auto="1" ids="id2" refid="id7"> - 1 - should be 1, - <footnote_reference auto="1" ids="id3" refid="id8"> - 3 - should be 3, \n\ - <problematic ids="id11 id4" refid="id10"> - [#]_ - is one too many, - <footnote_reference auto="1" ids="id5" refid="two"> - 2 - should be 2, and \n\ - <footnote_reference auto="1" ids="id6" refname="six"> - doesn't exist. - <footnote auto="1" backrefs="id2" ids="id7" names="1"> - <label> - 1 - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" backrefs="id5" ids="two" names="two"> - <label> - 2 - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" backrefs="id3" ids="id8" names="3"> - <label> - 3 - <paragraph> - Auto-numbered footnote 3. - <footnote auto="1" backrefs="id1" ids="four" names="four"> - <label> - 4 - <paragraph> - Auto-numbered footnote 4. - <footnote auto="1" dupnames="five" ids="five"> - <label> - 5 - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" dupnames="five" ids="id9"> - <label> - 6 - <system_message backrefs="id9" level="2" line="12" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "five". - <paragraph> - Auto-numbered footnote 5 again (duplicate). - <system_message backrefs="id11" ids="id10" level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Too many autonumbered footnote references: only 2 corresponding footnotes available. -"""], -["""\ -Mixed auto-numbered and manual footnotes: - -.. [1] manually numbered -.. [#] auto-numbered -.. [#label] autonumber-labeled -""", -"""\ -<document source="test data"> - <paragraph> - Mixed auto-numbered and manual footnotes: - <footnote ids="id1" names="1"> - <label> - 1 - <paragraph> - manually numbered - <footnote auto="1" ids="id2" names="2"> - <label> - 2 - <paragraph> - auto-numbered - <footnote auto="1" ids="label" names="label"> - <label> - 3 - <paragraph> - autonumber-labeled -"""], -["""\ -A labeled autonumbered footnote referece: [#footnote]_. - -An unlabeled autonumbered footnote referece: [#]_. - -.. [#] Unlabeled autonumbered footnote. -.. [#footnote] Labeled autonumbered footnote. - Note that the footnotes are not in the same - order as the references. -""", -"""\ -<document source="test data"> - <paragraph> - A labeled autonumbered footnote referece: \n\ - <footnote_reference auto="1" ids="id1" refid="footnote"> - 2 - . - <paragraph> - An unlabeled autonumbered footnote referece: \n\ - <footnote_reference auto="1" ids="id2" refid="id3"> - 1 - . - <footnote auto="1" backrefs="id2" ids="id3" names="1"> - <label> - 1 - <paragraph> - Unlabeled autonumbered footnote. - <footnote auto="1" backrefs="id1" ids="footnote" names="footnote"> - <label> - 2 - <paragraph> - Labeled autonumbered footnote. - Note that the footnotes are not in the same - order as the references. -"""], -["""\ -Mixed manually-numbered, anonymous auto-numbered, -and labelled auto-numbered footnotes: - -[#four]_ should be 4, [#]_ should be 2, -[1]_ is 1, [3]_ is 3, -[#]_ should be 6, [#]_ is one too many, -[#five]_ should be 5, and [#eight]_ doesn't exist. - -.. [1] Manually-numbered footnote 1. -.. [#] Auto-numbered footnote 2. -.. [#four] Auto-numbered footnote 4. -.. [3] Manually-numbered footnote 3 -.. [#five] Auto-numbered footnote 5. -.. [#] Auto-numbered footnote 6. -.. [#five] Auto-numbered footnote 5 again (duplicate). -""", -"""\ -<document source="test data"> - <paragraph> - Mixed manually-numbered, anonymous auto-numbered, - and labelled auto-numbered footnotes: - <paragraph> - <footnote_reference auto="1" ids="id1" refid="four"> - 4 - should be 4, \n\ - <footnote_reference auto="1" ids="id2" refid="id10"> - 2 - should be 2, - <footnote_reference ids="id3" refid="id9"> - 1 - is 1, \n\ - <footnote_reference ids="id4" refid="id11"> - 3 - is 3, - <footnote_reference auto="1" ids="id5" refid="id12"> - 6 - should be 6, \n\ - <problematic ids="id15 id6" refid="id14"> - [#]_ - is one too many, - <footnote_reference auto="1" ids="id7" refname="five"> - should be 5, and \n\ - <footnote_reference auto="1" ids="id8" refname="eight"> - doesn't exist. - <footnote backrefs="id3" ids="id9" names="1"> - <label> - 1 - <paragraph> - Manually-numbered footnote 1. - <footnote auto="1" backrefs="id2" ids="id10" names="2"> - <label> - 2 - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" backrefs="id1" ids="four" names="four"> - <label> - 4 - <paragraph> - Auto-numbered footnote 4. - <footnote backrefs="id4" ids="id11" names="3"> - <label> - 3 - <paragraph> - Manually-numbered footnote 3 - <footnote auto="1" dupnames="five" ids="five"> - <label> - 5 - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" backrefs="id5" ids="id12" names="6"> - <label> - 6 - <paragraph> - Auto-numbered footnote 6. - <footnote auto="1" dupnames="five" ids="id13"> - <label> - 7 - <system_message backrefs="id13" level="2" line="15" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "five". - <paragraph> - Auto-numbered footnote 5 again (duplicate). - <system_message backrefs="id15" ids="id14" level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Too many autonumbered footnote references: only 2 corresponding footnotes available. -"""], -["""\ -Referencing a footnote by symbol [*]_. - -.. [*] This is an auto-symbol footnote. -""", -"""\ -<document source="test data"> - <paragraph> - Referencing a footnote by symbol \n\ - <footnote_reference auto="*" ids="id1" refid="id2"> - * - . - <footnote auto="*" backrefs="id1" ids="id2"> - <label> - * - <paragraph> - This is an auto-symbol footnote. -"""], -["""\ -A sequence of symbol footnote references: -[*]_ [*]_ [*]_ [*]_ [*]_ [*]_ [*]_ [*]_ [*]_ [*]_ [*]_ [*]_. - -.. [*] Auto-symbol footnote 1. -.. [*] Auto-symbol footnote 2. -.. [*] Auto-symbol footnote 3. -.. [*] Auto-symbol footnote 4. -.. [*] Auto-symbol footnote 5. -.. [*] Auto-symbol footnote 6. -.. [*] Auto-symbol footnote 7. -.. [*] Auto-symbol footnote 8. -.. [*] Auto-symbol footnote 9. -.. [*] Auto-symbol footnote 10. -.. [*] Auto-symbol footnote 11. -.. [*] Auto-symbol footnote 12. -""", -u"""\ -<document source="test data"> - <paragraph> - A sequence of symbol footnote references: - <footnote_reference auto="*" ids="id1" refid="id13"> - * - \n\ - <footnote_reference auto="*" ids="id2" refid="id14"> - \u2020 - \n\ - <footnote_reference auto="*" ids="id3" refid="id15"> - \u2021 - \n\ - <footnote_reference auto="*" ids="id4" refid="id16"> - \u00A7 - \n\ - <footnote_reference auto="*" ids="id5" refid="id17"> - \u00B6 - \n\ - <footnote_reference auto="*" ids="id6" refid="id18"> - # - \n\ - <footnote_reference auto="*" ids="id7" refid="id19"> - \u2660 - \n\ - <footnote_reference auto="*" ids="id8" refid="id20"> - \u2665 - \n\ - <footnote_reference auto="*" ids="id9" refid="id21"> - \u2666 - \n\ - <footnote_reference auto="*" ids="id10" refid="id22"> - \u2663 - \n\ - <footnote_reference auto="*" ids="id11" refid="id23"> - ** - \n\ - <footnote_reference auto="*" ids="id12" refid="id24"> - \u2020\u2020 - . - <footnote auto="*" backrefs="id1" ids="id13"> - <label> - * - <paragraph> - Auto-symbol footnote 1. - <footnote auto="*" backrefs="id2" ids="id14"> - <label> - \u2020 - <paragraph> - Auto-symbol footnote 2. - <footnote auto="*" backrefs="id3" ids="id15"> - <label> - \u2021 - <paragraph> - Auto-symbol footnote 3. - <footnote auto="*" backrefs="id4" ids="id16"> - <label> - \u00A7 - <paragraph> - Auto-symbol footnote 4. - <footnote auto="*" backrefs="id5" ids="id17"> - <label> - \u00B6 - <paragraph> - Auto-symbol footnote 5. - <footnote auto="*" backrefs="id6" ids="id18"> - <label> - # - <paragraph> - Auto-symbol footnote 6. - <footnote auto="*" backrefs="id7" ids="id19"> - <label> - \u2660 - <paragraph> - Auto-symbol footnote 7. - <footnote auto="*" backrefs="id8" ids="id20"> - <label> - \u2665 - <paragraph> - Auto-symbol footnote 8. - <footnote auto="*" backrefs="id9" ids="id21"> - <label> - \u2666 - <paragraph> - Auto-symbol footnote 9. - <footnote auto="*" backrefs="id10" ids="id22"> - <label> - \u2663 - <paragraph> - Auto-symbol footnote 10. - <footnote auto="*" backrefs="id11" ids="id23"> - <label> - ** - <paragraph> - Auto-symbol footnote 11. - <footnote auto="*" backrefs="id12" ids="id24"> - <label> - \u2020\u2020 - <paragraph> - Auto-symbol footnote 12. -"""], -["""\ -Duplicate manual footnote labels: - -.. [1] Footnote. - -.. [1] Footnote. -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate manual footnote labels: - <footnote dupnames="1" ids="id1"> - <label> - 1 - <paragraph> - Footnote. - <footnote dupnames="1" ids="id2"> - <label> - 1 - <system_message backrefs="id2" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "1". - <paragraph> - Footnote. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_hyperlinks.py b/docutils/test/test_transforms/test_hyperlinks.py deleted file mode 100755 index cef12a4f1..000000000 --- a/docutils/test/test_transforms/test_hyperlinks.py +++ /dev/null @@ -1,845 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.references.Hyperlinks. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.references import PropagateTargets, \ - AnonymousHyperlinks, IndirectHyperlinks, ExternalTargets, \ - InternalTargets, DanglingReferences - -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -# Exhaustive listing of hyperlink variations: every combination of -# target/reference, direct/indirect, internal/external, and named/anonymous, -# plus embedded URIs. -totest['exhaustive_hyperlinks'] = ((PropagateTargets, AnonymousHyperlinks, - IndirectHyperlinks, - ExternalTargets, InternalTargets, - DanglingReferences), [ -["""\ -direct_ external - -.. _direct: http://direct -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="direct" refuri="http://direct"> - direct - external - <target ids="direct" names="direct" refuri="http://direct"> -"""], -["""\ -indirect_ external - -.. _indirect: xtarget_ -.. _xtarget: http://indirect -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="indirect" refuri="http://indirect"> - indirect - external - <target ids="indirect" names="indirect" refuri="http://indirect"> - <target ids="xtarget" names="xtarget" refuri="http://indirect"> -"""], -["""\ -.. _direct: - -direct_ internal -""", -"""\ -<document source="test data"> - <target refid="direct"> - <paragraph ids="direct" names="direct"> - <reference name="direct" refid="direct"> - direct - internal -"""], -["""\ -.. _ztarget: - -indirect_ internal - -.. _indirect2: ztarget_ -.. _indirect: indirect2_ -""", -"""\ -<document source="test data"> - <target refid="ztarget"> - <paragraph ids="ztarget" names="ztarget"> - <reference name="indirect" refid="ztarget"> - indirect - internal - <target ids="indirect2" names="indirect2" refid="ztarget"> - <target ids="indirect" names="indirect" refid="ztarget"> -"""], -["""\ -Implicit --------- - -indirect_ internal - -.. _indirect: implicit_ -""", -"""\ -<document source="test data"> - <section ids="implicit" names="implicit"> - <title> - Implicit - <paragraph> - <reference name="indirect" refid="implicit"> - indirect - internal - <target ids="indirect" names="indirect" refid="implicit"> -"""], -["""\ -Implicit --------- - -`multiply-indirect`_ internal - -.. _multiply-indirect: indirect_ -.. _indirect: implicit_ -""", -"""\ -<document source="test data"> - <section ids="implicit" names="implicit"> - <title> - Implicit - <paragraph> - <reference name="multiply-indirect" refid="implicit"> - multiply-indirect - internal - <target ids="multiply-indirect" names="multiply-indirect" refid="implicit"> - <target ids="indirect" names="indirect" refid="implicit"> -"""], -["""\ -circular_ indirect reference - -.. _circular: indirect_ -.. _indirect: circular_ -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id2" refid="id1"> - circular_ - indirect reference - <target ids="circular" names="circular" refid="circular"> - <problematic ids="id3 indirect" names="indirect" refid="id1"> - .. _indirect: circular_ - <system_message backrefs="id2 id3" ids="id1" level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Indirect hyperlink target "circular" (id="circular") refers to target "indirect", forming a circular reference. -"""], -["""\ -Implicit --------- - -Duplicate implicit targets. - -Implicit --------- - -indirect_ internal - -.. _indirect: implicit_ - -Direct internal reference: Implicit_ -""", -"""\ -<document source="test data"> - <section dupnames="implicit" ids="implicit"> - <title> - Implicit - <paragraph> - Duplicate implicit targets. - <section dupnames="implicit" ids="id1"> - <title> - Implicit - <system_message backrefs="id1" level="1" line="7" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "implicit". - <paragraph> - <problematic ids="id3" refid="id2"> - indirect_ - internal - <target ids="indirect" names="indirect" refname="implicit"> - <paragraph> - Direct internal reference: - <problematic ids="id5" refid="id4"> - Implicit_ - <system_message backrefs="id3" ids="id2" level="3" line="11" source="test data" type="ERROR"> - <paragraph> - Indirect hyperlink target "indirect" (id="indirect") refers to target "implicit", which is a duplicate, and cannot be used as a unique reference. - <system_message backrefs="id5" ids="id4" level="3" line="13" source="test data" type="ERROR"> - <paragraph> - Duplicate target name, cannot be used as a unique reference: "implicit". -"""], -["""\ -`direct external`__ - -__ http://direct -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1" name="direct external" refuri="http://direct"> - direct external - <target anonymous="1" ids="id1" refuri="http://direct"> -"""], -["""\ -`indirect external`__ - -__ xtarget_ -.. _xtarget: http://indirect -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1" name="indirect external" refuri="http://indirect"> - indirect external - <target anonymous="1" ids="id1" refuri="http://indirect"> - <target ids="xtarget" names="xtarget" refuri="http://indirect"> -"""], -["""\ -__ - -`direct internal`__ -""", -"""\ -<document source="test data"> - <target anonymous="1" refid="id1"> - <paragraph ids="id1"> - <reference anonymous="1" name="direct internal" refid="id1"> - direct internal -"""], -["""\ -.. _ztarget: - -`indirect internal`__ - -__ ztarget_ -""", -"""\ -<document source="test data"> - <target refid="ztarget"> - <paragraph ids="ztarget" names="ztarget"> - <reference anonymous="1" name="indirect internal" refid="ztarget"> - indirect internal - <target anonymous="1" ids="id1" refid="ztarget"> -"""], -["""\ -.. _ztarget: - -First - -.. _ztarget: - -Second - -`indirect internal`__ - -__ ztarget_ -""", -"""\ -<document source="test data"> - <target dupnames="ztarget" refid="ztarget"> - <paragraph ids="ztarget"> - First - <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "ztarget". - <target dupnames="ztarget" refid="id1"> - <paragraph ids="id1"> - Second - <paragraph> - <problematic ids="id4" refid="id3"> - `indirect internal`__ - <target anonymous="1" ids="id2" refname="ztarget"> - <system_message backrefs="id4" ids="id3" level="3" line="11" source="test data" type="ERROR"> - <paragraph> - Indirect hyperlink target (id="id2") refers to target "ztarget", which is a duplicate, and cannot be used as a unique reference. -"""], -["""\ -The next anonymous hyperlink reference is parsed (and discarded) at -some point, but nonetheless anonymous hyperlink references and targets -match in this snippet. - -.. |invalid| replace:: anonymous__ - -hyperlink__ - -__ URL -""", -"""\ -<document source="test data"> - <paragraph> - The next anonymous hyperlink reference is parsed (and discarded) at - some point, but nonetheless anonymous hyperlink references and targets - match in this snippet. - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Substitution definition contains illegal element: - <literal_block xml:space="preserve"> - <reference anonymous="1" name="anonymous"> - anonymous - <literal_block xml:space="preserve"> - .. |invalid| replace:: anonymous__ - <paragraph> - <reference anonymous="1" name="hyperlink" refuri="URL"> - hyperlink - <target anonymous="1" ids="id1" refuri="URL"> -"""], -["""\ -An `embedded uri <http://direct>`_. - -Another reference to the same `embedded URI`_. -""", -"""\ -<document source="test data"> - <paragraph> - An \n\ - <reference name="embedded uri" refuri="http://direct"> - embedded uri - <target ids="embedded-uri" names="embedded\ uri" refuri="http://direct"> - . - <paragraph> - Another reference to the same \n\ - <reference name="embedded URI" refuri="http://direct"> - embedded URI - . -"""], -["""\ -An `anonymous embedded uri <http://direct>`__. -""", -"""\ -<document source="test data"> - <paragraph> - An \n\ - <reference name="anonymous embedded uri" refuri="http://direct"> - anonymous embedded uri - . -"""], -["""\ -.. _target: - -.. [1] Footnote; target_ -""", -"""\ -<document source="test data"> - <target ids="target" names="target"> - <footnote ids="id1" names="1"> - <label> - 1 - <paragraph> - Footnote; \n\ - <reference name="target" refid="target"> - target -"""], -["""\ -.. _target: - -.. [cit] Citation; target_ -""", -"""\ -<document source="test data"> - <target ids="target" names="target"> - <citation ids="cit" names="cit"> - <label> - cit - <paragraph> - Citation; \n\ - <reference name="target" refid="target"> - target -"""], -]) - -totest['hyperlinks'] = ((PropagateTargets, AnonymousHyperlinks, - IndirectHyperlinks, ExternalTargets, - InternalTargets, DanglingReferences), [ -["""\ -.. _internal hyperlink: - -This paragraph referenced. - -By this `internal hyperlink`_ reference. -""", -"""\ -<document source="test data"> - <target refid="internal-hyperlink"> - <paragraph ids="internal-hyperlink" names="internal\ hyperlink"> - This paragraph referenced. - <paragraph> - By this \n\ - <reference name="internal hyperlink" refid="internal-hyperlink"> - internal hyperlink - reference. -"""], -["""\ -.. _chained: -.. _internal hyperlink: - -This paragraph referenced. - -By this `internal hyperlink`_ reference -as well as by this chained_ reference. - -The results of the transform are not visible at the XML level. -""", -"""\ -<document source="test data"> - <target refid="chained"> - <target refid="internal-hyperlink"> - <paragraph ids="internal-hyperlink chained" names="internal\ hyperlink chained"> - This paragraph referenced. - <paragraph> - By this \n\ - <reference name="internal hyperlink" refid="internal-hyperlink"> - internal hyperlink - reference - as well as by this \n\ - <reference name="chained" refid="chained"> - chained - reference. - <paragraph> - The results of the transform are not visible at the XML level. -"""], -["""\ -.. _chained: -__ http://anonymous - -Anonymous__ and chained_ both refer to the same URI. -""", -"""\ -<document source="test data"> - <target refid="chained"> - <target anonymous="1" ids="id1 chained" names="chained" refuri="http://anonymous"> - <paragraph> - <reference anonymous="1" name="Anonymous" refuri="http://anonymous"> - Anonymous - and \n\ - <reference name="chained" refuri="http://anonymous"> - chained - both refer to the same URI. -"""], -["""\ -.. _a: -.. _b: - -x -""", -"""\ -<document source="test data"> - <target refid="a"> - <target refid="b"> - <paragraph ids="b a" names="b a"> - x - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Hyperlink target "a" is not referenced. - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - Hyperlink target "b" is not referenced. -"""], -["""\ -.. _a: -.. _b: - -a_ -""", -"""\ -<document source="test data"> - <target refid="a"> - <target refid="b"> - <paragraph ids="b a" names="b a"> - <reference name="a" refid="a"> - a - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - Hyperlink target "b" is not referenced. -"""], -["""\ -.. _a: -.. _b: - -b_ -""", -"""\ -<document source="test data"> - <target refid="a"> - <target refid="b"> - <paragraph ids="b a" names="b a"> - <reference name="b" refid="b"> - b - <system_message level="1" line="1" source="test data" type="INFO"> - <paragraph> - Hyperlink target "a" is not referenced. -"""], -["""\ -.. _a: -.. _b: - -a_\ b_ -""", -"""\ -<document source="test data"> - <target refid="a"> - <target refid="b"> - <paragraph ids="b a" names="b a"> - <reference name="a" refid="a"> - a - <reference name="b" refid="b"> - b -"""], -["""\ -.. _external hyperlink: http://uri - -`External hyperlink`_ reference. -""", -"""\ -<document source="test data"> - <target ids="external-hyperlink" names="external\ hyperlink" refuri="http://uri"> - <paragraph> - <reference name="External hyperlink" refuri="http://uri"> - External hyperlink - reference. -"""], -["""\ -.. _external hyperlink: http://uri -.. _indirect target: `external hyperlink`_ -""", -"""\ -<document source="test data"> - <target ids="external-hyperlink" names="external\ hyperlink" refuri="http://uri"> - <target ids="indirect-target" names="indirect\ target" refuri="http://uri"> - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - Hyperlink target "indirect target" is not referenced. -"""], -["""\ -.. _chained: -.. _external hyperlink: http://uri - -`External hyperlink`_ reference -and a chained_ reference too. -""", -"""\ -<document source="test data"> - <target refid="chained"> - <target ids="external-hyperlink chained" names="external\ hyperlink chained" refuri="http://uri"> - <paragraph> - <reference name="External hyperlink" refuri="http://uri"> - External hyperlink - reference - and a \n\ - <reference name="chained" refuri="http://uri"> - chained - reference too. -"""], -["""\ -.. _external hyperlink: http://uri -.. _indirect hyperlink: `external hyperlink`_ - -`Indirect hyperlink`_ reference. -""", -"""\ -<document source="test data"> - <target ids="external-hyperlink" names="external\ hyperlink" refuri="http://uri"> - <target ids="indirect-hyperlink" names="indirect\ hyperlink" refuri="http://uri"> - <paragraph> - <reference name="Indirect hyperlink" refuri="http://uri"> - Indirect hyperlink - reference. -"""], -["""\ -.. _external hyperlink: http://uri -.. _chained: -.. _indirect hyperlink: `external hyperlink`_ - -Chained_ `indirect hyperlink`_ reference. -""", -"""\ -<document source="test data"> - <target ids="external-hyperlink" names="external\ hyperlink" refuri="http://uri"> - <target refuri="http://uri"> - <target ids="indirect-hyperlink chained" names="indirect\ hyperlink chained" refuri="http://uri"> - <paragraph> - <reference name="Chained" refuri="http://uri"> - Chained - \n\ - <reference name="indirect hyperlink" refuri="http://uri"> - indirect hyperlink - reference. -"""], -["""\ -.. __: http://full -__ -__ http://simplified -.. _external: http://indirect.external -__ external_ -__ - -`Full syntax anonymous external hyperlink reference`__, -`chained anonymous external reference`__, -`simplified syntax anonymous external hyperlink reference`__, -`indirect anonymous hyperlink reference`__, -`internal anonymous hyperlink reference`__. -""", -"""\ -<document source="test data"> - <target anonymous="1" ids="id1" refuri="http://full"> - <target anonymous="1" refid="id2"> - <target anonymous="1" ids="id3 id2" refuri="http://simplified"> - <target ids="external" names="external" refuri="http://indirect.external"> - <target anonymous="1" ids="id4" refuri="http://indirect.external"> - <target anonymous="1" refid="id5"> - <paragraph ids="id5"> - <reference anonymous="1" name="Full syntax anonymous external hyperlink reference" refuri="http://full"> - Full syntax anonymous external hyperlink reference - , - <reference anonymous="1" name="chained anonymous external reference" refuri="http://simplified"> - chained anonymous external reference - , - <reference anonymous="1" name="simplified syntax anonymous external hyperlink reference" refuri="http://simplified"> - simplified syntax anonymous external hyperlink reference - , - <reference anonymous="1" name="indirect anonymous hyperlink reference" refuri="http://indirect.external"> - indirect anonymous hyperlink reference - , - <reference anonymous="1" name="internal anonymous hyperlink reference" refid="id5"> - internal anonymous hyperlink reference - . -"""], -["""\ -Duplicate external target_'s (different URIs): - -.. _target: first - -.. _target: second -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate external \n\ - <problematic ids="id3" refid="id2"> - target_ - 's (different URIs): - <target dupnames="target" ids="target" refuri="first"> - <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <target dupnames="target" ids="id1" refuri="second"> - <system_message backrefs="id3" ids="id2" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Duplicate target name, cannot be used as a unique reference: "target". -"""], -["""\ -Duplicate external targets (different URIs) without reference: - -.. _target: first - -.. _target: second -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate external targets (different URIs) without reference: - <target dupnames="target" ids="target" refuri="first"> - <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <target dupnames="target" ids="id1" refuri="second"> -"""], -["""\ -Several__ anonymous__ hyperlinks__, but not enough targets. - -__ http://example.org -""", -"""\ -<document source="test data"> - <paragraph> - <problematic ids="id3" refid="id2"> - Several__ - \n\ - <problematic ids="id4" refid="id2"> - anonymous__ - \n\ - <problematic ids="id5" refid="id2"> - hyperlinks__ - , but not enough targets. - <target anonymous="1" ids="id1" refuri="http://example.org"> - <system_message backrefs="id3 id4 id5" ids="id2" level="3" source="test data" type="ERROR"> - <paragraph> - Anonymous hyperlink mismatch: 3 references but 1 targets. - See "backrefs" attribute for IDs. -"""], -["""\ -.. _external: http://uri -.. _indirect: external_ -.. _internal: - -.. image:: picture.png - :target: external_ - -.. image:: picture.png - :target: indirect_ - -.. image:: picture.png - :target: internal_ -""", -"""\ -<document source="test data"> - <target ids="external" names="external" refuri="http://uri"> - <target ids="indirect" names="indirect" refuri="http://uri"> - <target refid="internal"> - <reference ids="internal" name="external" names="internal" refuri="http://uri"> - <image uri="picture.png"> - <reference name="indirect" refuri="http://uri"> - <image uri="picture.png"> - <reference name="internal" refid="internal"> - <image uri="picture.png"> -"""], -["""\ -.. contents:: Table of Contents -.. _indirect reference to the table of contents: `table of contents`_ - -Section -======= - -Testing an `indirect reference to the table of contents`_. -""", -"""\ -<document source="test data"> - <topic classes="contents" ids="table-of-contents" names="table\ of\ contents"> - <title> - Table of Contents - <bullet_list> - <list_item> - <paragraph> - <reference ids="id1" refid="section"> - Section - <target ids="indirect-reference-to-the-table-of-contents" names="indirect\ reference\ to\ the\ table\ of\ contents" refid="table-of-contents"> - <section ids="section" names="section"> - <title refid="id1"> - Section - <paragraph> - Testing an - <reference name="indirect reference to the table of contents" refid="table-of-contents"> - indirect reference to the table of contents - . -"""], -["""\ -.. _explicit target: - -Title ------ - -Let's reference it (`explicit target`_) to avoid an irrelevant error. -""", -"""\ -<document source="test data"> - <target refid="explicit-target"> - <section ids="title explicit-target" names="title explicit\ target"> - <title> - Title - <paragraph> - Let's reference it ( - <reference name="explicit target" refid="explicit-target"> - explicit target - ) to avoid an irrelevant error. -"""], -["""\ -target1_ should refer to target2_, not the Title. - -.. _target1: -.. _target2: URI - -Title -===== -""", -"""\ -<document source="test data"> - <paragraph> - <reference name="target1" refuri="URI"> - target1 - should refer to \n\ - <reference name="target2" refuri="URI"> - target2 - , not the Title. - <target refid="target1"> - <target ids="target2 target1" names="target2 target1" refuri="URI"> - <section ids="title" names="title"> - <title> - Title -"""], -["""\ -Unknown reference_. -""", -"""\ -<document source="test data"> - <paragraph> - Unknown \n\ - <problematic ids="id2" refid="id1"> - reference_ - . - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown target name: "reference". -"""], -["""\ -Duplicate manual footnote labels, with reference ([1]_): - -.. [1] Footnote. - -.. [1] Footnote. -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate manual footnote labels, with reference ( - <problematic ids="id5 id1" refid="id4"> - [1]_ - ): - <footnote dupnames="1" ids="id2"> - <label> - 1 - <paragraph> - Footnote. - <footnote dupnames="1" ids="id3"> - <label> - 1 - <system_message backrefs="id3" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "1". - <paragraph> - Footnote. - <system_message backrefs="id5" ids="id4" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Duplicate target name, cannot be used as a unique reference: "1". -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_messages.py b/docutils/test/test_transforms/test_messages.py deleted file mode 100755 index 6ff8c9987..000000000 --- a/docutils/test/test_transforms/test_messages.py +++ /dev/null @@ -1,66 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.universal.Messages. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.universal import Messages -from docutils.transforms.references import Substitutions -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['system_message_sections'] = ((Substitutions, Messages), [ -["""\ -This |unknown substitution| will generate a system message, thanks to -the ``Substitutions`` transform. The ``Messages`` transform will -generate a "System Messages" section. - -(A second copy of the system message is tacked on to the end of the -document by the test framework.) -""", -"""\ -<document source="test data"> - <paragraph> - This \n\ - <problematic ids="id2" refid="id1"> - |unknown substitution| - will generate a system message, thanks to - the \n\ - <literal> - Substitutions - transform. The \n\ - <literal> - Messages - transform will - generate a "System Messages" section. - <paragraph> - (A second copy of the system message is tacked on to the end of the - document by the test framework.) - <section classes="system-messages"> - <title> - Docutils System Messages - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Undefined substitution referenced: "unknown substitution". -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_peps.py b/docutils/test/test_transforms/test_peps.py deleted file mode 100755 index 5e34aea80..000000000 --- a/docutils/test/test_transforms/test_peps.py +++ /dev/null @@ -1,68 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.peps. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.peps import TargetNotes -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['target_notes'] = ((TargetNotes,), [ -["""\ -No references or targets exist, therefore -no "References" section should be generated. -""", -"""\ -<document source="test data"> - <paragraph> - No references or targets exist, therefore - no "References" section should be generated. -"""], -["""\ -A target exists, here's the reference_. -A "References" section should be generated. - -.. _reference: http://www.example.org -""", -"""\ -<document source="test data"> - <paragraph> - A target exists, here's the \n\ - <reference name="reference" refname="reference"> - reference - \n\ - <footnote_reference auto="1" ids="id3" refname="TARGET_NOTE: id2"> - . - A "References" section should be generated. - <target ids="reference" names="reference" refuri="http://www.example.org"> - <section ids="id1"> - <title> - References - <footnote auto="1" ids="id2" names="TARGET_NOTE:\ id2"> - <paragraph> - <reference refuri="http://www.example.org"> - http://www.example.org -"""], -]) - - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_sectnum.py b/docutils/test/test_transforms/test_sectnum.py deleted file mode 100755 index 60237cea1..000000000 --- a/docutils/test/test_transforms/test_sectnum.py +++ /dev/null @@ -1,381 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger, Dmitry Jemerov -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for `docutils.transforms.parts.SectNum` (via -`docutils.transforms.universal.LastReaderPending`). -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.references import Substitutions -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['section_numbers'] = ((Substitutions,), [ -["""\ -.. sectnum:: - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -u"""\ -<document source="test data"> - <section ids="title-1" names="title\ 1"> - <title auto="1"> - <generated classes="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title auto="1"> - <generated classes="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title auto="1"> - <generated classes="sectnum"> - 1.1.1\u00a0\u00a0\u00a0 - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title auto="1"> - <generated classes="sectnum"> - 1.2\u00a0\u00a0\u00a0 - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. sectnum:: - -**Bold Title** -============== -Paragraph 1. -""", -u"""\ -<document source="test data"> - <section ids="bold-title" names="bold\ title"> - <title auto="1"> - <generated classes="sectnum"> - 1\u00a0\u00a0\u00a0 - <strong> - Bold Title - <paragraph> - Paragraph 1. -"""], -["""\ -.. sectnum:: :depth: 2 - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -u"""\ -<document source="test data"> - <section ids="title-1" names="title\ 1"> - <title auto="1"> - <generated classes="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title auto="1"> - <generated classes="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title auto="1"> - <generated classes="sectnum"> - 1.2\u00a0\u00a0\u00a0 - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. contents:: -.. sectnum:: :depth: 2 - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -u"""\ -<document source="test data"> - <topic classes="contents" ids="contents" names="contents"> - <title> - Contents - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id1" refid="title-1"> - <generated classes="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <bullet_list classes="auto-toc"> - <list_item> - <paragraph> - <reference ids="id2" refid="title-2"> - <generated classes="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference ids="id3" refid="title-3"> - Title 3 - <list_item> - <paragraph> - <reference ids="id4" refid="title-4"> - <generated classes="sectnum"> - 1.2\u00a0\u00a0\u00a0 - Title 4 - <section ids="title-1" names="title\ 1"> - <title auto="1" refid="id1"> - <generated classes="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title auto="1" refid="id2"> - <generated classes="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title refid="id3"> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title auto="1" refid="id4"> - <generated classes="sectnum"> - 1.2\u00a0\u00a0\u00a0 - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. sectnum:: - :prefix: Arbitrary- - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -u"""\ -<document source="test data"> - <section ids="title-1" names="title\ 1"> - <title auto="1"> - <generated classes="sectnum"> - Arbitrary-1\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title auto="1"> - <generated classes="sectnum"> - Arbitrary-1.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title auto="1"> - <generated classes="sectnum"> - Arbitrary-1.1.1\u00a0\u00a0\u00a0 - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title auto="1"> - <generated classes="sectnum"> - Arbitrary-1.2\u00a0\u00a0\u00a0 - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. sectnum:: - :start: 3 - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -u"""\ -<document source="test data"> - <section ids="title-1" names="title\ 1"> - <title auto="1"> - <generated classes="sectnum"> - 3\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title auto="1"> - <generated classes="sectnum"> - 3.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title auto="1"> - <generated classes="sectnum"> - 3.1.1\u00a0\u00a0\u00a0 - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title auto="1"> - <generated classes="sectnum"> - 3.2\u00a0\u00a0\u00a0 - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. sectnum:: - :prefix: (5.9. - :suffix: ) - :start: 3 - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. - -Title 3 -``````` -Paragraph 3. - -Title 4 -------- -Paragraph 4. -""", -u"""\ -<document source="test data"> - <section ids="title-1" names="title\ 1"> - <title auto="1"> - <generated classes="sectnum"> - (5.9.3)\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title\ 2"> - <title auto="1"> - <generated classes="sectnum"> - (5.9.3.1)\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title\ 3"> - <title auto="1"> - <generated classes="sectnum"> - (5.9.3.1.1)\u00a0\u00a0\u00a0 - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title\ 4"> - <title auto="1"> - <generated classes="sectnum"> - (5.9.3.2)\u00a0\u00a0\u00a0 - Title 4 - <paragraph> - Paragraph 4. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_strip_comments.py b/docutils/test/test_transforms/test_strip_comments.py deleted file mode 100755 index e3efc1e14..000000000 --- a/docutils/test/test_transforms/test_strip_comments.py +++ /dev/null @@ -1,49 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.universal.StripComments. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.universal import StripComments -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite( - parser, suite_settings={'strip_comments': 1}) - s.generateTests(totest) - return s - -totest = {} - -totest['strip_comments'] = ((StripComments,), [ -["""\ -.. this is a comment - -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <section ids="title" names="title"> - <title> - Title - <paragraph> - Paragraph. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_substitutions.py b/docutils/test/test_transforms/test_substitutions.py deleted file mode 100755 index 196bec9a1..000000000 --- a/docutils/test/test_transforms/test_substitutions.py +++ /dev/null @@ -1,353 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for docutils.transforms.references.Substitutions. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.references import Substitutions -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['substitutions'] = ((Substitutions,), [ -["""\ -The |biohazard| symbol is deservedly scary-looking. - -.. |biohazard| image:: biohazard.png -""", -"""\ -<document source="test data"> - <paragraph> - The \n\ - <image alt="biohazard" uri="biohazard.png"> - symbol is deservedly scary-looking. - <substitution_definition names="biohazard"> - <image alt="biohazard" uri="biohazard.png"> -"""], -["""\ -Here's an |unknown| substitution. -""", -"""\ -<document source="test data"> - <paragraph> - Here's an \n\ - <problematic ids="id2" refid="id1"> - |unknown| - substitution. - <system_message backrefs="id2" ids="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Undefined substitution referenced: "unknown". -"""], -[u"""\ -Substitutions support case differences: - -.. |eacute| replace:: \u00E9 -.. |Eacute| replace:: \u00C9 - -|Eacute|\\t\\ |eacute|, and even |EACUTE|. -""", -u"""\ -<document source="test data"> - <paragraph> - Substitutions support case differences: - <substitution_definition names="eacute"> - \u00E9 - <substitution_definition names="Eacute"> - \u00C9 - <paragraph> - \u00C9 - t - \u00E9 - , and even \n\ - \u00C9 - . -"""], -[u"""\ -Indirect substitution definitions with multiple references: - -|substitute| my coke for gin -|substitute| you for my mum -at least I'll get my washing done - -.. |substitute| replace:: |replace| -.. |replace| replace:: swap -""", -u"""\ -<document source="test data"> - <paragraph> - Indirect substitution definitions with multiple references: - <paragraph> - swap - my coke for gin - swap - you for my mum - at least I'll get my washing done - <substitution_definition names="substitute"> - swap - <substitution_definition names="replace"> - swap -"""], -["""\ -.. |l| unicode:: U+00AB .. left chevron -.. |r| unicode:: U+00BB .. right chevron -.. |.| replace:: |l|\ ``.``\ |r| - -.. Delete either of the following lines, and there is no error. - -Regular expression |.| will match any character - -.. Note:: Note that |.| matches *exactly* one character -""", -u"""\ -<document source="test data"> - <substitution_definition names="l"> - \xab - <substitution_definition names="r"> - \xbb - <substitution_definition names="."> - \xab - <literal> - . - \xbb - <comment xml:space="preserve"> - Delete either of the following lines, and there is no error. - <paragraph> - Regular expression \n\ - \xab - <literal> - . - \xbb - will match any character - <note> - <paragraph> - Note that \n\ - \xab - <literal> - . - \xbb - matches \n\ - <emphasis> - exactly - one character -"""], -["""\ -.. |sub| replace:: |sub| -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" names="sub" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition detected: - <literal_block xml:space="preserve"> - .. |sub| replace:: |sub| -"""], -["""\ -.. |sub| replace:: |indirect1| -.. |indirect1| replace:: |indirect2| -.. |indirect2| replace:: |Sub| -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" names="sub" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition detected: - <literal_block xml:space="preserve"> - .. |sub| replace:: |indirect1| - <system_message level="3" line="2" names="indirect1" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition detected: - <literal_block xml:space="preserve"> - .. |indirect1| replace:: |indirect2| - <system_message level="3" line="3" names="indirect2" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition detected: - <literal_block xml:space="preserve"> - .. |indirect2| replace:: |Sub| -"""], -["""\ -.. |indirect1| replace:: |indirect2| -.. |indirect2| replace:: |Sub| -.. |sub| replace:: |indirect1| - -Use |sub| and |indirect1| and |sub| again (and |sub| one more time). -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" names="indirect1" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition detected: - <literal_block xml:space="preserve"> - .. |indirect1| replace:: |indirect2| - <system_message level="3" line="2" names="indirect2" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition detected: - <literal_block xml:space="preserve"> - .. |indirect2| replace:: |Sub| - <system_message level="3" line="3" names="sub" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition detected: - <literal_block xml:space="preserve"> - .. |sub| replace:: |indirect1| - <paragraph> - Use \n\ - <problematic ids="id8" refid="id7"> - and \n\ - <problematic ids="id2" refid="id1"> - |indirect1| - and \n\ - <problematic ids="id4" refid="id3"> - |sub| - again (and \n\ - <problematic ids="id6" refid="id5"> - |sub| - one more time). - <system_message backrefs="id2" ids="id1" level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition referenced: "indirect1". - <system_message backrefs="id4" ids="id3" level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition referenced: "sub". - <system_message backrefs="id6" ids="id5" level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition referenced: "sub". - <system_message backrefs="id8" ids="id7" level="3" source="test data" type="ERROR"> - <paragraph> - Circular substitution definition referenced: "Sub". -"""], -]) - -totest['unicode'] = ((Substitutions,), [ -["""\ -Insert an em-dash (|mdash|), a copyright symbol (|copy|), a non-breaking -space (|nbsp|), a backwards-not-equals (|bne|), and a captial omega (|Omega|). - -.. |mdash| unicode:: 0x02014 -.. |copy| unicode:: \\u00A9 -.. |nbsp| unicode::   -.. |bne| unicode:: U0003D U020E5 -.. |Omega| unicode:: U+003A9 -""", -u"""\ -<document source="test data"> - <paragraph> - Insert an em-dash ( - \u2014 - ), a copyright symbol ( - \u00a9 - ), a non-breaking - space ( - \u00a0 - ), a backwards-not-equals ( - = - \u20e5 - ), and a captial omega ( - \u03a9 - ). - <substitution_definition names="mdash"> - \u2014 - <substitution_definition names="copy"> - \u00a9 - <substitution_definition names="nbsp"> - \u00a0 - <substitution_definition names="bne"> - = - \u20e5 - <substitution_definition names="Omega"> - \u03a9 -"""], -[""" -Testing comments and extra text. - -Copyright |copy| 2003, |BogusMegaCorp (TM)|. - -.. |copy| unicode:: 0xA9 .. copyright sign -.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign -""", -u"""\ -<document source="test data"> - <paragraph> - Testing comments and extra text. - <paragraph> - Copyright \n\ - \u00a9 - 2003, \n\ - BogusMegaCorp - \u2122 - . - <substitution_definition names="copy"> - \u00a9 - <substitution_definition names="BogusMegaCorp\ (TM)"> - BogusMegaCorp - \u2122 -"""], -["""\ -Insert an em-dash |---| automatically trimming whitespace. -Some substitutions |TM| only need trimming on one side. - -.. |---| unicode:: U+02014 - :trim: -.. |TM| unicode:: U+02122 - :ltrim: -""", -u"""\ -<document source="test data"> - <paragraph> - Insert an em-dash - \u2014 - automatically trimming whitespace. - Some substitutions - \u2122 - only need trimming on one side. - <substitution_definition ltrim="1" names="---" rtrim="1"> - \u2014 - <substitution_definition ltrim="1" names="TM"> - \u2122 -"""], -["""\ -Substitution definition with an illegal element: - -.. |target| replace:: _`target` - -Make sure this substitution definition is not registered: |target| -""", -"""\ -<document source="test data"> - <paragraph> - Substitution definition with an illegal element: - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Substitution definition contains illegal element: - <literal_block xml:space="preserve"> - <target ids="target" names="target"> - target - <literal_block xml:space="preserve"> - .. |target| replace:: _`target` - <paragraph> - Make sure this substitution definition is not registered: \n\ - <problematic ids="id2" refid="id1"> - |target| - <system_message backrefs="id2" ids="id1" level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Undefined substitution referenced: "target". -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_target_notes.py b/docutils/test/test_transforms/test_target_notes.py deleted file mode 100755 index cf625572d..000000000 --- a/docutils/test/test_transforms/test_target_notes.py +++ /dev/null @@ -1,84 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for `docutils.transforms.references.TargetNotes` (via -`docutils.transforms.universal.LastReaderPending`). -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.references import PropagateTargets, \ - AnonymousHyperlinks, IndirectHyperlinks, ExternalTargets, \ - InternalTargets, DanglingReferences, Footnotes -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['tables_of_contents'] = ((PropagateTargets, AnonymousHyperlinks, - IndirectHyperlinks, - ExternalTargets, InternalTargets, - DanglingReferences, - ), [ -["""\ -.. _target: http://exammple.org - -A reference to a target_. - -.. target-notes:: -""", -"""\ -<document source="test data"> - <target ids="target" names="target" refuri="http://exammple.org"> - <paragraph> - A reference to a \n\ - <reference name="target" refuri="http://exammple.org"> - target - \n\ - <footnote_reference auto="1" ids="id2" refid="id1"> - . - <footnote auto="1" ids="id1" names="TARGET_NOTE:\\ id1"> - <paragraph> - <reference refuri="http://exammple.org"> - http://exammple.org -"""], -["""\ -.. _target: http://exammple.org - -A reference to a target_. - -.. target-notes:: :class: custom -""", -"""\ -<document source="test data"> - <target ids="target" names="target" refuri="http://exammple.org"> - <paragraph> - A reference to a \n\ - <reference name="target" refuri="http://exammple.org"> - target - <inline classes="custom"> - \n\ - <footnote_reference auto="1" classes="custom" ids="id2" refid="id1"> - . - <footnote auto="1" ids="id1" names="TARGET_NOTE:\\ id1"> - <paragraph> - <reference refuri="http://exammple.org"> - http://exammple.org -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_transitions.py b/docutils/test/test_transforms/test_transitions.py deleted file mode 100755 index 098c8bba3..000000000 --- a/docutils/test/test_transforms/test_transitions.py +++ /dev/null @@ -1,308 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for misc.Transitions transform. -""" - -from __init__ import DocutilsTestSupport # must be imported before docutils -from docutils.transforms.misc import Transitions -from docutils.parsers.rst import Parser - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - - -totest = {} - -totest['transitions'] = ((Transitions,), [ -["""\ -Section 1 -========= - -Subsection 1 ------------- - -Some text. - ----------- - -Section 2 -========= - -Some text. -""", -"""\ -<document source="test data"> - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <section ids="subsection-1" names="subsection\ 1"> - <title> - Subsection 1 - <paragraph> - Some text. - <transition> - <section ids="section-2" names="section\ 2"> - <title> - Section 2 - <paragraph> - Some text. -"""], -["""\ -A paragraph. - ----------- - -Section 1 -========= - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph. - <transition> - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <paragraph> - Paragraph. -"""], -["""\ --------- - -A section or document may not begin with a transition. - -The DTD specifies that two transitions may not -be adjacent: - --------- - --------- - --------- - -The DTD also specifies that a section or document -may not end with a transition. - --------- -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Document or section may not begin with a transition. - <transition> - <paragraph> - A section or document may not begin with a transition. - <paragraph> - The DTD specifies that two transitions may not - be adjacent: - <transition> - <system_message level="3" line="10" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <system_message level="3" line="12" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <paragraph> - The DTD also specifies that a section or document - may not end with a transition. - <transition> - <system_message level="3" line="17" source="test data" type="ERROR"> - <paragraph> - Document may not end with a transition. -"""], -["""\ -Sections with transitions at beginning and end. - -Section 1 -========= - ----------- - -The next transition is legal: - ----------- - -Section 2 -========= - ----------- -""", -"""\ -<document source="test data"> - <paragraph> - Sections with transitions at beginning and end. - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <system_message level="3" line="6" source="test data" type="ERROR"> - <paragraph> - Document or section may not begin with a transition. - <transition> - <paragraph> - The next transition is legal: - <transition> - <section ids="section-2" names="section\ 2"> - <title> - Section 2 - <system_message level="3" line="15" source="test data" type="ERROR"> - <paragraph> - Document or section may not begin with a transition. - <transition> - <system_message level="3" line="15" source="test data" type="ERROR"> - <paragraph> - Document may not end with a transition. -"""], -["""\ -A paragraph and two transitions. - ----------- - ----------- -""", # the same: -"""\ -<document source="test data"> - <paragraph> - A paragraph and two transitions. - <transition> - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Document may not end with a transition. -"""], -["""\ -A paragraph, two transitions, and a blank line. - ----------- - ----------- - -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph, two transitions, and a blank line. - <transition> - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Document may not end with a transition. -"""], -["""\ ----------- - -Document beginning with a transition. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Document or section may not begin with a transition. - <transition> - <paragraph> - Document beginning with a transition. -"""], -["""\ -Section 1 -========= - ----------- - ----------- - ----------- - -Section 2 -========= - -Some text. -""", -"""\ -<document source="test data"> - <section ids="section-1" names="section\ 1"> - <title> - Section 1 - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - Document or section may not begin with a transition. - <transition> - <system_message level="3" line="6" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <system_message level="3" line="8" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <section ids="section-2" names="section\ 2"> - <title> - Section 2 - <paragraph> - Some text. -"""], -["""\ ----------- - ----------- - ----------- -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Document or section may not begin with a transition. - <transition> - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - At least one body element must separate transitions; adjacent transitions are not allowed. - <transition> - <system_message level="3" line="5" source="test data" type="ERROR"> - <paragraph> - Document may not end with a transition. -"""], -["""\ -A paragraph. - ----------- - -""", -"""\ -<document source="test data"> - <paragraph> - A paragraph. - <transition> - <system_message level="3" line="3" source="test data" type="ERROR"> - <paragraph> - Document may not end with a transition. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_transforms/test_writer_aux.py b/docutils/test/test_transforms/test_writer_aux.py deleted file mode 100755 index 5ec040a69..000000000 --- a/docutils/test/test_transforms/test_writer_aux.py +++ /dev/null @@ -1,57 +0,0 @@ -#! /usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for writer_aux transforms. -""" - -from __init__ import DocutilsTestSupport # must be imported before docutils -from docutils.transforms import writer_aux -from docutils.parsers.rst import Parser - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - - -totest = {} - -totest['compound'] = ((writer_aux.Compound,), [ -["""\ -.. class:: compound - -.. compound:: - - .. class:: paragraph1 - - Paragraph 1. - - .. class:: paragraph2 - - Paragraph 2. - - Block quote. -""", -"""\ -<document source="test data"> - <paragraph classes="paragraph1 compound"> - Paragraph 1. - <paragraph classes="paragraph2 continued"> - Paragraph 2. - <block_quote classes="continued"> - <paragraph> - Block quote. -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_utils.py b/docutils/test/test_utils.py deleted file mode 100755 index 006495ac9..000000000 --- a/docutils/test/test_utils.py +++ /dev/null @@ -1,213 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for utils.py. -""" - -import unittest -import StringIO -import sys -from DocutilsTestSupport import utils, nodes - - -class ReporterTests(unittest.TestCase): - - stream = StringIO.StringIO() - reporter = utils.Reporter('test data', 2, 4, stream, 1) - - def setUp(self): - self.stream.seek(0) - self.stream.truncate() - - def test_level0(self): - sw = self.reporter.system_message(0, 'debug output') - self.assertEquals(sw.pformat(), """\ -<system_message level="0" source="test data" type="DEBUG"> - <paragraph> - debug output -""") - self.assertEquals(self.stream.getvalue(), - 'test data:: (DEBUG/0) debug output\n') - - def test_level1(self): - sw = self.reporter.system_message(1, 'a little reminder') - self.assertEquals(sw.pformat(), """\ -<system_message level="1" source="test data" type="INFO"> - <paragraph> - a little reminder -""") - self.assertEquals(self.stream.getvalue(), '') - - def test_level2(self): - sw = self.reporter.system_message(2, 'a warning') - self.assertEquals(sw.pformat(), """\ -<system_message level="2" source="test data" type="WARNING"> - <paragraph> - a warning -""") - self.assertEquals(self.stream.getvalue(), - 'test data:: (WARNING/2) a warning\n') - - def test_level3(self): - sw = self.reporter.system_message(3, 'an error') - self.assertEquals(sw.pformat(), """\ -<system_message level="3" source="test data" type="ERROR"> - <paragraph> - an error -""") - self.assertEquals(self.stream.getvalue(), - 'test data:: (ERROR/3) an error\n') - - def test_level4(self): - self.assertRaises(utils.SystemMessage, self.reporter.system_message, 4, - 'a severe error, raises an exception') - self.assertEquals(self.stream.getvalue(), 'test data:: (SEVERE/4) ' - 'a severe error, raises an exception\n') - - -class QuietReporterTests(unittest.TestCase): - - stream = StringIO.StringIO() - reporter = utils.Reporter('test data', 5, 5, stream, 0) - - def setUp(self): - self.stream.seek(0) - self.stream.truncate() - - def test_debug(self): - sw = self.reporter.debug('a debug message') - # None because debug is disabled. - self.assertEquals(sw, None) - self.assertEquals(self.stream.getvalue(), '') - - def test_info(self): - sw = self.reporter.info('an informational message') - self.assertEquals(sw.pformat(), """\ -<system_message level="1" source="test data" type="INFO"> - <paragraph> - an informational message -""") - self.assertEquals(self.stream.getvalue(), '') - - def test_warning(self): - sw = self.reporter.warning('a warning') - self.assertEquals(sw.pformat(), """\ -<system_message level="2" source="test data" type="WARNING"> - <paragraph> - a warning -""") - self.assertEquals(self.stream.getvalue(), '') - - def test_error(self): - sw = self.reporter.error('an error') - self.assertEquals(sw.pformat(), """\ -<system_message level="3" source="test data" type="ERROR"> - <paragraph> - an error -""") - self.assertEquals(self.stream.getvalue(), '') - - def test_severe(self): - sw = self.reporter.severe('a severe error') - self.assertEquals(sw.pformat(), """\ -<system_message level="4" source="test data" type="SEVERE"> - <paragraph> - a severe error -""") - self.assertEquals(self.stream.getvalue(), '') - - -class NameValueTests(unittest.TestCase): - - def test_extract_name_value(self): - self.assertRaises(utils.NameValueError, utils.extract_name_value, - 'hello') - self.assertRaises(utils.NameValueError, utils.extract_name_value, - 'hello') - self.assertRaises(utils.NameValueError, utils.extract_name_value, - '=hello') - self.assertRaises(utils.NameValueError, utils.extract_name_value, - 'hello=') - self.assertRaises(utils.NameValueError, utils.extract_name_value, - 'hello="') - self.assertRaises(utils.NameValueError, utils.extract_name_value, - 'hello="something') - self.assertRaises(utils.NameValueError, utils.extract_name_value, - 'hello="something"else') - output = utils.extract_name_value( - """att1=val1 att2=val2 att3="value number '3'" att4=val4""") - self.assertEquals(output, [('att1', 'val1'), ('att2', 'val2'), - ('att3', "value number '3'"), - ('att4', 'val4')]) - - -class ExtensionOptionTests(unittest.TestCase): - - optionspec = {'a': int, 'bbb': float, 'cdef': (lambda x: x), - 'empty': (lambda x: x)} - - def test_assemble_option_dict(self): - input = utils.extract_name_value('a=1 bbb=2.0 cdef=hol%s' % chr(224)) - self.assertEquals( - utils.assemble_option_dict(input, self.optionspec), - {'a': 1, 'bbb': 2.0, 'cdef': ('hol%s' % chr(224))}) - input = utils.extract_name_value('a=1 b=2.0 c=hol%s' % chr(224)) - self.assertRaises(KeyError, utils.assemble_option_dict, - input, self.optionspec) - input = utils.extract_name_value('a=1 bbb=two cdef=hol%s' % chr(224)) - self.assertRaises(ValueError, utils.assemble_option_dict, - input, self.optionspec) - - def test_extract_extension_options(self): - field_list = nodes.field_list() - field_list += nodes.field( - '', nodes.field_name('', 'a'), - nodes.field_body('', nodes.paragraph('', '1'))) - field_list += nodes.field( - '', nodes.field_name('', 'bbb'), - nodes.field_body('', nodes.paragraph('', '2.0'))) - field_list += nodes.field( - '', nodes.field_name('', 'cdef'), - nodes.field_body('', nodes.paragraph('', 'hol%s' % chr(224)))) - field_list += nodes.field( - '', nodes.field_name('', 'empty'), nodes.field_body()) - self.assertEquals( - utils.extract_extension_options(field_list, self.optionspec), - {'a': 1, 'bbb': 2.0, 'cdef': ('hol%s' % chr(224)), - 'empty': None}) - self.assertRaises(KeyError, utils.extract_extension_options, - field_list, {}) - field_list += nodes.field( - '', nodes.field_name('', 'cdef'), - nodes.field_body('', nodes.paragraph('', 'one'), - nodes.paragraph('', 'two'))) - self.assertRaises(utils.BadOptionDataError, - utils.extract_extension_options, - field_list, self.optionspec) - field_list[-1] = nodes.field( - '', nodes.field_name('', 'cdef bad'), - nodes.field_body('', nodes.paragraph('', 'no arguments'))) - self.assertRaises(utils.BadOptionError, - utils.extract_extension_options, - field_list, self.optionspec) - field_list[-1] = nodes.field( - '', nodes.field_name('', 'cdef'), - nodes.field_body('', nodes.paragraph('', 'duplicate'))) - self.assertRaises(utils.DuplicateOptionError, - utils.extract_extension_options, - field_list, self.optionspec) - field_list[-2] = nodes.field( - '', nodes.field_name('', 'unkown'), - nodes.field_body('', nodes.paragraph('', 'unknown'))) - self.assertRaises(KeyError, utils.extract_extension_options, - field_list, self.optionspec) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_viewlist.py b/docutils/test/test_viewlist.py deleted file mode 100755 index 85164b148..000000000 --- a/docutils/test/test_viewlist.py +++ /dev/null @@ -1,166 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test module for the ViewList class from statemachine.py. -""" - -import unittest -import sys -import re -from DocutilsTestSupport import statemachine - - -class ViewListTests(unittest.TestCase): - - a_list = list('abcdefg') - b_list = list('AEIOU') - c_list = list('XYZ') - - def setUp(self): - self.a = statemachine.ViewList(self.a_list, 'a') - self.b = statemachine.ViewList(self.b_list, 'b') - self.c = statemachine.ViewList(self.c_list, 'c') - - def test_lists(self): - self.assertEqual(self.a, self.a_list) - self.assertEqual(str(self.a), str(self.a_list)) - self.assertEqual(self.b, self.b_list) - self.assertEqual(self.c, self.c_list) - self.assertEqual(self.a.items, - zip('a' * len(self.a_list), range(len(self.a_list)))) - - def test_get_slice(self): - a = self.a[1:-1] - a_list = self.a_list[1:-1] - self.assertEqual(a, a_list) - self.assertEqual(a.items, - zip('a' * len(a_list), range(1, len(a_list) + 1))) - self.assertEqual(a.parent, self.a) - - def test_set_slice(self): - a = statemachine.ViewList(self.a[:]) - s = a[2:-2] - s[2:2] = self.b - s_list = self.a_list[2:-2] - s_list[2:2] = self.b_list - self.assertEqual(s, s_list) - self.assertEqual(s, a[2:-2]) - self.assertEqual(s.items, a[2:-2].items) - - def test_del_slice(self): - a = statemachine.ViewList(self.a[:]) - s = a[2:] - s_list = self.a_list[2:] - del s[3:5] - del s_list[3:5] - self.assertEqual(s, s_list) - self.assertEqual(s, a[2:]) - self.assertEqual(s.items, a[2:].items) - - def test_insert(self): - a_list = self.a_list[:] - a_list.insert(2, 'Q') - a_list[4:4] = self.b_list - a = self.a[:] - self.assert_(isinstance(a, statemachine.ViewList)) - a.insert(2, 'Q', 'runtime') - a.insert(4, self.b) - self.assertEqual(a, a_list) - self.assertEqual(a.info(2), ('runtime', 0)) - self.assertEqual(a.info(5), ('b', 1)) - - def test_append(self): - a_list = self.a_list[:] - a_list.append('Q') - a_list.extend(self.b_list) - a = statemachine.ViewList(self.a) - a.append('Q', 'runtime') - a.append(self.b) - self.assertEqual(a, a_list) - self.assertEqual(a.info(len(self.a)), ('runtime', 0)) - self.assertEqual(a.info(-2), ('b', len(self.b) - 2)) - - def test_extend(self): - a_list = self.a_list[:] - a_list.extend(self.b_list) - a = statemachine.ViewList(self.a) - a.extend(self.b) - self.assertEqual(a, a_list) - self.assertEqual(a.info(len(self.a) + 1), ('b', 1)) - - def test_view(self): - a = statemachine.ViewList(self.a[:]) - a.insert(4, self.b) - s = a[2:-2] - s.insert(5, self.c) - self.assertEqual(s, a[2:-2]) - self.assertEqual(s.items, a[2:-2].items) - s.pop() - self.assertEqual(s, a[2:-2]) - self.assertEqual(s.items, a[2:-2].items) - s.remove('X') - self.assertEqual(s, a[2:-2]) - self.assertEqual(s.items, a[2:-2].items) - - def test_trim(self): - a = statemachine.ViewList(self.a[:]) - s = a[1:-1] - s.trim_start(1) - self.assertEquals(a, self.a) - self.assertEquals(s, a[2:-1]) - s.trim_end(1) - self.assertEquals(a, self.a) - self.assertEquals(s, a[2:-2]) - - -# print -# print a -# print s -# print a.items -# print s.items - - -class StringList(unittest.TestCase): - - text = """\ -This is some -example text. - - Here is some - indented text. - -Unindented text. -""" - - indented_string = """\ - a - literal - block""" - - - def setUp(self): - self.a_list = self.text.splitlines(1) - self.a = statemachine.StringList(self.a_list, 'a') - - def test_trim_left(self): - s = self.a[3:5] - s.trim_left(4) - self.assertEqual(s, [line.lstrip() for line in self.a_list[3:5]]) - - def test_get_indented(self): - self.assertEquals(self.a.get_indented(), - ([], 0, 0)) - block = statemachine.StringList( - statemachine.string2lines(self.indented_string)) - self.assertEquals(block.get_indented(), - ([s[6:] for s in block], 6, 1)) - - -if __name__ == '__main__': - unittest.main() diff --git a/docutils/test/test_writers/__init__.py b/docutils/test/test_writers/__init__.py deleted file mode 100644 index 46fc50e06..000000000 --- a/docutils/test/test_writers/__init__.py +++ /dev/null @@ -1,14 +0,0 @@ -import os -import os.path -import sys - -sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) -prev = '' -while sys.path[0] != prev: - try: - import DocutilsTestSupport - break - except ImportError: - prev = sys.path[0] - sys.path[0] = os.path.dirname(prev) -sys.path.pop(0) diff --git a/docutils/test/test_writers/test_docutils_xml.py b/docutils/test/test_writers/test_docutils_xml.py deleted file mode 100755 index c51d71379..000000000 --- a/docutils/test/test_writers/test_docutils_xml.py +++ /dev/null @@ -1,86 +0,0 @@ -#!/usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test for docutils XML writer. -""" - -from __init__ import DocutilsTestSupport - -import docutils -import docutils.core - - -class DocutilsXMLTestCase(DocutilsTestSupport.StandardTestCase): - - input = """\ -Test - ----------- - -Test. \xc3\xa4\xc3\xb6\xc3\xbc\xe2\x82\xac""" - xmldecl = '<?xml version="1.0" encoding="iso-8859-1"?>\n' - doctypedecl = '<!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML" "http://docutils.sourceforge.net/docs/ref/docutils.dtd">\n' - generatedby = '<!-- Generated by Docutils %s -->\n' % docutils.__version__ - bodynormal = '<document source="<string>"><paragraph>Test</paragraph><transition/><paragraph>Test. \xe4\xf6\xfc€</paragraph></document>' - bodynewlines = """\ -<document source="<string>"> -<paragraph> -Test -</paragraph> -<transition/> -<paragraph> -Test. \xe4\xf6\xfc€ -</paragraph> -</document> -""" - bodyindents = """\ -<document source="<string>"> - <paragraph> - Test - </paragraph> - <transition/> - <paragraph> - Test. \xe4\xf6\xfc€ - </paragraph> -</document> -""" - - def test_publish(self): - settings = {'input_encoding': 'utf8', - 'output_encoding': 'iso-8859-1', - '_disable_config': 1} - for settings['newlines'] in 0, 1: - for settings['indents'] in 0, 1: - for settings['xml_declaration'] in 0, 1: - for settings['doctype_declaration'] in 0, 1: - - expected = '' - if settings['xml_declaration']: - expected += self.xmldecl - if settings['doctype_declaration']: - expected += self.doctypedecl - expected += self.generatedby - if settings['indents']: - expected += self.bodyindents - elif settings['newlines']: - expected += self.bodynewlines - else: - expected += self.bodynormal - - self.assertEqual(docutils.core.publish_string - (source=self.input, - reader_name='standalone', - writer_name='docutils_xml', - settings_overrides=settings), - expected) - - -if __name__ == '__main__': - import unittest - unittest.main() diff --git a/docutils/test/test_writers/test_html4css1.py b/docutils/test/test_writers/test_html4css1.py deleted file mode 100755 index 7d87ee324..000000000 --- a/docutils/test/test_writers/test_html4css1.py +++ /dev/null @@ -1,373 +0,0 @@ -#! /usr/bin/env python - -# Author: reggie dugard -# Contact: reggie@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test for fragment code in HTML writer. - -Note: the 'body' and 'whole' entries have been removed from the parts -dictionaries (redundant), along with 'meta' and 'stylesheet' entries with -standard values, and any entries with empty values. -""" - -from __init__ import DocutilsTestSupport -from docutils import core - -def suite(): - s = DocutilsTestSupport.HtmlPublishPartsTestSuite() - s.generateTests(totest) - return s - - -totest = {} - -totest['Title promotion'] = ({'stylesheet_path': '', - 'embed_stylesheet': 0}, [ -["""\ -Simple String -""", -"""\ -{'fragment': '''<p>Simple String</p>\\n''', - 'html_body': '''<div class="document"> -<p>Simple String</p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -Simple String with *markup* -""", -"""\ -{'fragment': '''<p>Simple String with <em>markup</em></p>\\n''', - 'html_body': '''<div class="document"> -<p>Simple String with <em>markup</em></p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -Simple String with an even simpler ``inline literal`` -""", -"""\ -{'fragment': '''<p>Simple String with an even simpler <tt class="docutils literal"><span class="pre">inline</span> <span class="pre">literal</span></tt></p>\\n''', - 'html_body': '''<div class="document"> -<p>Simple String with an even simpler <tt class="docutils literal"><span class="pre">inline</span> <span class="pre">literal</span></tt></p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -A simple `anonymous reference`__ - -__ http://www.test.com/test_url -""", -"""\ -{'fragment': '''<p>A simple <a class="reference" href="http://www.test.com/test_url">anonymous reference</a></p>\\n''', - 'html_body': '''<div class="document"> -<p>A simple <a class="reference" href="http://www.test.com/test_url">anonymous reference</a></p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -One paragraph. - -Two paragraphs. -""", -"""\ -{'fragment': '''<p>One paragraph.</p> -<p>Two paragraphs.</p>\\n''', - 'html_body': '''<div class="document"> -<p>One paragraph.</p> -<p>Two paragraphs.</p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -A simple `named reference`_ with stuff in between the -reference and the target. - -.. _`named reference`: http://www.test.com/test_url -""", -"""\ -{'fragment': '''<p>A simple <a class="reference" href="http://www.test.com/test_url">named reference</a> with stuff in between the -reference and the target.</p>\\n''', - 'html_body': '''<div class="document"> -<p>A simple <a class="reference" href="http://www.test.com/test_url">named reference</a> with stuff in between the -reference and the target.</p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -+++++ -Title -+++++ - -Subtitle -======== - -Some stuff - -Section -------- - -Some more stuff - -Another Section -............... - -And even more stuff -""", -"""\ -{'fragment': '''<p>Some stuff</p> -<div class="section"> -<h1><a id="section" name="section">Section</a></h1> -<p>Some more stuff</p> -<div class="section"> -<h2><a id="another-section" name="another-section">Another Section</a></h2> -<p>And even more stuff</p> -</div> -</div>\\n''', - 'html_body': '''<div class="document" id="title"> -<h1 class="title">Title</h1> -<h2 class="subtitle" id="subtitle">Subtitle</h2> -<p>Some stuff</p> -<div class="section"> -<h1><a id="section" name="section">Section</a></h1> -<p>Some more stuff</p> -<div class="section"> -<h2><a id="another-section" name="another-section">Another Section</a></h2> -<p>And even more stuff</p> -</div> -</div> -</div>\\n''', - 'html_head': '''...<title>Title</title>\\n''', - 'html_subtitle': '''<h2 class="subtitle" id="subtitle">Subtitle</h2>\\n''', - 'html_title': '''<h1 class="title">Title</h1>\\n''', - 'subtitle': '''Subtitle''', - 'title': '''Title'''} -"""], -["""\ -+++++ -Title -+++++ - -:author: me - -Some stuff -""", -"""\ -{'docinfo': '''<table class="docinfo" frame="void" rules="none"> -<col class="docinfo-name" /> -<col class="docinfo-content" /> -<tbody valign="top"> -<tr><th class="docinfo-name">Author:</th> -<td>me</td></tr> -</tbody> -</table>\\n''', - 'fragment': '''<p>Some stuff</p>\\n''', - 'html_body': '''<div class="document" id="title"> -<h1 class="title">Title</h1> -<table class="docinfo" frame="void" rules="none"> -<col class="docinfo-name" /> -<col class="docinfo-content" /> -<tbody valign="top"> -<tr><th class="docinfo-name">Author:</th> -<td>me</td></tr> -</tbody> -</table> -<p>Some stuff</p> -</div>\\n''', - 'html_head': '''...<title>Title</title> -<meta name="author" content="me" />\\n''', - 'html_title': '''<h1 class="title">Title</h1>\\n''', - 'meta': '''<meta name="author" content="me" />\\n''', - 'title': '''Title'''} -"""] -]) - -totest['No title promotion'] = ({'doctitle_xform' : 0, - 'stylesheet_path': '', - 'embed_stylesheet': 0}, [ -["""\ -Simple String -""", -"""\ -{'fragment': '''<p>Simple String</p>\\n''', - 'html_body': '''<div class="document"> -<p>Simple String</p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -Simple String with *markup* -""", -"""\ -{'fragment': '''<p>Simple String with <em>markup</em></p>\\n''', - 'html_body': '''<div class="document"> -<p>Simple String with <em>markup</em></p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -Simple String with an even simpler ``inline literal`` -""", -"""\ -{'fragment': '''<p>Simple String with an even simpler <tt class="docutils literal"><span class="pre">inline</span> <span class="pre">literal</span></tt></p>\\n''', - 'html_body': '''<div class="document"> -<p>Simple String with an even simpler <tt class="docutils literal"><span class="pre">inline</span> <span class="pre">literal</span></tt></p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -A simple `anonymous reference`__ - -__ http://www.test.com/test_url -""", -"""\ -{'fragment': '''<p>A simple <a class="reference" href="http://www.test.com/test_url">anonymous reference</a></p>\\n''', - 'html_body': '''<div class="document"> -<p>A simple <a class="reference" href="http://www.test.com/test_url">anonymous reference</a></p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -A simple `named reference`_ with stuff in between the -reference and the target. - -.. _`named reference`: http://www.test.com/test_url -""", -"""\ -{'fragment': '''<p>A simple <a class="reference" href="http://www.test.com/test_url">named reference</a> with stuff in between the -reference and the target.</p>\\n''', - 'html_body': '''<div class="document"> -<p>A simple <a class="reference" href="http://www.test.com/test_url">named reference</a> with stuff in between the -reference and the target.</p> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -+++++ -Title -+++++ - -Not A Subtitle -============== - -Some stuff - -Section -------- - -Some more stuff - -Another Section -............... - -And even more stuff -""", -"""\ -{'fragment': '''<div class="section"> -<h1><a id="title" name="title">Title</a></h1> -<div class="section"> -<h2><a id="not-a-subtitle" name="not-a-subtitle">Not A Subtitle</a></h2> -<p>Some stuff</p> -<div class="section"> -<h3><a id="section" name="section">Section</a></h3> -<p>Some more stuff</p> -<div class="section"> -<h4><a id="another-section" name="another-section">Another Section</a></h4> -<p>And even more stuff</p> -</div> -</div> -</div> -</div>\\n''', - 'html_body': '''<div class="document"> -<div class="section"> -<h1><a id="title" name="title">Title</a></h1> -<div class="section"> -<h2><a id="not-a-subtitle" name="not-a-subtitle">Not A Subtitle</a></h2> -<p>Some stuff</p> -<div class="section"> -<h3><a id="section" name="section">Section</a></h3> -<p>Some more stuff</p> -<div class="section"> -<h4><a id="another-section" name="another-section">Another Section</a></h4> -<p>And even more stuff</p> -</div> -</div> -</div> -</div> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -* bullet -* list -""", -"""\ -{'fragment': '''<ul class="simple"> -<li>bullet</li> -<li>list</li> -</ul>\\n''', - 'html_body': '''<div class="document"> -<ul class="simple"> -<li>bullet</li> -<li>list</li> -</ul> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -["""\ -Not a docinfo. - -:This: .. _target: - - is -:a: -:simple: -:field: list -""", -"""\ -{'fragment': '''<p>Not a docinfo.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field"><th class="field-name">This:</th><td class="field-body"><p class="first last" id="target">is</p> -</td> -</tr> -<tr class="field"><th class="field-name">a:</th><td class="field-body"></td> -</tr> -<tr class="field"><th class="field-name">simple:</th><td class="field-body"></td> -</tr> -<tr class="field"><th class="field-name">field:</th><td class="field-body">list</td> -</tr> -</tbody> -</table>\\n''', - 'html_body': '''<div class="document"> -<p>Not a docinfo.</p> -<table class="docutils field-list" frame="void" rules="none"> -<col class="field-name" /> -<col class="field-body" /> -<tbody valign="top"> -<tr class="field"><th class="field-name">This:</th><td class="field-body"><p class="first last" id="target">is</p> -</td> -</tr> -<tr class="field"><th class="field-name">a:</th><td class="field-body"></td> -</tr> -<tr class="field"><th class="field-name">simple:</th><td class="field-body"></td> -</tr> -<tr class="field"><th class="field-name">field:</th><td class="field-body">list</td> -</tr> -</tbody> -</table> -</div>\\n''', - 'html_head': '''...<title></title>\\n'''} -"""], -]) - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_writers/test_html4css1_misc.py b/docutils/test/test_writers/test_html4css1_misc.py deleted file mode 100755 index 8b63d6f1c..000000000 --- a/docutils/test/test_writers/test_html4css1_misc.py +++ /dev/null @@ -1,36 +0,0 @@ -#! /usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Miscellaneous HTML writer tests. -""" - -from __init__ import DocutilsTestSupport -from docutils import core - - -class EncodingTestCase(DocutilsTestSupport.StandardTestCase): - - def test_xmlcharrefreplace(self): - # Test that xmlcharrefreplace is the default output encoding - # error handler. - settings_overrides={ - 'output_encoding': 'latin1', - 'stylesheet': '', - '_disable_config': 1,} - result = core.publish_string( - 'EUR = \xe2\x82\xac', writer_name='html4css1', - settings_overrides=settings_overrides) - # Encoding a euro sign with latin1 doesn't work, so the - # xmlcharrefreplcae handler is used. - self.assert_(result.find('EUR = €') != -1) - - -if __name__ == '__main__': - import unittest - unittest.main() diff --git a/docutils/test/test_writers/test_latex2e.py b/docutils/test/test_writers/test_latex2e.py deleted file mode 100755 index 04448883a..000000000 --- a/docutils/test/test_writers/test_latex2e.py +++ /dev/null @@ -1,377 +0,0 @@ -#! /usr/bin/env python - -# Author: engelbert gruber -# Contact: grubert@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for latex2e writer. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.PublishTestSuite('latex') - s.generateTests(totest) - return s - - -latex_head = """\ -\\documentclass[10pt,a4paper,english]{article} -\\usepackage{babel} -\\usepackage{ae} -\\usepackage{aeguill} -\\usepackage{shortvrb} -\\usepackage[latin1]{inputenc} -\\usepackage{tabularx} -\\usepackage{longtable} -\\setlength{\\extrarowheight}{2pt} -\\usepackage{amsmath} -\\usepackage{graphicx} -\\usepackage{color} -\\usepackage{multirow} -\\usepackage{ifthen} -\\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} -\\usepackage[DIV12]{typearea} -%% generator Docutils: http://docutils.sourceforge.net/ -\\newlength{\\admonitionwidth} -\\setlength{\\admonitionwidth}{0.9\\textwidth} -\\newlength{\\docinfowidth} -\\setlength{\\docinfowidth}{0.9\\textwidth} -\\newlength{\\locallinewidth} -\\newcommand{\\optionlistlabel}[1]{\\bf #1 \\hfill} -\\newenvironment{optionlist}[1] -{\\begin{list}{} - {\\setlength{\\labelwidth}{#1} - \\setlength{\\rightmargin}{1cm} - \\setlength{\\leftmargin}{\\rightmargin} - \\addtolength{\\leftmargin}{\\labelwidth} - \\addtolength{\\leftmargin}{\\labelsep} - \\renewcommand{\\makelabel}{\\optionlistlabel}} -}{\\end{list}} -\\newlength{\\lineblockindentation} -\\setlength{\\lineblockindentation}{2.5em} -\\newenvironment{lineblock}[1] -{\\begin{list}{} - {\\setlength{\\partopsep}{\\parskip} - \\addtolength{\\partopsep}{\\baselineskip} - \\topsep0pt\\itemsep0.15\\baselineskip\\parsep0pt - \\leftmargin#1} - \\raggedright} -{\\end{list}} -% begin: floats for footnotes tweaking. -\\setlength{\\floatsep}{0.5em} -\\setlength{\\textfloatsep}{\\fill} -\\addtolength{\\textfloatsep}{3em} -\\renewcommand{\\textfraction}{0.5} -\\renewcommand{\\topfraction}{0.5} -\\renewcommand{\\bottomfraction}{0.5} -\\setcounter{totalnumber}{50} -\\setcounter{topnumber}{50} -\\setcounter{bottomnumber}{50} -% end floats for footnotes -% some commands, that could be overwritten in the style file. -\\newcommand{\\rubric}[1]{\\subsection*{~\\hfill {\\it #1} \\hfill ~}} -\\newcommand{\\titlereference}[1]{\\textsl{#1}} -% end of "some commands" -""" - -totest = {} - -totest['table_of_contents'] = [ -# input -["""\ -.. contents:: Table of Contents - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. -""", -## # expected output -latex_head + """\ -\\title{} -\\author{} -\\date{} -\\raggedbottom -\\begin{document} - -\\setlength{\\locallinewidth}{\\linewidth} -\\hypertarget{table-of-contents}{} -\\pdfbookmark[0]{Table of Contents}{table-of-contents} -\\subsubsection*{~\\hfill Table of Contents\\hfill ~} -\\begin{list}{}{} -\\item {} \\href{\\#title-1}{Title 1} -\\begin{list}{}{} -\\item {} \\href{\#title-2}{Title 2} - -\\end{list} - -\\end{list} - - - -%___________________________________________________________________________ - -\\hypertarget{title-1}{} -\\pdfbookmark[0]{Title 1}{title-1} -\\section*{Title 1} - -Paragraph 1. - - -%___________________________________________________________________________ - -\\hypertarget{title-2}{} -\\pdfbookmark[1]{Title 2}{title-2} -\\subsection*{Title 2} - -Paragraph 2. - -\\end{document} -"""], - -] - - -totest['enumerated_lists'] = [ -# input -["""\ -1. Item 1. -2. Second to the previous item this one will explain - - a) nothing. - b) or some other. - -3. Third is - - (I) having pre and postfixes - (II) in roman numerals. -""", -# expected output -latex_head + """\ -\\title{} -\\author{} -\\date{} -\\raggedbottom -\\begin{document} - -\\setlength{\\locallinewidth}{\\linewidth} -\\newcounter{listcnt1} -\\begin{list}{\\arabic{listcnt1}.} -{ -\\usecounter{listcnt1} -\\setlength{\\rightmargin}{\\leftmargin} -} -\\item {} -Item 1. - -\\item {} -Second to the previous item this one will explain - -\\end{list} -\\begin{quote} -\\newcounter{listcnt2} -\\begin{list}{\\alph{listcnt2})} -{ -\\usecounter{listcnt2} -\\setlength{\\rightmargin}{\\leftmargin} -} -\\item {} -nothing. - -\\item {} -or some other. - -\\end{list} -\\end{quote} -\\newcounter{listcnt3} -\\begin{list}{\\arabic{listcnt3}.} -{ -\\usecounter{listcnt3} -\\addtocounter{listcnt3}{2} -\\setlength{\\rightmargin}{\\leftmargin} -} -\\item {} -Third is - -\\end{list} -\\begin{quote} -\\newcounter{listcnt4} -\\begin{list}{(\\Roman{listcnt4})} -{ -\\usecounter{listcnt4} -\\setlength{\\rightmargin}{\\leftmargin} -} -\\item {} -having pre and postfixes - -\\item {} -in roman numerals. - -\\end{list} -\\end{quote} - -\\end{document} -"""], -] - -# BUG: need to test for quote replacing if language is de (ngerman). - -totest['quote_mangling'] = [ -# input -["""\ -Depending on language quotes are converted for latex. -Expecting "en" here. - -Inside literal blocks quotes should be left untouched -(use only two quotes in test code makes life easier for -the python interpreter running the test):: - - "" - This is left "untouched" also *this*. - "" - -.. parsed-literal:: - - should get "quotes" and *italics*. - - -Inline ``literal "quotes"`` should be kept. -""", -latex_head + """\ -\\title{} -\\author{} -\\date{} -\\raggedbottom -\\begin{document} - -\\setlength{\\locallinewidth}{\\linewidth} - -Depending on language quotes are converted for latex. -Expecting ``en'' here. - -Inside literal blocks quotes should be left untouched -(use only two quotes in test code makes life easier for -the python interpreter running the test): -\\begin{quote}{\\ttfamily \\raggedright \\noindent -"{}"~\\\\ -This~is~left~"untouched"~also~*this*.~\\\\ -"{}" -}\\end{quote} -\\begin{quote}{\\ttfamily \\raggedright \\noindent -should~get~"quotes"~and~\\emph{italics}. -}\\end{quote} - -Inline \\texttt{literal "quotes"} should be kept. - -\\end{document} -"""], -] - -totest['table_caption'] = [ -# input -["""\ -.. table:: Foo - - +-----+-----+ - | | | - +-----+-----+ - | | | - +-----+-----+ -""", -latex_head + """\ -\\title{} -\\author{} -\\date{} -\\raggedbottom -\\begin{document} - -\\setlength{\\locallinewidth}{\\linewidth} - -\\begin{longtable}[c]{|p{0.07\locallinewidth}|p{0.07\locallinewidth}|} -\\caption{Foo}\\\\ -\\hline - & \\\\ -\hline - & \\\\ -\hline -\\end{longtable} - -\\end{document} -"""], -] - -# In "\\\n[" the "[" needs to be protected (otherwise it will be seen as an option to "\\"). -totest['brackett_protection'] = [ -# input -["""\ -:: - - something before to get a end of line. - [ - - the empty line gets tested too - ] -""", -latex_head + """\ -\\title{} -\\author{} -\\date{} -\\raggedbottom -\\begin{document} - -\\setlength{\\locallinewidth}{\\linewidth} -\\begin{quote}{\\ttfamily \\raggedright \\noindent -something~before~to~get~a~end~of~line.~\\\\ -{[}~\\\\ -~\\\\ -the~empty~line~gets~tested~too~\\\\ -{]} -}\\end{quote} - -\\end{document} -"""], -] - -totest['raw'] = [ -["""\ -.. raw:: latex - - \\noindent - -A paragraph. - -.. |sub| raw:: latex - - (some raw text) - -Foo |sub| -same paragraph. -""", -latex_head + """\ -\\title{} -\\author{} -\\date{} -\\raggedbottom -\\begin{document} - -\\setlength{\\locallinewidth}{\\linewidth} -\\noindent -A paragraph. - -Foo (some raw text) -same paragraph. - -\\end{document} -"""], -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_writers/test_null.py b/docutils/test/test_writers/test_null.py deleted file mode 100755 index da385e565..000000000 --- a/docutils/test/test_writers/test_null.py +++ /dev/null @@ -1,31 +0,0 @@ -#!/usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test for Null writer. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.PublishTestSuite('null') - s.generateTests(totest) - return s - -totest = {} - -totest['basic'] = [ -["""\ -This is a paragraph. -""", -None] -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_writers/test_pseudoxml.py b/docutils/test/test_writers/test_pseudoxml.py deleted file mode 100755 index db8bed7cb..000000000 --- a/docutils/test/test_writers/test_pseudoxml.py +++ /dev/null @@ -1,54 +0,0 @@ -#!/usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Test for pseudo-XML writer. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.PublishTestSuite('pseudoxml') - s.generateTests(totest) - return s - -totest = {} - -totest['basic'] = [ -# input -["""\ -This is a paragraph. - ----------- - -This is another paragraph. - -A Section ---------- - -Foo. -""", -# output -"""\ -<document source="<string>"> - <paragraph> - This is a paragraph. - <transition> - <paragraph> - This is another paragraph. - <section ids="a-section" names="a\ section"> - <title> - A Section - <paragraph> - Foo. -"""] -] - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/tools/buildhtml.py b/docutils/tools/buildhtml.py deleted file mode 100755 index e9ee0d16d..000000000 --- a/docutils/tools/buildhtml.py +++ /dev/null @@ -1,226 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Generates .html from all the .txt files in a directory. - -Ordinary .txt files are understood to be standalone reStructuredText. -Files named ``pep-*.txt`` are interpreted as reStructuredText PEPs. -""" -# Once PySource is here, build .html from .py as well. - -__docformat__ = 'reStructuredText' - - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -import sys -import os -import os.path -import copy -import docutils -from docutils import ApplicationError -from docutils import core, frontend -from docutils.parsers import rst -from docutils.readers import standalone, pep -from docutils.writers import html4css1, pep_html - - -usage = '%prog [options] [<directory> ...]' -description = ('Generates .html from all the reStructuredText .txt files ' - '(including PEPs) in each <directory> ' - '(default is the current directory).') - - -class SettingsSpec(docutils.SettingsSpec): - - """ - Runtime settings & command-line options for the front end. - """ - - # Can't be included in OptionParser below because we don't want to - # override the base class. - settings_spec = ( - 'Build-HTML Options', - None, - (('Recursively scan subdirectories for files to process. This is ' - 'the default.', - ['--recurse'], - {'action': 'store_true', 'default': 1, - 'validator': frontend.validate_boolean}), - ('Do not scan subdirectories for files to process.', - ['--local'], {'dest': 'recurse', 'action': 'store_false'}), - ('Do not process files in <directory>. This option may be used ' - 'more than once to specify multiple directories.', - ['--prune'], - {'metavar': '<directory>', 'action': 'append', - 'validator': frontend.validate_colon_separated_string_list}), - ('Work silently (no progress messages). Independent of "--quiet".', - ['--silent'], - {'action': 'store_true', 'validator': frontend.validate_boolean}),)) - - relative_path_settings = ('prune',) - config_section = 'buildhtml application' - config_section_dependencies = ('applications',) - - -class OptionParser(frontend.OptionParser): - - """ - Command-line option processing for the ``buildhtml.py`` front end. - """ - - def check_values(self, values, args): - frontend.OptionParser.check_values(self, values, args) - values._source = None - return values - - def check_args(self, args): - source = destination = None - if args: - self.values._directories = args - else: - self.values._directories = [os.getcwd()] - return source, destination - - -class Struct: - - """Stores data attributes for dotted-attribute access.""" - - def __init__(self, **keywordargs): - self.__dict__.update(keywordargs) - - -class Builder: - - def __init__(self): - self.publishers = { - '': Struct(components=(pep.Reader, rst.Parser, pep_html.Writer, - SettingsSpec)), - '.txt': Struct(components=(rst.Parser, standalone.Reader, - html4css1.Writer, SettingsSpec), - reader_name='standalone', - writer_name='html'), - 'PEPs': Struct(components=(rst.Parser, pep.Reader, - pep_html.Writer, SettingsSpec), - reader_name='pep', - writer_name='pep_html')} - """Publisher-specific settings. Key '' is for the front-end script - itself. ``self.publishers[''].components`` must contain a superset of - all components used by individual publishers.""" - - self.setup_publishers() - - def setup_publishers(self): - """ - Manage configurations for individual publishers. - - Each publisher (combination of parser, reader, and writer) may have - its own configuration defaults, which must be kept separate from those - of the other publishers. Setting defaults are combined with the - config file settings and command-line options by - `self.get_settings()`. - """ - for name, publisher in self.publishers.items(): - option_parser = OptionParser( - components=publisher.components, read_config_files=1, - usage=usage, description=description) - publisher.option_parser = option_parser - publisher.setting_defaults = option_parser.get_default_values() - frontend.make_paths_absolute(publisher.setting_defaults.__dict__, - option_parser.relative_path_settings) - publisher.config_settings = ( - option_parser.get_standard_config_settings()) - self.settings_spec = self.publishers[''].option_parser.parse_args( - values=frontend.Values()) # no defaults; just the cmdline opts - self.initial_settings = self.get_settings('') - - def get_settings(self, publisher_name, directory=None): - """ - Return a settings object, from multiple sources. - - Copy the setting defaults, overlay the startup config file settings, - then the local config file settings, then the command-line options. - Assumes the current directory has been set. - """ - publisher = self.publishers[publisher_name] - settings = frontend.Values(publisher.setting_defaults.__dict__) - settings.update(publisher.config_settings, publisher.option_parser) - if directory: - local_config = publisher.option_parser.get_config_file_settings( - os.path.join(directory, 'docutils.conf')) - frontend.make_paths_absolute( - local_config, publisher.option_parser.relative_path_settings, - directory) - settings.update(local_config, publisher.option_parser) - settings.update(self.settings_spec.__dict__, publisher.option_parser) - return settings - - def run(self, directory=None, recurse=1): - recurse = recurse and self.initial_settings.recurse - if directory: - self.directories = [directory] - elif self.settings_spec._directories: - self.directories = self.settings_spec._directories - else: - self.directories = [os.getcwd()] - for directory in self.directories: - os.path.walk(directory, self.visit, recurse) - - def visit(self, recurse, directory, names): - settings = self.get_settings('', directory) - if settings.prune and (os.path.abspath(directory) in settings.prune): - print >>sys.stderr, '/// ...Skipping directory (pruned):', directory - sys.stderr.flush() - names[:] = [] - return - if not self.initial_settings.silent: - print >>sys.stderr, '/// Processing directory:', directory - sys.stderr.flush() - prune = 0 - for name in names: - if name.endswith('.txt'): - prune = self.process_txt(directory, name) - if prune: - break - if not recurse: - del names[:] - - def process_txt(self, directory, name): - if name.startswith('pep-'): - publisher = 'PEPs' - else: - publisher = '.txt' - settings = self.get_settings(publisher, directory) - pub_struct = self.publishers[publisher] - if settings.prune and (directory in settings.prune): - return 1 - settings._source = os.path.normpath(os.path.join(directory, name)) - settings._destination = settings._source[:-4]+'.html' - if not self.initial_settings.silent: - print >>sys.stderr, ' ::: Processing:', name - sys.stderr.flush() - try: - core.publish_file(source_path=settings._source, - destination_path=settings._destination, - reader_name=pub_struct.reader_name, - parser_name='restructuredtext', - writer_name=pub_struct.writer_name, - settings=settings) - except ApplicationError, error: - print >>sys.stderr, (' Error (%s): %s' - % (error.__class__.__name__, error)) - - -if __name__ == "__main__": - Builder().run() diff --git a/docutils/tools/dev/README.txt b/docutils/tools/dev/README.txt deleted file mode 100644 index ca9e99ee8..000000000 --- a/docutils/tools/dev/README.txt +++ /dev/null @@ -1 +0,0 @@ -Tools for developers. diff --git a/docutils/tools/dev/create_unimap.py b/docutils/tools/dev/create_unimap.py deleted file mode 100755 index 1d1a2f8a0..000000000 --- a/docutils/tools/dev/create_unimap.py +++ /dev/null @@ -1,82 +0,0 @@ -#!/usr/bin/env python - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This file has been placed in the public domain. - -# Call: create_unimap.py < unicode.xml > unicode_latex.py -# -# Get unicode.xml from -# <http://www.w3.org/2003/entities/xml/unicode.xml>. - -from xml.dom import minidom -import sys -import pprint - -def w(s): - if isinstance(s, unicode): - s = s.encode('utf8') - sys.stdout.write(s) - -text_map = {} -math_map = {} - -class Visitor: - - """Node visitor for contents of unicode.xml.""" - - def visit_character(self, node): - for n in node.childNodes: - if n.nodeName == 'latex': - code = node.attributes['dec'].value - if '-' in code: - # I don't know what this means, but we probably - # don't need it.... - continue - if int(code) < 128: - # Wrong (maps "-" to "$-$", which is too wide) and - # unnecessary (maps "a" to "{a}"). - continue - latex_code = n.childNodes[0].nodeValue.encode('ascii').strip() - if node.attributes['mode'].value == 'math': - math_map[unichr(int(code))] = '$%s$' % latex_code - else: - text_map[unichr(int(code))] = '{%s}' % latex_code - -def call_visitor(node, visitor=Visitor()): - if isinstance(node, minidom.Text): - name = 'Text' - else: - name = node.nodeName.replace('#', '_') - if hasattr(visitor, 'visit_' + name): - getattr(visitor, 'visit_' + name)(node) - for child in node.childNodes: - call_visitor(child) - if hasattr(visitor, 'depart_' + name): - getattr(visitor, 'depart_' + name)(node) - -document = minidom.parse(sys.stdin) -call_visitor(document) - -unicode_map = math_map -unicode_map.update(text_map) -# Now unicode_map contains the text entries plus dollar-enclosed math -# entries for those chars for which no text entry exists. - -print '# Author: Felix Wiemann' -print '# Contact: Felix_Wiemann@ososo.de' -print '# Revision: $%s$' % 'Revision' -print '# Date: $%s$' % 'Date' -print '# Copyright: This file has been placed in the public domain.' -print -print '# This is a mapping of Unicode characters to LaTeX equivalents.' -print '# The information has been extracted from' -print '# <http://www.w3.org/2003/entities/xml/unicode.xml>, written by' -print '# David Carlisle and Sebastian Rahtz.' -print '#' -print '# The extraction has been done by the "create_unimap.py" script' -print '# located at <http://docutils.sf.net/tools/dev/create_unimap.py>.' -print -print 'unicode_map = %s' % pprint.pformat(unicode_map, indent=0) diff --git a/docutils/tools/dev/profile_docutils.py b/docutils/tools/dev/profile_docutils.py deleted file mode 100755 index 1f79c655e..000000000 --- a/docutils/tools/dev/profile_docutils.py +++ /dev/null @@ -1,41 +0,0 @@ -#!/usr/bin/python -i - -# Author: Felix Wiemann -# Contact: Felix_Wiemann@ososo.de -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This script has been placed in the public domain. - -import os.path -import docutils.core -import hotshot.stats - -print 'Profiler started.' - -os.chdir(os.path.join(os.path.dirname(docutils.__file__), '..')) - -print 'Profiling...' - -prof = hotshot.Profile('docutils.prof') -prof.runcall(docutils.core.publish_file, source_path='HISTORY.txt', - destination_path='prof.HISTORY.html', writer_name='html') -prof.close() - -print 'Loading statistics...' - -print """ -stats = hotshot.stats.load('docutils.prof') -stats.strip_dirs() -stats.sort_stats('time') # 'cumulative'; 'calls' -stats.print_stats(40) -""" - -stats = hotshot.stats.load('docutils.prof') -stats.strip_dirs() -stats.sort_stats('time') -stats.print_stats(40) - -try: - execfile(os.environ['PYTHONSTARTUP']) -except: - pass diff --git a/docutils/tools/dev/unicode2rstsubs.py b/docutils/tools/dev/unicode2rstsubs.py deleted file mode 100755 index abc85e48b..000000000 --- a/docutils/tools/dev/unicode2rstsubs.py +++ /dev/null @@ -1,204 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This program has been placed in the public domain. - -""" -unicode2subfiles.py -- produce character entity files (reSructuredText -substitutions) from the W3C master unicode.xml file. - -This program extracts character entity and entity set information from a -unicode.xml file and produces multiple reStructuredText files (in the current -directory) containing substitutions. Entity sets are from ISO 8879 & ISO -9573-13 (combined), MathML, and HTML4. One or two files are produced for each -entity set; a second file with a "-wide.txt" suffix is produced if there are -wide-Unicode characters in the set. - -The input file, unicode.xml, is maintained as part of the MathML 2 -Recommentation XML source, and is available from -<http://www.w3.org/2003/entities/xml/>. -""" - -import sys -import os -import optparse -import re -from xml.parsers.expat import ParserCreate - - -usage_msg = """Usage: %s [unicode.xml]""" - -def usage(prog, status=0, msg=None): - print >>sys.stderr, usage_msg % prog - if msg: - print >>sys.stderr, msg - sys.exit(status) - -def main(argv=None): - if argv is None: - argv = sys.argv - if len(argv) == 2: - inpath = argv[1] - elif len(argv) > 2: - usage(argv[0], 2, - 'Too many arguments (%s): only 1 expected.' % (len(argv) - 1)) - else: - inpath = 'unicode.xml' - if not os.path.isfile(inpath): - usage(argv[0], 1, 'No such file: "%s".' % inpath) - infile = open(inpath) - process(infile) - -def process(infile): - grouper = CharacterEntitySetExtractor(infile) - grouper.group() - grouper.write_sets() - - -class CharacterEntitySetExtractor: - - """ - Extracts character entity information from unicode.xml file, groups it by - entity set, and writes out reStructuredText substitution files. - """ - - unwanted_entity_sets = ['stix', # unknown, buggy set - 'predefined'] - - header = """\ -.. This data file has been placed in the public domain. -.. Derived from the Unicode character mappings available from - <http://www.w3.org/2003/entities/xml/>. - Processed by unicode2rstsubs.py, part of Docutils: - <http://docutils.sourceforge.net>. -""" - - def __init__(self, infile): - self.infile = infile - """Input unicode.xml file.""" - - self.parser = self.setup_parser() - """XML parser.""" - - self.elements = [] - """Stack of element names. Last is current element.""" - - self.sets = {} - """Mapping of charent set name to set dict.""" - - self.charid = None - """Current character's "id" attribute value.""" - - self.descriptions = {} - """Mapping of character ID to description.""" - - def setup_parser(self): - parser = ParserCreate() - parser.StartElementHandler = self.StartElementHandler - parser.EndElementHandler = self.EndElementHandler - parser.CharacterDataHandler = self.CharacterDataHandler - return parser - - def group(self): - self.parser.ParseFile(self.infile) - - def StartElementHandler(self, name, attributes): - self.elements.append(name) - handler = name + '_start' - if hasattr(self, handler): - getattr(self, handler)(name, attributes) - - def EndElementHandler(self, name): - assert self.elements[-1] == name, \ - 'unknown end-tag %r (%r)' % (name, self.element) - self.elements.pop() - handler = name + '_end' - if hasattr(self, handler): - getattr(self, handler)(name) - - def CharacterDataHandler(self, data): - handler = self.elements[-1] + '_data' - if hasattr(self, handler): - getattr(self, handler)(data) - - def character_start(self, name, attributes): - self.charid = attributes['id'] - - def entity_start(self, name, attributes): - set = self.entity_set_name(attributes['set']) - if not set: - return - if not self.sets.has_key(set): - print 'bad set: %r' % set - return - entity = attributes['id'] - assert (not self.sets[set].has_key(entity) - or self.sets[set][entity] == self.charid), \ - ('sets[%r][%r] == %r (!= %r)' - % (set, entity, self.sets[set][entity], self.charid)) - self.sets[set][entity] = self.charid - - def description_data(self, data): - self.descriptions.setdefault(self.charid, '') - self.descriptions[self.charid] += data - - entity_set_name_pat = re.compile(r'[0-9-]*(.+)$') - """Pattern to strip ISO numbers off the beginning of set names.""" - - def entity_set_name(self, name): - """ - Return lowcased and standard-number-free entity set name. - Return ``None`` for unwanted entity sets. - """ - match = self.entity_set_name_pat.match(name) - name = match.group(1).lower() - if name in self.unwanted_entity_sets: - return None - self.sets.setdefault(name, {}) - return name - - def write_sets(self): - sets = self.sets.keys() - sets.sort() - for set_name in sets: - self.write_set(set_name) - - def write_set(self, set_name, wide=None): - if wide: - outname = set_name + '-wide.txt' - else: - outname = set_name + '.txt' - outfile = open(outname, 'w') - print 'writing file "%s"' % outname - print >>outfile, self.header - set = self.sets[set_name] - entities = [(e.lower(), e) for e in set.keys()] - entities.sort() - longest = 0 - for _, entity_name in entities: - longest = max(longest, len(entity_name)) - has_wide = None - for _, entity_name in entities: - has_wide = self.write_entity( - set, set_name, entity_name, outfile, longest, wide) or has_wide - if has_wide and not wide: - self.write_set(set_name, 1) - - def write_entity(self, set, set_name, entity_name, outfile, longest, - wide=None): - charid = set[entity_name] - if not wide: - for code in charid[1:].split('-'): - if int(code, 16) > 0xFFFF: - return 1 # wide-Unicode character - codes = ' '.join(['U+%s' % code for code in charid[1:].split('-')]) - print >>outfile, ('.. %-*s unicode:: %s .. %s' - % (longest + 2, '|' + entity_name + '|', - codes, self.descriptions[charid])) - - -if __name__ == '__main__': - sys.exit(main()) diff --git a/docutils/tools/docutils.conf b/docutils/tools/docutils.conf deleted file mode 100644 index f4bcf8c6c..000000000 --- a/docutils/tools/docutils.conf +++ /dev/null @@ -1,12 +0,0 @@ -# These entries affect all processing: -[general] -source-link: yes -datestamp: %Y-%m-%d %H:%M UTC -generator: on - -# These entries affect HTML output: -[html4css1 writer] -# Required for docutils-update, the website build system: -stylesheet-path: ../docutils/writers/html4css1/html4css1.css -embed-stylesheet: no -field-name-limit: 20 diff --git a/docutils/tools/editors/README.txt b/docutils/tools/editors/README.txt deleted file mode 100644 index 517c0558a..000000000 --- a/docutils/tools/editors/README.txt +++ /dev/null @@ -1,23 +0,0 @@ -====================================== - Editor Support for reStructuredText_ -====================================== - -:Date: $Date$ - -The files in this directory contain support code for reStructuredText -editing for the following editors: - -* `Emacs <emacs>`__ - -External links: - -* `reStructuredText syntax highlighting mode for vim - <http://www.vim.org/scripts/script.php?script_id=973>`__ - -* `rst mode <http://jedmodes.sf.net/mode/rst/>`__ for the `JED`_ - programmers editor - -Additions are welcome. - -.. _reStructuredText: http://docutils.sf.net/rst.html -.. _JED: http://www.jedsoft.org/jed/ diff --git a/docutils/tools/editors/emacs/README.txt b/docutils/tools/editors/emacs/README.txt deleted file mode 100644 index 2c3e32ce5..000000000 --- a/docutils/tools/editors/emacs/README.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. -*- coding: utf-8 -*- - -===================== - Emacs Support Files -===================== - -:Date: $Date$ - -This directory contains the following Emacs lisp package files: - -* rst.el: Emacs support for reStructuredText_. This file contains - - * Section decoration/adornment creation and updating (M. Blais); - * Table-of-contents mode and insertion (M. Blais); - * Font-lock syntax highlighting (S. Merten); - * Some handy editing functions (D. Goodger). - * Some functions for converting documents from emacs (M. Blais). - -* tests subdirectory: automated tests for some of the features in rst.el. - Please make sure the tests pass if you change the LISP code. Just type "make" - to run the tests. - -To install the package, put a copy of the package file in a directory on your -``load-path`` (use ``C-h v load-path`` to check). - -For setup and usage details, see `Emacs Support for reStructuredText -<../../../docs/user/emacs.html>`_. - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html diff --git a/docutils/tools/editors/emacs/docutils.conf b/docutils/tools/editors/emacs/docutils.conf deleted file mode 100644 index a74f08d4a..000000000 --- a/docutils/tools/editors/emacs/docutils.conf +++ /dev/null @@ -1,2 +0,0 @@ -[general] -input_encoding: latin-1 diff --git a/docutils/tools/editors/emacs/rst.el b/docutils/tools/editors/emacs/rst.el deleted file mode 100644 index 88a74e2fe..000000000 --- a/docutils/tools/editors/emacs/rst.el +++ /dev/null @@ -1,2821 +0,0 @@ -;;; ================================================ -;;; rst.el -- ReStructuredText Support for Emacs -;;; ================================================ -;;; -;;; :Authors: Martin Blais <blais@furius.ca>, -;;; Stefan Merten <smerten@oekonux.de>, -;;; David Goodger <goodger@python.org> -;;; :Revision: $Revision$ -;;; :Date: $Date$ -;;; :Copyright: This module has been placed in the public domain. -;;; :Abstract: -;;; -;;; Support code for editing reStructuredText with Emacs. The latest version -;;; of this file lies in the docutils source code repository. -;;; -;;; Description -;;; =========== -;;; -;;; Basically, this package contains: -;;; -;;; - Functions to automatically adjust and cycle the section underline -;;; decorations; -;;; - A mode that displays the table of contents and allows you to jump anywhere -;;; from it; -;;; - Functions to insert and automatically update a TOC in your source -;;; document; -;;; - A mode which supports font-lock highlighting of reStructuredText -;;; structures; -;;; - Some other convenience functions. -;;; -;;; See the accompanying document in the docutils documentation about -;;; the contents of this package and how to use it. -;;; -;;; For more information about reStructuredText, see -;;; http://docutils.sourceforge.net/rst.html -;;; -;;; For full details on how to use the contents of this file, see -;;; http://docutils.sourceforge.net/docs/user/emacs.html -;;; -;;; Download -;;; ======== -;;; -;;; Click `Here <rst.el>`_ for download. -;;; -;;; END -;; -;; **IMPORTANT NOTE TO PACKAGERS**: this package is the result of merging: -;; -;; - restructuredtext.el -;; - rst-mode.el -;; - rst-html.el -;; -;; Those files are now OBSOLETE and have been replaced by this single package -;; file (2005-10-30). -;; -;; Installation instructions -;; ------------------------- -;; -;; Add this line to your .emacs file and bind the versatile sectioning commands -;; in text mode, like this:: -;; -;; (require 'rst) -;; (add-hook 'text-mode-hook 'rst-text-mode-bindings) -;; -;; rst-prefix-map is the prefix map for all the functionality provide by this -;; module. In addition, other shorter bindings are also provided on the -;; mode-specific-map prefix (i.e C-c). -;; -;; -;; C-c p a (also C-=): rst-adjust -;; -;; Updates or rotates the section title around point or promotes/demotes -;; the decorations within the region (see full details below). -;; -;; Note that C-= is a good binding, since it allows you to specify a -;; negative arg easily with C-- C-= (easy to type), as well as ordinary -;; prefix arg with C-u C-=. -;; -;; C-c p h: rst-display-decorations-hierarchy -;; -;; Displays the level decorations that are available in the file. -;; -;; C-c p t: rst-toc -;; -;; Displays the hierarchical table-of-contents of the document and allows -;; you to jump to any section from it. -;; -;; C-c p i: rst-toc-insert -;; -;; Inserts a table-of-contents in the document at the column where the -;; cursor is. -;; -;; C-c p u: rst-toc-insert-update -;; -;; Find an existing inserted table-of-contents in the document an -;; updates it. -;; -;; C-c p p, C-c p n (C-c C-p, C-c C-n): rst-backward-section, -;; rst-forward-section -;; -;; Navigate between section titles. -;; -;; C-c p l, C-c p r (C-c C-l, C-c C-r): rst-shift-region-left, -;; rst-shift-region-right -;; -;; Shift the region left or right by two-char increments, which is perfect -;; for bulleted lists. -;; -;; -;; Other specialized and more generic functions are also available (see source -;; code). The most important function provided by this file for section title -;; adjustments is rst-adjust. -;; -;; There are many variables that can be customized, look for defcustom and -;; defvar in this file. -;; -;; If you use the table-of-contents feature, you may want to add a hook to -;; update the TOC automatically everytime you adjust a section title:: -;; -;; (add-hook 'rst-adjust-hook 'rst-toc-insert-update) -;; -;; rst-mode -;; -------- -;; -;; There is a special mode that you can setup if you want to have syntax -;; highlighting. The mode is based on `text-mode' and inherits some things from -;; it. Particularly `text-mode-hook' is run before `rst-mode-hook'. -;; -;; Add the following lines to your `.emacs' file: -;; -;; (setq auto-mode-alist -;; (append '(("\\.rst$" . rst-mode) -;; ("\\.rest$" . rst-mode)) auto-mode-alist)) -;; -;; If you are using `.txt' as a standard extension for reST files as -;; http://docutils.sourceforge.net/FAQ.html#what-s-the-standard-filename-extension-for-a-restructuredtext-file -;; suggests you may use one of the `Local Variables in Files' mechanism Emacs -;; provides to set the major mode automatically. For instance you may use -;; -;; .. -*- mode: rst -*- -;; -;; in the very first line of your file. However, because this is a major -;; security breach you or your administrator may have chosen to switch that -;; feature off. See `Local Variables in Files' in the Emacs documentation for a -;; more complete discussion. -;; -;; -;; TODO list -;; ========= -;; -;; Bindings -;; -------- -;; - We need to automatically add the rst-text-mode-bindings to rst-mode -;; - We need to find better bindings because C-= does not generate an event on -;; the Macs. -;; -;; rst-toc-insert features -;; ------------------------ -;; - rst-toc-insert: We should parse the contents:: options to figure out how -;; deep to render the inserted TOC. -;; - On load, detect any existing TOCs and set the properties for links. -;; - TOC insertion should have an option to add empty lines. -;; - TOC insertion should deal with multiple lines -;; -;; - There is a bug on redo after undo of adjust when rst-adjust-hook uses the -;; automatic toc update. The cursor ends up in the TOC and this is -;; annoying. Gotta fix that. -;; -;; rst-mode -;; -------- -;; - Look at the possibility of converting rst-mode from a Major mode to a Minor -;; mode of text-mode. -;; -;; Other -;; ----- -;; - We should rename "adornment" to "decoration" or vice-versa in this -;; document. -;; - Add an option to forego using the file structure in order to make -;; suggestion, and to always use the preferred decorations to do that. -;; - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Bindings and hooks - -(defgroup rst nil "Support for reStructuredText documents" - :group 'wp - :version "21.1" - :link '(url-link "http://docutils.sourceforge.net/rst.html")) - -(defun rst-toc-or-hierarchy () - "Binding for either TOC or decorations hierarchy." - (interactive) - (if (not current-prefix-arg) - (rst-toc) - (rst-display-decorations-hierarchy))) - -;; Define a prefix map for the long form of key combinations. -(defvar rst-prefix-map (make-sparse-keymap) - "Keymap for rst commands.") -(define-key rst-prefix-map "a" 'rst-adjust) -(define-key rst-prefix-map "=" 'rst-adjust) -(define-key rst-prefix-map "t" 'rst-toc) -(define-key rst-prefix-map "h" 'rst-display-decorations-hierarchy) -(define-key rst-prefix-map "i" 'rst-toc-insert) -(define-key rst-prefix-map "+" 'rst-toc-insert) -(define-key rst-prefix-map "p" 'rst-backward-section) -(define-key rst-prefix-map "n" 'rst-forward-section) -(define-key rst-prefix-map "r" 'rst-shift-region-right) -(define-key rst-prefix-map "l" 'rst-shift-region-left) -(define-key rst-prefix-map "u" 'rst-toc-insert-update) -(define-key rst-prefix-map "c" 'rst-compile) -(define-key rst-prefix-map "C" (lambda () (interactive) (rst-compile t))) - -(defun rst-text-mode-bindings () - "Default text mode hook for rest." - - ;; Direct command (somehow this one does not work on the Mac). - (local-set-key [(control ?=)] 'rst-adjust) - - (define-key mode-specific-map [(control p)] 'rst-backward-section) - (define-key mode-specific-map [(control n)] 'rst-forward-section) - (define-key mode-specific-map [(control r)] 'rst-shift-region-right) - (define-key mode-specific-map [(control l)] 'rst-shift-region-left) - - ;; Bind the rst commands on the C-c p prefix. - (define-key mode-specific-map [(p)] rst-prefix-map) - ) - - -;; Note: we cannot bind the TOC update on file write because it messes with -;; undo. If we disable undo, since it adds and removes characters, the -;; positions in the undo list are not making sense anymore. Dunno what to do -;; with this, it would be nice to update when saving. -;; -;; (add-hook 'write-contents-hooks 'rst-toc-insert-update-fun) -;; (defun rst-toc-insert-update-fun () -;; ;; Disable undo for the write file hook. -;; (let ((buffer-undo-list t)) (rst-toc-insert-update) )) - - -;; Additional abbreviations for text-mode. -(define-abbrev text-mode-abbrev-table - "con" ".. contents::\n..\n " nil 0) - - -;; Paragraph separation customization. This will work better for -;; bullet and enumerated lists in restructuredtext documents and -;; should not affect filling for other documents too much. Set it up -;; like this: -;; -;; (add-hook 'text-mode-hook 'rst-set-paragraph-separation) -(defvar rst-extra-paragraph-start - "\\|[ \t]*\\([-+*] \\|[0-9]+\\. \\)" - "Extra parapraph-separate patterns to add for text-mode.") -;; FIXME: What about the missing >? -;; The author uses a hardcoded for paragraph-separate: "\f\\|>*[ \t]*$" - -(defun rst-set-paragraph-separation () - "Sets the paragraph separation for restructuredtext." - ;; FIXME: the variable should be made automatically buffer local rather than - ;; using a function here, this function is unnecessary. - (make-local-variable 'paragraph-start) ; prevent it growing every time - (setq paragraph-start (concat paragraph-start rst-extra-paragraph-start))) - -;; FIXME: What about paragraph-separate? paragraph-start and paragraph-separate -;; are different. The author hardcodes the value to -;; "\f\\|>*[ \t]*$\\|>*[ \t]*[-+*] \\|>*[ \t]*[0-9#]+\\. " - -;; FIXME: the variables above are in limbo and need some fixing. - - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Support functions - -(require 'cl) - -;; Generic Filter function. -(unless (fboundp 'filter) - (defun filter (pred list) - "Returns a list of all the elements fulfilling the pred requirement (that -is for which (pred elem) is true)" - (if list - (let ((head (car list)) - (tail (filter pred (cdr list)))) - (if (funcall pred head) - (cons head tail) - tail))))) - - -;; From emacs-22 -(unless (fboundp 'line-number-at-pos) - (defun line-number-at-pos (&optional pos) - "Return (narrowed) buffer line number at position POS. - If POS is nil, use current buffer location." - (let ((opoint (or pos (point))) start) - (save-excursion - (goto-char (point-min)) - (setq start (point)) - (goto-char opoint) - (forward-line 0) - (1+ (count-lines start (point)))))) ) - - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Section Decoration Adjusment -;; ============================ -;; -;; The following functions implement a smart automatic title sectioning feature. -;; The idea is that with the cursor sitting on a section title, we try to get as -;; much information from context and try to do the best thing automatically. -;; This function can be invoked many times and/or with prefix argument to rotate -;; between the various sectioning decorations. -;; -;; Definitions: the two forms of sectioning define semantically separate section -;; levels. A sectioning DECORATION consists in: -;; -;; - a CHARACTER -;; -;; - a STYLE which can be either of 'simple' or 'over-and-under'. -;; -;; - an INDENT (meaningful for the over-and-under style only) which determines -;; how many characters and over-and-under style is hanging outside of the -;; title at the beginning and ending. -;; -;; Important note: an existing decoration must be formed by at least two -;; characters to be recognized. -;; -;; Here are two examples of decorations (| represents the window border, column -;; 0): -;; -;; | -;; 1. char: '-' e |Some Title -;; style: simple |---------- -;; | -;; 2. char: '=' |============== -;; style: over-and-under | Some Title -;; indent: 2 |============== -;; | -;; -;; Some notes: -;; -;; - The underlining character that is used depends on context. The file is -;; scanned to find other sections and an appropriate character is selected. -;; If the function is invoked on a section that is complete, the character is -;; rotated among the existing section decorations. -;; -;; Note that when rotating the characters, if we come to the end of the -;; hierarchy of decorations, the variable rst-preferred-decorations is -;; consulted to propose a new underline decoration, and if continued, we cycle -;; the decorations all over again. Set this variable to nil if you want to -;; limit the underlining character propositions to the existing decorations in -;; the file. -;; -;; - A prefix argument can be used to alternate the style. -;; -;; - An underline/overline that is not extended to the column at which it should -;; be hanging is dubbed INCOMPLETE. For example:: -;; -;; |Some Title -;; |------- -;; -;; Examples of default invocation: -;; -;; |Some Title ---> |Some Title -;; | |---------- -;; -;; |Some Title ---> |Some Title -;; |----- |---------- -;; -;; | |------------ -;; | Some Title ---> | Some Title -;; | |------------ -;; -;; In over-and-under style, when alternating the style, a variable is -;; available to select how much default indent to use (it can be zero). Note -;; that if the current section decoration already has an indent, we don't -;; adjust it to the default, we rather use the current indent that is already -;; there for adjustment (unless we cycle, in which case we use the indent -;; that has been found previously). - -(defgroup rst-adjust nil - "Settings for adjustment and cycling of section title -decorations." - :group 'rst - :version "21.1") - -(defcustom rst-preferred-decorations '( (?= over-and-under 1) - (?= simple 0) - (?- simple 0) - (?~ simple 0) - (?+ simple 0) - (?` simple 0) - (?# simple 0) - (?@ simple 0) ) - "Preferred ordering of section title decorations. This - sequence is consulted to offer a new decoration suggestion when - we rotate the underlines at the end of the existing hierarchy - of characters, or when there is no existing section title in - the file." - :group 'rst-adjust) - - -(defcustom rst-default-indent 1 - "Number of characters to indent the section title when toggling - decoration styles. This is used when switching from a simple - decoration style to a over-and-under decoration style." - :group 'rst-adjust) - - -(defvar rst-section-text-regexp "^[ \t]*\\S-*[a-zA-Z0-9]\\S-*" - "Regular expression for valid section title text.") - - -(defun rst-line-homogeneous-p (&optional accept-special) - "Predicate return the unique char if the current line is - composed only of a single repeated non-whitespace - character. This returns the char even if there is whitespace at - the beginning of the line. - - If ACCEPT-SPECIAL is specified we do not ignore special sequences - which normally we would ignore when doing a search on many lines. - For example, normally we have cases to ignore commonly occuring - patterns, such as :: or ...; with the flag do not ignore them." - (save-excursion - (back-to-indentation) - (unless (looking-at "\n") - (let ((c (thing-at-point 'char))) - (if (and (looking-at (format "[%s]+[ \t]*$" c)) - (or accept-special - (and - ;; Common patterns. - (not (looking-at "::[ \t]*$")) - (not (looking-at "\\.\\.\\.[ \t]*$")) - ;; Discard one char line - (not (looking-at ".[ \t]*$")) - ))) - (string-to-char c)) - )) - )) - -(defun rst-line-homogeneous-nodent-p (&optional accept-special) - (save-excursion - (beginning-of-line) - (if (looking-at "^[ \t]+") - nil - (rst-line-homogeneous-p accept-special) - ))) - - -(defun rst-compare-decorations (deco1 deco2) - "Compare decorations. Returns true if both are equal, -according to restructured text semantics (only the character and -the style are compared, the indentation does not matter." - (and (eq (car deco1) (car deco2)) - (eq (cadr deco1) (cadr deco2)))) - - -(defun rst-get-decoration-match (hier deco) - "Returns the index (level) of the decoration in the given hierarchy. -This basically just searches for the item using the appropriate -comparison and returns the index. We return nil if the item is -not found." - (let ((cur hier)) - (while (and cur (not (rst-compare-decorations (car cur) deco))) - (setq cur (cdr cur))) - cur)) - - -(defun rst-suggest-new-decoration (alldecos &optional prev) - "Suggest a new, different decoration, different from all that -have been seen. - - ALLDECOS is the set of all decorations, including the line - numbers. PREV is the optional previous decoration, in order to - suggest a better match." - - ;; For all the preferred decorations... - (let* ( - ;; If 'prev' is given, reorder the list to start searching after the - ;; match. - (fplist - (cdr (rst-get-decoration-match rst-preferred-decorations prev))) - - ;; List of candidates to search. - (curpotential (append fplist rst-preferred-decorations))) - (while - ;; For all the decorations... - (let ((cur alldecos) - found) - (while (and cur (not found)) - (if (rst-compare-decorations (car cur) (car curpotential)) - ;; Found it! - (setq found (car curpotential)) - (setq cur (cdr cur)))) - found) - - (setq curpotential (cdr curpotential))) - - (copy-list (car curpotential)) )) - -(defun rst-delete-line () - "A version of kill-line that does not use the kill-ring." - (delete-region (line-beginning-position) (min (+ 1 (line-end-position)) - (point-max)))) - -(defun rst-update-section (char style &optional indent) - "Unconditionally updates the style of a section decoration - using the given character CHAR, with STYLE 'simple or - 'over-and-under, and with indent INDENT. If the STYLE is - 'simple, whitespace before the title is removed (indent is - always assume to be 0). - - If there are existing overline and/or underline from the - existing decoration, they are removed before adding the - requested decoration." - - (interactive) - (let (marker - len - ec - (c ?-)) - - (end-of-line) - (setq marker (point-marker)) - - ;; Fixup whitespace at the beginning and end of the line - (if (or (null indent) (eq style 'simple)) - (setq indent 0)) - (beginning-of-line) - (delete-horizontal-space) - (insert (make-string indent ? )) - - (end-of-line) - (delete-horizontal-space) - - ;; Set the current column, we're at the end of the title line - (setq len (+ (current-column) indent)) - - ;; Remove previous line if it consists only of a single repeated character - (save-excursion - (forward-line -1) - (and (rst-line-homogeneous-p 1) - ;; Avoid removing the underline of a title right above us. - (save-excursion (forward-line -1) - (not (looking-at rst-section-text-regexp))) - (rst-delete-line))) - - ;; Remove following line if it consists only of a single repeated - ;; character - (save-excursion - (forward-line +1) - (and (rst-line-homogeneous-p 1) - (rst-delete-line)) - ;; Add a newline if we're at the end of the buffer, for the subsequence - ;; inserting of the underline - (if (= (point) (buffer-end 1)) - (newline 1))) - - ;; Insert overline - (if (eq style 'over-and-under) - (save-excursion - (beginning-of-line) - (open-line 1) - (insert (make-string len char)))) - - ;; Insert underline - (forward-line +1) - (open-line 1) - (insert (make-string len char)) - - (forward-line +1) - (goto-char marker) - )) - - -(defun rst-normalize-cursor-position () - "If the cursor is on a decoration line or an empty line , place - it on the section title line (at the end). Returns the line - offset by which the cursor was moved. This works both over or - under a line." - (if (save-excursion (beginning-of-line) - (or (rst-line-homogeneous-p 1) - (looking-at "^[ \t]*$"))) - (progn - (beginning-of-line) - (cond - ((save-excursion (forward-line -1) - (beginning-of-line) - (and (looking-at rst-section-text-regexp) - (not (rst-line-homogeneous-p 1)))) - (progn (forward-line -1) -1)) - ((save-excursion (forward-line +1) - (beginning-of-line) - (and (looking-at rst-section-text-regexp) - (not (rst-line-homogeneous-p 1)))) - (progn (forward-line +1) +1)) - (t 0))) - 0 )) - - -(defun rst-find-all-decorations () - "Finds all the decorations in the file, and returns a list of - (line, decoration) pairs. Each decoration consists in a (char, - style, indent) triple. - - This function does not detect the hierarchy of decorations, it - just finds all of them in a file. You can then invoke another - function to remove redundancies and inconsistencies." - - (let (positions - (curline 1)) - ;; Iterate over all the section titles/decorations in the file. - (save-excursion - (beginning-of-buffer) - (while (< (point) (buffer-end 1)) - (if (rst-line-homogeneous-nodent-p) - (progn - (setq curline (+ curline (rst-normalize-cursor-position))) - - ;; Here we have found a potential site for a decoration, - ;; characterize it. - (let ((deco (rst-get-decoration))) - (if (cadr deco) ;; Style is existing. - ;; Found a real decoration site. - (progn - (push (cons curline deco) positions) - ;; Push beyond the underline. - (forward-line 1) - (setq curline (+ curline 1)) - ))) - )) - (forward-line 1) - (setq curline (+ curline 1)) - )) - (reverse positions))) - - -(defun rst-infer-hierarchy (decorations) - "Build a hierarchy of decorations using the list of given decorations. - - This function expects a list of (char, style, indent) - decoration specifications, in order that they appear in a file, - and will infer a hierarchy of section levels by removing - decorations that have already been seen in a forward traversal of the - decorations, comparing just the character and style. - - Similarly returns a list of (char, style, indent), where each - list element should be unique." - - (let ((hierarchy-alist (list))) - (dolist (x decorations) - (let ((char (car x)) - (style (cadr x)) - (indent (caddr x))) - (unless (assoc (cons char style) hierarchy-alist) - (setq hierarchy-alist - (append hierarchy-alist - (list (cons (cons char style) x)))) ) - )) - (mapcar 'cdr hierarchy-alist) - )) - - -(defun rst-get-hierarchy (&optional alldecos ignore) - "Returns a list of decorations that represents the hierarchy of - section titles in the file. - - If the line number in IGNORE is specified, the decoration found - on that line (if there is one) is not taken into account when - building the hierarchy." - (let ((all (or alldecos (rst-find-all-decorations)))) - (setq all (assq-delete-all ignore all)) - (rst-infer-hierarchy (mapcar 'cdr all)))) - - -(defun rst-get-decoration (&optional point) - "Looks around point and finds the characteristics of the - decoration that is found there. We assume that the cursor is - already placed on the title line (and not on the overline or - underline). - - This function returns a (char, style, indent) triple. If the - characters of overline and underline are different, we return - the underline character. The indent is always calculated. A - decoration can be said to exist if the style is not nil. - - A point can be specified to go to the given location before - extracting the decoration." - - (let (char style indent) - (save-excursion - (if point (goto-char point)) - (beginning-of-line) - (if (looking-at rst-section-text-regexp) - (let* ((over (save-excursion - (forward-line -1) - (rst-line-homogeneous-nodent-p))) - - (under (save-excursion - (forward-line +1) - (rst-line-homogeneous-nodent-p))) - ) - - ;; Check that the line above the overline is not part of a title - ;; above it. - (if (and over - (save-excursion - (and (equal (forward-line -2) 0) - (looking-at rst-section-text-regexp)))) - (setq over nil)) - - (cond - ;; No decoration found, leave all return values nil. - ((and (eq over nil) (eq under nil))) - - ;; Overline only, leave all return values nil. - ;; - ;; Note: we don't return the overline character, but it could - ;; perhaps in some cases be used to do something. - ((and over (eq under nil))) - - ;; Underline only. - ((and under (eq over nil)) - (setq char under - style 'simple)) - - ;; Both overline and underline. - (t - (setq char under - style 'over-and-under)) - ) - ) - ) - ;; Find indentation. - (setq indent (save-excursion (back-to-indentation) (current-column))) - ) - ;; Return values. - (list char style indent))) - - -(defun rst-get-decorations-around (&optional alldecos) - "Given the list of all decorations (with positions), -find the decorations before and after the given point. -A list of the previous and next decorations is returned." - (let* ((all (or alldecos (rst-find-all-decorations))) - (curline (line-number-at-pos)) - prev next - (cur all)) - - ;; Search for the decorations around the current line. - (while (and cur (< (caar cur) curline)) - (setq prev cur - cur (cdr cur))) - ;; 'cur' is the following decoration. - - (if (and cur (caar cur)) - (setq next (if (= curline (caar cur)) (cdr cur) cur))) - - (mapcar 'cdar (list prev next)) - )) - - -(defun rst-decoration-complete-p (deco &optional point) - "Return true if the decoration DECO around POINT is complete." - ;; Note: we assume that the detection of the overline as being the underline - ;; of a preceding title has already been detected, and has been eliminated - ;; from the decoration that is given to us. - - ;; There is some sectioning already present, so check if the current - ;; sectioning is complete and correct. - (let* ((char (car deco)) - (style (cadr deco)) - (indent (caddr deco)) - (endcol (save-excursion (end-of-line) (current-column))) - ) - (if char - (let ((exps (concat "^" - (regexp-quote (make-string (+ endcol indent) char)) - "$"))) - (and - (save-excursion (forward-line +1) - (beginning-of-line) - (looking-at exps)) - (or (not (eq style 'over-and-under)) - (save-excursion (forward-line -1) - (beginning-of-line) - (looking-at exps)))) - )) - )) - - -(defun rst-get-next-decoration - (curdeco hier &optional suggestion reverse-direction) - "Get the next decoration for CURDECO, in given hierarchy HIER, -and suggesting for new decoration SUGGESTION." - - (let* ( - (char (car curdeco)) - (style (cadr curdeco)) - - ;; Build a new list of decorations for the rotation. - (rotdecos - (append hier - ;; Suggest a new decoration. - (list suggestion - ;; If nothing to suggest, use first decoration. - (car hier)))) ) - (or - ;; Search for next decoration. - (cadr - (let ((cur (if reverse-direction rotdecos - (reverse rotdecos))) - found) - (while (and cur - (not (and (eq char (caar cur)) - (eq style (cadar cur))))) - (setq cur (cdr cur))) - cur)) - - ;; If not found, take the first of all decorations. - suggestion - ))) - - -(defun rst-adjust () - "Adjust/rotate the section decoration for the section title -around point or promote/demote the decorations inside the region, -depending on if the region is active. This function is meant to -be invoked possibly multiple times, and can vary its behaviour -with a positive prefix argument (toggle style), or with a -negative prefix argument (alternate behaviour). - -This function is the main focus of this module and is a bit of a -swiss knife. It is meant as the single most essential function -to be bound to invoke to adjust the decorations of a section -title in restructuredtext. It tries to deal with all the -possible cases gracefully and to do `the right thing' in all -cases. - -See the documentations of rst-adjust-decoration and -rst-promote-region for full details. - -Prefix Arguments -================ - -The method can take either (but not both) of - -a. a (non-negative) prefix argument, which means to toggle the - decoration style. Invoke with C-u prefix for example; - -b. a negative numerical argument, which generally inverts the - direction of search in the file or hierarchy. Invoke with C-- - prefix for example. - -" - (interactive) - - (let* ( ;; Parse the positive and negative prefix arguments. - (reverse-direction - (and current-prefix-arg - (< (prefix-numeric-value current-prefix-arg) 0))) - (toggle-style - (and current-prefix-arg (not reverse-direction)))) - - (if (and transient-mark-mode mark-active) - ;; Adjust decorations within region. - (rst-promote-region current-prefix-arg) - ;; Adjust decoration around point. - (rst-adjust-decoration toggle-style reverse-direction)) - - ;; Run the hooks to run after adjusting. - (run-hooks 'rst-adjust-hook) - - )) - -(defvar rst-adjust-hook nil - "Hooks to be run after running rst-adjust.") - -(defun rst-adjust-decoration (&optional toggle-style reverse-direction) -"Adjust/rotate the section decoration for the section title around point. - -This function is meant to be invoked possibly multiple times, and -can vary its behaviour with a true TOGGLE-STYLE argument, or with -a REVERSE-DIRECTION argument. - -General Behaviour -================= - -The next action it takes depends on context around the point, and -it is meant to be invoked possibly more than once to rotate among -the various possibilities. Basically, this function deals with: - -- adding a decoration if the title does not have one; - -- adjusting the length of the underline characters to fit a - modified title; - -- rotating the decoration in the set of already existing - sectioning decorations used in the file; - -- switching between simple and over-and-under styles. - -You should normally not have to read all the following, just -invoke the method and it will do the most obvious thing that you -would expect. - - -Decoration Definitions -====================== - -The decorations consist in - -1. a CHARACTER - -2. a STYLE which can be either of 'simple' or 'over-and-under'. - -3. an INDENT (meaningful for the over-and-under style only) - which determines how many characters and over-and-under - style is hanging outside of the title at the beginning and - ending. - -See source code for mode details. - - -Detailed Behaviour Description -============================== - -Here are the gory details of the algorithm (it seems quite -complicated, but really, it does the most obvious thing in all -the particular cases): - -Before applying the decoration change, the cursor is placed on -the closest line that could contain a section title. - -Case 1: No Decoration ---------------------- - -If the current line has no decoration around it, - -- search backwards for the last previous decoration, and apply - the decoration one level lower to the current line. If there - is no defined level below this previous decoration, we suggest - the most appropriate of the rst-preferred-decorations. - - If REVERSE-DIRECTION is true, we simply use the previous - decoration found directly. - -- if there is no decoration found in the given direction, we use - the first of rst-preferred-decorations. - -The prefix argument forces a toggle of the prescribed decoration -style. - -Case 2: Incomplete Decoration ------------------------------ - -If the current line does have an existing decoration, but the -decoration is incomplete, that is, the underline/overline does -not extend to exactly the end of the title line (it is either too -short or too long), we simply extend the length of the -underlines/overlines to fit exactly the section title. - -If the prefix argument is given, we toggle the style of the -decoration as well. - -REVERSE-DIRECTION has no effect in this case. - -Case 3: Complete Existing Decoration ------------------------------------- - -If the decoration is complete (i.e. the underline (overline) -length is already adjusted to the end of the title line), we -search/parse the file to establish the hierarchy of all the -decorations (making sure not to include the decoration around -point), and we rotate the current title's decoration from within -that list (by default, going *down* the hierarchy that is present -in the file, i.e. to a lower section level). This is meant to be -used potentially multiple times, until the desired decoration is -found around the title. - -If we hit the boundary of the hierarchy, exactly one choice from -the list of preferred decorations is suggested/chosen, the first -of those decoration that has not been seen in the file yet (and -not including the decoration around point), and the next -invocation rolls over to the other end of the hierarchy (i.e. it -cycles). This allows you to avoid having to set which character -to use by always using the - -If REVERSE-DIRECTION is true, the effect is to change the -direction of rotation in the hierarchy of decorations, thus -instead going *up* the hierarchy. - -However, if there is a non-negative prefix argument, we do not -rotate the decoration, but instead simply toggle the style of the -current decoration (this should be the most common way to toggle -the style of an existing complete decoration). - - -Point Location -============== - -The invocation of this function can be carried out anywhere -within the section title line, on an existing underline or -overline, as well as on an empty line following a section title. -This is meant to be as convenient as possible. - - -Indented Sections -================= - -Indented section titles such as :: - - My Title - -------- - -are illegal in restructuredtext and thus not recognized by the -parser. This code will thus not work in a way that would support -indented sections (it would be ambiguous anyway). - - -Joint Sections -============== - -Section titles that are right next to each other may not be -treated well. More work might be needed to support those, and -special conditions on the completeness of existing decorations -might be required to make it non-ambiguous. - -For now we assume that the decorations are disjoint, that is, -there is at least a single line between the titles/decoration -lines. - - -Suggested Binding -================= - -We suggest that you bind this function on C-=. It is close to -C-- so a negative argument can be easily specified with a flick -of the right hand fingers and the binding is unused in text-mode." - (interactive) - - ;; If we were invoked directly, parse the prefix arguments into the - ;; arguments of the function. - (if current-prefix-arg - (setq reverse-direction - (and current-prefix-arg - (< (prefix-numeric-value current-prefix-arg) 0)) - - toggle-style - (and current-prefix-arg (not reverse-direction)))) - - (let* (;; Check if we're on an underline around a section title, and move the - ;; cursor to the title if this is the case. - (moved (rst-normalize-cursor-position)) - - ;; Find the decoration and completeness around point. - (curdeco (rst-get-decoration)) - (char (car curdeco)) - (style (cadr curdeco)) - (indent (caddr curdeco)) - - ;; New values to be computed. - char-new style-new indent-new - ) - - ;; We've moved the cursor... if we're not looking at some text, we have - ;; nothing to do. - (if (save-excursion (beginning-of-line) - (looking-at rst-section-text-regexp)) - (progn - (cond - ;;------------------------------------------------------------------- - ;; Case 1: No Decoration - ((and (eq char nil) (eq style nil)) - - (let* ((alldecos (rst-find-all-decorations)) - - (around (rst-get-decorations-around alldecos)) - (prev (car around)) - cur - - (hier (rst-get-hierarchy alldecos)) - ) - - ;; Advance one level down. - (setq cur - (if prev - (if (not reverse-direction) - (or (cadr (rst-get-decoration-match hier prev)) - (rst-suggest-new-decoration hier prev)) - prev) - (copy-list (car rst-preferred-decorations)) - )) - - ;; Invert the style if requested. - (if toggle-style - (setcar (cdr cur) (if (eq (cadr cur) 'simple) - 'over-and-under 'simple)) ) - - (setq char-new (car cur) - style-new (cadr cur) - indent-new (caddr cur)) - )) - - ;;------------------------------------------------------------------- - ;; Case 2: Incomplete Decoration - ((not (rst-decoration-complete-p curdeco)) - - ;; Invert the style if requested. - (if toggle-style - (setq style (if (eq style 'simple) 'over-and-under 'simple))) - - (setq char-new char - style-new style - indent-new indent)) - - ;;------------------------------------------------------------------- - ;; Case 3: Complete Existing Decoration - (t - (if toggle-style - - ;; Simply switch the style of the current decoration. - (setq char-new char - style-new (if (eq style 'simple) 'over-and-under 'simple) - indent-new rst-default-indent) - - ;; Else, we rotate, ignoring the decoration around the current - ;; line... - (let* ((alldecos (rst-find-all-decorations)) - - (hier (rst-get-hierarchy alldecos (line-number-at-pos))) - - ;; Suggestion, in case we need to come up with something - ;; new - (suggestion (rst-suggest-new-decoration - hier - (car (rst-get-decorations-around alldecos)))) - - (nextdeco (rst-get-next-decoration - curdeco hier suggestion reverse-direction)) - - ) - - ;; Indent, if present, always overrides the prescribed indent. - (setq char-new (car nextdeco) - style-new (cadr nextdeco) - indent-new (caddr nextdeco)) - - ))) - ) - - ;; Override indent with present indent! - (setq indent-new (if (> indent 0) indent indent-new)) - - (if (and char-new style-new) - (rst-update-section char-new style-new indent-new)) - )) - - - ;; Correct the position of the cursor to more accurately reflect where it - ;; was located when the function was invoked. - (unless (= moved 0) - (forward-line (- moved)) - (end-of-line)) - - )) - -;; Maintain an alias for compatibility. -(defalias 'rst-adjust-section-title 'rst-adjust) - - -(defun rst-promote-region (&optional demote) - "Promote the section titles within the region. - -With argument DEMOTE or a prefix argument, demote the -section titles instead. The algorithm used at the boundaries of -the hierarchy is similar to that used by rst-adjust-decoration." - (interactive) - - (let* ((demote (or current-prefix-arg demote)) - (alldecos (rst-find-all-decorations)) - (cur alldecos) - - (hier (rst-get-hierarchy alldecos)) - (suggestion (rst-suggest-new-decoration hier)) - - (region-begin-line (line-number-at-pos (region-beginning))) - (region-end-line (line-number-at-pos (region-end))) - - marker-list - ) - - ;; Skip the markers that come before the region beginning - (while (and cur (< (caar cur) region-begin-line)) - (setq cur (cdr cur))) - - ;; Create a list of markers for all the decorations which are found within - ;; the region. - (save-excursion - (let (m line) - (while (and cur (< (setq line (caar cur)) region-end-line)) - (setq m (make-marker)) - (goto-line line) - (push (list (set-marker m (point)) (cdar cur)) marker-list) - (setq cur (cdr cur)) )) - - ;; Apply modifications. - (let (nextdeco) - (dolist (p marker-list) - ;; Go to the decoration to promote. - (goto-char (car p)) - - ;; Rotate the next decoration. - (setq nextdeco (rst-get-next-decoration - (cadr p) hier suggestion demote)) - - ;; Update the decoration. - (apply 'rst-update-section nextdeco) - - ;; Clear marker to avoid slowing down the editing after we're done. - (set-marker (car p) nil) - )) - (setq deactivate-mark nil) - ))) - - - -(defun rst-display-decorations-hierarchy (&optional decorations) - "Display the current file's section title decorations hierarchy. - This function expects a list of (char, style, indent) triples." - (interactive) - - (if (not decorations) - (setq decorations (rst-get-hierarchy))) - (with-output-to-temp-buffer "*rest section hierarchy*" - (let ((level 1)) - (with-current-buffer standard-output - (dolist (x decorations) - (insert (format "\nSection Level %d" level)) - (apply 'rst-update-section x) - (end-of-buffer) - (insert "\n") - (incf level) - )) - ))) - - -(defun rst-rstrip (str) - "Strips the whitespace at the end of a string." - (let ((tmp)) - (string-match "[ \t\n]*\\'" str) - (substring str 0 (match-beginning 0)) - )) - -(defun rst-get-stripped-line () - "Returns the line at cursor, stripped from whitespace." - (re-search-forward "\\S-.*\\S-" (line-end-position)) - (buffer-substring-no-properties (match-beginning 0) - (match-end 0)) ) - -(defun rst-section-tree (alldecos) - "Returns a hierarchical tree of the sections titles in the -document. This can be used to generate a table of contents for -the document. The top node will always be a nil node, with the -top-level titles as children (there may potentially be more than -one). - -Each section title consists in a cons of the stripped title -string and a marker to the section in the original text document. - -If there are missing section levels, the section titles are -inserted automatically, and the title string is set to nil, and -the marker set to the first non-nil child of itself. -Conceptually, the nil nodes--i.e. those which have no title--are -to be considered as being the same line as their first non-nil -child. This has advantages later in processing the graph." - - (let* (thelist - (hier (rst-get-hierarchy alldecos)) - (levels (make-hash-table :test 'equal :size 10)) - lines) - - (let ((lev 0)) - (dolist (deco hier) - ;; Compare just the character and indent in the hash table. - (puthash (cons (car deco) (cadr deco)) lev levels) - (incf lev))) - - ;; Create a list of lines that contains (text, level, marker) for each - ;; decoration. - (save-excursion - (setq lines - (mapcar (lambda (deco) - (goto-line (car deco)) - (list (gethash (cons (cadr deco) (caddr deco)) levels) - (rst-get-stripped-line) - (let ((m (make-marker))) - (beginning-of-line 1) - (set-marker m (point))) - )) - alldecos))) - - (let ((lcontnr (cons nil lines))) - (rst-section-tree-rec lcontnr -1)))) - - -(defun rst-section-tree-rec (decos lev) - "Recursive function for the implementation of the section tree - building. DECOS is a cons cell whose cdr is the remaining list - of decorations, and we change it as we consume them. LEV is - the current level of that node. This function returns a pair - of the subtree that was built. This treats the decos list - destructively." - - (let ((ndeco (cadr decos)) - node - children) - - ;; If the next decoration matches our level - (when (and ndeco (= (car ndeco) lev)) - ;; Pop the next decoration and create the current node with it - (setcdr decos (cddr decos)) - (setq node (cdr ndeco)) ) - ;; Else we let the node title/marker be unset. - - ;; Build the child nodes - (while (and (cdr decos) (> (caadr decos) lev)) - (setq children - (cons (rst-section-tree-rec decos (1+ lev)) - children))) - (setq children (reverse children)) - - ;; If node is still unset, we use the marker of the first child. - (when (eq node nil) - (setq node (cons nil (cdaar children)))) - - ;; Return this node with its children. - (cons node children) - )) - - -(defun rst-section-tree-point (node &optional point) - "Given a computed and valid section tree SECTREE and a point - POINT (default being the current point in the current buffer), - find and return the node within the sectree where the cursor - lives. - - Return values: a pair of (parent path, container subtree). The - parent path is simply a list of the nodes above the container - subtree node that we're returning." - - (let (path outtree) - - (let* ((curpoint (or point (point)))) - - ;; Check if we are before the current node. - (if (and (cadar node) (>= curpoint (cadar node))) - - ;; Iterate all the children, looking for one that might contain the - ;; current section. - (let ((curnode (cdr node)) - last) - - (while (and curnode (>= curpoint (cadaar curnode))) - (setq last curnode - curnode (cdr curnode))) - - (if last - (let ((sub (rst-section-tree-point (car last) curpoint))) - (setq path (car sub) - outtree (cdr sub))) - (setq outtree node)) - - ))) - (cons (cons (car node) path) outtree) - )) - - -(defun rst-toc-insert (&optional pfxarg) - "Insert a simple text rendering of the table of contents. -By default the top level is ignored if there is only one, because -we assume that the document will have a single title. - -If a numeric prefix argument is given, insert the TOC up to the -specified level. - -The TOC is inserted indented at the current column." - - (interactive "P") - - (let* (;; Check maximum level override - (rst-toc-insert-max-level - (if (and (integerp pfxarg) (> (prefix-numeric-value pfxarg) 0)) - (prefix-numeric-value pfxarg) rst-toc-insert-max-level)) - - ;; Get the section tree for the current cursor point. - (sectree-pair - (rst-section-tree-point - (rst-section-tree (rst-find-all-decorations)))) - - ;; Figure out initial indent. - (initial-indent (make-string (current-column) ? )) - (init-point (point))) - - (when (cddr sectree-pair) - (rst-toc-insert-node (cdr sectree-pair) 0 initial-indent "") - - ;; Fixup for the first line. - (delete-region init-point (+ init-point (length initial-indent))) - - ;; Delete the last newline added. - (delete-backward-char 1) - ))) - - -(defgroup rst-toc nil - "Settings for reStructuredText table of contents." - :group 'rst - :version "21.1") - -(defcustom rst-toc-indent 2 - "Indentation for table-of-contents display (also used for - formatting insertion, when numbering is disabled)." - :group 'rst-toc) - -(defcustom rst-toc-insert-style 'fixed - "Set this to one of the following values to determine numbering and -indentation style: -- plain: no numbering (fixed indentation) -- fixed: numbering, but fixed indentation -- aligned: numbering, titles aligned under each other -- listed: numbering, with dashes like list items (EXPERIMENTAL) -" - :group 'rst-toc) - -(defcustom rst-toc-insert-number-separator " " - "Separator that goes between the TOC number and the title." - :group 'rst-toc) - -;; This is used to avoid having to change the user's mode. -(defvar rst-toc-insert-click-keymap - (let ((map (make-sparse-keymap))) - (define-key map [mouse-1] 'rst-toc-mode-mouse-goto) - map) - "(Internal) What happens when you click on propertized text in the TOC.") - -(defcustom rst-toc-insert-max-level nil - "If non-nil, maximum depth of the inserted TOC." - :group 'rst-toc) - -(defun rst-toc-insert-node (node level indent pfx) - "Recursive function that does the print of the inserted -toc. PFX is the prefix numbering, that includes the alignment -necessary for all the children of this level to align." - - ;; Note: we do child numbering from the parent, so we start number the - ;; children one level before we print them. - (let ((do-print (> level 0)) - (count 1) - b) - (when do-print - (insert indent) - (let ((b (point))) - (unless (equal rst-toc-insert-style 'plain) - (insert pfx rst-toc-insert-number-separator)) - (insert (or (caar node) "[missing node]")) - ;; Add properties to the text, even though in normal text mode it - ;; won't be doing anything for now. Not sure that I want to change - ;; mode stuff. At least the highlighting gives the idea that this - ;; is generated automatically. - (put-text-property b (point) 'mouse-face 'highlight) - (put-text-property b (point) 'rst-toc-target (cadar node)) - (put-text-property b (point) 'keymap rst-toc-insert-click-keymap) - - ) - (insert "\n") - - ;; Prepare indent for children. - (setq indent - (cond - ((eq rst-toc-insert-style 'plain) - (concat indent rst-toc-indent)) - - ((eq rst-toc-insert-style 'fixed) - (concat indent (make-string rst-toc-indent ? ))) - - ((eq rst-toc-insert-style 'aligned) - (concat indent (make-string (+ (length pfx) 2) ? ))) - - ((eq rst-toc-insert-style 'listed) - (concat (substring indent 0 -3) - (concat (make-string (+ (length pfx) 2) ? ) " - "))) - )) - ) - - (if (or (eq rst-toc-insert-max-level nil) - (< level rst-toc-insert-max-level)) - (let ((do-child-numbering (>= level 0)) - fmt) - (if do-child-numbering - (progn - ;; Add a separating dot if there is already a prefix - (if (> (length pfx) 0) - (setq pfx (concat (rst-rstrip pfx) "."))) - - ;; Calculate the amount of space that the prefix will require - ;; for the numbers. - (if (cdr node) - (setq fmt (format "%%-%dd" - (1+ (floor (log10 (length - (cdr node)))))))) - )) - - (dolist (child (cdr node)) - (rst-toc-insert-node child - (1+ level) - indent - (if do-child-numbering - (concat pfx (format fmt count)) pfx)) - (incf count))) - - ))) - - -(defun rst-toc-insert-find-delete-contents () - "Finds and deletes an existing comment after the first contents directive and -delete that region. Return t if found and the cursor is left after the comment." - (goto-char (point-min)) - ;; We look for the following and the following only (in other words, if your - ;; syntax differs, this won't work. If you would like a more flexible thing, - ;; contact the author, I just can't imagine that this requirement is - ;; unreasonable for now). - ;; - ;; .. contents:: [...anything here...] - ;; .. - ;; XXXXXXXX - ;; XXXXXXXX - ;; [more lines] - ;; - (let ((beg - (re-search-forward "^\\.\\. contents[ \t]*::\\(.*\\)\n\\.\\." - nil t)) - last-real) - (when beg - ;; Look for the first line that starts at the first column. - (forward-line 1) - (beginning-of-line) - (while (and - (< (point) (point-max)) - (or (and (looking-at "[ \t]+[^ \t]") (setq last-real (point)) t) - (looking-at "\\s-*$"))) - (forward-line 1) - ) - (if last-real - (progn - (goto-char last-real) - (end-of-line) - (delete-region beg (point))) - (goto-char beg)) - t - ))) - -(defun rst-toc-insert-update () - "Automatically find the .. contents:: section of a document and update the -inserted TOC if present. You can use this in your file-write hook to always -make it up-to-date automatically." - (interactive) - (save-excursion - (if (rst-toc-insert-find-delete-contents) - (progn (insert "\n ") - (rst-toc-insert))) ) - ;; Note: always return nil, because this may be used as a hook. - ) - - -;;------------------------------------------------------------------------------ - -(defun rst-toc-node (node level) - "Recursive function that does the print of the TOC in rst-toc-mode." - - (if (> level 0) - (let ((b (point))) - ;; Insert line text. - (insert (make-string (* rst-toc-indent (1- level)) ? )) - (insert (or (caar node) "[missing node]")) - - ;; Highlight lines. - (put-text-property b (point) 'mouse-face 'highlight) - - ;; Add link on lines. - (put-text-property b (point) 'rst-toc-target (cadar node)) - - (insert "\n") - )) - - (dolist (child (cdr node)) - (rst-toc-node child (1+ level)))) - -(defun rst-toc-count-lines (node target-node) - "Count the number of lines to the TARGET-NODE node. This -recursive function returns a cons of the number of additional -lines that have been counted for its node and children and 't if -the node has been found." - - (let ((count 1) - found) - (if (eq node target-node) - (setq found t) - (let ((child (cdr node))) - (while (and child (not found)) - (let ((cl (rst-toc-count-lines (car child) target-node))) - (setq count (+ count (car cl)) - found (cdr cl) - child (cdr child)))))) - (cons count found))) - - -(defun rst-toc () - "Finds all the section titles and their decorations in the - file, and displays a hierarchically-organized list of the - titles, which is essentially a table-of-contents of the - document. - - The emacs buffer can be navigated, and selecting a section - brings the cursor in that section." - (interactive) - (let* ((curbuf (current-buffer)) - - ;; Get the section tree - (alldecos (rst-find-all-decorations)) - (sectree (rst-section-tree alldecos)) - - (our-node (cdr (rst-section-tree-point sectree))) - line - - ;; Create a temporary buffer. - (buf (get-buffer-create rst-toc-buffer-name)) - ) - - (with-current-buffer buf - (let ((inhibit-read-only t)) - (rst-toc-mode) - (delete-region (point-min) (point-max)) - (insert (format "Table of Contents: %s\n" (or (caar sectree) ""))) - (put-text-property (point-min) (point) - 'face (list '(background-color . "lightgray"))) - (rst-toc-node sectree 0) - - ;; Count the lines to our found node. - (let ((linefound (rst-toc-count-lines sectree our-node))) - (setq line (if (cdr linefound) (car linefound) 0))) - )) - (display-buffer buf) - (pop-to-buffer buf) - - ;; Save the buffer to return to. - (set (make-local-variable 'rst-toc-return-buffer) curbuf) - - ;; Move the cursor near the right section in the TOC. - (goto-line line) - )) - - -(defun rst-toc-mode-find-section () - (let ((pos (get-text-property (point) 'rst-toc-target))) - (unless pos - (error "No section on this line")) - (unless (buffer-live-p (marker-buffer pos)) - (error "Buffer for this section was killed")) - pos)) - -(defvar rst-toc-buffer-name "*Table of Contents*" - "Name of the Table of Contents buffer.") - -(defun rst-toc-mode-goto-section () - "Go to the section the current line describes." - (interactive) - (let ((pos (rst-toc-mode-find-section))) - (kill-buffer (get-buffer rst-toc-buffer-name)) - (pop-to-buffer (marker-buffer pos)) - (goto-char pos) - (recenter 5))) - -(defun rst-toc-mode-mouse-goto (event) - "In Rst-Toc mode, go to the occurrence whose line you click on." - (interactive "e") - (let (pos) - (save-excursion - (set-buffer (window-buffer (posn-window (event-end event)))) - (save-excursion - (goto-char (posn-point (event-end event))) - (setq pos (rst-toc-mode-find-section)))) - (pop-to-buffer (marker-buffer pos)) - (goto-char pos))) - -(defun rst-toc-mode-mouse-goto-kill (event) - (interactive "e") - (call-interactively 'rst-toc-mode-mouse-goto event) - (kill-buffer (get-buffer rst-toc-buffer-name))) - -(defvar rst-toc-return-buffer nil - "Buffer local variable that is used to return to the original - buffer from the TOC.") - -(defun rst-toc-quit-window () - (interactive) - (quit-window) - (pop-to-buffer rst-toc-return-buffer)) - -(defvar rst-toc-mode-map - (let ((map (make-sparse-keymap))) - (define-key map [mouse-1] 'rst-toc-mode-mouse-goto-kill) - (define-key map [mouse-2] 'rst-toc-mode-mouse-goto) - (define-key map "\C-m" 'rst-toc-mode-goto-section) - (define-key map "f" 'rst-toc-mode-goto-section) - (define-key map "q" 'rst-toc-quit-window) - (define-key map "z" 'kill-this-buffer) - map) - "Keymap for `rst-toc-mode'.") - -(put 'rst-toc-mode 'mode-class 'special) - -(defun rst-toc-mode () - "Major mode for output from \\[rst-toc]." - (interactive) - (kill-all-local-variables) - (use-local-map rst-toc-mode-map) - (setq major-mode 'rst-toc-mode) - (setq mode-name "Rst-TOC") - (setq buffer-read-only t) - ) - -;; Note: use occur-mode (replace.el) as a good example to complete missing -;; features. - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; Section movement commands. -;; - -(defun rst-forward-section (&optional offset) - "Skip to the next restructured text section title. - OFFSET specifies how many titles to skip. Use a negative OFFSET to move - backwards in the file (default is to use 1)." - (interactive) - (let* (;; Default value for offset. - (offset (or offset 1)) - - ;; Get all the decorations in the file, with their line numbers. - (alldecos (rst-find-all-decorations)) - - ;; Get the current line. - (curline (line-number-at-pos)) - - (cur alldecos) - (idx 0) - line - ) - - ;; Find the index of the "next" decoration w.r.t. to the current line. - (while (and cur (< (caar cur) curline)) - (setq cur (cdr cur)) - (incf idx)) - ;; 'cur' is the decoration on or following the current line. - - (if (and (> offset 0) cur (= (caar cur) curline)) - (incf idx)) - - ;; Find the final index. - (setq idx (+ idx (if (> offset 0) (- offset 1) offset))) - (setq cur (nth idx alldecos)) - - ;; If the index is positive, goto the line, otherwise go to the buffer - ;; boundaries. - (if (and cur (>= idx 0)) - (goto-line (car cur)) - (if (> offset 0) (end-of-buffer) (beginning-of-buffer))) - )) - -(defun rst-backward-section () - "Like rst-forward-section, except move back one title." - (interactive) - (rst-forward-section -1)) - - - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Functions to indent/dedent item lists, which are always two-characters apart -;; horizontally with rest. - -(defvar rst-shift-fill-region nil - "Set to true if you want to automatically re-fill the region that is being -shifted.") -;; FIXME: need to finish this feature properly. - - -(defun rst-shift-region-right () - "Indent region ridigly, by two characters to the right." - (interactive) - (let ((mbeg (set-marker (make-marker) (region-beginning))) - (mend (set-marker (make-marker) (region-end)))) - (indent-rigidly mbeg mend 2) - (when rst-shift-fill-region - (fill-region mbeg mend)) - )) - -(defun rst-find-leftmost-column (beg end) - "Finds the leftmost column in the region." - (let ((mincol 1000)) - (save-excursion - (goto-char beg) - (while (< (point) end) - (back-to-indentation) - (unless (looking-at "[ \t]*$") - (setq mincol (min mincol (current-column)))) - (forward-line 1) - )) - mincol)) - -(defun rst-shift-region-left (pfxarg) - "Indent region ridigly, by two characters to the left. -If invoked with a prefix arg, the entire indentation is removed, -up to the leftmost character in the region." - (interactive "P") - (let ((chars - (if pfxarg - (- (rst-find-leftmost-column (region-beginning) (region-end))) - -2)) - (mbeg (set-marker (make-marker) (region-beginning))) - (mend (set-marker (make-marker) (region-end))) - ) - (indent-rigidly mbeg mend chars) - (when rst-shift-fill-region - (fill-region mbeg mend)) - )) - - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; rst-mode.el --- Mode for viewing and editing reStructuredText-documents. -;; -;; Copyright 2003 Stefan Merten <smerten@oekonux.de> -;; -;; Note: this is an update from version 0.2.9 of rst-mode.el -;; -;; DESCRIPTION -;; -;; This package provides support for documents marked up using the -;; reStructuredText format. Support includes font locking as well as some -;; convenience functions for editing. It does this by defining a Emacs major -;; mode. -;; -;; The package is based on text-mode and inherits some things from it. -;; Particularly text-mode-hook is run before rst-mode-hook. -;; -;; OPTIONS -;; -;; There are a number of things which can be customized using the standard -;; Emacs customization features. There are two customization groups for this -;; mode. -;; -;; Customization -;; ============= -;; -;; rst -;; --- -;; This group contains some general customizable features. -;; -;; The group is contained in the wp group. -;; -;; rst-faces -;; --------- -;; This group contains all necessary for customizing fonts. The default -;; settings use standard font-lock-*-face's so if you set these to your -;; liking they are probably good in rst-mode also. -;; -;; The group is contained in the faces group as well as in the rst group. -;; -;; rst-faces-defaults -;; ------------------ -;; This group contains all necessary for customizing the default fonts used for -;; section title faces. -;; -;; The general idea for section title faces is to have a non-default background -;; but do not change the background. The section level is shown by the -;; lightness of the background color. If you like this general idea of -;; generating faces for section titles but do not like the details this group -;; is the point where you can customize the details. If you do not like the -;; general idea, however, you should customize the faces used in -;; rst-adornment-faces-alist. -;; -;; Note: If you are using a dark background please make sure the variable -;; frame-background-mode is set to the symbol dark. This triggers -;; some default values which are probably right for you. -;; -;; The group is contained in the rst-faces group. -;; -;; All customizable features have a comment explaining their meaning. Refer to -;; the customization of your Emacs (try ``M-x customize``). - -;; SEE ALSO -;; -;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html - -;; AUTHOR -;; -;; Stefan Merten <smerten AT oekonux.de> - -;; LICENSE -;; -;; This program is licensed under the terms of the GPL. See -;; -;; http://www.gnu.org/licenses/gpl.txt - -;; AVAILABILITY -;; -;; See -;; -;; http://www.merten-home.de/FreeSoftware/rst-mode/ - - -;;; Code: - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; Customization: - -(defcustom rst-mode-hook nil - "Hook run when Rst Mode is turned on. The hook for Text Mode is run before - this one." - :group 'rst - :type '(hook)) - -(defcustom rst-mode-lazy t - "*If non-nil Rst Mode font-locks comment, literal blocks, and section titles -correctly. Because this is really slow it switches on Lazy Lock Mode -automatically. You may increase Lazy Lock Defer Time for reasonable results. - -If nil comments and literal blocks are font-locked only on the line they start. - -The value of this variable is used when Rst Mode is turned on." - :group 'rst - :type '(boolean)) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(defgroup rst-faces nil "Faces used in Rst Mode" - :group 'rst - :group 'faces - :version "21.1") - -(defcustom rst-block-face 'font-lock-keyword-face - "All syntax marking up a special block" - :group 'rst-faces - :type '(face)) - -(defcustom rst-external-face 'font-lock-type-face - "Field names and interpreted text" - :group 'rst-faces - :type '(face)) - -(defcustom rst-definition-face 'font-lock-function-name-face - "All other defining constructs" - :group 'rst-faces - :type '(face)) - -(defcustom rst-directive-face - ;; XEmacs compatibility - (if (boundp 'font-lock-builtin-face) - 'font-lock-builtin-face - 'font-lock-preprocessor-face) - "Directives and roles" - :group 'rst-faces - :type '(face)) - -(defcustom rst-comment-face 'font-lock-comment-face - "Comments" - :group 'rst-faces - :type '(face)) - -(defcustom rst-emphasis1-face - ;; XEmacs compatibility - (if (facep 'italic) - ''italic - 'italic) - "Simple emphasis" - :group 'rst-faces - :type '(face)) - -(defcustom rst-emphasis2-face - ;; XEmacs compatibility - (if (facep 'bold) - ''bold - 'bold) - "Double emphasis" - :group 'rst-faces - :type '(face)) - -(defcustom rst-literal-face 'font-lock-string-face - "Literal text" - :group 'rst-faces - :type '(face)) - -(defcustom rst-reference-face 'font-lock-variable-name-face - "References to a definition" - :group 'rst-faces - :type '(face)) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(defgroup rst-faces-defaults nil - "Values used to generate default faces for section titles on all levels. -Tweak these if you are content with how section title faces are built in -general but you do not like the details." - :group 'rst-faces - :version "21.1") - -(defun rst-define-level-faces () - "Define the faces for the section title text faces from the values." - ;; All variables used here must be checked in `rst-set-level-default' - (let ((i 1)) - (while (<= i rst-level-face-max) - (let ((sym (intern (format "rst-level-%d-face" i))) - (doc (format "Face for showing section title text at level %d" i)) - (col (format (concat "%s" rst-level-face-format-light) - rst-level-face-base-color - (+ (* (1- i) rst-level-face-step-light) - rst-level-face-base-light)))) - (make-empty-face sym) - (set-face-doc-string sym doc) - (set-face-background sym col) - (set sym sym) - (setq i (1+ i)))))) - -(defun rst-set-level-default (sym val) - "Set a customized value affecting section title text face and recompute the -faces." - (custom-set-default sym val) - ;; Also defines the faces initially when all values are available - (and (boundp 'rst-level-face-max) - (boundp 'rst-level-face-format-light) - (boundp 'rst-level-face-base-color) - (boundp 'rst-level-face-step-light) - (boundp 'rst-level-face-base-light) - (rst-define-level-faces))) - -;; Faces for displaying items on several levels; these definitions define -;; different shades of grey where the lightest one (i.e. least contrasting) is -;; used for level 1 -(defcustom rst-level-face-max 6 - "Maximum depth of levels for which section title faces are defined." - :group 'rst-faces-defaults - :type '(integer) - :set 'rst-set-level-default) -(defcustom rst-level-face-base-color "grey" - "The base name of the color to be used for creating background colors in -ection title faces for all levels." - :group 'rst-faces-defaults - :type '(string) - :set 'rst-set-level-default) -(defcustom rst-level-face-base-light - (if (eq frame-background-mode 'dark) - 15 - 85) - "The lightness factor for the base color. This value is used for level 1. The -default depends on whether the value of `frame-background-mode' is `dark' or -not." - :group 'rst-faces-defaults - :type '(integer) - :set 'rst-set-level-default) -(defcustom rst-level-face-format-light "%2d" - "The format for the lightness factor appended to the base name of the color. -This value is expanded by `format' with an integer." - :group 'rst-faces-defaults - :type '(string) - :set 'rst-set-level-default) -(defcustom rst-level-face-step-light - (if (eq frame-background-mode 'dark) - 7 - -7) - "The step width to use for the next color. The formula - - `rst-level-face-base-light' - + (`rst-level-face-max' - 1) * `rst-level-face-step-light' - -must result in a color level which appended to `rst-level-face-base-color' -using `rst-level-face-format-light' results in a valid color such as `grey50'. -This color is used as background for section title text on level -`rst-level-face-max'." - :group 'rst-faces-defaults - :type '(integer) - :set 'rst-set-level-default) - -(defcustom rst-adornment-faces-alist - (let ((alist '((t . font-lock-keyword-face) - (nil . font-lock-keyword-face))) - (i 1)) - (while (<= i rst-level-face-max) - (nconc alist (list (cons i (intern (format "rst-level-%d-face" i))))) - (setq i (1+ i))) - alist) - "Provides faces for the various adornment types. Key is a number (for the -section title text of that level), t (for transitions) or nil (for section -title adornment). If you generally do not like how section title text faces are -set up tweak here. If the general idea is ok for you but you do not like the -details check the Rst Faces Defaults group." - :group 'rst-faces - :type '(alist - :key-type - (choice - (integer - :tag - "Section level (may not be bigger than `rst-level-face-max')") - (boolean :tag "transitions (on) / section title adornment (off)")) - :value-type (face)) - :set-after '(rst-level-face-max)) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -;; FIXME: Code from `restructuredtext.el' should be integrated - -(defvar rst-mode-syntax-table nil - "Syntax table used while in rst mode.") - -(unless rst-mode-syntax-table - (setq rst-mode-syntax-table (make-syntax-table text-mode-syntax-table)) - (modify-syntax-entry ?$ "." rst-mode-syntax-table) - (modify-syntax-entry ?% "." rst-mode-syntax-table) - (modify-syntax-entry ?& "." rst-mode-syntax-table) - (modify-syntax-entry ?' "." rst-mode-syntax-table) - (modify-syntax-entry ?* "." rst-mode-syntax-table) - (modify-syntax-entry ?+ "." rst-mode-syntax-table) - (modify-syntax-entry ?. "_" rst-mode-syntax-table) - (modify-syntax-entry ?/ "." rst-mode-syntax-table) - (modify-syntax-entry ?< "." rst-mode-syntax-table) - (modify-syntax-entry ?= "." rst-mode-syntax-table) - (modify-syntax-entry ?> "." rst-mode-syntax-table) - (modify-syntax-entry ?\\ "\\" rst-mode-syntax-table) - (modify-syntax-entry ?| "." rst-mode-syntax-table) - (modify-syntax-entry ?_ "." rst-mode-syntax-table) - ) - -(defvar rst-mode-abbrev-table nil - "Abbrev table used while in rst mode.") -(define-abbrev-table 'rst-mode-abbrev-table ()) - -;; FIXME: Movement keys to skip forward / backward over or mark an indented -;; block could be defined; keys to markup section titles based on -;; `rst-adornment-level-alist' would be useful -(defvar rst-mode-map nil - "Keymap for rst mode. This inherits from Text mode.") - -(unless rst-mode-map - (setq rst-mode-map (copy-keymap text-mode-map))) - -(defun rst-mode () - "Major mode for editing reStructuredText documents. - -You may customize `rst-mode-lazy' to switch font-locking of blocks. - -\\{rst-mode-map} -Turning on `rst-mode' calls the normal hooks `text-mode-hook' and -`rst-mode-hook'." - (interactive) - (kill-all-local-variables) - - ;; Maps and tables - (use-local-map rst-mode-map) - (setq local-abbrev-table rst-mode-abbrev-table) - (set-syntax-table rst-mode-syntax-table) - - ;; For editing text - ;; - ;; FIXME: It would be better if this matches more exactly the start of a reST - ;; paragraph; however, this not always possible with a simple regex because - ;; paragraphs are determined by indentation of the following line - (set (make-local-variable 'paragraph-start) - (concat page-delimiter "\\|[ \t]*$")) - (if (eq ?^ (aref paragraph-start 0)) - (setq paragraph-start (substring paragraph-start 1))) - (set (make-local-variable 'paragraph-separate) paragraph-start) - (set (make-local-variable 'indent-line-function) 'indent-relative-maybe) - (set (make-local-variable 'adaptive-fill-mode) t) - (set (make-local-variable 'comment-start) ".. ") - - ;; Special variables - (make-local-variable 'rst-adornment-level-alist) - - ;; Font lock - (set (make-local-variable 'font-lock-defaults) - '(rst-font-lock-keywords-function - t nil nil nil - (font-lock-multiline . t) - (font-lock-mark-block-function . mark-paragraph))) - (when (boundp 'font-lock-support-mode) - ;; rst-mode has its own mind about font-lock-support-mode - (make-local-variable 'font-lock-support-mode) - (cond - ((and (not rst-mode-lazy) (not font-lock-support-mode))) - ;; No support mode set and none required - leave it alone - ((or (not font-lock-support-mode) ;; No support mode set (but required) - (symbolp font-lock-support-mode)) ;; or a fixed mode for all - (setq font-lock-support-mode - (list (cons 'rst-mode (and rst-mode-lazy 'lazy-lock-mode)) - (cons t font-lock-support-mode)))) - ((and (listp font-lock-support-mode) - (not (assoc 'rst-mode font-lock-support-mode))) - ;; A list of modes missing rst-mode - (setq font-lock-support-mode - (append '((cons 'rst-mode (and rst-mode-lazy 'lazy-lock-mode))) - font-lock-support-mode))))) - - ;; Names and hooks - (setq mode-name "reST") - (setq major-mode 'rst-mode) - (run-hooks 'text-mode-hook) - (run-hooks 'rst-mode-hook)) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Font lock - -(defun rst-font-lock-keywords-function () - "Returns keywords to highlight in rst mode according to current settings." - ;; The reST-links in the comments below all relate to sections in - ;; http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html - (let* ( ;; This gets big - so let's define some abbreviations - ;; horizontal white space - (re-hws "[\t ]") - ;; beginning of line with possible indentation - (re-bol (concat "^" re-hws "*")) - ;; Separates block lead-ins from their content - (re-blksep1 (concat "\\(" re-hws "+\\|$\\)")) - ;; explicit markup tag - (re-emt "\\.\\.") - ;; explicit markup start - (re-ems (concat re-emt re-hws "+")) - ;; inline markup prefix - (re-imp1 (concat "\\(^\\|" re-hws "\\|[-'\"([{</:]\\)")) - ;; inline markup suffix - (re-ims1 (concat "\\(" re-hws "\\|[]-'\")}>/:.,;!?\\]\\|$\\)")) - ;; symbol character - (re-sym1 "\\(\\sw\\|\\s_\\)") - ;; inline markup content begin - (re-imbeg2 "\\(\\S \\|\\S \\([^") - - ;; There seems to be a bug leading to error "Stack overflow in regexp - ;; matcher" when "|" or "\\*" are the characters searched for - (re-imendbeg - (if (< emacs-major-version 21) - "]" - "\\]\\|\\\\.")) - ;; inline markup content end - (re-imend (concat re-imendbeg "\\)*[^\t \\\\]\\)")) - ;; inline markup content without asterisk - (re-ima2 (concat re-imbeg2 "*" re-imend)) - ;; inline markup content without backquote - (re-imb2 (concat re-imbeg2 "`" re-imend)) - ;; inline markup content without vertical bar - (re-imv2 (concat re-imbeg2 "|" re-imend)) - ;; Supported URI schemes - (re-uris1 "\\(acap\\|cid\\|data\\|dav\\|fax\\|file\\|ftp\\|gopher\\|http\\|https\\|imap\\|ldap\\|mailto\\|mid\\|modem\\|news\\|nfs\\|nntp\\|pop\\|prospero\\|rtsp\\|service\\|sip\\|tel\\|telnet\\|tip\\|urn\\|vemmi\\|wais\\)") - ;; Line starting with adornment and optional whitespace; complete - ;; adornment is in (match-string 1); there must be at least 3 - ;; characters because otherwise explicit markup start would be - ;; recognized - (re-ado2 (concat "^\\(\\([" - (if (or - (< emacs-major-version 21) - (save-match-data - (string-match "XEmacs\\|Lucid" emacs-version))) - "^a-zA-Z0-9 \t\x00-\x1F" - "^[:word:][:space:][:cntrl:]") - "]\\)\\2\\2+\\)" re-hws "*$")) - ) - (list - ;; FIXME: Block markup is not recognized in blocks after explicit markup - ;; start - - ;; Simple `Body Elements`_ - ;; `Bullet Lists`_ - (list - (concat re-bol "\\([-*+]" re-blksep1 "\\)") - 1 rst-block-face) - ;; `Enumerated Lists`_ - (list - (concat re-bol "\\((?\\([0-9]+\\|[A-Za-z]\\|[IVXLCMivxlcm]+\\)[.)]" - re-blksep1 "\\)") - 1 rst-block-face) - ;; `Definition Lists`_ FIXME: missing - ;; `Field Lists`_ - (list - (concat re-bol "\\(:[^:]+:\\)" re-blksep1) - 1 rst-external-face) - ;; `Option Lists`_ - (list - (concat re-bol "\\(\\(\\(\\([-+/]\\|--\\)\\sw\\(-\\|\\sw\\)*" - "\\([ =]\\S +\\)?\\)\\(,[\t ]\\)?\\)+\\)\\($\\|[\t ]\\{2\\}\\)") - 1 rst-block-face) - - ;; `Tables`_ FIXME: missing - - ;; All the `Explicit Markup Blocks`_ - ;; `Footnotes`_ / `Citations`_ - (list - (concat re-bol "\\(" re-ems "\\[[^[]+\\]\\)" re-blksep1) - 1 rst-definition-face) - ;; `Directives`_ / `Substitution Definitions`_ - (list - (concat re-bol "\\(" re-ems "\\)\\(\\(|[^|]+|[\t ]+\\)?\\)\\(" - re-sym1 "+::\\)" re-blksep1) - (list 1 rst-directive-face) - (list 2 rst-definition-face) - (list 4 rst-directive-face)) - ;; `Hyperlink Targets`_ - (list - (concat re-bol "\\(" re-ems "_\\([^:\\`]\\|\\\\.\\|`[^`]+`\\)+:\\)" - re-blksep1) - 1 rst-definition-face) - (list - (concat re-bol "\\(__\\)" re-blksep1) - 1 rst-definition-face) - - ;; All `Inline Markup`_ - ;; FIXME: Condition 5 preventing fontification of e.g. "*" not implemented - ;; `Strong Emphasis`_ - (list - (concat re-imp1 "\\(\\*\\*" re-ima2 "\\*\\*\\)" re-ims1) - 2 rst-emphasis2-face) - ;; `Emphasis`_ - (list - (concat re-imp1 "\\(\\*" re-ima2 "\\*\\)" re-ims1) - 2 rst-emphasis1-face) - ;; `Inline Literals`_ - (list - (concat re-imp1 "\\(``" re-imb2 "``\\)" re-ims1) - 2 rst-literal-face) - ;; `Inline Internal Targets`_ - (list - (concat re-imp1 "\\(_`" re-imb2 "`\\)" re-ims1) - 2 rst-definition-face) - ;; `Hyperlink References`_ - ;; FIXME: `Embedded URIs`_ not considered - (list - (concat re-imp1 "\\(\\(`" re-imb2 "`\\|\\sw+\\)__?\\)" re-ims1) - 2 rst-reference-face) - ;; `Interpreted Text`_ - (list - (concat re-imp1 "\\(\\(:" re-sym1 "+:\\)?\\)\\(`" re-imb2 "`\\)\\(\\(:" - re-sym1 "+:\\)?\\)" re-ims1) - (list 2 rst-directive-face) - (list 5 rst-external-face) - (list 8 rst-directive-face)) - ;; `Footnote References`_ / `Citation References`_ - (list - (concat re-imp1 "\\(\\[[^]]+\\]_\\)" re-ims1) - 2 rst-reference-face) - ;; `Substitution References`_ - (list - (concat re-imp1 "\\(|" re-imv2 "|\\)" re-ims1) - 2 rst-reference-face) - ;; `Standalone Hyperlinks`_ - (list - ;; FIXME: This takes it easy by using a whitespace as delimiter - (concat re-imp1 "\\(" re-uris1 ":\\S +\\)" re-ims1) - 2 rst-definition-face) - (list - (concat re-imp1 "\\(" re-sym1 "+@" re-sym1 "+\\)" re-ims1) - 2 rst-definition-face) - - ;; Do all block fontification as late as possible so 'append works - - ;; Sections_ / Transitions_ - (append - (list - re-ado2) - (if (not rst-mode-lazy) - (list 1 rst-block-face) - (list - (list 'rst-font-lock-handle-adornment - '(progn - (setq rst-font-lock-adornment-point (match-end 1)) - (point-max)) - nil - (list 1 '(cdr (assoc nil rst-adornment-faces-alist)) - 'append t) - (list 2 '(cdr (assoc rst-font-lock-level - rst-adornment-faces-alist)) - 'append t) - (list 3 '(cdr (assoc nil rst-adornment-faces-alist)) - 'append t))))) - - ;; `Comments`_ - (append - (list - (concat re-bol "\\(" re-ems "\\)\[^[|_]\\([^:]\\|:\\([^:]\\|$\\)\\)*$") - (list 1 rst-comment-face)) - (if rst-mode-lazy - (list - (list 'rst-font-lock-find-unindented-line - '(progn - (setq rst-font-lock-indentation-point (match-end 1)) - (point-max)) - nil - (list 0 rst-comment-face 'append))))) - (append - (list - (concat re-bol "\\(" re-emt "\\)\\(\\s *\\)\\?$") - (list 1 rst-comment-face) - (list 2 rst-comment-face)) - (if rst-mode-lazy - (list - (list 'rst-font-lock-find-unindented-line - '(progn - (setq rst-font-lock-indentation-point 'next) - (point-max)) - nil - (list 0 rst-comment-face 'append))))) - - ;; `Literal Blocks`_ - (append - (list - (concat re-bol "\\(\\([^.\n]\\|\\.[^.\n]\\).*\\)?\\(::\\)$") - (list 3 rst-block-face)) - (if rst-mode-lazy - (list - (list 'rst-font-lock-find-unindented-line - '(progn - (setq rst-font-lock-indentation-point t) - (point-max)) - nil - (list 0 rst-literal-face 'append))))) - ))) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Indented blocks - -(defun rst-forward-indented-block (&optional column limit) - "Move forward across one indented block. -Find the next non-empty line which is not indented at least to COLUMN (defaults -to the column of the point). Moves point to first character of this line or the -first empty line immediately before it and returns that position. If there is -no such line before LIMIT (defaults to the end of the buffer) returns nil and -point is not moved." - (interactive) - (let ((clm (or column (current-column))) - (start (point)) - fnd beg cand) - (if (not limit) - (setq limit (point-max))) - (save-match-data - (while (and (not fnd) (< (point) limit)) - (forward-line 1) - (when (< (point) limit) - (setq beg (point)) - (if (looking-at "\\s *$") - (setq cand (or cand beg)) ; An empty line is a candidate - (move-to-column clm) - ;; FIXME: No indentation [(zerop clm)] must be handled in some - ;; useful way - though it is not clear what this should mean at all - (if (string-match - "^\\s *$" (buffer-substring-no-properties beg (point))) - (setq cand nil) ; An indented line resets a candidate - (setq fnd (or cand beg))))))) - (goto-char (or fnd start)) - fnd)) - -;; Stores the point where the current indentation ends if a number. If `next' -;; indicates `rst-font-lock-find-unindented-line' shall take the indentation -;; from the next line if this is not empty. If non-nil indicates -;; `rst-font-lock-find-unindented-line' shall take the indentation from the -;; next non-empty line. Also used as a trigger for -;; `rst-font-lock-find-unindented-line'. -(defvar rst-font-lock-indentation-point nil) - -(defun rst-font-lock-find-unindented-line (limit) - (let* ((ind-pnt rst-font-lock-indentation-point) - (beg-pnt ind-pnt)) - ;; May run only once - enforce this - (setq rst-font-lock-indentation-point nil) - (when (and ind-pnt (not (numberp ind-pnt))) - ;; Find indentation point in next line if any - (setq ind-pnt - (save-excursion - (save-match-data - (if (eq ind-pnt 'next) - (when (and (zerop (forward-line 1)) (< (point) limit)) - (setq beg-pnt (point)) - (when (not (looking-at "\\s *$")) - (looking-at "\\s *") - (match-end 0))) - (while (and (zerop (forward-line 1)) (< (point) limit) - (looking-at "\\s *$"))) - (when (< (point) limit) - (setq beg-pnt (point)) - (looking-at "\\s *") - (match-end 0))))))) - (when ind-pnt - (goto-char ind-pnt) - ;; Always succeeds because the limit set by PRE-MATCH-FORM is the - ;; ultimate point to find - (goto-char (or (rst-forward-indented-block nil limit) limit)) - (set-match-data (list beg-pnt (point))) - t))) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Adornments - -;; Stores the point where the current adornment ends. Also used as a trigger -;; for `rst-font-lock-handle-adornment'. -(defvar rst-font-lock-adornment-point nil) - -;; Here `rst-font-lock-handle-adornment' stores the section level of the -;; current adornment or t for a transition. -(defvar rst-font-lock-level nil) - -;; FIXME: It would be good if this could be used to markup section titles of -;; given level with a special key; it would be even better to be able to -;; customize this so it can be used for a generally available personal style -;; -;; FIXME: There should be some way to reset and reload this variable - probably -;; a special key -;; -;; FIXME: Some support for `outline-mode' would be nice which should be based -;; on this information -(defvar rst-adornment-level-alist nil - "Associates adornments with section levels. -The key is a two character string. The first character is the adornment -character. The second character distinguishes underline section titles (`u') -from overline/underline section titles (`o'). The value is the section level. - -This is made buffer local on start and adornments found during font lock are -entered.") - -;; Returns section level for adornment key KEY. Adds new section level if KEY -;; is not found and ADD. If KEY is not a string it is simply returned. -(defun rst-adornment-level (key &optional add) - (let ((fnd (assoc key rst-adornment-level-alist)) - (new 1)) - (cond - ((not (stringp key)) - key) - (fnd - (cdr fnd)) - (add - (while (rassoc new rst-adornment-level-alist) - (setq new (1+ new))) - (setq rst-adornment-level-alist - (append rst-adornment-level-alist (list (cons key new)))) - new)))) - -;; Classifies adornment for section titles and transitions. ADORNMENT is the -;; complete adornment string as found in the buffer. END is the point after the -;; last character of ADORNMENT. For overline section adornment LIMIT limits the -;; search for the matching underline. Returns a list. The first entry is t for -;; a transition, or a key string for `rst-adornment-level' for a section title. -;; The following eight values forming four match groups as can be used for -;; `set-match-data'. First match group contains the maximum points of the whole -;; construct. Second and last match group matched pure section title adornment -;; while third match group matched the section title text or the transition. -;; Each group but the first may or may not exist. -(defun rst-classify-adornment (adornment end limit) - (save-excursion - (save-match-data - (goto-char end) - (let ((ado-ch (aref adornment 0)) - (ado-re (regexp-quote adornment)) - (end-pnt (point)) - (beg-pnt (progn - (forward-line 0) - (point))) - (nxt-emp - (save-excursion - (or (not (zerop (forward-line 1))) - (looking-at "\\s *$")))) - (prv-emp - (save-excursion - (or (not (zerop (forward-line -1))) - (looking-at "\\s *$")))) - key beg-ovr end-ovr beg-txt end-txt beg-und end-und) - (cond - ((and nxt-emp prv-emp) - ;; A transition - (setq key t) - (setq beg-txt beg-pnt) - (setq end-txt end-pnt)) - (prv-emp - ;; An overline - (setq key (concat (list ado-ch) "o")) - (setq beg-ovr beg-pnt) - (setq end-ovr end-pnt) - (forward-line 1) - (setq beg-txt (point)) - (while (and (< (point) limit) (not end-txt)) - (if (looking-at "\\s *$") - ;; No underline found - (setq end-txt (1- (point))) - (when (looking-at (concat "\\(" ado-re "\\)\\s *$")) - (setq end-und (match-end 1)) - (setq beg-und (point)) - (setq end-txt (1- beg-und)))) - (forward-line 1))) - (t - ;; An underline - (setq key (concat (list ado-ch) "u")) - (setq beg-und beg-pnt) - (setq end-und end-pnt) - (setq end-txt (1- beg-und)) - (setq beg-txt (progn - (if (re-search-backward "^\\s *$" 1 'move) - (forward-line 1)) - (point))))) - (list key - (or beg-ovr beg-txt beg-und) - (or end-und end-txt end-und) - beg-ovr end-ovr beg-txt end-txt beg-und end-und))))) - -;; Handles adornments for font-locking section titles and transitions. Returns -;; three match groups. First and last match group matched pure overline / -;; underline adornment while second group matched section title text. Each -;; group may not exist. -(defun rst-font-lock-handle-adornment (limit) - (let ((ado-pnt rst-font-lock-adornment-point)) - ;; May run only once - enforce this - (setq rst-font-lock-adornment-point nil) - (if ado-pnt - (let* ((ado (rst-classify-adornment (match-string-no-properties 1) - ado-pnt limit)) - (key (car ado)) - (mtc (cdr ado))) - (setq rst-font-lock-level (rst-adornment-level key t)) - (goto-char (nth 1 mtc)) - (set-match-data mtc) - t)))) - -;;; rst-mode.el ends here - - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Support for conversion from within Emacs - -(defgroup rst-compile nil - "Settings for support of conversion of reStructuredText -document with \\[rst-compile]." - :group 'rst - :version "21.1") - -(defvar rst-compile-toolsets - '((html . ("rst2html.py" ".html" nil)) - (latex . ("rst2latex.py" ".tex" nil)) - (newlatex . ("rst2newlatex.py" ".tex" nil)) - (pseudoxml . ("rst2pseudoxml.py" ".xml" nil)) - (xml . ("rst2xml.py" ".xml" nil))) - "An association list of the toolset to a list of the (command to use, -extension of produced filename, options to the tool (nil or a -string)) to be used for converting the document.") - -;; Note for Python programmers not familiar with association lists: you can set -;; values in an alists like this, e.g. : -;; (setcdr (assq 'html rst-compile-toolsets) -;; '("rst2html.py" ".htm" "--stylesheet=/docutils.css")) - - -(defvar rst-compile-primary-toolset 'html - "The default toolset for rst-compile.") - -(defvar rst-compile-secondary-toolset 'latex - "The default toolset for rst-compile with a prefix argument.") - -(defun rst-compile-find-conf () - "Look for the configuration file in the parents of the current path." - (interactive) - (let ((file-name "docutils.conf") - (buffer-file (buffer-file-name))) - ;; Move up in the dir hierarchy till we find a change log file. - (let ((dir (file-name-directory buffer-file))) - (while (and (or (not (string= "/" dir)) (setq dir nil) nil) - (not (file-exists-p (concat dir file-name)))) - ;; Move up to the parent dir and try again. - (setq dir (expand-file-name (file-name-directory - (directory-file-name - (file-name-directory dir))))) ) - (or (and dir (concat dir file-name)) nil) - ))) - -(defun rst-compile (&optional pfxarg) - "Compile command to convert reST document into some output file. -Attempts to find configuration file, if it can, overrides the -options." - (interactive "P") - ;; Note: maybe we want to check if there is a Makefile too and not do anything - ;; if that is the case. I dunno. - (let* ((toolset (cdr (assq (if pfxarg - rst-compile-secondary-toolset - rst-compile-primary-toolset) - rst-compile-toolsets))) - (command (car toolset)) - (extension (cadr toolset)) - (options (caddr toolset)) - (conffile (rst-compile-find-conf)) - (bufname (file-name-nondirectory buffer-file-name)) - (outname (file-name-sans-extension bufname))) - - ;; Set compile-command before invocation of compile. - (set (make-local-variable 'compile-command) - (mapconcat 'identity - (list command - (or options "") - (if conffile - (concat "--config=\"" conffile "\"") - "") - bufname - (concat outname extension)) - " ")) - - ;; Invoke the compile command. - (if (or compilation-read-command current-prefix-arg) - (call-interactively 'compile) - (compile compile-command)) - )) - - - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; -;; Generic text functions that are more convenient than the defaults. -;; - -(defun replace-lines (fromchar tochar) - "Replace flush-left lines, consisting of multiple FROMCHAR characters, -with equal-length lines of TOCHAR." - (interactive "\ -cSearch for flush-left lines of char: -cand replace with char: ") - (save-excursion - (let* ((fromstr (string fromchar)) - (searchre (concat "^" (regexp-quote fromstr) "+ *$")) - (found 0)) - (condition-case err - (while t - (search-forward-regexp searchre) - (setq found (1+ found)) - (search-backward fromstr) ;; point will be *before* last char - (setq p (1+ (point))) - (beginning-of-line) - (setq l (- p (point))) - (rst-delete-line) - (insert-char tochar l)) - (search-failed - (message (format "%d lines replaced." found))))))) - -(defun join-paragraph () - "Join lines in current paragraph into one line, removing end-of-lines." - (interactive) - (let ((fill-column 65000)) ; some big number - (call-interactively 'fill-paragraph))) - -;; FIXME: can we remove this? -(defun force-fill-paragraph () - "Fill paragraph at point, first joining the paragraph's lines into one. -This is useful for filling list item paragraphs." - (interactive) - (join-paragraph) - (fill-paragraph nil)) - - -;; Generic character repeater function. -;; For sections, better to use the specialized function above, but this can -;; be useful for creating separators. -(defun repeat-last-character (&optional tofill) - "Fills the current line up to the length of the preceding line (if not -empty), using the last character on the current line. If the preceding line is -empty, we use the fill-column. - -If a prefix argument is provided, use the next line rather than the preceding -line. - -If the current line is longer than the desired length, shave the characters off -the current line to fit the desired length. - -As an added convenience, if the command is repeated immediately, the alternative -column is used (fill-column vs. end of previous/next line)." - (interactive) - (let* ((curcol (current-column)) - (curline (+ (count-lines (point-min) (point)) - (if (eq curcol 0) 1 0))) - (lbp (line-beginning-position 0)) - (prevcol (if (and (= curline 1) (not current-prefix-arg)) - fill-column - (save-excursion - (forward-line (if current-prefix-arg 1 -1)) - (end-of-line) - (skip-chars-backward " \t" lbp) - (let ((cc (current-column))) - (if (= cc 0) fill-column cc))))) - (rightmost-column - (cond (tofill fill-column) - ((equal last-command 'repeat-last-character) - (if (= curcol fill-column) prevcol fill-column)) - (t (save-excursion - (if (= prevcol 0) fill-column prevcol))) - )) ) - (end-of-line) - (if (> (current-column) rightmost-column) - ;; shave characters off the end - (delete-region (- (point) - (- (current-column) rightmost-column)) - (point)) - ;; fill with last characters - (insert-char (preceding-char) - (- rightmost-column (current-column)))) - )) - - - -(provide 'rst) -;;; rst.el ends here diff --git a/docutils/tools/editors/emacs/tests/Makefile b/docutils/tools/editors/emacs/tests/Makefile deleted file mode 100644 index ea024e3fd..000000000 --- a/docutils/tools/editors/emacs/tests/Makefile +++ /dev/null @@ -1,9 +0,0 @@ - -runtests: - emacs-21 --batch -l tests-basic.el - emacs-21 --batch -l tests-adjust-section.el - -runtests-emacs-cvs: - emacs --script tests-basic.el - emacs --script tests-adjust-section.el - diff --git a/docutils/tools/editors/emacs/tests/README b/docutils/tools/editors/emacs/tests/README deleted file mode 100644 index a1f4b0e4a..000000000 --- a/docutils/tools/editors/emacs/tests/README +++ /dev/null @@ -1,27 +0,0 @@ -========================================== - Tests for automatic section adjustment -========================================== - -:Author: Martin Blais <blais@furius.ca> -:Date: 2005-09-03 - - -Running the tests -================= - -To run the test suite, you can either evaluate the relevant progn from within -emacs, or you can run them from the command-line like this, e.g.:: - - emacs --script tests-basic.el - -See the Makefile for more details. - -Status -====== - -We are planning to write many more tests and eventually to rewrite the -interactive section adjustment because it contains a few bugs (it nonetheless -pretty much works well otherwise). Some of those bugs have been added and are -currently failing if you run the tests. - -(See the FIXME statements for where to continue.) diff --git a/docutils/tools/editors/emacs/tests/tests-adjust-section.el b/docutils/tools/editors/emacs/tests/tests-adjust-section.el deleted file mode 100644 index a4d39f2bc..000000000 --- a/docutils/tools/editors/emacs/tests/tests-adjust-section.el +++ /dev/null @@ -1,830 +0,0 @@ -;; Authors: Martin Blais <blais@furius.ca> -;; Date: $Date: 2005/04/01 23:19:41 $ -;; Copyright: This module has been placed in the public domain. -;; -;; Regression tests for rst-adjust-section-title. -;; -;; Run this with:: -;; -;; emacs --script tests-adjust-section.el -;; -;; See test-runner.el for documentation on how the format of tests. - - -;; Define tests. -(setq rst-adjust-decoration-tests - '( -;;------------------------------------------------------------------------------ -(nodec-first-simple-1 -" -Some Title@ - -" -" -============ - Some Title -============ - -" -) - -;;------------------------------------------------------------------------------ -(nodec-first-simple-2 -" -Some Title -@ -" -" -============ - Some Title -============ - -" -) - -;;------------------------------------------------------------------------------ -(nodec-first-simple-3 -" -Some Tit@le - -" -" -============ - Some Title -============ - -" -) - -;;------------------------------------------------------------------------------ -(nodec-first-simple-4 -" -@Some Title - -" -" -============ - Some Title -============ - -") - - -;;------------------------------------------------------------------------------ -(nodec-first-simple-others -" -Some Title@ - -Other Title ------------ - -Other Title2 -~~~~~~~~~~~~ - -" -" -============ - Some Title -============ - -Other Title ------------ - -Other Title2 -~~~~~~~~~~~~ - -" -) - - -;;------------------------------------------------------------------------------ -(nodec-first-toggle -" -Some Title@ - -" -" -Some Title -========== - -" -(t)) - -;;------------------------------------------------------------------------------ -(nodec-first-forced -" - Some Title@ - -" -" -================ - Some Title -================ - -" -) - -;;------------------------------------------------------------------------------ -(nodec-first-forced-2 -" - Some Title@ - -" -" -Some Title -========== - -" -(t)) - -;;------------------------------------------------------------------------------ -(nodec-simple -" -Previous Title --------------- - -Some Title@ - -" -" -Previous Title --------------- - -Some Title -~~~~~~~~~~ - -" -) - -;;------------------------------------------------------------------------------ -(nodec-simple-neg -" -Previous Title --------------- - -Some Title@ - -Next Title -~~~~~~~~~~ - -" -" -Previous Title --------------- - -Some Title -~~~~~~~~~~ - -Next Title -~~~~~~~~~~ - -" -) - -;;------------------------------------------------------------------------------ -(nodec-simple-toggle -" -Previous Title --------------- - -Some Title@ - -" -" -Previous Title --------------- - -~~~~~~~~~~ -Some Title -~~~~~~~~~~ - -" -(t)) - -;;------------------------------------------------------------------------------ -(nodec-simple-force-toggle -" -Previous Title --------------- - - Some Title@ - -" -" -Previous Title --------------- - -~~~~~~~~~~~~~~ - Some Title -~~~~~~~~~~~~~~ - -" -(t)) - - -;;------------------------------------------------------------------------------ -(nodec-simple-forced -" -Previous Title --------------- - - Some Title@ - -" -" -Previous Title --------------- - -Some Title -~~~~~~~~~~ - -" -) - -;;------------------------------------------------------------------------------ -(nodec-neg -" -Previous Title --------------- - -Some Title@ - -Next Title -~~~~~~~~~~ -" -" -Previous Title --------------- - -Some Title ----------- - -Next Title -~~~~~~~~~~ -" -(-1)) - -;;------------------------------------------------------------------------------ -(incomplete-simple-1 -" -Previous Title@ ----------- -" -" -Previous Title --------------- - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-simple-2 -" -Previous Title -----------@ -" -" -Previous Title --------------- - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-simple-3 -" -Previous Title --@ -" -" -================ - Previous Title -================ - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-simple-too-long -" -Previous Title -------------------@ -" -" -Previous Title --------------- - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-simple-uo -" ----------------- - Previous Title -----------@ -" -" ----------------- - Previous Title ----------------- - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-partial-overline -" -----------@ - Previous Title ----------------- -" -" ----------------- - Previous Title ----------------- - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-both -" ----------- - Previous Title@ ------ -" -" ----------------- - Previous Title ----------------- - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-toggle -" -Previous Title -----------@ -" -" --------------- -Previous Title --------------- - -" -(t)) - -;;------------------------------------------------------------------------------ -(incomplete-toggle-2 -" ----------------- - Previous Title@ --------- -" -" -Previous Title --------------- - -" -(t)) - -;;------------------------------------------------------------------------------ -(incomplete-toggle-overline -" ---------@ - Previous Title ----------------- -" -" -Previous Title --------------- - -" -(t)) - -;;------------------------------------------------------------------------------ -(incomplete-top -"--------@ - Previous Title ----------------- -" -"---------------- - Previous Title ----------------- - -" -) - -;;------------------------------------------------------------------------------ -(incomplete-top-2 -"======= -Document Title@ -============== -" -"============== -Document Title -============== - -" -) - -;;------------------------------------------------------------------------------ -(complete-simple -" -================ - Document Title -================ - -SubTitle --------- - -My Title@ --------- - -After Title -~~~~~~~~~~~ - -" -" -================ - Document Title -================ - -SubTitle --------- - -========== - My Title -========== - -After Title -~~~~~~~~~~~ - -" -) - -;;------------------------------------------------------------------------------ -(complete-simple-neg -" -================ - Document Title -================ - -SubTitle --------- - -My Title@ --------- - -After Title -~~~~~~~~~~~ - -" -" -================ - Document Title -================ - -SubTitle --------- - -My Title -~~~~~~~~ - -After Title -~~~~~~~~~~~ - -" -(-1)) - -;;------------------------------------------------------------------------------ -(complete-simple-suggestion-down -" -================ - Document Title -================ - -SubTitle -======== - -My Title@ -======== - -" -" -================ - Document Title -================ - -SubTitle -======== - -My Title --------- - -" -(-1)) - -;;------------------------------------------------------------------------------ -(complete-simple-boundary-down -" -================ - Document Title -================ - -SubTitle -======== - -My Title@ --------- - -" -" -================ - Document Title -================ - -SubTitle -======== - -========== - My Title -========== - -" -(-1)) - -;;------------------------------------------------------------------------------ -(complete-simple-suggestion-up -" -================ - Document Title -================ - -SubTitle -======== - -========== - My Title@ -========== - -" -" -================ - Document Title -================ - -SubTitle -======== - -My Title --------- - -" -) - -;;------------------------------------------------------------------------------ -(complete-simple-boundary-up ;; Note: boundary-up does not exist. -" -================ - Document Title -================ - -SubTitle -======== - -My Title@ --------- -" -" -================ - Document Title -================ - -SubTitle -======== - -My Title -======== - -" -) - -;;------------------------------------------------------------------------------ -(complete-toggle-1 -" -SubTitle@ -~~~~~~~~ - -" -" -~~~~~~~~~~ - SubTitle -~~~~~~~~~~ - -" -(t)) - -;;------------------------------------------------------------------------------ -(complete-toggle-2 -" -~~~~~~~~~~ - SubTitle@ -~~~~~~~~~~ - -" -" -SubTitle -~~~~~~~~ - -" -(t)) - -;;------------------------------------------------------------------------------ -(at-file-beginning -" -Document Title@ - -" -" -================ - Document Title@ -================ - -" -) - - -;;------------------------------------------------------------------------------ -(at-file-ending -" - -Document Title@ -" -" - -================ - Document Title@ -================ - -" -) - -;;------------------------------------------------------------------------------ -(at-file-ending-2 -" - -Document Title@" -" - -================ - Document Title@ -================ -" -) - -;;------------------------------------------------------------------------------ -(conjoint -" -Document Title -============== -Subtitle@ - -" -" -Document Title -============== -Subtitle@ --------- - -" -) - -;;------------------------------------------------------------------------------ -(same-conjoint-2 -"============== -Document Title@ -============== -Subtitle -======== - -" -"Document Title@ -============== -Subtitle -======== - -" -) - -;;------------------------------------------------------------------------------ -(same-conjoint-2b -" -============== -Document Title@ -============== -Subtitle -======== - -" -" -Document Title@ -============== -Subtitle -======== - -" -) - - -;;------------------------------------------------------------------------------ -(same-conjoint-2 -" -============== -Document Title -============== -=============== -Document Title2@ -=============== - -" -" -============== -Document Title -============== -Document Title2 -=============== - -" -) - -;; FIXME: todo -;; ;;------------------------------------------------------------------------------ -;; (cycle-previous-only -;; " -;; ================== -;; Document Title -;; ================== -;; -;; Document Title2 -;; =============== -;; -;; ======= -;; Bli@ -;; ======= -;; -;; Document Title2 -;; =============== -;; -;; Document Title3 -;; --------------- -;; -;; Document Title4 -;; ~~~~~~~~~~~~~~~ -;; -;; " -;; " -;; ================== -;; Document Title -;; ================== -;; -;; Document Title2 -;; =============== -;; -;; Bli@ -;; --- -;; -;; Document Title2 -;; =============== -;; -;; Document Title3 -;; --------------- -;; -;; Document Title4 -;; ~~~~~~~~~~~~~~~ -;; -;; " -;; ) - -)) - - -;; Main program. Evaluate this to run the tests. -;; (setq debug-on-error t) - -;; Import the module from the file in the parent directory directly. -(add-to-list 'load-path ".") -(load "tests-runner.el") -(add-to-list 'load-path "..") -(load "rst.el") - -(progn - (regression-test-compare-expect-buffer - "Test interactive adjustment of sections." - rst-adjust-decoration-tests - (lambda () - (call-interactively 'rst-adjust)) - nil)) - diff --git a/docutils/tools/editors/emacs/tests/tests-basic.el b/docutils/tools/editors/emacs/tests/tests-basic.el deleted file mode 100644 index 5f94304ce..000000000 --- a/docutils/tools/editors/emacs/tests/tests-basic.el +++ /dev/null @@ -1,813 +0,0 @@ -;; Authors: Martin Blais <blais@furius.ca> -;; Date: $Date: 2005/04/01 23:19:41 $ -;; Copyright: This module has been placed in the public domain. -;; -;; Regression tests for rst-adjust-section-title. -;; -;; Run this with:: -;; -;; emacs --script tests-adjust-section.el -;; -;; See test-runner.el for documentation on how the format of tests. - - -;; Import the module from the file in the parent directory directly. -(add-to-list 'load-path ".") -(load "tests-runner.el") -(add-to-list 'load-path "..") -(load "rst.el") - -;; (setq debug-on-error t) - - -(setq rst-line-homogeneous-p-tests - '( -;;------------------------------------------------------------------------------ -(simple "Blablabla bla@" nil) -(true "-----------@" ?-) -(indented " -----------@" ?-) -(letter "aaaa@aaa" ?a) -(true2 "uuuuuuuuuuuuuuuuu@" ?u) -(misleading "--=---------@" nil) -(notstrip " uuuuuuuuuuuuuuuuu@" ?u) -(notstrip2 " uuuuuuuuuuuuuuuuu @" ?u) -(position "-------@----" ?-) -(one-char "-@" nil) -)) - -(progn - (regression-test-compare-expect-values - "Tests for predicate for one char line." - rst-line-homogeneous-p-tests 'rst-line-homogeneous-p nil)) - -(setq rst-line-homogeneous-nodent-p-tests - '( -;;------------------------------------------------------------------------------ -(simple "Blablabla bla@" nil) -(true "-----------@" ?-) -(indented " -----------@" nil) -(letter "aaaa@aaa" ?a) -(true2 "uuuuuuuuuuuuuuuuu@" ?u) -(misleading "--=---------@" nil) -(notstrip " uuuuuuuuuuuuuuuuu@" nil) -(notstrip2 " uuuuuuuuuuuuuuuuu @" nil) -(position "-------@----" ?-) -(one-char "-@" nil) -)) - -(progn - (regression-test-compare-expect-values - "Tests for predicate for one char line." - rst-line-homogeneous-nodent-p-tests 'rst-line-homogeneous-nodent-p nil)) - - - - -(setq rst-normalize-cursor-position-tests - '( -;;------------------------------------------------------------------------------ -(under -" - -Du bon vin tous les jours. -@ -" -" - -@Du bon vin tous les jours. - -" -) - -;;------------------------------------------------------------------------------ -(over -" -@ -Du bon vin tous les jours. - -" -" - -@Du bon vin tous les jours. - -" -) - -;;------------------------------------------------------------------------------ -(underline -" - -Du bon vin tous les jours. -------@----- -" -" - -@Du bon vin tous les jours. ------------ -" -) - -;;------------------------------------------------------------------------------ -(overline -" -------@----- -Du bon vin tous les jours. - -" -" ------------ -@Du bon vin tous les jours. - -" -) - -;;------------------------------------------------------------------------------ -(both -" -@----------- -Du bon vin tous les jours. ------------ - -" -" ------------ -@Du bon vin tous les jours. ------------ - -" -) - -;;------------------------------------------------------------------------------ -(joint -" -Du bon vin tous les jours. -@----------- -Du bon vin tous les jours. ------------ - -" -" -@Du bon vin tous les jours. ------------ -Du bon vin tous les jours. ------------ - -" -) - -;;------------------------------------------------------------------------------ -(separator -" - -@----------- - -" -" - -@----------- - -" -) - -;;------------------------------------------------------------------------------ -(between -" -Line 1 -@ -Line 2 - -" -" -@Line 1 - -Line 2 - -" -) - -;;------------------------------------------------------------------------------ -(between-2 -" -===================================== - Project Idea: Panorama Stitcher -==================================== - -:Author: Martin Blais <blais@furius.ca> -@ -Another Title -============= -" -" -===================================== - Project Idea: Panorama Stitcher -==================================== - -@:Author: Martin Blais <blais@furius.ca> - -Another Title -============= -" -) - -)) - - -(progn - (regression-test-compare-expect-buffer - "Test preparation of cursor position." - rst-normalize-cursor-position-tests 'rst-normalize-cursor-position nil)) - - - - - - - -(setq rst-get-decoration-tests - '( -;;------------------------------------------------------------------------------ -(nodec-1 -" - -@Du bon vin tous les jours - -" -(nil nil 0)) - -;;------------------------------------------------------------------------------ -(nodec-2 -" - -@ -Du bon vin tous les jours - -" -(nil nil 0)) - -;;------------------------------------------------------------------------------ -(nodec-indent -" - -@ Du bon vin tous les jours - -" -(nil nil 2)) - -;;------------------------------------------------------------------------------ -(underline -" - -@Du bon vin tous les jours -========================= - -" -(?= simple 0)) - -;;------------------------------------------------------------------------------ -(underline-incomplete -" - -@Du bon vin tous les jours -==================== - -" -(?= simple 0)) - -;;------------------------------------------------------------------------------ -(underline-indent -" - -@ Du bon vin tous les jours -==================== - -" -(?= simple 5)) - -;;------------------------------------------------------------------------------ -(underline-one-char -" - -@Du bon vin tous les jours -- -" -(nil nil 0)) - -;;------------------------------------------------------------------------------ -(underline-two-char -" - -@Du bon vin tous les jours --- -" -(?- simple 0)) - -;;------------------------------------------------------------------------------ -(over-and-under -" -~~~~~~~~~~~~~~~~~~~~~~~~~ -@Du bon vin tous les jours -~~~~~~~~~~~~~~~~~~~~~~~~~ - -" -(?~ over-and-under 0)) - -;;------------------------------------------------------------------------------ -(over-and-under-top -"~~~~~~~~~~~~~~~~~~~~~~~~~ -@Du bon vin tous les jours -~~~~~~~~~~~~~~~~~~~~~~~~~ - -" -(?~ over-and-under 0)) - -;;------------------------------------------------------------------------------ -(over-and-under-indent -" -~~~~~~~~~~~~~~~~~~~~~~~~~ -@ Du bon vin tous les jours -~~~~~~~~~~~~~~~~~~~~~~~~~ - -" -(?~ over-and-under 3)) - -;;------------------------------------------------------------------------------ -(over-and-under-incomplete -" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -@Du bon vin tous les jours -~~~~~~~~~~~~~~~~~~~ - -" -(?~ over-and-under 0)) - -;;------------------------------------------------------------------------------ -(over-and-under-different-chars -" ---------------------------- -@Du bon vin tous les jours -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -" -(?~ over-and-under 0)) - - -;;------------------------------------------------------------------------------ -(not-beginning -" - -Du bon vin to@us les jours -========================= - -" -(?= simple 0)) - -;;------------------------------------------------------------------------------ -(over-over-and-under -" -@ -========================= -Du bon vin tous les jours -========================= -" -(nil nil 0)) - -;;------------------------------------------------------------------------------ -(joint-1 -" -========================= -Du bon vin tous les jours -========================= -Du bon vin@ - -" -(nil nil 0)) - -;;------------------------------------------------------------------------------ -(joint-2 -" -========================= -Du bon vin tous les jours -========================= -Du bon vin@ ----------- - -" -(45 simple 0)) - -;;------------------------------------------------------------------------------ -(joint-3 -" -========================= -Du bon vin tous les jours -========================= ----------- -Du bon vin@ ----------- - -" -(45 over-and-under 0)) - -;;------------------------------------------------------------------------------ -(joint-4 -" -========================= -Du bon vin tous les jours -========================= --------------- - Du bon vin@ --------------- - -" -(45 over-and-under 2)) - -;;------------------------------------------------------------------------------ -(indented-1 -" - - Du bon vin tous les jours@ - ========================= - -" -(nil nil 2)) - -)) - - -(progn - (regression-test-compare-expect-values - "Test getting the decoration." - rst-get-decoration-tests 'rst-get-decoration nil)) - - - - - - - - - - - - - - -(setq text-1 -"=============================== - Project Idea: My Document -=============================== - -:Author: Martin Blais - -Introduction -============ - -This is the introduction. - -Notes ------ - -Some notes. - -Main Points -=========== - -Yep. - -Super Point ------------ - -~~~~~~~~~~~ -@ Sub Point -~~~~~~~~~~~ - -Isn't this fabulous? - -Conclusion -========== - -That's it, really. - -") - - -(setq text-2 -" - -Previous --------- - -Current@ -~~~~~~~ - -Next -++++ - -") - -(setq text-3 -" - -Previous --------- - -Current@ -~~~~~~~ - - Next - ++++ - -") - -;; ~~~~~~~~~~~~~~~~~~ -;; Buggy Decoration -;; ~~~~~~ -;; -;; ~~~~~~~~~~~~ -;; Decoration -;; -;; -;; ========== - -(setq rst-find-all-decorations-tests - `( - ;;------------------------------------------------------------------------------ - (basic-1 ,text-1 - ((2 61 over-and-under 3) - (7 61 simple 0) - (12 45 simple 0) - (17 61 simple 0) - (22 45 simple 0) - (26 126 over-and-under 1) - (31 61 simple 0)) - ) - - (basic-2 ,text-2 - ((3 45 simple 0) - (6 126 simple 0) - (9 43 simple 0)) - ) - - (basic-3 ,text-3 - ((3 45 simple 0) - (6 126 simple 0)) - ) - - )) - - -(progn - (regression-test-compare-expect-values - "Test finding all the decorations in a file." - rst-find-all-decorations-tests 'rst-find-all-decorations nil)) - - - - -(setq rst-get-hierarchy-tests - `( - ;;------------------------------------------------------------------------------ - (basic-1 ,text-1 - ((61 over-and-under 3) - (61 simple 0) - (45 simple 0) - (126 over-and-under 1)) - ) - )) - -(progn - (regression-test-compare-expect-values - "Test finding the hierarchy of sections in a file." - rst-get-hierarchy-tests 'rst-get-hierarchy nil)) - - - - -(setq rst-get-hierarchy-ignore-tests - `( - ;;------------------------------------------------------------------------------ - (basic-1 ,text-1 - ((61 over-and-under 3) - (61 simple 0) - (45 simple 0)) - ) - )) - -(progn - (regression-test-compare-expect-values - "Test finding the hierarchy of sections in a file, ignoring lines." - rst-get-hierarchy-ignore-tests - (lambda () (rst-get-hierarchy nil (line-number-at-pos))) nil)) - - - - - - - -(setq rst-decoration-complete-p-tests - '( -;;------------------------------------------------------------------------------ -(nodec -" - -@Vaudou - -" nil ((?= simple 0))) - -;;------------------------------------------------------------------------------ -(complete-simple -" -@Vaudou -====== -" t ((?= simple 0))) - -;;------------------------------------------------------------------------------ -(complete-over-and-under -" -====== -@Vaudou -====== -" t ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(complete-over-and-under-indent -" -========== -@ Vaudou -========== -" t ((?= over-and-under 2))) - -;;------------------------------------------------------------------------------ -(incomplete-simple-short -" -@Vaudou -===== -" nil ((?= simple 0))) - -;;------------------------------------------------------------------------------ -(incomplete-simple-long -" -@Vaudou -======= -" nil ((?= simple 0))) - -;;------------------------------------------------------------------------------ -(incomplete-simple-mixed -" -@Vaudou -===-== -" nil ((?= simple 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-1 -" -====== -@Vaudou -===== -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-2 -" -===== -@Vaudou -====== -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-mixed-1 -" -====== -@Vaudou -===-== -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-mixed-2 -" -===-== -@Vaudou -====== -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-only -" -====== -@Vaudou - -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-mixed -" -====== -@Vaudou ------- -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-1 -" -========== - @Vaudou -========= -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-2 -" -========= - @Vaudou -========== -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-mixed-1 -" -========== - @Vaudou -===-====== -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-and-under-mixed-2 -" -===-====== - @Vaudou -========== -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-over-only -" -========== - @Vaudou - -" nil ((?= over-and-under 0))) - -;;------------------------------------------------------------------------------ -(incomplete-mixed-2 -" -========== - @Vaudou ----------- -" nil ((?= over-and-under 0))) - -)) - -(progn - (regression-test-compare-expect-values - "Tests for completeness predicate." - rst-decoration-complete-p-tests 'rst-decoration-complete-p nil)) - - - - - - - - - - - - - -(setq rst-get-decorations-around-tests - '( -;;------------------------------------------------------------------------------ -(simple -" - -Previous --------- - -@Current - -Next -++++ - -" ((?- simple 0) (?+ simple 0))) - -;;------------------------------------------------------------------------------ -(simple-2 -" - -Previous --------- - -Current@ -~~~~~~~ - -Next -++++ - -" ((?- simple 0) (?+ simple 0))) - -)) - -(progn - (regression-test-compare-expect-values - "Tests getting the decorations around a point." - rst-get-decorations-around-tests 'rst-get-decorations-around nil)) - diff --git a/docutils/tools/editors/emacs/tests/tests-runner.el b/docutils/tools/editors/emacs/tests/tests-runner.el deleted file mode 100644 index 014093e6d..000000000 --- a/docutils/tools/editors/emacs/tests/tests-runner.el +++ /dev/null @@ -1,167 +0,0 @@ -;; Authors: Martin Blais <blais@furius.ca> -;; Date: $Date: 2005/04/01 23:19:41 $ -;; Copyright: This module has been placed in the public domain. -;; -;; Simple generic test runner for test scripts. -;; -;; Run this with:: -;; -;; emacs --script <file>.el -;; -;; -;; There are mainly two useful functions from this pacakge: -;; -;; 1. regression-test-compare-expect-values : used to compare expected output -;; values from running a function; -;; -;; 2. regression-test-compare-expect-buffer : used to compare expected output -;; buffer contents after running the function. -;; -;; regression-test-compare-expect-values test format -;; ------------------------------------------------- -;; -;; The tests are a list of tuples, with the following entries: -;; -;; - a SYMBOL that uniquely identifies the test. -;; -;; - the input buffer CONTENTS to prepare and run the test on. If char @ is -;; present in the buffer, it is removed and the cursor is placed at that -;; position before running the tested function. -;; -;; - the expected OUTPUT value that the function should return. If the actual -;; output is different from this, the test will fail. -;; -;; - an optional list of INPUT ARGUMENTS that the test function is called with -;; for this test. -;; -;; regression-test-compare-expect-buffer test format -;; ------------------------------------------------- -;; -;; - a SYMBOL that uniquely identifies the test. -;; -;; - the input buffer CONTENTS to prepare and run the test on. Here too, char @ -;; is present in the buffer, it is removed and the cursor is placed at that -;; position before running the tested function. -;; -;; - the EXPECTED buffer contents after the function has been run. -;; Additionally, if char @ is present, it is checked that the cursor is -;; located at that position in the buffer after the function is run (this is -;; optional). -;; -;; - an optional list of PREFIX ARGUMENTS, which indicates to the test program -;; to set those prefix arguments before running the given function. If there -;; are multiple prefix args, the function is invoked many times. -;; - - -(require 'cl) - -(defvar regression-point-char "@" - "Special character used to mark the position of point in input - text and expected text.") - -(defun regression-test-loop (suitename testfun testlist fun &optional continue) - "Loop over a series of tests in a buffer and run the 'testfun' -function." - - (message (format "\n\n Test Suite: %s\n\n" suitename)) - - (let ((buf (get-buffer-create "regression-tests")) - errtxt - ) - (dolist (curtest testlist) - - ;; Print current text. - (message (format "========= %s" (prin1-to-string (car curtest)))) - - ;; Prepare a buffer with the starting text, and move the cursor where - ;; the special character is located. - (switch-to-buffer buf) - (erase-buffer) - (insert (cadr curtest)) - - (if (not (search-backward regression-point-char nil t)) - (error (concat "Error: Badly formed test input, missing " - "the cursor position marker."))) - - (delete-char 1) - - (setq errtxt (funcall testfun - (car curtest) - (caddr curtest) - (cadddr curtest))) - - (if errtxt - (if continue - (progn (message errtxt) - (message "(Continuing...)")) - (error errtxt))) - )) - (message "Done.")) - - -(defun regression-compare-buffers (testname expected testargs) - "Compare the buffer and expected text and return actual -contents if they do not match." - - ;; Run the section title update command n times. - (dolist (x (or testargs (list nil))) - (let ((current-prefix-arg x)) - (funcall fun))) - - ;; Compare the buffer output with the expected text. - (let* (;; Get the actual buffer contents. - (actual (buffer-string)) - ;; Get the expected location of point - (exppoint (string-match regression-point-char expected)) - - (expected-clean (if exppoint - (concat (substring expected 0 exppoint) - (substring expected (+ 1 exppoint))) - expected)) - - ;; Adjust position of point vs. string index. - (exppoint (and exppoint (+ exppoint 1))) - - ) - - (if (not (string= expected-clean actual)) - ;; Error! Test failed. - (format "Error: Test %s failed: \nexpected\n%s\ngot\n%s" - testname - (prin1-to-string expected-clean) - (prin1-to-string actual)) - (if (and exppoint (not (equal exppoint (point)))) - ;; Error! Test failed, final position of cursor is not the same. - (format "Error: Test %s failed: cursor badly placed." testname)) - ))) - -(defun regression-test-compare-expect-buffer - (suitename testlist fun &optional continue) - "Run the regression tests for the expected buffer contents." - (regression-test-loop - suitename 'regression-compare-buffers testlist fun continue)) - - -(defun regression-compare-values (testname expected testargs) - "Compare the buffer and expected text and return actual -contents if they do not match." - - (let (actual) - ;; Run the section title update command n times. - (setq actual (apply fun testargs)) - - ;; Compare the buffer output with the expected text. - (if (not (equal actual expected)) - ;; Error! Test failed. - (format "Error: Test %s failed: expected '%s' got '%s'." - testname - (prin1-to-string expected) - (prin1-to-string actual)) - ))) - -(defun regression-test-compare-expect-values - (suitename testlist fun &optional continue) - "Run the regression tests for expected values comparison." - (regression-test-loop - suitename 'regression-compare-values testlist fun continue)) diff --git a/docutils/tools/quicktest.py b/docutils/tools/quicktest.py deleted file mode 100755 index fbccb1aaa..000000000 --- a/docutils/tools/quicktest.py +++ /dev/null @@ -1,211 +0,0 @@ -#!/usr/bin/env python - -# Author: Garth Kidd -# Contact: garth@deadlybloodyserious.com -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -import sys -import os -import getopt -import docutils -from docutils.frontend import OptionParser -from docutils.utils import new_document -from docutils.parsers.rst import Parser - - -usage_header = """\ -quicktest.py: quickly test the restructuredtext parser. - -Usage:: - - quicktest.py [options] [<source> [<destination>]] - -``source`` is the name of the file to use as input (default is stdin). -``destination`` is the name of the file to create as output (default is -stdout). - -Options: -""" - -options = [('pretty', 'p', - 'output pretty pseudo-xml: no "&abc;" entities (default)'), - ('test', 't', 'output test-ready data (input & expected output, ' - 'ready to be copied to a parser test module)'), - ('rawxml', 'r', 'output raw XML'), - ('styledxml=', 's', 'output raw XML with XSL style sheet ' - 'reference (filename supplied in the option argument)'), - ('xml', 'x', 'output pretty XML (indented)'), - ('attributes', 'A', 'dump document attributes after processing'), - ('debug', 'd', 'debug mode (lots of output)'), - ('version', 'V', 'show Docutils version then exit'), - ('help', 'h', 'show help text then exit')] -"""See ``distutils.fancy_getopt.FancyGetopt.__init__`` for a description of -the data structure: (long option, short option, description).""" - -def usage(): - print usage_header - for longopt, shortopt, description in options: - if longopt[-1:] == '=': - opts = '-%s arg, --%sarg' % (shortopt, longopt) - else: - opts = '-%s, --%s' % (shortopt, longopt) - print '%-15s' % opts, - if len(opts) > 14: - print '%-16s' % '\n', - while len(description) > 60: - limit = description.rindex(' ', 0, 60) - print description[:limit].strip() - description = description[limit + 1:] - print '%-15s' % ' ', - print description - -def _pretty(input, document, optargs): - return document.pformat() - -def _rawxml(input, document, optargs): - return document.asdom().toxml() - -def _styledxml(input, document, optargs): - docnode = document.asdom().childNodes[0] - return '%s\n%s\n%s' % ( - '<?xml version="1.0" encoding="ISO-8859-1"?>', - '<?xml-stylesheet type="text/xsl" href="%s"?>' - % optargs['styledxml'], docnode.toxml()) - -def _prettyxml(input, document, optargs): - return document.asdom().toprettyxml(' ', '\n') - -def _test(input, document, optargs): - tq = '"""' - output = document.pformat() # same as _pretty() - return """\ - totest['change_this_test_name'] = [ -[%s\\ -%s -%s, -%s\\ -%s -%s], -] -""" % ( tq, escape(input.rstrip()), tq, tq, escape(output.rstrip()), tq ) - -def escape(text): - """ - Return `text` in triple-double-quoted Python string form. - """ - text = text.replace('\\', '\\\\') # escape backslashes - text = text.replace('"""', '""\\"') # break up triple-double-quotes - text = text.replace(' \n', ' \\n\\\n') # protect trailing whitespace - return text - -_outputFormatters = { - 'rawxml': _rawxml, - 'styledxml': _styledxml, - 'xml': _prettyxml, - 'pretty' : _pretty, - 'test': _test - } - -def format(outputFormat, input, document, optargs): - formatter = _outputFormatters[outputFormat] - return formatter(input, document, optargs) - -def getArgs(): - if os.name == 'mac' and len(sys.argv) <= 1: - return macGetArgs() - else: - return posixGetArgs(sys.argv[1:]) - -def posixGetArgs(argv): - outputFormat = 'pretty' - # convert fancy_getopt style option list to getopt.getopt() arguments - shortopts = ''.join([option[1] + ':' * (option[0][-1:] == '=') - for option in options if option[1]]) - longopts = [option[0] for option in options if option[0]] - try: - opts, args = getopt.getopt(argv, shortopts, longopts) - except getopt.GetoptError: - usage() - sys.exit(2) - optargs = {'debug': 0, 'attributes': 0} - for o, a in opts: - if o in ['-h', '--help']: - usage() - sys.exit() - elif o in ['-V', '--version']: - print >>sys.stderr, ('quicktest.py (Docutils %s)' - % docutils.__version__) - sys.exit() - elif o in ['-r', '--rawxml']: - outputFormat = 'rawxml' - elif o in ['-s', '--styledxml']: - outputFormat = 'styledxml' - optargs['styledxml'] = a - elif o in ['-x', '--xml']: - outputFormat = 'xml' - elif o in ['-p', '--pretty']: - outputFormat = 'pretty' - elif o in ['-t', '--test']: - outputFormat = 'test' - elif o in ['--attributes', '-A']: - optargs['attributes'] = 1 - elif o in ['-d', '--debug']: - optargs['debug'] = 1 - else: - raise getopt.GetoptError, "getopt should have saved us!" - if len(args) > 2: - print 'Maximum 2 arguments allowed.' - usage() - sys.exit(1) - inputFile = sys.stdin - outputFile = sys.stdout - if args: - inputFile = open(args.pop(0)) - if args: - outputFile = open(args.pop(0), 'w') - return inputFile, outputFile, outputFormat, optargs - -def macGetArgs(): - import EasyDialogs - EasyDialogs.Message("""\ -Use the next dialog to build a command line: - -1. Choose an output format from the [Option] list -2. Click [Add] -3. Choose an input file: [Add existing file...] -4. Save the output: [Add new file...] -5. [OK]""") - optionlist = [(longopt, description) - for (longopt, shortopt, description) in options] - argv = EasyDialogs.GetArgv(optionlist=optionlist, addfolder=0) - return posixGetArgs(argv) - -def main(): - # process cmdline arguments: - inputFile, outputFile, outputFormat, optargs = getArgs() - settings = OptionParser(components=(Parser,)).get_default_values() - settings.debug = optargs['debug'] - parser = Parser() - input = inputFile.read() - document = new_document(inputFile.name, settings) - parser.parse(input, document) - output = format(outputFormat, input, document, optargs) - outputFile.write(output) - if optargs['attributes']: - import pprint - pprint.pprint(document.__dict__) - - -if __name__ == '__main__': - sys.stderr = sys.stdout - main() diff --git a/docutils/tools/rst2html.py b/docutils/tools/rst2html.py deleted file mode 100755 index 35e5558aa..000000000 --- a/docutils/tools/rst2html.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@python.org -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A minimal front end to the Docutils Publisher, producing HTML. -""" - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates (X)HTML documents from standalone reStructuredText ' - 'sources. ' + default_description) - -publish_cmdline(writer_name='html', description=description) diff --git a/docutils/tools/rst2latex.py b/docutils/tools/rst2latex.py deleted file mode 100755 index 5f51f34e2..000000000 --- a/docutils/tools/rst2latex.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A minimal front end to the Docutils Publisher, producing LaTeX. -""" - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates LaTeX documents from standalone reStructuredText ' - 'sources. ' + default_description) - -publish_cmdline(writer_name='latex', description=description) diff --git a/docutils/tools/rst2newlatex.py b/docutils/tools/rst2newlatex.py deleted file mode 100755 index 46524753f..000000000 --- a/docutils/tools/rst2newlatex.py +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A minimal front end to the Docutils Publisher, producing LaTeX using -the new LaTeX writer. -""" - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates LaTeX documents from standalone reStructuredText ' - 'sources. This writer is EXPERIMENTAL and should not be used ' - 'in a production environment. ' + default_description) - -publish_cmdline(writer_name='newlatex2e', description=description) diff --git a/docutils/tools/rst2pseudoxml.py b/docutils/tools/rst2pseudoxml.py deleted file mode 100755 index 627b3d198..000000000 --- a/docutils/tools/rst2pseudoxml.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A minimal front end to the Docutils Publisher, producing pseudo-XML. -""" - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates pseudo-XML from standalone reStructuredText ' - 'sources (for testing purposes). ' + default_description) - -publish_cmdline(description=description) diff --git a/docutils/tools/rst2s5.py b/docutils/tools/rst2s5.py deleted file mode 100755 index b4a9396d1..000000000 --- a/docutils/tools/rst2s5.py +++ /dev/null @@ -1,26 +0,0 @@ -#!/usr/bin/python - -# Author: Chris Liechti -# Contact: cliechti@gmx.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A minimal front end to the Docutils Publisher, producing HTML slides using -the S5 template system. -""" - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates S5 (X)HTML slideshow documents from standalone ' - 'reStructuredText sources. ' + default_description) - -publish_cmdline(writer_name='s5', description=description) diff --git a/docutils/tools/rst2xml.py b/docutils/tools/rst2xml.py deleted file mode 100755 index 8e2ad757f..000000000 --- a/docutils/tools/rst2xml.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A minimal front end to the Docutils Publisher, producing Docutils XML. -""" - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates Docutils-native XML from standalone ' - 'reStructuredText sources. ' + default_description) - -publish_cmdline(writer_name='xml', description=description) diff --git a/docutils/tools/rstpep2html.py b/docutils/tools/rstpep2html.py deleted file mode 100755 index 5aa4b8afc..000000000 --- a/docutils/tools/rstpep2html.py +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A minimal front end to the Docutils Publisher, producing HTML from PEP -(Python Enhancement Proposal) documents. -""" - -try: - import locale - locale.setlocale(locale.LC_ALL, '') -except: - pass - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates (X)HTML from reStructuredText-format PEP files. ' - + default_description) - -publish_cmdline(reader_name='pep', writer_name='pep_html', - description=description) diff --git a/docutils/docutils/transforms/__init__.py b/docutils/transforms/__init__.py index 36aa4e735..36aa4e735 100644 --- a/docutils/docutils/transforms/__init__.py +++ b/docutils/transforms/__init__.py diff --git a/docutils/docutils/transforms/components.py b/docutils/transforms/components.py index 1c3ecbef6..1c3ecbef6 100644 --- a/docutils/docutils/transforms/components.py +++ b/docutils/transforms/components.py diff --git a/docutils/docutils/transforms/frontmatter.py b/docutils/transforms/frontmatter.py index 14a3aa8cc..14a3aa8cc 100644 --- a/docutils/docutils/transforms/frontmatter.py +++ b/docutils/transforms/frontmatter.py diff --git a/docutils/docutils/transforms/misc.py b/docutils/transforms/misc.py index 9567055f9..9567055f9 100644 --- a/docutils/docutils/transforms/misc.py +++ b/docutils/transforms/misc.py diff --git a/docutils/docutils/transforms/parts.py b/docutils/transforms/parts.py index 1e275c78a..1e275c78a 100644 --- a/docutils/docutils/transforms/parts.py +++ b/docutils/transforms/parts.py diff --git a/docutils/docutils/transforms/peps.py b/docutils/transforms/peps.py index edaba2557..edaba2557 100644 --- a/docutils/docutils/transforms/peps.py +++ b/docutils/transforms/peps.py diff --git a/docutils/docutils/transforms/references.py b/docutils/transforms/references.py index c7e17b50e..c7e17b50e 100644 --- a/docutils/docutils/transforms/references.py +++ b/docutils/transforms/references.py diff --git a/docutils/docutils/transforms/universal.py b/docutils/transforms/universal.py index b31648632..b31648632 100644 --- a/docutils/docutils/transforms/universal.py +++ b/docutils/transforms/universal.py diff --git a/docutils/docutils/transforms/writer_aux.py b/docutils/transforms/writer_aux.py index 74ac4d4f6..74ac4d4f6 100644 --- a/docutils/docutils/transforms/writer_aux.py +++ b/docutils/transforms/writer_aux.py diff --git a/docutils/docutils/urischemes.py b/docutils/urischemes.py index 584dad622..584dad622 100644 --- a/docutils/docutils/urischemes.py +++ b/docutils/urischemes.py diff --git a/docutils/docutils/utils.py b/docutils/utils.py index 24c4986f0..24c4986f0 100644 --- a/docutils/docutils/utils.py +++ b/docutils/utils.py diff --git a/docutils/docutils/writers/__init__.py b/docutils/writers/__init__.py index 5482cad42..5482cad42 100644 --- a/docutils/docutils/writers/__init__.py +++ b/docutils/writers/__init__.py diff --git a/docutils/docutils/writers/docutils_xml.py b/docutils/writers/docutils_xml.py index 2362e6b78..2362e6b78 100644 --- a/docutils/docutils/writers/docutils_xml.py +++ b/docutils/writers/docutils_xml.py diff --git a/docutils/docutils/writers/html4css1/__init__.py b/docutils/writers/html4css1/__init__.py index 02833d66a..02833d66a 100644 --- a/docutils/docutils/writers/html4css1/__init__.py +++ b/docutils/writers/html4css1/__init__.py diff --git a/docutils/docutils/writers/html4css1/html4css1.css b/docutils/writers/html4css1/html4css1.css index e94df1546..e94df1546 100644 --- a/docutils/docutils/writers/html4css1/html4css1.css +++ b/docutils/writers/html4css1/html4css1.css diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/writers/latex2e/__init__.py index cf7af05fd..cf7af05fd 100644 --- a/docutils/docutils/writers/latex2e/__init__.py +++ b/docutils/writers/latex2e/__init__.py diff --git a/docutils/docutils/writers/latex2e/latex2e.tex b/docutils/writers/latex2e/latex2e.tex index 6e041a14b..6e041a14b 100644 --- a/docutils/docutils/writers/latex2e/latex2e.tex +++ b/docutils/writers/latex2e/latex2e.tex diff --git a/docutils/docutils/writers/newlatex2e/__init__.py b/docutils/writers/newlatex2e/__init__.py index e46866d0d..e46866d0d 100644 --- a/docutils/docutils/writers/newlatex2e/__init__.py +++ b/docutils/writers/newlatex2e/__init__.py diff --git a/docutils/docutils/writers/newlatex2e/base.tex b/docutils/writers/newlatex2e/base.tex index 231f3911f..231f3911f 100644 --- a/docutils/docutils/writers/newlatex2e/base.tex +++ b/docutils/writers/newlatex2e/base.tex diff --git a/docutils/docutils/writers/newlatex2e/unicode_map.py b/docutils/writers/newlatex2e/unicode_map.py index 2998178f4..2998178f4 100644 --- a/docutils/docutils/writers/newlatex2e/unicode_map.py +++ b/docutils/writers/newlatex2e/unicode_map.py diff --git a/docutils/docutils/writers/null.py b/docutils/writers/null.py index 4632c7457..4632c7457 100644 --- a/docutils/docutils/writers/null.py +++ b/docutils/writers/null.py diff --git a/docutils/docutils/writers/pep_html/__init__.py b/docutils/writers/pep_html/__init__.py index a672e1c6d..a672e1c6d 100644 --- a/docutils/docutils/writers/pep_html/__init__.py +++ b/docutils/writers/pep_html/__init__.py diff --git a/docutils/docutils/writers/pep_html/pep.css b/docutils/writers/pep_html/pep.css index 014d3e423..014d3e423 100644 --- a/docutils/docutils/writers/pep_html/pep.css +++ b/docutils/writers/pep_html/pep.css diff --git a/docutils/docutils/writers/pep_html/template.txt b/docutils/writers/pep_html/template.txt index 6f96977e8..6f96977e8 100644 --- a/docutils/docutils/writers/pep_html/template.txt +++ b/docutils/writers/pep_html/template.txt diff --git a/docutils/docutils/writers/pseudoxml.py b/docutils/writers/pseudoxml.py index c0e18bffb..c0e18bffb 100644 --- a/docutils/docutils/writers/pseudoxml.py +++ b/docutils/writers/pseudoxml.py diff --git a/docutils/docutils/writers/s5_html/__init__.py b/docutils/writers/s5_html/__init__.py index e4bde3375..e4bde3375 100644 --- a/docutils/docutils/writers/s5_html/__init__.py +++ b/docutils/writers/s5_html/__init__.py diff --git a/docutils/docutils/writers/s5_html/themes/README.txt b/docutils/writers/s5_html/themes/README.txt index 2e01b51ee..2e01b51ee 100644 --- a/docutils/docutils/writers/s5_html/themes/README.txt +++ b/docutils/writers/s5_html/themes/README.txt diff --git a/docutils/docutils/writers/s5_html/themes/big-black/__base__ b/docutils/writers/s5_html/themes/big-black/__base__ index f08be9ad5..f08be9ad5 100644 --- a/docutils/docutils/writers/s5_html/themes/big-black/__base__ +++ b/docutils/writers/s5_html/themes/big-black/__base__ diff --git a/docutils/docutils/writers/s5_html/themes/big-black/framing.css b/docutils/writers/s5_html/themes/big-black/framing.css index 5a31113fb..5a31113fb 100644 --- a/docutils/docutils/writers/s5_html/themes/big-black/framing.css +++ b/docutils/writers/s5_html/themes/big-black/framing.css diff --git a/docutils/docutils/writers/s5_html/themes/big-black/pretty.css b/docutils/writers/s5_html/themes/big-black/pretty.css index 82bcc9dc4..82bcc9dc4 100644 --- a/docutils/docutils/writers/s5_html/themes/big-black/pretty.css +++ b/docutils/writers/s5_html/themes/big-black/pretty.css diff --git a/docutils/docutils/writers/s5_html/themes/big-white/framing.css b/docutils/writers/s5_html/themes/big-white/framing.css index cd343432b..cd343432b 100644 --- a/docutils/docutils/writers/s5_html/themes/big-white/framing.css +++ b/docutils/writers/s5_html/themes/big-white/framing.css diff --git a/docutils/docutils/writers/s5_html/themes/big-white/pretty.css b/docutils/writers/s5_html/themes/big-white/pretty.css index c5e2fcf97..c5e2fcf97 100644 --- a/docutils/docutils/writers/s5_html/themes/big-white/pretty.css +++ b/docutils/writers/s5_html/themes/big-white/pretty.css diff --git a/docutils/docutils/writers/s5_html/themes/default/blank.gif b/docutils/writers/s5_html/themes/default/blank.gif Binary files differindex 75b945d25..75b945d25 100644 --- a/docutils/docutils/writers/s5_html/themes/default/blank.gif +++ b/docutils/writers/s5_html/themes/default/blank.gif diff --git a/docutils/docutils/writers/s5_html/themes/default/framing.css b/docutils/writers/s5_html/themes/default/framing.css index c4727f303..c4727f303 100644 --- a/docutils/docutils/writers/s5_html/themes/default/framing.css +++ b/docutils/writers/s5_html/themes/default/framing.css diff --git a/docutils/docutils/writers/s5_html/themes/default/iepngfix.htc b/docutils/writers/s5_html/themes/default/iepngfix.htc index 9f3d628b5..9f3d628b5 100644 --- a/docutils/docutils/writers/s5_html/themes/default/iepngfix.htc +++ b/docutils/writers/s5_html/themes/default/iepngfix.htc diff --git a/docutils/docutils/writers/s5_html/themes/default/opera.css b/docutils/writers/s5_html/themes/default/opera.css index c9d1148be..c9d1148be 100644 --- a/docutils/docutils/writers/s5_html/themes/default/opera.css +++ b/docutils/writers/s5_html/themes/default/opera.css diff --git a/docutils/docutils/writers/s5_html/themes/default/outline.css b/docutils/writers/s5_html/themes/default/outline.css index fa767e227..fa767e227 100644 --- a/docutils/docutils/writers/s5_html/themes/default/outline.css +++ b/docutils/writers/s5_html/themes/default/outline.css diff --git a/docutils/docutils/writers/s5_html/themes/default/pretty.css b/docutils/writers/s5_html/themes/default/pretty.css index 1cede72d4..1cede72d4 100644 --- a/docutils/docutils/writers/s5_html/themes/default/pretty.css +++ b/docutils/writers/s5_html/themes/default/pretty.css diff --git a/docutils/docutils/writers/s5_html/themes/default/print.css b/docutils/writers/s5_html/themes/default/print.css index 9d057cc8c..9d057cc8c 100644 --- a/docutils/docutils/writers/s5_html/themes/default/print.css +++ b/docutils/writers/s5_html/themes/default/print.css diff --git a/docutils/docutils/writers/s5_html/themes/default/s5-core.css b/docutils/writers/s5_html/themes/default/s5-core.css index 6965f5e8f..6965f5e8f 100644 --- a/docutils/docutils/writers/s5_html/themes/default/s5-core.css +++ b/docutils/writers/s5_html/themes/default/s5-core.css diff --git a/docutils/docutils/writers/s5_html/themes/default/slides.css b/docutils/writers/s5_html/themes/default/slides.css index 82bdc0ee0..82bdc0ee0 100644 --- a/docutils/docutils/writers/s5_html/themes/default/slides.css +++ b/docutils/writers/s5_html/themes/default/slides.css diff --git a/docutils/docutils/writers/s5_html/themes/default/slides.js b/docutils/writers/s5_html/themes/default/slides.js index 81e04e5d4..81e04e5d4 100644 --- a/docutils/docutils/writers/s5_html/themes/default/slides.js +++ b/docutils/writers/s5_html/themes/default/slides.js diff --git a/docutils/docutils/writers/s5_html/themes/medium-black/__base__ b/docutils/writers/s5_html/themes/medium-black/__base__ index 401b621bd..401b621bd 100644 --- a/docutils/docutils/writers/s5_html/themes/medium-black/__base__ +++ b/docutils/writers/s5_html/themes/medium-black/__base__ diff --git a/docutils/docutils/writers/s5_html/themes/medium-black/pretty.css b/docutils/writers/s5_html/themes/medium-black/pretty.css index 2ec10e2e8..2ec10e2e8 100644 --- a/docutils/docutils/writers/s5_html/themes/medium-black/pretty.css +++ b/docutils/writers/s5_html/themes/medium-black/pretty.css diff --git a/docutils/docutils/writers/s5_html/themes/medium-white/framing.css b/docutils/writers/s5_html/themes/medium-white/framing.css index 6c4e3abf2..6c4e3abf2 100644 --- a/docutils/docutils/writers/s5_html/themes/medium-white/framing.css +++ b/docutils/writers/s5_html/themes/medium-white/framing.css diff --git a/docutils/docutils/writers/s5_html/themes/medium-white/pretty.css b/docutils/writers/s5_html/themes/medium-white/pretty.css index 07e07b9ab..07e07b9ab 100644 --- a/docutils/docutils/writers/s5_html/themes/medium-white/pretty.css +++ b/docutils/writers/s5_html/themes/medium-white/pretty.css diff --git a/docutils/docutils/writers/s5_html/themes/small-black/__base__ b/docutils/writers/s5_html/themes/small-black/__base__ index 67f4db2bf..67f4db2bf 100644 --- a/docutils/docutils/writers/s5_html/themes/small-black/__base__ +++ b/docutils/writers/s5_html/themes/small-black/__base__ diff --git a/docutils/docutils/writers/s5_html/themes/small-black/pretty.css b/docutils/writers/s5_html/themes/small-black/pretty.css index 5c1932704..5c1932704 100644 --- a/docutils/docutils/writers/s5_html/themes/small-black/pretty.css +++ b/docutils/writers/s5_html/themes/small-black/pretty.css diff --git a/docutils/docutils/writers/s5_html/themes/small-white/framing.css b/docutils/writers/s5_html/themes/small-white/framing.css index 70287dd06..70287dd06 100644 --- a/docutils/docutils/writers/s5_html/themes/small-white/framing.css +++ b/docutils/writers/s5_html/themes/small-white/framing.css diff --git a/docutils/docutils/writers/s5_html/themes/small-white/pretty.css b/docutils/writers/s5_html/themes/small-white/pretty.css index ba988e13b..ba988e13b 100644 --- a/docutils/docutils/writers/s5_html/themes/small-white/pretty.css +++ b/docutils/writers/s5_html/themes/small-white/pretty.css |
