diff options
Diffstat (limited to 'docutils')
205 files changed, 0 insertions, 64166 deletions
diff --git a/docutils/.cvsignore b/docutils/.cvsignore deleted file mode 100644 index 378eac25d..000000000 --- a/docutils/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -build diff --git a/docutils/COPYING.txt b/docutils/COPYING.txt deleted file mode 100644 index cdeefe248..000000000 --- a/docutils/COPYING.txt +++ /dev/null @@ -1,124 +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 CVS -repository (Internet host cvs.sourceforge.net, filesystem path -/cvsroot/docutils), whose Internet web interface is located at -<http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/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: - -* 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/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; if you have Python 2.2 or higher, difflib.py is not needed and - may be removed. (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 327c1ddf5..000000000 --- a/docutils/FAQ.txt +++ /dev/null @@ -1,480 +0,0 @@ -===================================== - Docutils Frequently Asked Questions -===================================== - -:Date: $Date$ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. Please note that until there's a Q&A-specific construct available, - this FAQ will use section titles for questions. Therefore - questions must fit on one line. The title may be a summary of the - question, with the full question in the section body. - - -.. 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: -__ mailto:docutils-users@lists.sourceforge.net -__ http://lists.sourceforge.net/lists/listinfo/docutils-users - - -Docutils -======== - -What is Docutils? ------------------ - -Docutils_ is a system for processing plaintext documentation into -useful formats, such as HTML, XML, and TeX. 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: spec/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: spec/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 CVS (or `development snapshots`_) is almost always -the most stable (bug-free) as well as the most featureful. - - -What is the Docutils project release policy? --------------------------------------------- - -It ought to be "release early & often", but official releases are a -significant effort and aren't done that often. We have -automatically-generated `development snapshots`_ which always contain -the latest code from CVS. As the project matures, we may formalize on -a stable/development-branch scheme, but we're not using anything like -that yet. - -If anyone would like to volunteer as a release coordinator, please -`contact the project coordinator`_. - -.. _development snapshots: - http://docutils.sf.net/#development-snapshots - -.. _contact the project coordinator: - mailto:goodger@python.org - - -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 <docs/rst/quickstart.html>`_ and the `Quick -reStructuredText <docs/rst/quickref.html>`_ user reference are a good -place to start. The `reStructuredText Markup Specification -<spec/rst/reStructuredText.html>`_ is a detailed technical -specification. - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/ -.. _Setext: 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://www.xml.com/pub/a/2002/02/06/rest.html - - -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? -------------------------------------------------- - -There is `some code under development for Emacs`__. - -Extensions for other editors are welcome. - -__ http://docutils.sf.net/tools/editors/emacs/ - - -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. - - -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 ``\u2014``) 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. - -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. Files containing character entity set -substitution definitions using the "unicode" directive `are available -<tmp/charents/>`__ (`tarball <tmp/charents.tgz>`__). A description -and instructions for use `are here <tmp/charents/README.html>`__. -Thanks to David Priest for the original idea. Incorporating these -files into Docutils is on the `to-do list <spec/notes.html#to-do>`_. - -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;". - - -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. - -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, but little if any actual work has -ever been done. 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. No general-purpose filter exists. An 80/20 -approach should work though: build a tool that does 80% of the work -automatically, leaving the other 20% for manual tweaks. - - -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: - -* `Ian Bicking's experimental code <sandbox/ianb/wiki/WikiPage.py>`__ -* `MoinMoin <http://moin.sf.net>`__ has some support; `here's a sample - <http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample>`__ -* Zope-based `Zwiki <http://zwiki.org/>`__ -* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__ - -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: - -* `Python Desktop Server <http://pyds.muensterland.org/>`__ -* `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom>`__ - -Please `let us know`_ of any other reStructuredText Blogs. - - -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 `HTML 4.01`_ and `XHTML 1.0`_ -specifications. A cascading style sheet ("default.css" by default) is -required for proper viewing with a modern graphical browser. Correct -rendering of the HTML produced depends on the CSS support of the -browser. - -.. _HTML 4.01: http://www.w3.org/TR/html4/ -.. _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. 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/html.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/html.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> - <link rel="stylesheet" href="default.css" type="text/css" /> - </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.) Rather than use a plain H1 for that, 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: -tools/stylesheets/default.css. Of course, you're welcome to roll your -own. - -(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 Mozilla or -MSIE). - - -Python Source Reader -==================== - -Can I use Docutils for Python auto-documentation? -------------------------------------------------- - -Docstring extraction is still under development. There is most of a -source code parsing module in docutils/readers/python/moduleparser.py. -I (David Goodger) haven't worked on it in a while, but I do plan to -finish it eventually. Ian Bicking wrote an initial front end for my -moduleparser module, in sandbox/ianb/extractor/extractor.py. - - -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 b8ef1a128..000000000 --- a/docutils/HISTORY.txt +++ /dev/null @@ -1,1179 +0,0 @@ -================== - Docutils History -================== - -: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:: - -Acknowledgements -================ - -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, tasty treats, -and related projects: - - Aahz, David Abrahams, David Ascher, Eric Bellot, Ian Bicking, - Martin Blais, Fred Bremmer, Simon Budig, Bill Bumgarner, Brett - Cannon, Adam Chodorowski, Jason Diamond, William Dode, Fred Drake, - Dethe Elza, Marcus Ertl, Benja Fallenstein, fantasai, Stefane - Fermigier, Jim Fulton, Peter Funk, Jorge Gonzalez, Engelbert - Gruber, Simon Hefti, Doug Hellmann, Juergen Hermann, Jannie - Hofmeyr, Michael Hudson, Marcelo Huerta San Martin, Ludger - Humbert, Jeremy Hylton, Tony Ibbs, Alan Jaffray, Dmitry Jemerov, - Richard Jones, Andreas Jung, Garth Kidd, Nicola Larosa, Daniel - Larsson, Marc-Andre Lemburg, Julien Letessier, Wolfgang Lipp, - Edward Loper, Dallas Mahrt, Ken Manheimer, Vasko Miroslav, Skip - Montanaro, Paul Moore, Nigel W. Moriarty, Mark Nodine, Patrick - K. O'Brien, Michel Pelletier, Sam Penrose, Tim Peters, Pearu - Peterson, Mark Pilgrim, Brett g Porter, David Priest, Jens Quade, - Andy Robinson, Tavis Rudd, Oliver Rutherfurd, Kenichi Sato, Ueli - Schlaepfer, Gunnar Schwant, Bruce Smith, Roman Suzi, tav, Bob - Tolbert, Paul Tremblay, Laurence Tratt, Adrian van den Dries, - Guido van Rossum, Martin von Loewis, Greg Ward, Barry Warsaw, - Edward Welbourne, Ka-Ping Yee, Moshe Zadka - -Thank you! - -(I'm still waiting for contributions of computer equipment and cold -hard cash :-).) Hopefully I haven't forgotten anyone or misspelled -any names; apologies (and please let me know!) if I have. - - -Future Plans -============ - -* The config file layout will be completely overhauled for the 0.4 - release. - -* Include substitution files for character entities, produced by the - tools/unicode2rstsubs.py. As static data, these files could go - inside the docutils package somewhere. - -* Rename front-end tools (perhaps to "rst2*" pattern) and have - setup.py install them. - -* A Python Source Reader component (Python auto-documentation) will be - added as soon as there's enough time, effort, and will. If you'd - like to help, let me know! - - -Changes Since 0.3 -================= - -* docutils/core.py: - - - Catch system messages to stop tracebacks from parsing errors. - - Catch exceptions during processing report & exit without - tracebacks, except when "--traceback" used. - -* docutils/frontend.py: - - - Added "--traceback" & "--no-traceback" options ("traceback" - setting). - -* docutils/io.py: - - - Catch IOErrors when opening source & destination files, report & - exit without tracebacks. - -* docutils/utils.py: - - - Added "level" attribute to SystemMessage exceptions. - -* docutils/languages/af.py: Added to project; Afrikaans - mappings by Jannie Hofmeyr. - -* docutils/languages/ru.py: Added to project; Russian mappings by - Roman Suzi. - -* docutils/parsers/rst/languages/af.py: Added to project; Afrikaans - mappings by Jannie Hofmeyr. - -* docutils/parsers/rst/languages/ru.py: Added to project; Russian - mappings by Roman Suzi. - -* docutils/writers/html4css1.py: - - - Fixed unicode handling of attribute values (bug 760673). - - -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. - -* 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 0c4105833..000000000 --- a/docutils/MANIFEST.in +++ /dev/null @@ -1,10 +0,0 @@ -include *.txt -include *.py -recursive-include docutils * -recursive-include docs * -recursive-include extras * -recursive-include licenses * -recursive-include spec * -recursive-include test * -recursive-include tools * -recursive-exclude * .cvsignore *.pyc *~ diff --git a/docutils/README.txt b/docutils/README.txt deleted file mode 100644 index 9b0823c23..000000000 --- a/docutils/README.txt +++ /dev/null @@ -1,330 +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:: - - -Thank you for downloading the Python Docutils project archive. As -this is a work in progress, please check the project website for -updated working files (snapshots). This project should be considered -highly experimental; APIs are subject to change at any time. - - -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 [#py21]_ is required; Python 2.2.2 or later is - recommended. - -2. Use the latest Docutils code. Get the code from CVS or from the - snapshot: - - http://docutils.sf.net/docutils-snapshot.tgz - - See `Releases & Snapshots`_ below for details. - -3. Unpack the tarball and install with the standard :: - - python setup.py install - - 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 - html.py test.txt test.html - - 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 TeX. 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. **This is the focus of the current - development effort.** - -* 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 -==================== - -Putting together an official "Release" of Docutils is a significant -effort, so it isn't done that often. In the meantime, the CVS -snapshots always contain the latest code and documentation, usually -updated within an hour of changes being committed to the repository, -and usually bug-free: - -* Snapshot of Docutils code, front-end tools, tests, documentation, - and specifications: http://docutils.sf.net/docutils-snapshot.tgz - -* Snapshot of the Sandbox (experimental, contributed code): - http://docutils.sf.net/docutils-sandbox-snapshot.tgz - -* Snapshot of web files (the files that generate the web site): - http://docutils.sf.net/docutils-web-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 CVS repository, and a mailing list -for CVS messages. See the web site [address above] or spec/notes.txt -for details.) - - -Requirements -============ - -To run the code, Python 2.2 or later [#py21]_ must already be -installed. The latest release is recommended (2.2.2 as of this -writing). Python is available from http://www.python.org/. - -.. [#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. - - -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: Docutils Frequently Asked Questions. - -* HISTORY.txt: Release notes for the current and previous project - releases. - -* setup.py: Installation script. See "Installation" below. - -* install.py: Quick & dirty installation script. Just run it. - -* 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 user documentation directory. Contains the - following documents: - - - docs/tools.txt: Docutils Front-End Tools - - docs/latex.txt: Docutils LaTeX Writer - - docs/rst/quickstart.txt: A ReStructuredText Primer - - docs/rst/quickref.html: Quick reStructuredText (HTML only) - -* licenses: Directory containing copies of license files for - non-public-domain files. - -* spec: The project specification directory. Contains PEPs (Python - Enhancement Proposals), XML DTDs (document type definitions), and - other documents. The ``spec/rst`` directory contains the - reStructuredText specification. The ``spec/howto`` directory - contains How-To documents for developers. - -* tools: Directory for Docutils front-end tools. See docs/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 ``.tar.gz`` or ``.tgz`` archive. 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 -------- - -1. Open a DOS box (Command Shell, MSDOS 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 - -If your system is set up to run Python when you double-click on .py -files, you can run install.py to do the same as the above. - - -Mac OS 8/9 ----------- - -1. Open the folder containing the expanded archive. - -2. Double-click on the file "setup.py", which should be a "Python - module" file. - - If the file isn't a "Python module", the line endings are probably - also wrong, and you will need to set up your system to recognize - ".py" file extensions as Python files. See - http://gotools.sourceforge.net/mac/python.html for detailed - instructions. Once set up, it's easiest to start over by expanding - the archive again. - -3. The distutils options window will appear. From the "Command" popup - list choose "install", click "Add", then click "OK". - -If install.py is a "Python module" (see step 2 above if it isn't), you -can run it (double-click) instead of the above. The distutils options -window will not appear. - - -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 ../ - -The final directory name of the ``<archive_directory_path>`` is -"docutils" for snapshots. For official releases, the directory may be -called "docutils-X.Y", where "X.Y" is the release version. -Alternatively:: - - cd <archive_directory_path> - tools/buildhtml.py --config=tools/docutils.conf - -Some files may generate system messages (warnings and errors). The -``tools/test.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 "html.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/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! - -.. _Docutils Front-End Tools: docs/tools.html - - -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 - -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`_ or `send -email`_. Please include all relevant output, information about your -operating system, Python version, and Docutils version. To see the -Docutils version, use these commands:: - - cd ../tools - ./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=Docutils%20test%20suite%20failure - - -Getting Help -============ - -If you have questions or need assistance with Docutils or -reStructuredText, please `post a message`_ to the `Docutils-Users -mailing list`_. - -.. _post a message: mailto:docutils-users@lists.sourceforge.net -.. _Docutils-Users mailing list: - http://lists.sourceforge.net/lists/listinfo/docutils-users - - -.. - 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 79a074cec..000000000 --- a/docutils/docs/dev/pysource.dtd +++ /dev/null @@ -1,258 +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/spec/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/spec/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 ab677a004..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 spec/ppdi.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: http://docutils.sourceforge.net/spec/pysource.dtd -.. _docutils.dtd: http://docutils.sourceforge.net/spec/docutils.dtd - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - fill-column: 70 - End: diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt deleted file mode 100644 index b089d58b2..000000000 --- a/docutils/docs/dev/rst/alternatives.txt +++ /dev/null @@ -1,2005 +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. - -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage -.. _Problems with StructuredText: problems.html -.. _reStructuredText Markup Specification: reStructuredText.html - - -.. contents:: - - -... 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? - - -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 -below`__). 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? - -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. - - -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. - -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: - reStructuredText.html#character-level-inline-markup - - -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`_ below) for the somewhat awkward ".. __:" syntax is "__":: - - An anonymous__ reference. - - __ http://anonymous - - -Reworking Explicit Markup -========================= - -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! - - -Reworking Footnotes -=================== - -As a further wrinkle (see `Reworking Explicit Markup`_ 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. - - -Auto-Enumerated Lists -===================== - -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. - - -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 name="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 name="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 name="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 name="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/ - - -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 - -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. - - -.. - 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 a8747af88..000000000 --- a/docutils/docs/dev/rst/problems.txt +++ /dev/null @@ -1,870 +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://dev.zope.org/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://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _detailed description: - http://www.tibsnjoan.demon.co.uk/STNG-format.html -.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html -.. _StructuredTextNG: - http://dev.zope.org/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: 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/todo.txt b/docutils/docs/dev/todo.txt deleted file mode 100644 index eab2208fe..000000000 --- a/docutils/docs/dev/todo.txt +++ /dev/null @@ -1,2114 +0,0 @@ -================= - Docutils_ Notes -================= -:Author: David Goodger (with input from many) -:Contact: goodger@users.sourceforge.net -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - - -To Do -===== - -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! - - -Bugs ----- - -* The "contents" directive now automatically names the "topic" - produced (using its title), so that it can be referred to by name. - However, this naming happens late in the game, after most references - have been resolved. So the following indirect target produces a - warning because the name "contents" is not available when resolved:: - - .. contents:: - - .. _alternate name for contents: contents_ - - Fixing this may be tricky, and isn't a high priority. - - Idea: two-pass hyperlink resolution, ignoring errors on the first - pass? - - Perhaps the directive should do a bit more work up-front: create the - "topic" and "title", and leave the "pending" node for contents. - -* The parser doesn't know anything about double-width characters such - as Chinese hanza & Japanese kanji/kana. Also, it's dependent on - whitespace and punctuation as markup delimiters, which may not be - applicable in these languages. - -* In text inserted by the "include" directive, errors are often not - reported with the correct "source" or "line" numbers. Perhaps all - Reporter calls need a "base_node" parameter. There's a test in - test/test_parsers/test_rst/test_directives/test_include.py - (commented out, because the test fails). - -* tools/buildhtml.py needs a mechanism to skip directories - (e.g. licenses, test). Perhaps a ".prune-buildhtml" file? A - command-line option wouldn't work because it would require user - action. - - -General -------- - -* Refactor - - - Rename methods & variables according to the `Python coding - conventions`_ below. - - - The name-to-id conversion and hyperlink resolution code needs to be - checked for correctness and refactored. I'm afraid it's a bit of - a spaghetti mess now. - -* Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP. - -* 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. - -* 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"?) - -* Need a Unicode to HTML entities codec for HTML writer? - -* Perhaps the ``Component.supports`` method should deal with - individual features ("meta" etc.) instead of formats ("html" etc.)? - -* Standalone Reader: Implement an option to turn off the DocTitle - transform? - -* Add /usr/etc/docutils.conf to config file list? System-wide, - whereas /etc/docutils.conf is machine-specific. - /usr/local/etc/docutils.conf too? See the `Filesystem Hierarchy - Standard`_. - - .. _Filesystem Hierarchy Standard: http://www.pathname.com/fhs. - -* 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 - - To name tables, we could use a "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. - - - 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. - - 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. - - .. _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). - - 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. - - __ 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 functional testing to Docutils: Readers, Writers, front ends. - -* Changes to sandbox/davidg/infrastructure/docutils-update? - - - Modify the script to only update the snapshots if files have - actually changed in CVS (saving some SourceForge server cycles). - - - Make passing the test suite a prerequisite to snapshot update, - but only if the process is completely automatic. - - - Rewrite in Python? - -* 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. - -* 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 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.) - -* Change the "class" attribute of elements (set with - Element.set_class) to a list? - -* Enable feedback of some kind from internal decisions, such as - reporting the successful input encoding. Modify runtime settings? - System message? Simple stderr output? - -* Perhaps we need to re-evaluate the config file format, possibly - enabling a section for each Docutils component so that (for example) - HTML's and LaTeX's stylesheets don't interfere with each other. - - Idea: adopt sections in the config file corresponding to Docutils - components, which define flat namespaces that can be applied in an - overlay fashion defined by the components themselves. For example, - if the "pep_html" writer defines itself as derivative of the - "html4css1" writer, the "stylesheet" setting in the "[html4css1]" - section will be used unless the "[pep_html]" section overrides it. - In the absence of any "stylesheet" setting in either section, a - "stylesheet" setting in "[general]" would be used. This would also - allow component-specific definitions of general or - other-component-specific settings, such as writer-specific overrides - for the "trim_footnote_reference_space" parser setting. - -* The "docutils.conf" included with Docutils should become complete, - with examples of every setting (possibly commented). It's currently - sparse, requiring doc lookups. - -* Add internationalization to footer boilerplate text (resulting from - "--generator", "--source-link", and "--date" etc.), allowing - translations. - - -Documentation -------------- - -* User docs. What's needed? - - -Implementation Docs -``````````````````` - -* Internal module documentation (docstrings). - -* spec/doctree.txt: DTD element structural relationships, semantics, - and attributes. In progress; element descriptions to be completed. - -* How-to docs: In spec/howto/. - - - How a Writer works & how to write one - - - Transforms - -* 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. - - -Specification -````````````` - -* 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. - - -Web Site -```````` - -* Add an "examples" directory, beside "tools" and "docs", for - interesting examples of Docutils usage? Have a top-level README.txt - file and a subdirectory for each example. (Martin Blais) - - -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 0.3. - -Miscellaneous ideas: - -* 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: 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 - -* Clean up the code; refactor as required. - -* Add motivation sections for constructs in spec. - -* Allow very long titles (on two or more lines)? - -* And for the sake of completeness, should definition list terms be - allowed to be very long (two or more lines) also? - -* 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.* - - Should the choice be from among existing files only? Documents - only, or objects (images, etc.) also? (How to differentiate? - Element context [within "image"]?) - - This may not be just a parser issue though; it may need framework - support. - -* 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".) - -* Tony says inline markup rule 7 could do with a *little* more - exposition in the spec, to make clear what is going on for people - with head colds. - -* @@ Fix the parser's indentation handling to conform with the - stricter definition in the spec. (Explicit markup blocks should be - strict or forgiving?) - -* @@ Tighten up the spec for indentation of "constructs using complex - markers": field lists and option lists? Bodies may begin on the - same line as the marker or on a subsequent line (with blank lines - optional). Require that for bodies beginning on the same line as - the marker, all lines be in strict alignment. Currently, this is - acceptable:: - - :Field-name-of-medium-length: Field body beginning on the same - line as the field name. - - This proposal would make the above example illegal, instead - requiring strict alignment. A field body may either begin on the - same line:: - - :Field-name-of-medium-length: Field body beginning on the same - line as the field name. - - Or it may begin on a subsequent line:: - - :Field-name-of-medium-length: - Field body beginning on a line subsequent to that of the - field name. - - This would be especially relevant in degenerate cases like this:: - - :Number-of-African-swallows-requried-to-carry-a-coconut: - It would be very difficult to align the field body with - the left edge of the first line if it began on the same - line as the field name. - -* 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. Also - docutils-users, 2003-02-17. - -* Make the parser modular. Allow syntax constructs to be added or - disabled at run-time. Or is subclassing enough? - -* Continue to report (info, level 1) enumerated lists whose start - value is not ordinal-1? - -* 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"). - -* Generalize the "literal block" construct to allow blocks with a - per-line quoting to avoid indentation? For example, in this email - reply quoting the original, the block quoted with "``>``" (and - prefaced by "``::``") would be treated as a literal block:: - - John Doe wrote:: - - >> Great idea! - > - > Why didn't I think of that? - - You just did! ;-) - - The literal block would have to be a continuous text block (the - first blank line ends it) where every line begins with the same - non-alphanumeric non-whitespace character. - -* Should the "doctest" element go away, and the construct simply be a - front-end to generic literal blocks? - -* Add support for pragma (syntax-altering) directives. - - Some pragma directives could be local-scope unless explicitly - specified as global/pragma using ":global:" options. - -* Remove leading numbers from section titles for implicit link names? - A section titled "3. Conclusion" could then be referred to by - "``Conclusion_``" (i.e., without the "3."). - -* Syntax for the "line-block" directive? 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... - - 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 - - (And arguably invalid, since in Japanese the word "haiku" contains - three syllables.) - -* Implement auto-enumerated lists? See `Auto-Enumerated Lists`__. - - __ rst/alternatives.html#auto-enumerated-lists - -* 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? - -* Make enumerated list parsing more strict, so that this would parse - as a paragraph with an info message:: - - 1. line one - 3. line two - -* Line numbers in system messages are inconsistent in the parser. - Fix? - -* Generalize the "target-notes" directive into a command-line option - somehow? See docutils-develop 2003-02-13. - -* Include the _`character entity substitution definition files` - `temporarily stored here <tmp/charents>`__, perhaps in a - ``docutils/parsers/rst/includes/`` directory. See `misc.include`_ - below. - -* 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. - -* 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. - -* 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. What if one wants a - definition list item which defines the term "::"? We'd have to - escape it. Currenty, "\::" doesn't work (although it should; - **bug**), and ":\:" is misinterpreted as a field name (name "\"; - also a **bug**). Assuming these bugs are squashed, I suppose it's a - useful special case. 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. - - Another idea. Would it be worthwhile to allow literal blocks to - begin without a newline after the "::"? Example:: - - :: while True: - print 'hello world' - - Perhaps. Perhaps not. - -* Add new syntax for _`nested inline markup`? Or extend the parser to - parse nested inline markup somehow? See the `collected notes - <http://docutils.sf.net/spec/rst/alternatives.html#nested-inline-markup>`__. - -* Idea from Beni Cherniavsky:: - - I'm writing a README document linking to all other interesting - files in its directory. If these were full URLs I could just - write them in the text but these are relative links that can't - be auto-recognized. The shortest way to make such links that I - found was `file_name <file_name>`_. Perhaps a shortcut for such - usage could be added, e.g. `<file_name>`_ would take the target - as the link name? - - IOW these would be equivalent:: - - `<file_name>`_ - `file_name <file_name>`_ - - Another possibility is to drop the backticks. Should the angle - brackets be kept in the output or not? This syntax could be adopted - in addition to the one above:: - - <file_name>_ - - -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. - -* 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? - -* Implement options on existing directives: - - - Add a "name" option to directives, to set an author-supplied - identifier? - - - _`images.image`: "border"? "link"? - - Units of measure? (See docutils-users, 2003-03-02.) - - - _`images.figure`: "title" and "number", to indicate a formal - figure? - - - _`parts.sectnum`: "local"?, "start", "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 "start" option will specify the sequence set to use at the - same time as the starting value, for the first part of the section - number (i.e., section, not subsection). For example:: - - .. sectnum: :start: 1 - - .. sectnum: :start: A - - .. sectnum: :start: 5 - - .. sectnum: :start: I - - The first one is the default: start at 1, numbered. The second - one specifies letters, and start at "A". The third specifies - numbers, start at 5. The last example could signal Roman - numerals, although I don't know if they'd be applicable here. - Enumerated lists already do all this; perhaps that code could be - reused. - - Here comes the tricky part. 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? - See docutils-develop 2003-01-29. - - - _`misc.include`: - - - "encoding" option? Take default from runtime settings. Use - Input component to read it in? - - - Option to select a range of lines? - - - Option to label lines? - - - Default directory for "built-in includes", using the C syntax - ``#include <name>``? - - Use C-preprocessor semantics for locating include files? - E.g., ``.. include:: file.txt`` will read another file into - the current one, relative to the current file's directory, - and ``.. include:: <standard>`` will read a standard include - file from ``docutils/include/``. (Should "quotes" be - required around non-standard include files?) - - -- http://sf.net/mailarchive/message.php?msg_id=1938401 - - I now think that ``docutils/parsers/rst/include/`` is a better - place for these files, since they're reStructuredText-specific. - - Keeping standard data files together with the package code makes - sense to me. It seems much less complex to implement than a - separate system data directory, such as ``/usr/share/docutils``. - Any reason a system data directory should be used? How does - Distutils handle data files? - - How about an environment variable, say RSTINCLUDEPATH or - RSTPATH? This could be combined with a setting/option to allow - user-defined include directories. - - For a specific application, see the discussion of `character - entity substitution definition files`_ above. - -* 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` (Useful outside of HTML? If not, replace with - image only in non-HTML writers?) - - - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_. - - - _`parts.citations`: See `Footnote & Citation Gathering`_. - - - _`misc.exec`: Execute Python code & insert the results. Perhaps - dangerous? Call it "python" to allow for other languages? - - - _`misc.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) - - - _`misc.eval`: Evaluate an expression & insert the text. At parse - time or at substitution time? Dangerous? Perhaps limit to canned - macros; see text.date_ below. - - - _`misc.encoding`: Specify the character encoding of the input - data. But there are problems: - - - 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. - - - _`misc.language`: Specify the language of a document. There is a - problem similar to the first problem listed for misc.encoding_, - although to a lesser degree. - - - _`misc.settings`: Set any Docutils runtime setting from within a - document? - - - _`misc.charents`: Equivalent to:: - - .. include:: {includepath}/charents.txt - - - 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. - - 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.qa` (directive a.k.a. "faq", "questions"): 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. - - - _`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. - - 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. - - 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> - - - _`body.literal`: Literal block, possibly "formal" (see `object - numbering and object references`_ above). Possible options: - - - "highlight" a range of lines - - "number" or "line-numbers" - - See docutils-users 2003-03-03. - - - _`body.sidebar`: Add to the already implemented directive. Allow - internal section structure, with adornment styles independent of - the main document. - - - _`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. - - - _`text.date`: Datestamp. For substitutions. The directive could - be followed by a formatting string, using strftime codes. Default - is "%Y-%m-%d" (ISO 8601 date), but time fields can also be used. - - - Combined with the "include" directive, implement canned macros? - E.g.:: - - .. include:: <macros> - - Today's date is |date|. - - Where "macros" contains ``.. |date| date::``, among others. - - - _`text.time`: Timestamp. For substitutions. Shortcut for - ``.. date:: %H:%M``. Date fields can also be used. - - - _`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 be known by the Parser. -Adding a new role often involves 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 -spec/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 a test for language mappings of roles. - -* Alan Jaffray suggested (and I agree) that it would be sensible to: - - - have a directive and/or command-line option to specify a default - role for interpreted text - - allow the reST processor to take an argument for the default role - (this will be subsumed by the above via the runtime settings - mechanism) - - issue a warning when processing documents with no default role - which contain interpreted text with no explicitly specified role - (there will always be a default role, so this won't happen) - -* Add a directive establishing a mapping of interpreted text role - aliases? A set of default roles (index, acronym, etc.) could exist, - and the directive could assign abbreviations (i, a, etc.) or other - alternatives. - -* 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-riference (& 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 - -* Add document-local _`role bindings`, associating directives with - roles? :: - - ``She wore ribbons in her hair and it lay with streaks of - grey``:rewrite: - - .. :rewrite: class:: 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 do need to be - worked out though. Syntax idea from Jeffrey C. Jacobs. - - 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 same thing could be done with a directive, albeit a bit more - verbosely:: - - .. role:: rewrite - :class: rewrite - - The advantage of the new syntax would be flexibility. Uses other - than "class" may present themselves. - -* Perhaps a "role" directive can modify existing roles with - attributes? :: - - .. :api-ti: role:: api - :base: twisted.internet - - To start the reactor, use the :api-ti:`reactor.run` method. To - stop it, use :api-ti:`reactor.stop`. - -* Implement roles: - - - "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? - - 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. - - __ 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`__. - - __ rst/reStructuredText.html#implicit-hyperlink-targets - - - "annotation": 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?). - - - "figure", "table", "listing", "chapter", "page", etc: See `object - numbering and object references`_ above. - - - "term"?: Unfamiliar or specialized terminology. - - - "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.) - - -Hyperlink Target Gathering -`````````````````````````` - -It probably comes in two phases, because in a Python context we need -to *resolve* them on a per-docstring basis [do we? --DG], but if the -user is trying to do the callout form of presentation, they would -then want to group them all at the end of the document. - - -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.) - -Idea: insert a "split here" attribute into the root element of each -split-out document, containing the path/filename. The Output object -will recognize this attribute and split out the files accordingly. -Must allow for common headers & footers, prev/next, breadcrumbs, etc. - - -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). - - -Filtering System Messages -````````````````````````` - -Currently the Writer is responsible for filtering out system messages -that are below the current threshold. Should the filtering be in a -separate transform? It would then happen regardless of the writer -used. Perhaps some writers don't want system messages filtered? - - -Others -`````` - -Index - - -HTML Writer ------------ - -* @@ Construct a _`templating system`, as in ht2html/yaptu, using - directives and substitutions for dynamic stuff. Or a specialized - writer to generate .ht & links.h files for ht2html? - -* Add a setting (or another writer) which produces just the contents - of the <body> element. What about the rest; it should be accessible - somehow, especially the docinfo fields. Part of the ht2html - implementation? Generic component output? - - I think a separate writer which inherits from html4css1.py would be - a good start. An "inline" or body-only HTML writer has to omit some - of the information given by the full HTML writer. Some applications - won't need this information, but others will; they'll want to deal - with it in different ways. I envision such a writer returning a set - of values: body html, and everything else (metadata). Perhaps a - tuple of this form:: - - (body_html, {'title': value, - 'subtitle': value, - 'docinfo': (tuple of (name, value) pairs), - etc.}) - - By having a separate writer, a different return data structure is - possible. We may need to add support to all of docutils to allow - for this variant output. Should the metadata values be simple text - strings, or HTML snippets (they may contain markup), or both? There - may be other issues to be worked out. - -* Add more support for <link> elements, especially for navigation - bars. - -* Make the admonitions more distinctive and varied. - -* Make the "class" attributes optional? Implies no stylesheet? - -* Add a setting to customize the header tag levels, i.e. <h1>. - -* 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. - -* Add an option to restrict the document title to <head><title> only, - and not include it in the document body. Subtitle? - - -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? - -* Implement the "sectnum" directive as a command-line option also? - -* @@@ Come up with better names for the most-used tools, and install - them as scripts. - -* Create a single dynamic_ or unqualified_ front end that can be - installed? - - -Project Policies -================ - -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, I currently function as -BDFN (Benevolent Dictator For Now), but I 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. - - .. _The Magic Cauldron: - http://www.tuxedo.org/~esr/writings/magic-cauldron/ - -Therefore, 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", not absolutes; exceptions are expected, tolerated, and -used as a source of improvement. - -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. - - -Python Coding Conventions -------------------------- - -These are the conventions I use in my own code. 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, with the following clarifications (from most to -least important): - -* 4 spaces per indentation level. No tabs. Indent continuation lines - according to the Emacs python-mode standard. - -* Use only 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 O.K.). - -* 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. - -* 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 - - -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 CVS, 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. - - -CVS Check-ins -------------- - -Instructions for CVS access can be found at -http://sourceforge.net/cvs/?group_id=38414. Anyone can access the CVS -repository anonymously. Only project developers can make changes. - -Unless you really *really* know what you're doing, please limit your -CVS commands to ``cvs checkout``, ``cvs commit/checkin``, and ``cvs -add``. Do **NOT** use ``cvs import`` unless you're absolutely sure -you know what you're doing. Even then, grab a copy of the `nightly -CVS tarball <http://cvs.sf.net/cvstarballs/docutils-cvsroot.tar.gz>`_, -set it up on your own machine, and experiment *there* first. - -The `main source tree`_ ("docutils" CVS module) should always be kept -in a stable state (usable and as problem-free as possible). The -Docutils project shall follow the `Python Check-in Policies`_ (as -applicable), with particular emphasis as follows: - -* 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 - -* 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! - -* The `sandbox CVS directory`_ is the place to put new, incomplete or - experimental code. See `Additions to Docutils`_ and `The Sandbox`_ - below. - -* For bugs or omissions that have an obvious fix and can't possibly - mess up anything else, go right ahead and check it in directly. - -* For larger changes, use your best judgement. If you're unsure of - the impact, or feel that you require advice or approval, patches or - `the sandbox`_ are the way to go. - -Docutils will pursue an open and trusting policy for as long as -possible, and deal with any abberations if (and hopefully not when) -they happen. I'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 CVS is for. - -.. _main source tree: - http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/docutils/ -.. _Python Check-in Policies: http://www.python.org/dev/tools.html -.. _sandbox CVS directory: - http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/ - - -Additions to Docutils -````````````````````` - -Additions to the project, such as new components, should be developed -in the `sandbox CVS directory`_ until they're in `good shape`_, -usable_, and `reasonably complete`_. Adding to the `main source -tree`_ or to a `parallel project`_ implies a commitment to the -Docutils user community. - -* Why the sandbox? - - Developers should be able to try out new components while they're - being developed for addition to main source tree. See `The - Sandbox`_ below. - -* _`Good shape` means that the component code is clean, readable, and - free of junk code (unused legacy code; by analogy with "junk DNA"). - -* _`Usable` means that the code does what it claims to do. An "XYZ - Writer" should produce reasonable XYZ. - -* _`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 into the main source tree, you can, -but you'll have to be prepared to work on it intensively and complete -it quickly. 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 in the sandbox first. -It's easy to move code over to the main source tree once it's closer -to completion. - - -Mailing Lists -------------- - -Developers should subscribe to the mailing lists: - -* The `Python Documentation Special Interest Group (Doc-SIG) mailing - list`__ for high-level discussions on syntax, strategy, and design - (email to Doc-SIG@python.org). -* Docutils-develop__, for implementation discussions - (email to docutils-develop@lists.sourceforge.net). -* Docutils-checkins__, to monitor CVS checkin messages (automatically - generated; normally read-only). - -__ http://mail.python.org/mailman/listinfo/doc-sig -__ http://lists.sourceforge.net/lists/listinfo/docutils-develop -__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins - - -The Sandbox ------------ - -The `sandbox CVS directory`_ is a place to play around, to try out and -share ideas. It's a part of the CVS repository but it isn't -distributed as part of Docutils releases. Feel free to check in code -to the CVS 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 `main -source tree`_. Each developer who wants to play in the sandbox should -create their own subdirectory (suggested name: SourceForge ID, -nickname, or given name + family initial). It's OK to make a mess! -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/ - userid/ - component_name/ # A verbose name is best. - README.txt # Please explain 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 - - -.. _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 CVS directory beside -(or parallel to) the main Docutils CVS directory. It can have its own -web page in the docutils.sourceforge.net domain, its own file releases -and downloadable CVS 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. - - -Release Procedure -================= - -1. Edit the version number in the following files: - - * docutils: - - - setup.py - - HISTORY.txt - - docutils/__init__.py - - * web: index.txt - -2. Run the test suite: ``cd test ; alltests.py``. - -3. Isolate from outside influence: - - (a) Remove the old installation from site-packages (including - roman.py, and optparse.py, textwrap.py for pre-2.3 - installations). - - (b) Clear/unset the PYTHONPATH environment variable. - -4. Create the release tarball: - - (a) Create a new empty directory and ``cd`` into it. - - (b) Get a clean snapshot of the CVS files:: - - cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/docutils \ - export -rHEAD docutils - - (c) Use Distutils to create the release tarball:: - - cd docutils - python setup.py sdist - -5. Expand and install the release tarball **in isolation** (as per - step 3 above): - - (a) Expand the tarball in a new location, not over any existing - files. - - (b) Install from expanded directory:: - - cd docutils-X.Y - python setup.py install - - The "install" command may require root permissions. - -6. Run the test suite from the expanded archive directory: ``cd test ; - alltests.py``. - -7. Run ``cd tools ; buildhtml.py ..`` to confirm that there are no - unexpected issues with the docs. - -8. 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 filename - -9. Log in to the SourceForge web interface. - -10. 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 announcement> - - Also check the "Preserve my pre-formatted text" box. - -11. Wait up to 30 minutes for the file to become available on - SourceForge. - -12. Download the release tarball and verify its integrity by walking - through an installation, as outlined above (steps 5, 6, & 7). - -13. Add a SourceForge News item, with title "Docutils 0.x released" - and containing the release tarball's download URL. - -14. Send announcement email to: - - * docutils-develop@lists.sourceforge.net - * docutils-users@lists.sourceforge.net - * doc-sig@python.org - * python-list@python.org - * python-announce@python.org - -15. Register - - (a) with PyPI (Fill in details. ``python setup.py register``? - How to log in?) - (b) with Vaults of Parnassus - (c) with FreshMeat? - - -.. - 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 11a8d13bd..000000000 --- a/docutils/docs/howto/i18n.txt +++ /dev/null @@ -1,178 +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`_. 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``. - -.. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html -.. _ISO 639: http://lcweb.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 just one module -attribute: - -``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 diff --git a/docutils/docs/howto/rst-directives.txt b/docutils/docs/howto/rst-directives.txt deleted file mode 100644 index 377ca31ad..000000000 --- a/docutils/docs/howto/rst-directives.txt +++ /dev/null @@ -1,348 +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`_. - -.. _reStructuredText Markup Specification: - ../rst/reStructuredText.html#directives -.. _reStructuredText Directives: ../rst/directives.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. Directives -have no corresponding element; choose the most appropriate elements -from the existing Docutils elements. See `The Docutils Document -Tree`_ and the ``docutils.nodes`` module. - -.. _The Docutils Document Tree: ../doctree.html - - -Specify Directive Arguments, Options, and Content -================================================= - -Function attributes are interpreted by the directive parser (the -``docutils.parsers.rst.states.Body.parse_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``: Returns the argument, unchanged. Raises - ``ValueError`` if no argument is found. - - - ``path``: Returns the path argument unwrapped (with newlines - removed). Raises ``ValueError`` if no argument is found or if the - path contains internal whitespace. - - - ``nonnegative_int``: Checks for a nonnegative integer argument, - and raises ``ValueError`` if not. - - 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 ``parse_directive()`` method is to call the -directive function itself. - - -Register the Directive -====================== - -Register the new directive in -``docutils/parsers/rst/directives/__init__.py``, in the -``_directive_registry`` dictionary. This allows the reStructuredText -parser to find and use the directive. - -Add an entry to ``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. - -Please check for and update any other language modules for languages -in which you are proficient. - - -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, 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 the -image directive function:: - - def image(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - reference = ''.join(arguments[0].split('\n')) - if reference.find(' ') != -1: - error = state_machine.reporter.error( - 'Image URI contains whitespace.', '', - nodes.literal_block(block_text, block_text), - line=lineno) - return [error] - 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 newlines. Then the - result is checked for embedded spaces, which are *not* allowed. - -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 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/peps/pep-0256.txt b/docutils/docs/peps/pep-0256.txt deleted file mode 100644 index bad386391..000000000 --- a/docutils/docs/peps/pep-0256.txt +++ /dev/null @@ -1,299 +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_ - -- 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://www.perldoc.com/perl5.6/pod/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.lemburg.com/files/python/SoftwareDescriptions.html#doc.py - -.. _pythondoc: -.. _gendoc: http://starship.python.net/crew/danilo/pythondoc/ - -.. _HappyDoc: http://happydoc.sourceforge.net/ - -.. _Crystal: http://www.btinternet.com/~tratt/comp/python/crystal/ - -.. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html - -.. _docutils: http://homepage.ntlworld.com/tibsnjoan/docutils/ - -.. _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 09bec5d88..000000000 --- a/docutils/docs/peps/pep-0258.txt +++ /dev/null @@ -1,999 +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). - - - 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``) - - - Module "docutils.writers.html4css1" is a simple HyperText Markup - Language document tree writer for HTML 4.01 and CSS1. - - - 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. - - - Writers to be added: HTML 3.2 or 4.01-loose, XML (various forms, - such as DocBook), PDF, TeX, plaintext, reStructuredText, and - perhaps others. - - 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.sf.net/docs/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 - 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. - -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/spec/docutils.dtd - -.. _soextbl.dtd: http://docutils.sourceforge.net/spec/soextblx.dtd - -.. _The Docutils Document Tree: - http://docutils.sourceforge.net/spec/doctree.html - -.. _VMS error condition severity levels: - http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html - #error_cond_severity - -.. _log4j project: http://jakarta.apache.org/log4j/ - -.. _Docutils Python Source DTD: - http://docutils.sourceforge.net/spec/pysource.dtd - -.. _ISO 639: http://lcweb.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 c6e48901b..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/spec/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/spec/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://www.perldoc.com/perl5.6/pod/perlpod.html - -.. _JavaDoc: http://java.sun.com/j2se/javadoc/ - -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html - -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage - -.. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/rst/quickstart.html - -.. _Quick reStructuredText: - http://docutils.sourceforge.net/docs/rst/quickref.html - -.. _An Introduction to reStructuredText: - http://docutils.sourceforge.net/spec/rst/introduction.html - -.. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html - -.. _reStructuredText Directives: - http://docutils.sourceforge.net/spec/rst/directives.html - -.. _Problems with StructuredText: - http://docutils.sourceforge.net/spec/rst/problems.html - -.. _A Record of reStructuredText Syntax Alternatives: - http://docutils.sourceforge.net/spec/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 7f0c6cd6d..000000000 --- a/docutils/docs/ref/doctree.txt +++ /dev/null @@ -1,4840 +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: ../docs/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, docinfo, decoration] | - | +--------------------------------------+ - | | 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. - -Category members: title_, subtitle_, docinfo_, decoration_, -transition_ - - -Bibliographic Elements -`````````````````````` - -The docinfo_ element is an optional child of document_. It groups -bibliographic elements together. - -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_, 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 directly are empty or 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_, line_block_, -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_, danger_, definition_list_, enumerated_list_, -error_, field_list_, figure_, footnote_, hint_, important_, 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_, 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 id="a-title" name="a title"> - <title>A Title</title> - <paragraph>A paragraph.</paragraph> - </section> - </document> - - - Pseudo-XML:: - - <document> - <section id="a-title" name="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 -line_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 line_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`_ (id_, - name_, dupname_, source_, and class_), 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 id="document-title" name="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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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`_: id_, name_, dupname_, source_, and class_. - -: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`_ - (id_, name_, dupname_, source_, and class_), 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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - - -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`_. - - -``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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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. - - -``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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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 -page navigation, notes, time/datestamp, etc. Currently only the -footer_ element is implemented, populated with processing information -(datestamp, a link to Docutils_, 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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: id_, name_, dupname_, source_, and class_. - -: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`_: id_, name_, dupname_, source_, and class_. - - -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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: - id_, name_, dupname_, source_, and class_. - - -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 id="docinfo-example" name="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`_ - (id_, name_, dupname_, source_, and class_), 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_?)?, - docinfo_?, - decoration_?, - `%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 "docinfo_" may be transformed from -an initial field_list_, and "decoration_" is usually constructed -programmatically. - -See the `%structure.model;`_ parameter entity for details of the body -of a ``document``. - -:Attributes: - The ``document`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. - - -Examples --------- - -reStructuredText_ source:: - - A Title - ======= - - A paragraph. - -Complete pseudo-XML_ result from simple parsing:: - - <document> - <section id="a-title" name="a title"> - <title> - A Title - <paragraph> - A paragraph. - -After applying transforms, the section title is promoted to become the -document title:: - - <document id="a-title" name="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`_ - (id_, name_, dupname_, source_, and class_), 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`_: id_, - name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: - id_, name_, dupname_, source_, and class_. - -: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 data only. It is analogous -to a database field's name. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the field_ element contains ``field_name``. - -:Children: - ``field_name`` elements have no children. They may contain text - data only. - -:Analogues: - ``field_name`` has no direct analogues in common DTDs. - -:Processing: - See field_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (#PCDATA) - -:Attributes: - The ``field_name`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. - - -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. Currently the ``footer`` element may contain -processing information (datestamp, a link to Docutils_, etc.). - - -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`_: - id_, name_, dupname_, source_, and class_. - - -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`` -============= - -`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. Docutils does not yet make use of the ``header`` element. - - -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`_: - id_, name_, dupname_, source_, and class_. - - -Examples --------- - -None. - - -``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`_: id_, - name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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_block`` -============== - -The ``line_block`` element contains a block of text where line breaks -and whitespace are significant and must be preserved. ``line_block`` -elements are commonly used for verse and addresses. See `line_block`_ -for an alternative useful for program listings and interactive -computer sessions. - - -Details -------- - -:Category: - `Simple 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 text data plus `inline - 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 all - whitespace and line breaks are preserved in the rendered form. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``line_block`` element contains the `common attributes`_ (id_, - name_, dupname_, source_, and class_), 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! - - .. line-block:: - - 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 xml:space="preserve"> - A one, two, a one two three four - - Half a bee, philosophically, - must, <emphasis>ipso facto</emphasis>, half not be. - But half the bee has got to be, - <emphasis>vis a vis</emphasis>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... - - -``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`_: - id_, name_, dupname_, source_, and class_. - - -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`_ - (id_, name_, dupname_, source_, and class_), 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`_: id_, - name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - - -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`_ (id_, - name_, dupname_, source_, and class_), 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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="title-1" name="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="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`_. - -: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;`_)+) - -:Attributes: - The ``sidebar`` element contains only the `common attributes`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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`_: - id_, name_, dupname_, source_, and class_. - - -Examples --------- - -reStructuredText_ source:: - - ======= - Title - ======= - ---------- - Subtitle - ---------- - - A paragraph. - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document id="title" name="title"> - <title> - Title - <subtitle id="subtitle" name="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 ``id`` and ``name`` -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`_: - id_, name_, dupname_, source_, and class_. - - -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`_: id_, - name_, dupname_, source_, and class_. - -: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`` -========= - -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`_ (id_, - name_, dupname_, source_, and class_), 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 id="a-title" name="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`` (or sidebar_). - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The following elements may contain ``topic``: document_, section_ - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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 other body -elements, 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`__. - -__ rst/alternatives.txt#doctree-representation-of-transitions -__ rst/alternatives.txt - - -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`_: - id_, name_, dupname_, source_, and class_. - -: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`_: - id_, name_, dupname_, source_, and class_. - -: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 id="document-title" name="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`_: - id_, name_, dupname_, source_, and class_. - -: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: id_, name_, dupname_, -source_, and class_. - -.. _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 id_ -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. - - -``class`` -========= - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``class`` attribute contains 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 ``class`` attribute's contents should be ignorable. Writers that -are not familiar with the variant expressed should be able to ignore -the attribute. - -``class`` 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. - - -``dupname`` -=========== - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``dupname`` attribute contains the name of an element when there -has been a naming conflict. The contents of the ``dupname`` attribute -would have been transferred from the `name`_ attribute. An element -may have at most one of the ``name`` or ``dupname`` attributes, but -not both. ``dupname`` 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. - - -``id`` -====== - -`Attribute type`_: ``ID``. Default value: none. - -The ``id`` attribute contains a unique identifier key. ``id`` is one -of the `common attributes`_, shared by all Docutils elements. - - -``name`` -======== - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``name`` attribute contains the name of an element, typically -originating from the element's title or content. ``name`` must be -unique; if there are name conflicts (two or more elements want to the -same name), the contents will be transferred to the `dupname`_ -attribute on the duplicate elements. An element may have at most one -of the ``name`` or ``dupname`` attributes, but not both. ``name`` 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 `id`_ 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 -`name`_ 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. - - ----------------------------- - 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:: - - id_ ID #IMPLIED - name_ NMTOKENS #IMPLIED - dupname_ NMTOKENS #IMPLIED - source_ CDATA #IMPLIED - class_ 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_ | 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_ - | 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_, 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 `id`_ 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 `name`_ 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_, (`%body.elements;`_ | topic_ | sidebar_)+ )*, - (`%section.elements;`_)* ) - | (`%section.elements;`_)+ ) - -Each document_ or section_ contains either: - -- multiple body elements, topics, and/or sidebars, optionally - interspersed with transitions (but transitions cannot occur at the - beginning or end, nor may there be two transitions in a row), - followed by zero or more sections; or - -- one or more sections (whose contents are recursively the same as this - model). - -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_, 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 06fe4bf55..000000000 --- a/docutils/docs/ref/docutils.dtd +++ /dev/null @@ -1,571 +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/spec/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"> - -<!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 - " id ID #IMPLIED - name NMTOKENS #IMPLIED - dupname NMTOKENS #IMPLIED - source CDATA #IMPLIED - class 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' "> - - -<!-- 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 | 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 - | 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 -================================================================== --> - -<!ENTITY % structure.model - " ( ( (%body.elements; | topic | sidebar)+, - (transition, (%body.elements; | topic | sidebar)+ )*, - (%section.elements;)* ) - | (%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; "> -<!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?)?, docinfo?, decoration?, %structure.model;)> -<!ATTLIST document %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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;> - -<!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, %structure.model;)> -<!ATTLIST section %basic.atts;> - -<!ELEMENT topic (title?, (%body.elements;)+)> -<!ATTLIST topic %basic.atts;> - -<!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)> -<!ATTLIST sidebar %basic.atts;> - -<!ELEMENT transition EMPTY> -<!ATTLIST transition %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Body Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT paragraph %text.model;> -<!ATTLIST paragraph %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 (#PCDATA)> -<!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 %text.model;> -<!ATTLIST line_block - %basic.atts; - %fixedspace.att;> - -<!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;> - -<!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; - width %number; #IMPLIED> - -<!-- Also an inline element. --> -<!ELEMENT image EMPTY> -<!ATTLIST image - %basic.atts; - uri CDATA #REQUIRED - alt CDATA #IMPLIED - height %number; #IMPLIED - width %number; #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 NMTOKEN #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;> - -<!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/directives.txt b/docutils/docs/ref/rst/directives.txt deleted file mode 100644 index 5fc316a99..000000000 --- a/docutils/docs/ref/rst/directives.txt +++ /dev/null @@ -1,979 +0,0 @@ -============================= - reStructuredText Directives -============================= -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -: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. - -.. _Directives: ./reStructuredText.html#directives -.. _reStructuredText Markup Specification: ./reStructuredText.html -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../gpdi.dtd - - -------------- - 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 height of the image in pixels, used to reserve space or scale - the image vertically. - -``width`` : integer - The width of the image in pixels, used to reserve space or scale - the image horizontally. - -``scale`` : integer - The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size. - -``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. - -``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_ [#]_). 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. - -.. [#] `Python Imaging Library`_. - -.. _PIL: -.. _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 (including 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 -========== - -: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 whitespace -(including linebreaks) 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; there is no protection from parsing. -Backslash-escapes may be necessary in places. - -For example, all the element names in this content model are links:: - - .. parsed-literal:: - - ((title_, - subtitle_?)?, - docinfo_?, - decoration_?, - `%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. - -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. - -Produces a highlights-class block quote. See Epigraph_ above. - - -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. - -Produces a pull-quote-class block quote. See Epigraph_ above. - - ----------------- - 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 inserts a table of contents (TOC) in two -passes: initial parse and transform. During the initial parse, a -"pending" element is generated which acts as a placeholder, storing -the TOC title and any options internally. At a later stage in the -processing, the "pending" element is replaced by a "topic" element, a -title and the table of contents proper. - -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. - - ------------- - References ------------- - -.. _target-notes: - -Target Footnotes -================ - -:Directive Type: "target-notes" -:Doctree Elements: pending, footnote, footnote_reference -:Directive Arguments: None. -:Directive Options: None. -: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. - - -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. - - ---------------- - Miscellaneous ---------------- - -.. _include: - -Including an External Document Fragment -======================================= - -:Directive Type: "include" -:Doctree Elements: depend on data being included -:Directive Arguments: One, required (path to include file). -:Directive Options: Possible. -:Directive Content: None. - -The "include" directive reads a reStructuredText-formatted text file -and parses it in the current document's context at the point of 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. - -The text encoding of the master input source is used for included -files. - -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). - - -.. _raw: - -Raw Data Pass-Through -===================== - -:Directive Type: "raw" -:Doctree Element: raw -:Directive Arguments: One, required (output format type). -:Directive Options: Possible. -:Directive Content: Stored verbatim, uninterpreted. None (empty) if a - "file" or "url" option given. - -The "raw" directive indicates non-reStructuredText data that is to be -passed untouched to the Writer. The name of the output format is -given in the first argument. 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 - - \documentclass[twocolumn]{article} - -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 - The local filesystem path of a raw data file to be included. -``url`` : string - An Internet URL reference to a raw data file to be included. - - -.. _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: None. -:Directive Content: None. - -The "unicode" directive converts Unicode character codes (numerical -values) to characters, and may be used in substitution definitions -only. Codes may be decimal numbers, hexadecimal numbers (prefixed by -``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numeric -character entities (e.g. ``ᨫ``). Codes are case-insensitive. - -Text following " .. " is a comment and is ignored. Spaces are -ignored, and any other text remains as-is. - -Example:: - - Copyright |copy| 2003, |BogusMegaCorp (TM)|. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - - -Class -===== - -:Directive Type: "class" -:Doctree Element: pending -:Directive Arguments: One, required (class name / attribute value). -:Directive Options: None. -:Directive Content: None. - -The "class" directive sets a "class" attribute value on the first -immediately following non-comment element [#]_. For details of the -"class" attribute, see `its entry`__ in `The Docutils Document Tree`_. -The "class" attribute value is converted to lowercase and all -non-alphanumeric characters are converted to hyphens in order to match -this regular expression: ``[a-z](-?[a-z0-9]+)*``. See the docstring -from ``docutils.nodes.make_id`` for the rationale. - -Examples:: - - .. class:: special - - This is a "special" paragraph. - - .. class:: exceptional - - An Exceptional Section - ====================== - - This is an ordinary paragraph. - -The text above is parsed and transformed into this doctree fragment:: - - <paragraph class="special"> - This is a "special" paragraph. - <section class="exceptional"> - <title> - An Exceptional Section - <paragraph> - This is an ordinary 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. - -__ ../doctree.html#class - - -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 13823b5b7..000000000 --- a/docutils/docs/ref/rst/introduction.txt +++ /dev/null @@ -1,315 +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://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _A ReStructuredText Primer: ../../docs/rst/quickstart.html -.. _Quick reStructuredText: ../../docs/rst/quickref.html -.. _reStructuredText Markup Specification: reStructuredText.html -.. _Problems with StructuredText: 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/spec/, 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://dev.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG -.. _project history file: http://docutils.sourceforge.net/HISTORY.html -.. _PEP 287: http://docutils.sourceforge.net/spec/pep-0287.html -.. _Docstring Processing System framework: - http://docutils.sourceforge.net/spec/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 1ad25ff35..000000000 --- a/docutils/docs/ref/rst/restructuredtext.txt +++ /dev/null @@ -1,2679 +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: ../../docs/rst/quickstart.html -.. _Quick reStructuredText: ../../docs/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 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 - -- `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: - -- multi-line contents of list items, -- multiple body elements within a list item (including nested lists), -- the definition part of a definition list item, -- block quotes, -- the extent of literal blocks, and -- the extent 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. 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). - -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. - -Nested enumerated lists must be created with indentation. For -example:: - - 1. Item 1. - - a) Item 1a. - b) Item 1b. - -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, an optional classifier, and -a definition. A term is a simple one-line word or phrase. An -optional classifier may follow the term on the same line, 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. - -Inline markup is parsed in the term line before the term/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 is made up of one or more letters, -numbers, whitespace, and punctuation, except colons (":"). Field -names are case-insensitive. 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. A -specialized form of line block`_ (see `reStructuredText Directives`_), -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 all of these conditions -hold: - -1. The field list is in bibliographic context (first non-comment - construct in the document, after a document title if there is - one). - -2. The field name is a recognized bibliographic field name. - -3. The sole contents of the field is an expanded RCS keyword, of the - form "$Keyword: data $". - - -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. - -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 all -following **indented** text blocks comprise a literal block. 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. A 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 - -The minimum leading whitespace will be removed from each line of the -literal block. Other than that, all whitespace (including line -breaks) 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. - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | (ends with "::") | - +------------------------------+ - +---------------------------+ - | literal block | - +---------------------------+ - - -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 "--" (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. - -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 immediately after the explicit markup start -determines the indentation of the block body. 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`_). - -If the first body element within a footnote is a simple paragraph, it -may begin on the same line as the footnote label. Other elements must -begin on a new line, consistently indented (by at least 3 spaces) and -left-aligned. - -Footnotes may occur anywhere in the document, not only at the end. -Where or 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 "†") -- double dagger ("‡") -- section mark ("§") -- pilcrow or paragraph mark ("¶") -- number sign ("#") -- spade suit ("♠") -- heart suit ("♥") -- diamond suit ("♦") -- club suit ("♣") - -.. [#] 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.). - - -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 stripped of leading and trailing whitespace and concatenated. - 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 a reference name contains a colon followed by whitespace, 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 syntax. 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: - -- To avoid 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), the entire - directive block (including the directive itself) will be treated as - a literal block, and a level-3 (error) system message generated. - 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 an image. 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/ - - -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:: ! - -A 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. - -.. 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 W3C's `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. - -.. [#URI] Uniform Resource Identifier. URIs are a general form of - URLs (Uniform Resource Locators). For the syntax of URIs see - RFC2396_ and RFC2732_. - - ----------------- - 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: ../gpdi.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/manual/glibc-2.2.3/html_node/libc_516.html -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html -.. _Emacs table mode: http://table.sourceforge.net/ -.. _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 -.. _reStructuredText Directives: directives.html -.. _reStructuredText Interpreted Text Roles: interpreted.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: http://docutils.sourceforge.net/spec/pep-0258.txt - - -.. - 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 a34c4a5ed..000000000 --- a/docutils/docs/ref/rst/roles.txt +++ /dev/null @@ -1,175 +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:`_. - -See the `Interpreted Text`_ section in the `reStructuredText Markup -Specification`_ for syntax details. - -.. _Interpreted Text: ./reStructuredText.html#interpreted-text -.. _reStructuredText Markup Specification: ./reStructuredText.html - - -.. contents:: - - -``:emphasis:`` -============== - -:Aliases: None -:DTD Element: emphasis - -Implements emphasis. These are equivalent:: - - *text* - :emphasis:`text` - - -``:literal:`` -============== - -:Aliases: None -:DTD Element: literal - -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 - -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 - -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 - -Implements strong emphasis. These are equivalent:: - - **text** - :strong:`text` - - -``:subscript:`` -=============== - -:Aliases: ``:sub:`` -:DTD Element: subscript - -Implements subscripts. - - -``:superscript:`` -================= - -:Aliases: ``:sup:`` -:DTD Element: superscript - -Implements superscripts. - - -``:title-reference:`` -===================== - -:Aliases: ``:title:``, ``:t:``. -:DTD Element: title_reference - -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 role must be used. - - -.. _pseudo-XML: ../doctree.html#pseudo-xml 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 4c5fe135a..000000000 --- a/docutils/docs/ref/transforms.txt +++ /dev/null @@ -1,103 +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: 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 - -frontmatter.DocTitle standalone (r) 320 - -frontmatter.DocInfo standalone (r) 340 - -peps.Headers pep (r) 360 - -peps.Contents pep (r) 380 - -references.ChainedTargets standalone (r), pep (r) 420 - -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) - -peps.PEPZero pep.Headers (t/p) 760 - -components.Filter "meta" (d/p) 780 - -universal.Decorations Transformer 820 - -universal.FinalChecks Transformer 840 - -universal.Messages Transformer 860 - -universal.TestMessages DocutilsTestSupport 890 - -misc.CallBack n/a 990 -============================== ============================ ======== - -Key: - -* (r): Reader -* (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/latex.txt b/docutils/docs/user/latex.txt deleted file mode 100644 index 1b3d0b53b..000000000 --- a/docutils/docs/user/latex.txt +++ /dev/null @@ -1,263 +0,0 @@ -======================= - Docutils LaTex Writer -======================= - -: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. - - -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. - -Options on the Commandline --------------------------- - -===================== ================================================ -Setting/Config Entry Description -===================== ================================================ ---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. ---------------------- ------------------------------------------------ ---hyperlink-color Color of any hyperlinks embedded in text - (default: "blue", "0" to disable). ---------------------- ------------------------------------------------ ---documentclass Specify latex documentclass, *but* beaware that - books have chapters articles not. - (default: "article"). ---------------------- ------------------------------------------------ ---stylesheet Specify a stylesheet file. The file will be - ``input`` by latex in the document header. - If this is set to "" disables generation of - input latex command. - (default: "style.tex"). ---------------------- ------------------------------------------------ ---footnote-references Format for footnote references: one of - "superscript" or "brackets". - Default is "brackets". ---------------------- ------------------------------------------------ ---attribution Format for block quote attributions: one of - "dash" (em-dash prefix), "parentheses"/"parens", - or "none". - - Default: "dash". Options: ``--attribution``. -===================== ================================================ - - -Options in the Stylesheet -------------------------- - -===================== ================================================ -Setting/Config Entry 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. ---------------------- ------------------------------------------------ -font selection see below -===================== ================================================ - -Missing options ---------------- - -* Selection of latex fontsize. -* Assumed reST linelength for table width setting. - -Font selection --------------- - -When generating pdf-files from LaTeX, use the pdflatex command, the files -are a lot smaller if postscript fonts are used. To do so put -``\usepackage{times}`` into the styleshee - -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}``. - - -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} - - -Problems -======== - -Open to be fixed or open to discussion. - -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}. -* Table heads and footer for longtable (firstpage lastpage ..). -* Longtable does not work with multirow -* Tabularx says "do not use any multicolmn which spans any X column. - maybe use ltxtable instead of tabularx (Longtable combined with tabularx). - but ltxtable disables longtable's multicolumn. -* Table cells with multirow and multicolumn -* Tables have borders, and the border is missing in empty cells. - - -Miscellaneous -------------- - -* recongize LaTeX (or even latex) and replace by ```\LaTeX``. -* Support embed-stylesheet. -* the ^-sign is problematic: using mathmode wedge is usually the wrong font. -* 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. - -* Hyphens: co-developers should be co--developers ? -* The indentional problematic error in test.txt is not referring anywhere. -* Footnotes are not all on the same page (as in tools/test.txt) and do not link back - and forth. -* No link to system errors. -* Hyperlinks are not hyphenated this leads to bad spacing. see tools/test.txt - 2.14 directives 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). - 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 b60cbf1b0..000000000 --- a/docutils/docs/user/rst/quickref.html +++ /dev/null @@ -1,1243 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> - <head> - <title>Quick reStructuredText</title> - - <style type="text/css"><!-- - a.backref { text-decoration: none ; color: black } - --></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/rst/quickref.html" - >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> - <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2003-06-10</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="../../spec/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/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="#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="../../spec/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="#hyperlinks" >Hyperlinks</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">Hyperlinks</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">Hyperlinks</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">Hyperlinks</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="../../spec/rst/reStructuredText.html#backslashes">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="../../spec/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> - - <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. - </table> - - <h2><a href="#contents" name="paragraphs" class="backref" - >Paragraphs</a></h2> - - <p>(<a href="../../spec/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="../../spec/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="../../spec/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> - <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). - </ol> - </table> - - <h2><a href="#contents" name="definition-lists" class="backref" - >Definition Lists</a></h2> - - <p>(<a href="../../spec/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="../../spec/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="../../spec/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%"><p><samp>-a</samp> - <td><p>command-line option "a" - <tr> - <td><p><samp>-b <i>file</i></samp> - <td><p>options can have arguments and long descriptions - <tr> - <td><p><samp>--long</samp> - <td><p>options can be long also - <tr> - <td><p><samp>--input=<i>file</i></samp> - <td><p>long options can also have arguments - <tr> - <td><p><samp>/V</samp> - <td><p>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="../../spec/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>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::</samp> -<br> -<br><samp> We start here</samp> -<br><samp> and continue here</samp> -<br><samp> and end here.</samp> -<br> -<br><samp>is possible.</samp> - - <td> - <p>A paragraph containing only two colons -indicates that the following indented -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: - - <pre> - We start here - and continue here - and end here.</pre> - - <p>is possible. - </table> - - <h2><a href="#contents" name="block-quotes" class="backref" - >Block Quotes</a></h2> - - <p>(<a href="../../spec/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="../../spec/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="../../spec/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"> - <tr valign="top"> - <th>Header 1 - <th>Header 2 - <th>Header 3 - <tr> - <td>body row 1 - <td>column 2 - <td>column 3 - <tr> - <td>body row 2 - <td colspan="2">Cells may span columns. - <tr valign="top"> - <td>body row 3 - <td rowspan="2">Cells may<br>span rows. - <td rowspan="2"> - <ul> - <li>Cells - <li>contain - <li>blocks. - </ul> - <tr valign="top"> - <td>body row 4 - </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 frame="border" rules="all"> - <colgroup> - <col colwidth="31%" /> - <col colwidth="31%" /> - <col colwidth="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="../../spec/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="../../spec/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="../../spec/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="../../spec/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> - <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>Indirect hyperlinks, like - <a href="http://www.python.org">Python</a>. - <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. - - <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><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. - <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="../../spec/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="../../spec/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"> <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="../../spec/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="../../spec/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="../../spec/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="../../spec/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@users.sourceforge.net">goodger@users.sourceforge.net</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 d936147b0..000000000 --- a/docutils/docs/user/rst/quickstart.txt +++ /dev/null @@ -1,382 +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/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 overline 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`_``". - -To indicate the document title, 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" 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. - -__ ../../spec/rst/directives.html -__ ../../spec/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`_. The `Docutils project web site`_ has more -information. - -.. [#] If that relative link doesn't work, try the master document: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html. - -.. _reStructuredText Markup Specification: - ../../spec/rst/reStructuredText.html -.. _post a message: mailto:docutils-users@lists.sourceforge.net -.. _Docutils-Users mailing list: - http://lists.sourceforge.net/lists/listinfo/docutils-users -.. _Docutils project web site: http://docutils.sourceforge.net/ diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt deleted file mode 100644 index b9af291f6..000000000 --- a/docutils/docs/user/tools.txt +++ /dev/null @@ -1,724 +0,0 @@ -========================== - Docutils Front-End Tools -========================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -: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 pep2html.py_. See html.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`_. The `Docutils project web site`_ has more -information. - -.. _post a message: mailto:docutils-users@lists.sourceforge.net -.. _Docutils-Users mailing list: - http://lists.sourceforge.net/lists/listinfo/docutils-users -.. _Docutils project web site: http://docutils.sourceforge.net/ - - -The 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 -(tools/test.txt contains intentional errors); use the ``--quiet`` -option to suppress all warnings. The ``--config`` option ensures that -the correct stylesheets, templates, and settings are in place -(``./docutils.conf`` is picked up automatically). Command-line -options may be used to override config file settings or replace them -altogether. - - -html.py -------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: HTML - -The ``html.py`` front end reads standalone reStructuredText source -files and produces HTML 4 (XHTML 1) output compatible with modern -browsers. For example, to process a reStructuredText file -"``test.txt``" into HTML:: - - html.py test.txt test.html - -In fact, there *is* a "``test.txt``" file in the "``tools``" -directory. It contains "at least one example of each reStructuredText -construct", including intentional errors. Use it to put the system -through its paces and compare input to output. - -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 projects, add some options:: - - html.py -stg test.txt test.html - - -Stylesheets -``````````` - -``html.py`` inserts into the generated HTML a link to a cascading -stylesheet, defaulting to "``default.css``" (override with a -"``--stylesheet``" or "``--stylesheet-path``" command-line option or -with configuration file settings). The -"``tools/stylesheets/default.css``" stylesheet is provided for basic -use. To experiment with styles, rather than editing the default -stylesheet (which will be updated as the project evolves), it is -recommended to use an "``@import``" statement to create a "wrapper" -stylesheet. For example, a "``my.css``" stylesheet could contain the -following:: - - @import url(default.css); - - h1, h2, h3, h4, h5, h6, p.topic-title { - font-family: sans-serif } - -Generate HTML with the following command:: - - html.py -stg --stylesheet my.css test.txt test.html - -When viewed in a browser, the new "wrapper" stylesheet will change the -typeface family of titles to "sans serif", typically Helvetica or -Arial. Other styles will not be affected. Styles in wrapper -stylesheets override styles in imported stylesheets, enabling -incremental experimentation. - - -pep.py ------- - -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML - -``pep.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 a -"``default.css``" stylesheet in the current directory, but these can -be overridden by command-line options or configuration files. The -"``tools/stylesheets/pep.css``" stylesheet is intended specifically -for PEP use. - -The "``docutils.conf``" `configuration file`_ in the "``spec``" -directory of Docutils contains a default setup for use in processing -the PEP files there (``spec/pep-*.txt``) into HTML. It specifies a -default template (``tools/pep-html-template``) and a default -stylesheet (``tools/stylesheets/pep.css``). See Stylesheets_ above -for more information. - - -pep2html.py ------------ - -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML - -``pep2html.py`` is a modified version of the original script by -Fredrik Lundh, with support for Docutils added. It reads the -beginning of a PEP text file to determine the format (old-style -indented or new-style reStructuredText) and processes accordingly. -Since it does not use the Docutils front end mechanism (the common -command-line options are not supported), it must be configured using -`configuration files`_. The template and stylesheet requirements of -``pep2html.py`` are the same as those of `pep.py`_ above. - -Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt -files. If no arguments are given, all files of the form -"``pep-*.txt``" are processed. - - -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 or png images are not handled, when processed with - ``latex``, use ``pdflatex`` instead. -- Only Latin-1 is tested up to now. -- The generated file includes a file ``style.tex``, which allows the - inclusion of special packages or changes to settings made in the - header. -- Not all constructs are possible (e.g. multirow/multicoumn entries in - tables are not). - - -docutils-xml.py ---------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: XML (Docutils native) - -The ``docutils-xml.py`` front end produces Docutils-native XML output. -This can be transformed with standard XML tools such as XSLT -processors into arbitrary final forms. - - -publish.py ----------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: Pseudo-XML - -``publish.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`_. - -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 -`Configuration File Entries`_ below. - - -.. _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. - -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. - -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. - -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. The optional - values can contain format strings which refer to other values in - the same section, or values in a special DEFAULT section. - Additional defaults can be provided upon initialization and - retrieval. Lines beginning with "#" or ";" are ignored and may be - used to provide comments. - -Docutils currently only uses an "[options]" section; all other -sections are ignored. - -.. Note:: The configuration file format may change in the future. - -Configuration entry names correspond to internal option attributes. -Underscores ("_") and hyphens ("-") can be used interchangably in -entry names. The correspondence between entry names and command-line -options is listed in `Configuration File Entries`_ below. - -.. _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 - - -Configuration File Entries --------------------------- - -Listed below are the Docutils runtime settings. Most may be specified -in `configuration files`_, where hyphens may be used in place of -underscores. Some knowledge of Python_ is assumed for some -attributes. - -attribution - (HTML Writer.) Format for block quote attributions: one of "dash" - (em-dash prefix), "parentheses"/"parens", or "none". - - Default: "dash". Options: ``--attribution``. - -compact_lists - (HTML Writer.) Remove extra vertical whitespace between items of - bullet lists and enumerated lists, when list items are "simple" - (i.e., all items each contain one paragraph and/or one "simple" - sublist only). - - Default: enabled (1). Options: ``--compact-lists, - --no-compact-lists``. - -config - Path to a configuration file to read (if it exists) - [#pwd]_. Settings may override defaults and earlier settings. - This is only effective as a command-line option; setting it in a - config file has no effect. - - 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``. - -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``. - - __ http://www.python.org/doc/current/lib/module-time.html - -debug - Report debug-level system messages. - - Default: don't (None). Options: ``--debug, --no-debug``. - -docinfo_xform - (Standalone Reader.) Enable or disable the bibliographic field - list transform (docutils.transforms.frontmatter.DocInfo). - - Default: enabled (1). Options: ``--no-doc-info``. - -doctitle_xform - - (Standalone Reader.) 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 (). Options: ``--no-doc-title``. - -doctype_declaration - (XML Writer.) Generate XML with a DOCTYPE declaration. - - Default: do (1). Options: ``--no-doctype``. - -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). - -embed_stylesheet - (HTML Writer.) Embed the stylesheet in the output HTML file. The - stylesheet file must be accessible during processing. The - stylesheet is embedded inside a comment, so it must not contain - the text "``--``" (two hyphens). - - Default: link, don't embed (None). Options: ``--embed-stylesheet, - --link-stylesheet``. - -error_encoding - The text encoding for error output. - - Default: "ascii". Options: ``--error-encoding, -e``. - -error_encoding_error_handler - The encoding error handler for unencodable characters in error - output. Acceptable values are the same as for the "error" - parameter of Python's ``encode`` string method. - - Default: "backslashreplace" for Python 2.3 and later; "replace" - otherwise. Options: ``--error-encoding-error-handler, - --error-encoding, -e``. - -exit_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``. - -expose_internals - List of internal attribues to expose as external attributes (with - "internal:" namespace prefix). - - 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``. - -footnote_references - (HTML Writer.) Format for footnote references, one of - "superscript" or "brackets". - - Default: "superscript"; "brackets" in PEP/HTML Writer. Options: - ``--footnote-references``. - -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. - - Default: severe (4). Options: ``--halt, --strict``. - -indents - (XML Writer.) Generate XML with indents and newlines. - - Default: don't (None). Options: ``--indents``. - -input_encoding - The text encoding for input. - - Default: auto-detect (None). Options: ``--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``. - -newlines - (XML Writer.) Generate XML with newlines before and after tags. - - Default: don't (None). Options: ``--newlines``. - -no_random - (PEP/HTML Writer.) Workaround for platforms which core-dump on - "``import random``". - - Default: random enabled (None). Options: ``--no-random`` - (hidden). - -output_encoding - The text encoding for output. - - Default: "UTF-8". Options: ``--output-encoding, -o``. - -output_encoding_error_handler - The encoding error handler for unencodable characters in output. - Acceptable values are the same as for the "error" parameter of - Python's ``encode`` string method. - - Default: "strict". Options: ``--output-encoding-error-handler, - --output-encoding, -o``. - -pep_home - (PEP/HTML Writer.) Home URL prefix for PEPs. - - Default: current directory ("."). Options: ``--pep-home``. - -pep_references - (reStructuredText Parser.) Recognize and link to PEP references - (like "PEP 258"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--pep-references``. - -pep_stylesheet - (PEP/HTML Writer.) CSS stylesheet URL, used verbatim. Overrides - HTML stylesheet (``--stylesheet``). - - Default: None. Options: ``--pep-stylesheet``. - -pep_stylesheet_path - (PEP/HTML Writer.) Path to CSS stylesheet [#pwd]_. Path is - adjusted relative to the output HTML file. Overrides HTML - stylesheet (``--stylesheet``) and PEP stylesheet - (``--pep-stylesheet``). - - Default: None. Options: ``--pep-stylesheet-path``. - -pep_template - (PEP/HTML Writer.) Path to PEP template file [#pwd]_. - - Default: "pep-html-template" (in current directory). Options: - ``--pep-template``. - -python_home - (PEP/HTML Writer.) Python's home URL. - - Default: parent directory (".."). Options: ``--python-home``. - -recurse - (``buildhtml.py`` front end.) Recursively scan subdirectories. - - Default: recurse (1). Options: ``--recurse, --local``. - -report_level - Verbosity threshold at or above which system messages are - reported. - - Default: warning (2). Options: ``--report, -r, --verbose, -v, - --quiet, -q``. - -rfc_references - (reStructuredText Parser.) Recognize and link to RFC references - (like "RFC 822"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--rfc-references``. - -silent - (``buildhtml.py`` front end.) Work silently (no progress - messages). Independent of "report_level". - - Default: show progress (None). Options: ``--silent``. - -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-uri, - --no-source-link``. - -stylesheet - (HTML Writer.) CSS stylesheet URL, used verbatim. Overridden by - "stylesheet_path" URL option (``--stylesheet-path``). - - Default: "default.css". Options: ``--stylesheet``. - -stylesheet_path - (HTML Writer.) Path to CSS stylesheet [#pwd]_. Overrides - "stylesheet" URL option (``--stylesheet``). Path is adjusted - relative to the output HTML file. - - Default: None. Options: ``--stylesheet``. - -tab_width - (reStructuredText Parser.) Number of spaces for hard tab - expansion. - - Default: 8. Options: ``--tab-width``. - -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 an error occurs. - - Default: disabled (None). Options: ``--traceback, - --no-traceback``. - -trim-footnote-reference-space - (reStructuredText Parser.) Remove spaces before footnote - references. - - Default: don't (None). Options: - ``--trim-footnote-reference-space``. - -warning_stream - Path to a file for the output of system messages (warnings) - [#pwd]_. - - Default: stderr (None). Options: ``--warnings``. - -xml_declaration - (XML and HTML Writers.) Generate XML with an XML declaration. - - .. 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``. - - -For Internal Use Only -````````````````````` - -Setting these in a config file has no effect. - - -_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. - - 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://lcweb.loc.gov/standards/iso639-2/englangn.html - -.. [#pwd] Path relative to the working directory of the process at - launch. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docutils/__init__.py b/docutils/docutils/__init__.py deleted file mode 100644 index 188a3a711..000000000 --- a/docutils/docutils/__init__.py +++ /dev/null @@ -1,128 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This is the Docutils (Python Documentation Utilities) package. - -Package Structure -================= - -Modules: - -- __init__.py: Contains the package docstring only (this text). - -- core.py: Contains the ``Publisher`` class and ``publish()`` convenience - function. - -- frontend.py: Command-line and common processing for Docutils front-ends. - -- io.py: Provides a uniform API for low-level input and output. - -- nodes.py: Docutils document tree (doctree) node class library. - -- statemachine.py: A finite state machine specialized for - regular-expression-based text filters. - -- urischemes.py: Contains a complete mapping of known URI addressing - scheme names to descriptions. - -- utils.py: Contains the ``Reporter`` system warning class and miscellaneous - utilities. - -Subpackages: - -- languages: Language-specific mappings of terms. - -- parsers: Syntax-specific input parser modules or packages. - -- readers: Context-specific input handlers which understand the data - source and manage a parser. - -- transforms: Modules used by readers and writers to modify DPS - doctrees. - -- writers: Format-specific output translators. -""" - -__docformat__ = 'reStructuredText' - -__version__ = '0.3.0' -"""``major.minor.micro`` version number. The micro number is bumped any time -there's a change in the API incompatible with one of the front ends. The -minor number is bumped whenever there is a project release. The major number -will be bumped when the project is feature-complete, and perhaps if there is a -major change in the design.""" - - -class ApplicationError(StandardError): pass -class DataError(ApplicationError): pass - - -class SettingsSpec: - - """ - Runtime setting specification base class. - - SettingsSpec subclass objects used by `docutils.frontend.OptionParser`. - """ - - settings_spec = () - """Runtime settings specification. Override in subclasses. - - Specifies runtime settings and associated command-line options, as used by - `docutils.frontend.OptionParser`. This tuple contains one or more sets of - option group title, description, and a list/tuple of tuples: ``('help - text', [list of option strings], {keyword arguments})``. Group title - and/or description may be `None`; no group title implies no group, just a - list of single options. Runtime settings names are derived implicitly - from long option names ("--a-setting" becomes ``settings.a_setting``) or - explicitly from the "dest" keyword argument.""" - - settings_defaults = None - """A dictionary of defaults for internal or inaccessible (by command-line - or config file) settings. Override in subclasses.""" - - settings_default_overrides = None - """A dictionary of auxiliary defaults, to override defaults for settings - defined in other components. Override in subclasses.""" - - relative_path_settings = () - """Settings containing filesystem paths. Override in subclasses. - - Settings listed here are to be interpreted relative to the current working - directory.""" - - -class TransformSpec: - - """ - Runtime transform specification base class. - - TransformSpec subclass objects used by `docutils.transforms.Transformer`. - """ - - default_transforms = () - """Transforms required by this class. Override in subclasses.""" - - -class Component(SettingsSpec, TransformSpec): - - """Base class for Docutils components.""" - - component_type = None - """Override in subclasses.""" - - supported = () - """Names for this component. Override in subclasses.""" - - def supports(self, format): - """ - Is `format` supported by this component? - - To be used by transforms to ask the dependent component if it supports - a certain input context or output format. - """ - return format in self.supported diff --git a/docutils/docutils/core.py b/docutils/docutils/core.py deleted file mode 100644 index 6d78ac57f..000000000 --- a/docutils/docutils/core.py +++ /dev/null @@ -1,360 +0,0 @@ -# Authors: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Calling the ``publish_*`` convenience functions (or instantiating a -`Publisher` object) with component names will result in default -behavior. For custom behavior (setting component options), create -custom component objects first, and pass *them* to -``publish_*``/`Publisher`. -""" - -__docformat__ = 'reStructuredText' - -import sys -from docutils import Component, __version__ -from docutils import frontend, io, utils, readers, parsers, writers -from docutils.frontend import OptionParser - - -class Publisher: - - """ - A facade encapsulating the high-level logic of a Docutils system. - """ - - def __init__(self, reader=None, parser=None, writer=None, - source=None, source_class=io.FileInput, - destination=None, destination_class=io.FileOutput, - settings=None): - """ - Initial setup. If any of `reader`, `parser`, or `writer` are not - specified, the corresponding ``set_...`` method should be called with - a component name (`set_reader` sets the parser as well). - """ - - self.reader = reader - """A `readers.Reader` instance.""" - - self.parser = parser - """A `parsers.Parser` instance.""" - - self.writer = writer - """A `writers.Writer` instance.""" - - self.source = source - """The source of input data, an `io.Input` instance.""" - - self.source_class = source_class - """The class for dynamically created source objects.""" - - self.destination = destination - """The destination for docutils output, an `io.Output` instance.""" - - self.destination_class = destination_class - """The class for dynamically created destination objects.""" - - self.settings = settings - """An object containing Docutils settings as instance attributes. - Set by `self.process_command_line()` or `self.get_settings()`.""" - - def set_reader(self, reader_name, parser, parser_name): - """Set `self.reader` by name.""" - reader_class = readers.get_reader_class(reader_name) - self.reader = reader_class(parser, parser_name) - self.parser = self.reader.parser - - def set_writer(self, writer_name): - """Set `self.writer` by name.""" - writer_class = writers.get_writer_class(writer_name) - self.writer = writer_class() - - def set_components(self, reader_name, parser_name, writer_name): - if self.reader is None: - self.set_reader(reader_name, self.parser, parser_name) - if self.parser is None: - if self.reader.parser is None: - self.reader.set_parser(parser_name) - self.parser = self.reader.parser - if self.writer is None: - self.set_writer(writer_name) - - def setup_option_parser(self, usage=None, description=None, - settings_spec=None, **defaults): - #@@@ Add self.source & self.destination to components in future? - option_parser = OptionParser( - components=(settings_spec, self.parser, self.reader, self.writer), - defaults=defaults, read_config_files=1, - usage=usage, description=description) - return option_parser - - def get_settings(self, usage=None, description=None, - settings_spec=None, **defaults): - """ - Set and return default settings (overrides in `defaults` keyword - argument). - - Set components first (`self.set_reader` & `self.set_writer`). - Explicitly setting `self.settings` disables command line option - processing from `self.publish()`. - """ - option_parser = self.setup_option_parser(usage, description, - settings_spec, **defaults) - self.settings = option_parser.get_default_values() - return self.settings - - def process_command_line(self, argv=None, usage=None, description=None, - settings_spec=None, **defaults): - """ - Pass an empty list to `argv` to avoid reading `sys.argv` (the - default). - - Set components first (`self.set_reader` & `self.set_writer`). - """ - option_parser = self.setup_option_parser(usage, description, - settings_spec, **defaults) - if argv is None: - argv = sys.argv[1:] - self.settings = option_parser.parse_args(argv) - - def set_io(self, source_path=None, destination_path=None): - if self.source is None: - self.set_source(source_path=source_path) - if self.destination is None: - self.set_destination(destination_path=destination_path) - - def set_source(self, source=None, source_path=None): - if source_path is None: - source_path = self.settings._source - else: - self.settings._source = source_path - self.source = self.source_class( - source=source, source_path=source_path, - encoding=self.settings.input_encoding) - - def set_destination(self, destination=None, destination_path=None): - if destination_path is None: - destination_path = self.settings._destination - else: - self.settings._destination = destination_path - self.destination = self.destination_class( - destination=destination, destination_path=destination_path, - encoding=self.settings.output_encoding, - error_handler=self.settings.output_encoding_error_handler) - - def apply_transforms(self, document): - document.transformer.populate_from_components( - (self.source, self.reader, self.reader.parser, self.writer, - self.destination)) - document.transformer.apply_transforms() - - def publish(self, argv=None, usage=None, description=None, - settings_spec=None, settings_overrides=None, - enable_exit=None): - """ - Process command line options and arguments (if `self.settings` not - already set), run `self.reader` and then `self.writer`. Return - `self.writer`'s output. - """ - if self.settings is None: - self.process_command_line(argv, usage, description, settings_spec, - **(settings_overrides or {})) - elif settings_overrides: - self.settings._update(settings_overrides, 'loose') - self.set_io() - exit = None - document = None - try: - document = self.reader.read(self.source, self.parser, - self.settings) - self.apply_transforms(document) - output = self.writer.write(document, self.destination) - except utils.SystemMessage, error: - if self.settings.traceback: - raise - print >>sys.stderr, ('Exiting due to level-%s (%s) system message.' - % (error.level, - utils.Reporter.levels[error.level])) - exit = 1 - except Exception, error: - if self.settings.traceback: - raise - print >>sys.stderr, error - print >>sys.stderr, ("""\ -Exiting due to error. Use "--traceback" to diagnose. -Please report errors to <docutils-users@lists.sf.net>. -Include "--traceback" output, Docutils version (%s), -Python version (%s), your OS type & version, and the -command line used.""" % (__version__, sys.version.split()[0])) - exit = 1 - if self.settings.dump_settings: - from pprint import pformat - print >>sys.stderr, '\n::: Runtime settings:' - print >>sys.stderr, pformat(self.settings.__dict__) - if self.settings.dump_internals and document: - from pprint import pformat - print >>sys.stderr, '\n::: Document internals:' - print >>sys.stderr, pformat(document.__dict__) - if self.settings.dump_transforms and document: - from pprint import pformat - print >>sys.stderr, '\n::: Transforms applied:' - print >>sys.stderr, pformat(document.transformer.applied) - if self.settings.dump_pseudo_xml and document: - print >>sys.stderr, '\n::: Pseudo-XML:' - print >>sys.stderr, document.pformat().encode( - 'raw_unicode_escape') - if enable_exit and document and (document.reporter.max_level - >= self.settings.exit_level): - sys.exit(document.reporter.max_level + 10) - elif exit: - sys.exit(1) - return output - - -default_usage = '%prog [options] [<source> [<destination>]]' -default_description = ('Reads from <source> (default is stdin) and writes to ' - '<destination> (default is stdout).') - -def publish_cmdline(reader=None, reader_name='standalone', - parser=None, parser_name='restructuredtext', - writer=None, writer_name='pseudoxml', - settings=None, settings_spec=None, - settings_overrides=None, enable_exit=1, argv=None, - usage=default_usage, description=default_description): - """ - Set up & run a `Publisher`. For command-line front ends. - - Parameters: - - - `reader`: A `docutils.readers.Reader` object. - - `reader_name`: Name or alias of the Reader class to be instantiated if - no `reader` supplied. - - `parser`: A `docutils.parsers.Parser` object. - - `parser_name`: Name or alias of the Parser class to be instantiated if - no `parser` supplied. - - `writer`: A `docutils.writers.Writer` object. - - `writer_name`: Name or alias of the Writer class to be instantiated if - no `writer` supplied. - - `settings`: Runtime settings object. - - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec` - subclass. Used only if no `settings` specified. - - `settings_overrides`: A dictionary containing program-specific overrides - of component settings. - - `enable_exit`: Boolean; enable exit status at end of processing? - - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``. - - `usage`: Usage string, output if there's a problem parsing the command - line. - - `description`: Program description, output for the "--help" option - (along with command-line option descriptions). - """ - pub = Publisher(reader, parser, writer, settings=settings) - pub.set_components(reader_name, parser_name, writer_name) - pub.publish(argv, usage, description, settings_spec, settings_overrides, - enable_exit=enable_exit) - -def publish_file(source=None, source_path=None, - destination=None, destination_path=None, - reader=None, reader_name='standalone', - parser=None, parser_name='restructuredtext', - writer=None, writer_name='pseudoxml', - settings=None, settings_spec=None, settings_overrides=None, - enable_exit=None): - """ - Set up & run a `Publisher`. For programmatic use with file-like I/O. - - Parameters: - - - `source`: A file-like object (must have "read" and "close" methods). - - `source_path`: Path to the input file. Opened if no `source` supplied. - If neither `source` nor `source_path` are supplied, `sys.stdin` is used. - - `destination`: A file-like object (must have "write" and "close" - methods). - - `destination_path`: Path to the input file. Opened if no `destination` - supplied. If neither `destination` nor `destination_path` are supplied, - `sys.stdout` is used. - - `reader`: A `docutils.readers.Reader` object. - - `reader_name`: Name or alias of the Reader class to be instantiated if - no `reader` supplied. - - `parser`: A `docutils.parsers.Parser` object. - - `parser_name`: Name or alias of the Parser class to be instantiated if - no `parser` supplied. - - `writer`: A `docutils.writers.Writer` object. - - `writer_name`: Name or alias of the Writer class to be instantiated if - no `writer` supplied. - - `settings`: Runtime settings object. - - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec` - subclass. Used only if no `settings` specified. - - `settings_overrides`: A dictionary containing program-specific overrides - of component settings. - - `enable_exit`: Boolean; enable exit status at end of processing? - """ - pub = Publisher(reader, parser, writer, settings=settings) - pub.set_components(reader_name, parser_name, writer_name) - if settings is None: - settings = pub.get_settings(settings_spec=settings_spec) - if settings_overrides: - settings._update(settings_overrides, 'loose') - pub.set_source(source, source_path) - pub.set_destination(destination, destination_path) - pub.publish(enable_exit=enable_exit) - -def publish_string(source, source_path=None, destination_path=None, - reader=None, reader_name='standalone', - parser=None, parser_name='restructuredtext', - writer=None, writer_name='pseudoxml', - settings=None, settings_spec=None, - settings_overrides=None, enable_exit=None): - """ - Set up & run a `Publisher`, and return the string output. - For programmatic use with string I/O. - - For encoded string output, be sure to set the "output_encoding" setting to - the desired encoding. Set it to "unicode" for unencoded Unicode string - output. Here's how:: - - publish_string(..., settings_overrides={'output_encoding': 'unicode'}) - - Similarly for Unicode string input (`source`):: - - publish_string(..., settings_overrides={'input_encoding': 'unicode'}) - - Parameters: - - - `source`: An input string; required. This can be an encoded 8-bit - string (set the "input_encoding" setting to the correct encoding) or a - Unicode string (set the "input_encoding" setting to "unicode"). - - `source_path`: Path to the file or object that produced `source`; - optional. Only used for diagnostic output. - - `destination_path`: Path to the file or object which will receive the - output; optional. Used for determining relative paths (stylesheets, - source links, etc.). - - `reader`: A `docutils.readers.Reader` object. - - `reader_name`: Name or alias of the Reader class to be instantiated if - no `reader` supplied. - - `parser`: A `docutils.parsers.Parser` object. - - `parser_name`: Name or alias of the Parser class to be instantiated if - no `parser` supplied. - - `writer`: A `docutils.writers.Writer` object. - - `writer_name`: Name or alias of the Writer class to be instantiated if - no `writer` supplied. - - `settings`: Runtime settings object. - - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec` - subclass. Used only if no `settings` specified. - - `settings_overrides`: A dictionary containing program-specific overrides - of component settings. - - `enable_exit`: Boolean; enable exit status at end of processing? - """ - pub = Publisher(reader, parser, writer, settings=settings, - source_class=io.StringInput, - destination_class=io.StringOutput) - pub.set_components(reader_name, parser_name, writer_name) - if settings is None: - settings = pub.get_settings(settings_spec=settings_spec) - if settings_overrides: - settings._update(settings_overrides, 'loose') - pub.set_source(source, source_path) - pub.set_destination(destination_path=destination_path) - return pub.publish(enable_exit=enable_exit) diff --git a/docutils/docutils/frontend.py b/docutils/docutils/frontend.py deleted file mode 100644 index 5952ec19e..000000000 --- a/docutils/docutils/frontend.py +++ /dev/null @@ -1,477 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Command-line and common processing for Docutils front-end tools. - -Exports the following classes: - -- `OptionParser`: Standard Docutils command-line processing. -- `Values`: Runtime settings; objects are simple structs - (``object.attribute``). -- `ConfigParser`: Standard Docutils config file processing. -""" - -__docformat__ = 'reStructuredText' - -import os -import os.path -import sys -import types -import ConfigParser as CP -import codecs -import docutils -import optparse -from optparse import Values, SUPPRESS_HELP - - -def store_multiple(option, opt, value, parser, *args, **kwargs): - """ - Store multiple values in `parser.values`. (Option callback.) - - Store `None` for each attribute named in `args`, and store the value for - each key (attribute name) in `kwargs`. - """ - for attribute in args: - setattr(parser.values, attribute, None) - for key, value in kwargs.items(): - setattr(parser.values, key, value) - -def read_config_file(option, opt, value, parser): - """ - Read a configuration file during option processing. (Option callback.) - """ - config_parser = ConfigParser() - config_parser.read(value, parser) - settings = config_parser.get_section('options') - make_paths_absolute(settings, parser.relative_path_settings, - os.path.dirname(value)) - parser.values.__dict__.update(settings) - -def set_encoding(option, opt, value, parser): - """ - Validate & set the encoding specified. (Option callback.) - """ - try: - value = validate_encoding(option.dest, value) - except LookupError, error: - raise (optparse.OptionValueError('option "%s": %s' % (opt, error)), - None, sys.exc_info()[2]) - setattr(parser.values, option.dest, value) - -def validate_encoding(name, value): - try: - codecs.lookup(value) - except LookupError: - raise (LookupError('unknown encoding: "%s"' % value), - None, sys.exc_info()[2]) - return value - -def set_encoding_error_handler(option, opt, value, parser): - """ - Validate & set the encoding error handler specified. (Option callback.) - """ - try: - value = validate_encoding_error_handler(option.dest, value) - except LookupError, error: - raise (optparse.OptionValueError('option "%s": %s' % (opt, error)), - None, sys.exc_info()[2]) - setattr(parser.values, option.dest, value) - -def validate_encoding_error_handler(name, value): - try: - codecs.lookup_error(value) - except AttributeError: # prior to Python 2.3 - if value not in ('strict', 'ignore', 'replace'): - raise (LookupError( - 'unknown encoding error handler: "%s" (choices: ' - '"strict", "ignore", or "replace")' % value), - None, sys.exc_info()[2]) - except LookupError: - raise (LookupError( - 'unknown encoding error handler: "%s" (choices: ' - '"strict", "ignore", "replace", "backslashreplace", ' - '"xmlcharrefreplace", and possibly others; see documentation for ' - 'the Python ``codecs`` module)' % value), - None, sys.exc_info()[2]) - return value - -def set_encoding_and_error_handler(option, opt, value, parser): - """ - Validate & set the encoding and error handler specified. (Option callback.) - """ - try: - value = validate_encoding_and_error_handler(option.dest, value) - except LookupError, error: - raise (optparse.OptionValueError('option "%s": %s' % (opt, error)), - None, sys.exc_info()[2]) - if ':' in value: - encoding, handler = value.split(':') - setattr(parser.values, option.dest + '_error_handler', handler) - else: - encoding = value - setattr(parser.values, option.dest, encoding) - -def validate_encoding_and_error_handler(name, value): - if ':' in value: - encoding, handler = value.split(':') - validate_encoding_error_handler(name + '_error_handler', handler) - else: - encoding = value - validate_encoding(name, encoding) - return value - -def make_paths_absolute(pathdict, keys, base_path=None): - """ - Interpret filesystem path settings relative to the `base_path` given. - - Paths are values in `pathdict` whose keys are in `keys`. Get `keys` from - `OptionParser.relative_path_settings`. - """ - if base_path is None: - base_path = os.getcwd() - for key in keys: - if pathdict.has_key(key) and pathdict[key]: - pathdict[key] = os.path.normpath( - os.path.abspath(os.path.join(base_path, pathdict[key]))) - - -class OptionParser(optparse.OptionParser, docutils.SettingsSpec): - - """ - Parser for command-line and library use. The `settings_spec` - specification here and in other Docutils components are merged to build - the set of command-line options and runtime settings for this process. - - Common settings (defined below) and component-specific settings must not - conflict. Short options are reserved for common settings, and components - are restrict to using long options. - """ - - threshold_choices = 'info 1 warning 2 error 3 severe 4 none 5'.split() - """Possible inputs for for --report and --halt threshold values.""" - - thresholds = {'info': 1, 'warning': 2, 'error': 3, 'severe': 4, 'none': 5} - """Lookup table for --report and --halt threshold values.""" - - if hasattr(codecs, 'backslashreplace_errors'): - default_error_encoding_error_handler = 'backslashreplace' - else: - default_error_encoding_error_handler = 'replace' - - settings_spec = ( - 'General Docutils Options', - None, - (('Include a "Generated by Docutils" credit and link at the end ' - 'of the document.', - ['--generator', '-g'], {'action': 'store_true'}), - ('Do not include a generator credit.', - ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}), - ('Include the date at the end of the document (UTC).', - ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d', - 'dest': 'datestamp'}), - ('Include the time & date at the end of the document (UTC).', - ['--time', '-t'], {'action': 'store_const', - 'const': '%Y-%m-%d %H:%M UTC', - 'dest': 'datestamp'}), - ('Do not include a datestamp of any kind.', - ['--no-datestamp'], {'action': 'store_const', 'const': None, - 'dest': 'datestamp'}), - ('Include a "View document source" link (relative to destination).', - ['--source-link', '-s'], {'action': 'store_true'}), - ('Use the supplied <URL> verbatim for a "View document source" ' - 'link; implies --source-link.', - ['--source-url'], {'metavar': '<URL>'}), - ('Do not include a "View document source" link.', - ['--no-source-link'], - {'action': 'callback', 'callback': store_multiple, - 'callback_args': ('source_link', 'source_url')}), - ('Enable backlinks from section headers to table of contents ' - 'entries. This is the default.', - ['--toc-entry-backlinks'], - {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'entry', - 'default': 'entry'}), - ('Enable backlinks from section headers to the top of the table of ' - 'contents.', - ['--toc-top-backlinks'], - {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'top'}), - ('Disable backlinks to the table of contents.', - ['--no-toc-backlinks'], - {'dest': 'toc_backlinks', 'action': 'store_false'}), - ('Enable backlinks from footnotes and citations to their ' - 'references. This is the default.', - ['--footnote-backlinks'], - {'action': 'store_true', 'default': 1}), - ('Disable backlinks from footnotes and citations.', - ['--no-footnote-backlinks'], - {'dest': 'footnote_backlinks', 'action': 'store_false'}), - ('Set verbosity threshold; report system messages at or higher than ' - '<level> (by name or number: "info" or "1", warning/2, error/3, ' - 'severe/4; also, "none" or "5"). Default is 2 (warning).', - ['--report', '-r'], {'choices': threshold_choices, 'default': 2, - 'dest': 'report_level', 'metavar': '<level>'}), - ('Report all system messages, info-level and higher. (Same as ' - '"--report=info".)', - ['--verbose', '-v'], {'action': 'store_const', 'const': 'info', - 'dest': 'report_level'}), - ('Do not report any system messages. (Same as "--report=none".)', - ['--quiet', '-q'], {'action': 'store_const', 'const': 'none', - 'dest': 'report_level'}), - ('Set the threshold (<level>) at or above which system messages are ' - 'converted to exceptions, halting execution immediately. Levels ' - 'as in --report. Default is 4 (severe).', - ['--halt'], {'choices': threshold_choices, 'dest': 'halt_level', - 'default': 4, 'metavar': '<level>'}), - ('Same as "--halt=info": halt processing at the slightest problem.', - ['--strict'], {'action': 'store_const', 'const': 'info', - 'dest': 'halt_level'}), - ('Enable a non-zero exit status for normal exit if non-halting ' - 'system messages (at or above <level>) were generated. Levels as ' - 'in --report. Default is 5 (disabled). Exit status is the maximum ' - 'system message level plus 10 (11 for INFO, etc.).', - ['--exit'], {'choices': threshold_choices, 'dest': 'exit_level', - 'default': 5, 'metavar': '<level>'}), - ('Report debug-level system messages and generate diagnostic output.', - ['--debug'], {'action': 'store_true'}), - ('Do not report debug-level system messages or generate diagnostic ' - 'output.', - ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}), - ('Send the output of system messages (warnings) to <file>.', - ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}), - ('Enable Python tracebacks when an error occurs.', - ['--traceback'], {'action': 'store_true', 'default': None}), - ('Disable Python tracebacks when errors occur; report just the error ' - 'instead. This is the default.', - ['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}), - ('Specify the encoding of input text. Default is locale-dependent.', - ['--input-encoding', '-i'], - {'action': 'callback', 'callback': set_encoding, - 'metavar': '<name>', 'type': 'string', 'dest': 'input_encoding'}), - ('Specify the text encoding for output. Default is UTF-8. ' - 'Optionally also specify the encoding error handler for unencodable ' - 'characters (see "--error-encoding"); default is "strict".', - ['--output-encoding', '-o'], - {'action': 'callback', 'callback': set_encoding_and_error_handler, - 'metavar': '<name[:handler]>', 'type': 'string', - 'dest': 'output_encoding', 'default': 'utf-8'}), - (SUPPRESS_HELP, # usually handled by --output-encoding - ['--output_encoding_error_handler'], - {'action': 'callback', 'callback': set_encoding_error_handler, - 'type': 'string', 'dest': 'output_encoding_error_handler', - 'default': 'strict'}), - ('Specify the text encoding for error output. Default is ASCII. ' - 'Optionally also specify the encoding error handler for unencodable ' - 'characters, after a colon (":"). Acceptable values are the same ' - 'as for the "error" parameter of Python\'s ``encode`` string ' - 'method. Default is "%s".' % default_error_encoding_error_handler, - ['--error-encoding', '-e'], - {'action': 'callback', 'callback': set_encoding_and_error_handler, - 'metavar': '<name[:handler]>', 'type': 'string', - 'dest': 'error_encoding', 'default': 'ascii'}), - (SUPPRESS_HELP, # usually handled by --error-encoding - ['--error_encoding_error_handler'], - {'action': 'callback', 'callback': set_encoding_error_handler, - 'type': 'string', 'dest': 'error_encoding_error_handler', - 'default': default_error_encoding_error_handler}), - ('Specify the language of input text (ISO 639 2-letter identifier).' - ' Default is "en" (English).', - ['--language', '-l'], {'dest': 'language_code', 'default': 'en', - 'metavar': '<name>'}), - ('Read configuration settings from <file>, if it exists.', - ['--config'], {'metavar': '<file>', 'type': 'string', - 'action': 'callback', 'callback': read_config_file}), - ("Show this program's version number and exit.", - ['--version', '-V'], {'action': 'version'}), - ('Show this help message and exit.', - ['--help', '-h'], {'action': 'help'}), - # Hidden options, for development use only: - (SUPPRESS_HELP, ['--dump-settings'], {'action': 'store_true'}), - (SUPPRESS_HELP, ['--dump-internals'], {'action': 'store_true'}), - (SUPPRESS_HELP, ['--dump-transforms'], {'action': 'store_true'}), - (SUPPRESS_HELP, ['--dump-pseudo-xml'], {'action': 'store_true'}), - (SUPPRESS_HELP, ['--expose-internal-attribute'], - {'action': 'append', 'dest': 'expose_internals'}),)) - """Runtime settings and command-line options common to all Docutils front - ends. Setting specs specific to individual Docutils components are also - used (see `populate_from_components()`).""" - - settings_defaults = {'_disable_config': None} - """Defaults for settings that don't have command-line option equivalents.""" - - relative_path_settings = ('warning_stream',) - - version_template = '%%prog (Docutils %s)' % docutils.__version__ - """Default version message.""" - - def __init__(self, components=(), defaults=None, read_config_files=None, - *args, **kwargs): - """ - `components` is a list of Docutils components each containing a - ``.settings_spec`` attribute. `defaults` is a mapping of setting - default overrides. - """ - optparse.OptionParser.__init__( - self, add_help_option=None, - formatter=optparse.TitledHelpFormatter(width=78), - *args, **kwargs) - if not self.version: - self.version = self.version_template - # Make an instance copy (it will be modified): - self.relative_path_settings = list(self.relative_path_settings) - self.populate_from_components((self,) + tuple(components)) - defaults = defaults or {} - if read_config_files and not self.defaults['_disable_config']: - config = ConfigParser() - config.read_standard_files(self) - config_settings = config.get_section('options') - make_paths_absolute(config_settings, self.relative_path_settings) - defaults.update(config_settings) - # Internal settings with no defaults from settings specifications; - # initialize manually: - self.set_defaults(_source=None, _destination=None, **defaults) - - def populate_from_components(self, components): - """ - For each component, first populate from the `SettingsSpec.settings_spec` - structure, then from the `SettingsSpec.settings_defaults` dictionary. - After all components have been processed, check for and populate from - each component's `SettingsSpec.settings_default_overrides` dictionary. - """ - for component in components: - if component is None: - continue - i = 0 - settings_spec = component.settings_spec - self.relative_path_settings.extend( - component.relative_path_settings) - while i < len(settings_spec): - title, description, option_spec = settings_spec[i:i+3] - if title: - group = optparse.OptionGroup(self, title, description) - self.add_option_group(group) - else: - group = self # single options - for (help_text, option_strings, kwargs) in option_spec: - group.add_option(help=help_text, *option_strings, - **kwargs) - if component.settings_defaults: - self.defaults.update(component.settings_defaults) - i += 3 - for component in components: - if component and component.settings_default_overrides: - self.defaults.update(component.settings_default_overrides) - - def check_values(self, values, args): - if hasattr(values, 'report_level'): - values.report_level = self.check_threshold(values.report_level) - if hasattr(values, 'halt_level'): - values.halt_level = self.check_threshold(values.halt_level) - if hasattr(values, 'exit_level'): - values.exit_level = self.check_threshold(values.exit_level) - values._source, values._destination = self.check_args(args) - make_paths_absolute(values.__dict__, self.relative_path_settings, - os.getcwd()) - return values - - def check_threshold(self, level): - try: - return int(level) - except ValueError: - try: - return self.thresholds[level.lower()] - except (KeyError, AttributeError): - self.error('Unknown threshold: %r.' % level) - - def check_args(self, args): - source = destination = None - if args: - source = args.pop(0) - if source == '-': # means stdin - source = None - if args: - destination = args.pop(0) - if destination == '-': # means stdout - destination = None - if args: - self.error('Maximum 2 arguments allowed.') - if source and source == destination: - self.error('Do not specify the same file for both source and ' - 'destination. It will clobber the source file.') - return source, destination - - -class ConfigParser(CP.ConfigParser): - - standard_config_files = ( - '/etc/docutils.conf', # system-wide - './docutils.conf', # project-specific - os.path.expanduser('~/.docutils')) # user-specific - """Docutils configuration files, using ConfigParser syntax (section - 'options'). Later files override earlier ones.""" - - validation = { - 'options': - {'input_encoding': validate_encoding, - 'output_encoding': validate_encoding, - 'output_encoding_error_handler': validate_encoding_error_handler, - 'error_encoding': validate_encoding, - 'error_encoding_error_handler': validate_encoding_error_handler}} - """{section: {option: validation function}} mapping, used by - `validate_options`. Validation functions take two parameters: name and - value. They return a (possibly modified) value, or raise an exception.""" - - def read_standard_files(self, option_parser): - self.read(self.standard_config_files, option_parser) - - def read(self, filenames, option_parser): - if type(filenames) in types.StringTypes: - filenames = [filenames] - for filename in filenames: - CP.ConfigParser.read(self, filename) - self.validate_options(filename, option_parser) - - def validate_options(self, filename, option_parser): - for section in self.validation.keys(): - if not self.has_section(section): - continue - for option in self.validation[section].keys(): - if self.has_option(section, option): - value = self.get(section, option) - validator = self.validation[section][option] - try: - new_value = validator(option, value) - except Exception, error: - raise (ValueError( - 'Error in config file "%s", section "[%s]":\n' - ' %s: %s\n %s = %s' - % (filename, section, error.__class__.__name__, - error, option, value)), None, sys.exc_info()[2]) - self.set(section, option, new_value) - - def optionxform(self, optionstr): - """ - Transform '-' to '_' so the cmdline form of option names can be used. - """ - return optionstr.lower().replace('-', '_') - - def get_section(self, section, raw=0, vars=None): - """ - Return a given section as a dictionary (empty if the section - doesn't exist). - - All % interpolations are expanded in the return values, based on the - defaults passed into the constructor, unless the optional argument - `raw` is true. Additional substitutions may be provided using the - `vars` argument, which must be a dictionary whose contents overrides - any pre-existing defaults. - - The section DEFAULT is special. - """ - section_dict = {} - if self.has_section(section): - for option in self.options(section): - section_dict[option] = self.get(section, option, raw, vars) - return section_dict diff --git a/docutils/docutils/io.py b/docutils/docutils/io.py deleted file mode 100644 index 0ef4bdab6..000000000 --- a/docutils/docutils/io.py +++ /dev/null @@ -1,289 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -I/O classes provide a uniform API for low-level input and output. Subclasses -will exist for a variety of input/output mechanisms. -""" - -__docformat__ = 'reStructuredText' - -import sys -import locale -from types import UnicodeType -from docutils import TransformSpec - - -class Input(TransformSpec): - - """ - Abstract base class for input wrappers. - """ - - component_type = 'input' - - default_source_path = None - - def __init__(self, source=None, source_path=None, encoding=None): - self.encoding = encoding - """Text encoding for the input source.""" - - self.source = source - """The source of input data.""" - - self.source_path = source_path - """A text reference to the source.""" - - if not source_path: - self.source_path = self.default_source_path - - def __repr__(self): - return '%s: source=%r, source_path=%r' % (self.__class__, self.source, - self.source_path) - - def read(self): - raise NotImplementedError - - def decode(self, data): - """ - Decode a string, `data`, heuristically. - Raise UnicodeError if unsuccessful. - - The client application should call ``locale.setlocale`` at the - beginning of processing:: - - locale.setlocale(locale.LC_ALL, '') - """ - if (self.encoding and self.encoding.lower() == 'unicode' - or isinstance(data, UnicodeType)): - return unicode(data) - encodings = [self.encoding, 'utf-8'] - try: - encodings.append(locale.nl_langinfo(locale.CODESET)) - except: - pass - try: - encodings.append(locale.getlocale()[1]) - except: - pass - try: - encodings.append(locale.getdefaultlocale()[1]) - except: - pass - encodings.append('latin-1') - for enc in encodings: - if not enc: - continue - try: - return unicode(data, enc) - except (UnicodeError, LookupError): - pass - raise UnicodeError( - 'Unable to decode input data. Tried the following encodings: %s.' - % ', '.join([repr(enc) for enc in encodings if enc])) - - -class Output(TransformSpec): - - """ - Abstract base class for output wrappers. - """ - - component_type = 'output' - - default_destination_path = None - - def __init__(self, destination=None, destination_path=None, - encoding=None, error_handler='strict'): - self.encoding = encoding - """Text encoding for the output destination.""" - - self.error_handler = error_handler or 'strict' - """Text encoding error handler.""" - - self.destination = destination - """The destination for output data.""" - - self.destination_path = destination_path - """A text reference to the destination.""" - - if not destination_path: - self.destination_path = self.default_destination_path - - def __repr__(self): - return ('%s: destination=%r, destination_path=%r' - % (self.__class__, self.destination, self.destination_path)) - - def write(self, data): - raise NotImplementedError - - def encode(self, data): - if self.encoding and self.encoding.lower() == 'unicode': - return data - else: - return data.encode(self.encoding, self.error_handler) - - -class FileInput(Input): - - """ - Input for single, simple file-like objects. - """ - - def __init__(self, source=None, source_path=None, - encoding=None, autoclose=1): - """ - :Parameters: - - `source`: either a file-like object (which is read directly), or - `None` (which implies `sys.stdin` if no `source_path` given). - - `source_path`: a path to a file, which is opened and then read. - - `autoclose`: close automatically after read (boolean); always - false if `sys.stdin` is the source. - """ - Input.__init__(self, source, source_path, encoding) - self.autoclose = autoclose - if source is None: - if source_path: - try: - self.source = open(source_path) - except IOError, error: - print >>sys.stderr, '%s: %s' % (error.__class__.__name__, - error) - print >>sys.stderr, ( - 'Unable to open source file for reading (%s). Exiting.' - % source_path) - sys.exit(1) - else: - self.source = sys.stdin - self.autoclose = None - if not source_path: - try: - self.source_path = self.source.name - except AttributeError: - pass - - def read(self): - """Read and decode a single file and return the data.""" - data = self.source.read() - if self.autoclose: - self.close() - return self.decode(data) - - def close(self): - self.source.close() - - -class FileOutput(Output): - - """ - Output for single, simple file-like objects. - """ - - def __init__(self, destination=None, destination_path=None, - encoding=None, error_handler='strict', autoclose=1): - """ - :Parameters: - - `destination`: either a file-like object (which is written - directly) or `None` (which implies `sys.stdout` if no - `destination_path` given). - - `destination_path`: a path to a file, which is opened and then - written. - - `autoclose`: close automatically after write (boolean); always - false if `sys.stdout` is the destination. - """ - Output.__init__(self, destination, destination_path, - encoding, error_handler) - self.opened = 1 - self.autoclose = autoclose - if destination is None: - if destination_path: - self.opened = None - else: - self.destination = sys.stdout - self.autoclose = None - if not destination_path: - try: - self.destination_path = self.destination.name - except AttributeError: - pass - - def open(self): - try: - self.destination = open(self.destination_path, 'w') - except IOError, error: - print >>sys.stderr, '%s: %s' % (error.__class__.__name__, - error) - print >>sys.stderr, ('Unable to open destination file for writing ' - '(%s). Exiting.' % source_path) - sys.exit(1) - self.opened = 1 - - def write(self, data): - """Encode `data`, write it to a single file, and return it.""" - output = self.encode(data) - if not self.opened: - self.open() - self.destination.write(output) - if self.autoclose: - self.close() - return output - - def close(self): - self.destination.close() - self.opened = None - - -class StringInput(Input): - - """ - Direct string input. - """ - - default_source_path = '<string>' - - def read(self): - """Decode and return the source string.""" - return self.decode(self.source) - - -class StringOutput(Output): - - """ - Direct string output. - """ - - default_destination_path = '<string>' - - def write(self, data): - """Encode `data`, store it in `self.destination`, and return it.""" - self.destination = self.encode(data) - return self.destination - - -class NullInput(Input): - - """ - Degenerate input: read nothing. - """ - - default_source_path = 'null input' - - def read(self): - """Return a null string.""" - return u'' - - -class NullOutput(Output): - - """ - Degenerate output: write nothing. - """ - - default_destination_path = 'null output' - - def write(self, data): - """Do nothing ([don't even] send data to the bit bucket).""" - pass diff --git a/docutils/docutils/languages/__init__.py b/docutils/docutils/languages/__init__.py deleted file mode 100644 index a4d451156..000000000 --- a/docutils/docutils/languages/__init__.py +++ /dev/null @@ -1,23 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# Internationalization details are documented in -# <http://docutils.sf.net/spec/howto/i18n.html>. - -""" -This package contains modules for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -_languages = {} - -def get_language(language_code): - if _languages.has_key(language_code): - return _languages[language_code] - module = __import__(language_code, globals(), locals()) - _languages[language_code] = module - return module diff --git a/docutils/docutils/languages/af.py b/docutils/docutils/languages/af.py deleted file mode 100644 index 6bfe4f162..000000000 --- a/docutils/docutils/languages/af.py +++ /dev/null @@ -1,60 +0,0 @@ -# Author: Jannie Hofmeyr -# Contact: jhsh@sun.ac.za -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Afrikaans-language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - 'author': 'Auteur', - 'authors': 'Auteurs', - 'organization': 'Organisasie', - 'address': 'Adres', - 'contact': 'Kontak', - 'version': 'Weergawe', - 'revision': 'Revisie', - 'status': 'Status', - 'date': 'Datum', - 'copyright': 'Kopiereg', - 'dedication': 'Opdrag', - 'abstract': 'Opsomming', - 'attention': 'Aandag!', - 'caution': 'Wees versigtig!', - 'danger': '!GEVAAR!', - 'error': 'Fout', - 'hint': 'Wenk', - 'important': 'Belangrik', - 'note': 'Nota', - 'tip': 'Tip', # hint and tip both have the same translation: wenk - 'warning': 'Waarskuwing', - 'contents': 'Inhoud'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - 'auteur': 'author', - 'auteurs': 'authors', - 'organisasie': 'organization', - 'adres': 'address', - 'kontak': 'contact', - 'weergawe': 'version', - 'revisie': 'revision', - 'status': 'status', - 'datum': 'date', - 'kopiereg': 'copyright', - 'opdrag': 'dedication', - 'opsomming': 'abstract'} -"""Afrikaans (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/de.py b/docutils/docutils/languages/de.py deleted file mode 100644 index ddffbda74..000000000 --- a/docutils/docutils/languages/de.py +++ /dev/null @@ -1,60 +0,0 @@ -# Authors: David Goodger; Gunnar Schwant -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -German language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - 'author': 'Autor', - 'authors': 'Autoren', - 'organization': 'Organisation', - 'address': 'Adresse', - 'contact': 'Kontakt', - 'version': 'Version', - 'revision': 'Revision', - 'status': 'Status', - 'date': 'Datum', - 'dedication': 'Widmung', - 'copyright': 'Copyright', - 'abstract': 'Zusammenfassung', - 'attention': 'Achtung!', - 'caution': 'Vorsicht!', - 'danger': '!GEFAHR!', - 'error': 'Fehler', - 'hint': 'Hinweis', - 'important': 'Wichtig', - 'note': 'Bemerkung', - 'tip': 'Tipp', - 'warning': 'Warnung', - 'contents': 'Inhalt'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - 'autor': 'author', - 'autoren': 'authors', - 'organisation': 'organization', - 'adresse': 'address', - 'kontakt': 'contact', - 'version': 'version', - 'revision': 'revision', - 'status': 'status', - 'datum': 'date', - 'copyright': 'copyright', - 'widmung': 'dedication', - 'zusammenfassung': 'abstract'} -"""German (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/en.py b/docutils/docutils/languages/en.py deleted file mode 100644 index db578810b..000000000 --- a/docutils/docutils/languages/en.py +++ /dev/null @@ -1,62 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -English-language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - # fixed: language-dependent - 'author': 'Author', - 'authors': 'Authors', - 'organization': 'Organization', - 'address': 'Address', - 'contact': 'Contact', - 'version': 'Version', - 'revision': 'Revision', - 'status': 'Status', - 'date': 'Date', - 'copyright': 'Copyright', - 'dedication': 'Dedication', - 'abstract': 'Abstract', - 'attention': 'Attention!', - 'caution': 'Caution!', - 'danger': '!DANGER!', - 'error': 'Error', - 'hint': 'Hint', - 'important': 'Important', - 'note': 'Note', - 'tip': 'Tip', - 'warning': 'Warning', - 'contents': 'Contents'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - # language-dependent: fixed - 'author': 'author', - 'authors': 'authors', - 'organization': 'organization', - 'address': 'address', - 'contact': 'contact', - 'version': 'version', - 'revision': 'revision', - 'status': 'status', - 'date': 'date', - 'copyright': 'copyright', - 'dedication': 'dedication', - 'abstract': 'abstract'} -"""English (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/es.py b/docutils/docutils/languages/es.py deleted file mode 100644 index 7505de5da..000000000 --- a/docutils/docutils/languages/es.py +++ /dev/null @@ -1,60 +0,0 @@ -# Author: Marcelo Huerta San Martín -# Contact: mghsm@uol.com.ar -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Spanish-language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - 'author': u'Autor', - 'authors': u'Autores', - 'organization': u'Organizaci\u00f3n', - 'address': u'Direcci\u00f3n', - 'contact': u'Contacto', - 'version': u'Versi\u00f3n', - 'revision': u'Revisi\u00f3n', - 'status': u'Estado', - 'date': u'Fecha', - 'copyright': u'Copyright', - 'dedication': u'Dedicatoria', - 'abstract': u'Resumen', - 'attention': u'\u00a1Atenci\u00f3n!', - 'caution': u'\u00a1Precauci\u00f3n!', - 'danger': u'\u00a1PELIGRO!', - 'error': u'Error', - 'hint': u'Sugerencia', - 'important': u'Importante', - 'note': u'Nota', - 'tip': u'Consejo', - 'warning': u'Advertencia', - 'contents': u'Contenido'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - u'autor': 'author', - u'autores': 'authors', - u'organizaci\u00f3n': 'organization', - u'direcci\u00f3n': 'address', - u'contacto': 'contact', - u'versi\u00f3n': 'version', - u'revisi\u00f3n': 'revision', - u'estado': 'status', - u'fecha': 'date', - u'copyright': 'copyright', - u'dedicatoria': 'dedication', - u'resumen': 'abstract'} -"""Spanish (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/fr.py b/docutils/docutils/languages/fr.py deleted file mode 100644 index 52317c174..000000000 --- a/docutils/docutils/languages/fr.py +++ /dev/null @@ -1,60 +0,0 @@ -# Author: Stefane Fermigier -# Contact: sf@fermigier.com -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -French-language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - u'author': u'Auteur', - u'authors': u'Auteurs', - u'organization': u'Organisation', - u'address': u'Adresse', - u'contact': u'Contact', - u'version': u'Version', - u'revision': u'R\u00e9vision', - u'status': u'Statut', - u'date': u'Date', - u'copyright': u'Copyright', - u'dedication': u'D\u00e9dicace', - u'abstract': u'R\u00e9sum\u00e9', - u'attention': u'Attention!', - u'caution': u'Avertissement!', - u'danger': u'!DANGER!', - u'error': u'Erreur', - u'hint': u'Indication', - u'important': u'Important', - u'note': u'Note', - u'tip': u'Astuce', - u'warning': u'Avis', - u'contents': u'Sommaire'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - u'auteur': u'author', - u'auteurs': u'authors', - u'organisation': u'organization', - u'adresse': u'address', - u'contact': u'contact', - u'version': u'version', - u'r\u00e9vision': u'revision', - u'statut': u'status', - u'date': u'date', - u'copyright': u'copyright', - u'd\u00e9dicace': u'dedication', - u'r\u00e9sum\u00e9': u'abstract'} -"""French (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/it.py b/docutils/docutils/languages/it.py deleted file mode 100644 index d86a5b1ec..000000000 --- a/docutils/docutils/languages/it.py +++ /dev/null @@ -1,60 +0,0 @@ -# Author: Nicola Larosa -# Contact: docutils@tekNico.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Italian-language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - 'author': 'Autore', - 'authors': 'Autori', - 'organization': 'Organizzazione', - 'address': 'Indirizzo', - 'contact': 'Contatti', - 'version': 'Versione', - 'revision': 'Revisione', - 'status': 'Status', - 'date': 'Data', - 'copyright': 'Copyright', - 'dedication': 'Dedica', - 'abstract': 'Riassunto', - 'attention': 'Attenzione!', - 'caution': 'Cautela!', - 'danger': '!PERICOLO!', - 'error': 'Errore', - 'hint': 'Suggerimento', - 'important': 'Importante', - 'note': 'Nota', - 'tip': 'Consiglio', - 'warning': 'Avvertenza', - 'contents': 'Indice'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - 'autore': 'author', - 'autori': 'authors', - 'organizzazione': 'organization', - 'indirizzo': 'address', - 'contatti': 'contact', - 'versione': 'version', - 'revisione': 'revision', - 'status': 'status', - 'data': 'date', - 'copyright': 'copyright', - 'dedica': 'dedication', - 'riassunto': 'abstract'} -"""Italian (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/ru.py b/docutils/docutils/languages/ru.py deleted file mode 100644 index e3b24a0c6..000000000 --- a/docutils/docutils/languages/ru.py +++ /dev/null @@ -1,68 +0,0 @@ -# Author: Roman Suzi -# Contact: rnd@onego.ru -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Russian-language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - u'abstract': u'\u0410\u043d\u043d\u043e\u0442\u0430\u0446\u0438\u044f', - u'address': u'\u0410\u0434\u0440\u0435\u0441', - u'attention': u'\u0412\u043d\u0438\u043c\u0430\u043d\u0438\u0435!', - u'author': u'\u0410\u0432\u0442\u043e\u0440', - u'authors': u'\u0410\u0432\u0442\u043e\u0440\u044b', - u'caution': u'\u041e\u0441\u0442\u043e\u0440\u043e\u0436\u043d\u043e!', - u'contact': u'\u041a\u043e\u043d\u0442\u0430\u043a\u0442', - u'contents': - u'\u0421\u043e\u0434\u0435\u0440\u0436\u0430\u043d\u0438\u0435', - u'copyright': u'\u041f\u0440\u0430\u0432\u0430 ' - u'\u043a\u043e\u043f\u0438\u0440\u043e\u0432\u0430\u043d\u0438\u044f', - u'danger': u'\u041e\u041f\u0410\u0421\u041d\u041e!', - u'date': u'\u0414\u0430\u0442\u0430', - u'dedication': - u'\u041f\u043e\u0441\u0432\u044f\u0449\u0435\u043d\u0438\u0435', - u'error': u'\u041e\u0448\u0438\u0431\u043a\u0430', - u'hint': u'\u0421\u043e\u0432\u0435\u0442', - u'important': u'\u0412\u0430\u0436\u043d\u043e', - u'note': u'\u041f\u0440\u0438\u043c\u0435\u0447\u0430\u043d\u0438\u0435', - u'organization': - u'\u041e\u0440\u0433\u0430\u043d\u0438\u0437\u0430\u0446\u0438\u044f', - u'revision': u'\u0420\u0435\u0434\u0430\u043a\u0446\u0438\u044f', - u'status': u'\u0421\u0442\u0430\u0442\u0443\u0441', - u'tip': u'\u041f\u043e\u0434\u0441\u043a\u0430\u0437\u043a\u0430', - u'version': u'\u0412\u0435\u0440\u0441\u0438\u044f', - u'warning': u'\u041f\u0440\u0435\u0434\u0443\u043f\u0440\u0435\u0436' - u'\u0434\u0435\u043d\u0438\u0435'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - u'\u0410\u043d\u043d\u043e\u0442\u0430\u0446\u0438\u044f': u'abstract', - u'\u0410\u0434\u0440\u0435\u0441': u'address', - u'\u0410\u0432\u0442\u043e\u0440': u'author', - u'\u0410\u0432\u0442\u043e\u0440\u044b': u'authors', - u'\u041a\u043e\u043d\u0442\u0430\u043a\u0442': u'contact', - u'\u041f\u0440\u0430\u0432\u0430 \u043a\u043e\u043f\u0438\u0440\u043e' - u'\u0432\u0430\u043d\u0438\u044f': u'copyright', - u'\u0414\u0430\u0442\u0430': u'date', - u'\u041f\u043e\u0441\u0432\u044f\u0449\u0435\u043d\u0438\u0435': - u'dedication', - u'\u041e\u0440\u0433\u0430\u043d\u0438\u0437\u0430\u0446\u0438\u044f': - u'organization', - u'\u0420\u0435\u0434\u0430\u043a\u0446\u0438\u044f': u'revision', - u'\u0421\u0442\u0430\u0442\u0443\u0441': u'status', - u'\u0412\u0435\u0440\u0441\u0438\u044f': u'version'} -"""Russian (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/sk.py b/docutils/docutils/languages/sk.py deleted file mode 100644 index 20fa645ad..000000000 --- a/docutils/docutils/languages/sk.py +++ /dev/null @@ -1,60 +0,0 @@ -# :Author: Miroslav Vasko -# :Contact: zemiak@zoznam.sk -# :Revision: $Revision$ -# :Date: $Date$ -# :Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Slovak-language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - 'author': u'Autor', - 'authors': u'Autori', - 'organization': u'Organiz\u00E1cia', - 'address': u'Adresa', - 'contact': u'Kontakt', - 'version': u'Verzia', - 'revision': u'Rev\u00EDzia', - 'status': u'Stav', - 'date': u'D\u00E1tum', - 'copyright': u'Copyright', - 'dedication': u'Venovanie', - 'abstract': u'Abstraktne', - 'attention': u'Pozor!', - 'caution': u'Opatrne!', - 'danger': u'!NEBEZPE\u010cENSTVO!', - 'error': u'Chyba', - 'hint': u'Rada', - 'important': u'D\u00F4le\u017Eit\u00E9', - 'note': u'Pozn\u00E1mka', - 'tip': u'Tip', - 'warning': u'Varovanie', - 'contents': u'Obsah'} -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - u'autor': 'author', - u'autori': 'authors', - u'organiz\u00E1cia': 'organization', - u'adresa': 'address', - u'kontakt': 'contact', - u'verzia': 'version', - u'rev\u00EDzia': 'revision', - u'stav': 'status', - u'd\u00E1tum': 'date', - u'copyright': 'copyright', - u'venovanie': 'dedication', - u'abstraktne': 'abstract'} -"""Slovak (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/languages/sv.py b/docutils/docutils/languages/sv.py deleted file mode 100644 index 3454ca6c1..000000000 --- a/docutils/docutils/languages/sv.py +++ /dev/null @@ -1,61 +0,0 @@ -# Author: Adam Chodorowski -# Contact: chodorowski@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Swedish language mappings for language-dependent features of Docutils. -""" - -__docformat__ = 'reStructuredText' - -labels = { - 'author': u'F\u00f6rfattare', - 'authors': u'F\u00f6rfattare', - 'organization': u'Organisation', - 'address': u'Adress', - 'contact': u'Kontakt', - 'version': u'Version', - 'revision': u'Revision', - 'status': u'Status', - 'date': u'Datum', - 'copyright': u'Copyright', - 'dedication': u'Dedikation', - 'abstract': u'Sammanfattning', - 'attention': u'Observera!', - 'caution': u'Varning!', - 'danger': u'FARA!', - 'error': u'Fel', - 'hint': u'V\u00e4gledning', - 'important': u'Viktigt', - 'note': u'Notera', - 'tip': u'Tips', - 'warning': u'Varning', - 'contents': u'Inneh\u00e5ll' } -"""Mapping of node class name to label text.""" - -bibliographic_fields = { - # 'Author' and 'Authors' identical in Swedish; assume the plural: - u'f\u00f6rfattare': 'authors', - u' n/a': 'author', - u'organisation': 'organization', - u'adress': 'address', - u'kontakt': 'contact', - u'version': 'version', - u'revision': 'revision', - u'status': 'status', - u'datum': 'date', - u'copyright': 'copyright', - u'dedikation': 'dedication', - u'sammanfattning': 'abstract' } -"""Swedish (lowcased) to canonical name mapping for bibliographic fields.""" - -author_separators = [';', ','] -"""List of separator strings for the 'Authors' bibliographic field. Tried in -order.""" diff --git a/docutils/docutils/nodes.py b/docutils/docutils/nodes.py deleted file mode 100644 index b24f5f9fc..000000000 --- a/docutils/docutils/nodes.py +++ /dev/null @@ -1,1478 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Docutils document tree element class library. - -Classes in CamelCase are abstract base classes or auxiliary classes. The one -exception is `Text`, for a text (PCDATA) node; uppercase is used to -differentiate from element classes. Classes in lower_case_with_underscores -are element classes, matching the XML element generic identifiers in the DTD_. - -The position of each node (the level at which it can occur) is significant and -is represented by abstract base classes (`Root`, `Structural`, `Body`, -`Inline`, etc.). Certain transformations will be easier because we can use -``isinstance(node, base_class)`` to determine the position of the node in the -hierarchy. - -.. _DTD: http://docutils.sourceforge.net/spec/docutils.dtd -""" - -__docformat__ = 'reStructuredText' - -import sys -import os -import re -import xml.dom.minidom -from types import IntType, SliceType, StringType, UnicodeType, \ - TupleType, ListType -from UserString import UserString - - -# ============================== -# Functional Node Base Classes -# ============================== - -class Node: - - """Abstract base class of nodes in a document tree.""" - - parent = None - """Back-reference to the Node immediately containing this Node.""" - - document = None - """The `document` node at the root of the tree containing this Node.""" - - source = None - """Path or description of the input source which generated this Node.""" - - line = None - """The line number (1-based) of the beginning of this Node in `source`.""" - - def __nonzero__(self): - """ - Node instances are always true, even if they're empty. A node is more - than a simple container. Its boolean "truth" does not depend on - having one or more subnodes in the doctree. - - Use `len()` to check node length. Use `None` to represent a boolean - false value. - """ - return 1 - - def asdom(self, dom=xml.dom.minidom): - """Return a DOM **fragment** representation of this Node.""" - domroot = dom.Document() - return self._dom_node(domroot) - - def pformat(self, indent=' ', level=0): - """Return an indented pseudo-XML representation, for test purposes.""" - raise NotImplementedError - - def copy(self): - """Return a copy of self.""" - raise NotImplementedError - - def setup_child(self, child): - child.parent = self - if self.document: - child.document = self.document - if child.source is None: - child.source = self.document.current_source - if child.line is None: - child.line = self.document.current_line - - def walk(self, visitor): - """ - Traverse a tree of `Node` objects, calling ``visit_...`` methods of - `visitor` when entering each node. If there is no - ``visit_particular_node`` method for a node of type - ``particular_node``, the ``unknown_visit`` method is called. (The - `walkabout()` method is similar, except it also calls ``depart_...`` - methods before exiting each node.) - - This tree traversal supports limited in-place tree - modifications. Replacing one node with one or more nodes is - OK, as is removing an element. However, if the node removed - or replaced occurs after the current node, the old node will - still be traversed, and any new nodes will not. - - Within ``visit_...`` methods (and ``depart_...`` methods for - `walkabout()`), `TreePruningException` subclasses may be raised - (`SkipChildren`, `SkipSiblings`, `SkipNode`, `SkipDeparture`). - - Parameter `visitor`: A `NodeVisitor` object, containing a - ``visit_...`` method for each `Node` subclass encountered. - """ - name = 'visit_' + self.__class__.__name__ - method = getattr(visitor, name, visitor.unknown_visit) - visitor.document.reporter.debug(name, category='nodes.Node.walk') - try: - method(self) - except (SkipChildren, SkipNode): - return - except SkipDeparture: # not applicable; ignore - pass - children = self.get_children() - try: - for child in children[:]: - child.walk(visitor) - except SkipSiblings: - pass - - def walkabout(self, visitor): - """ - Perform a tree traversal similarly to `Node.walk()` (which see), - except also call ``depart_...`` methods before exiting each node. If - there is no ``depart_particular_node`` method for a node of type - ``particular_node``, the ``unknown_departure`` method is called. - - Parameter `visitor`: A `NodeVisitor` object, containing ``visit_...`` - and ``depart_...`` methods for each `Node` subclass encountered. - """ - call_depart = 1 - name = 'visit_' + self.__class__.__name__ - method = getattr(visitor, name, visitor.unknown_visit) - visitor.document.reporter.debug(name, category='nodes.Node.walkabout') - try: - try: - method(self) - except SkipNode: - return - except SkipDeparture: - call_depart = 0 - children = self.get_children() - try: - for child in children[:]: - child.walkabout(visitor) - except SkipSiblings: - pass - except SkipChildren: - pass - if call_depart: - name = 'depart_' + self.__class__.__name__ - method = getattr(visitor, name, visitor.unknown_departure) - visitor.document.reporter.debug( - name, category='nodes.Node.walkabout') - method(self) - - -class Text(Node, UserString): - - """ - Instances are terminal nodes (leaves) containing text only; no child - nodes or attributes. Initialize by passing a string to the constructor. - Access the text itself with the `astext` method. - """ - - tagname = '#text' - - def __init__(self, data, rawsource=''): - UserString.__init__(self, data) - - self.rawsource = rawsource - """The raw text from which this element was constructed.""" - - def __repr__(self): - data = repr(self.data) - if len(data) > 70: - data = repr(self.data[:64] + ' ...') - return '<%s: %s>' % (self.tagname, data) - - def __len__(self): - return len(self.data) - - def shortrepr(self): - data = repr(self.data) - if len(data) > 20: - data = repr(self.data[:16] + ' ...') - return '<%s: %s>' % (self.tagname, data) - - def _dom_node(self, domroot): - return domroot.createTextNode(self.data) - - def astext(self): - return self.data - - def copy(self): - return self.__class__(self.data) - - def pformat(self, indent=' ', level=0): - result = [] - indent = indent * level - for line in self.data.splitlines(): - result.append(indent + line + '\n') - return ''.join(result) - - def get_children(self): - """Text nodes have no children. Return [].""" - return [] - - -class Element(Node): - - """ - `Element` is the superclass to all specific elements. - - Elements contain attributes and child nodes. Elements emulate - dictionaries for attributes, indexing by attribute name (a string). To - set the attribute 'att' to 'value', do:: - - element['att'] = 'value' - - Elements also emulate lists for child nodes (element nodes and/or text - nodes), indexing by integer. To get the first child node, use:: - - element[0] - - Elements may be constructed using the ``+=`` operator. To add one new - child node to element, do:: - - element += node - - This is equivalent to ``element.append(node)``. - - To add a list of multiple child nodes at once, use the same ``+=`` - operator:: - - element += [node1, node2] - - This is equivalent to ``element.extend([node1, node2])``. - """ - - tagname = None - """The element generic identifier. If None, it is set as an instance - attribute to the name of the class.""" - - child_text_separator = '\n\n' - """Separator for child nodes, used by `astext()` method.""" - - def __init__(self, rawsource='', *children, **attributes): - self.rawsource = rawsource - """The raw text from which this element was constructed.""" - - self.children = [] - """List of child nodes (elements and/or `Text`).""" - - self.extend(children) # maintain parent info - - self.attributes = {} - """Dictionary of attribute {name: value}.""" - - for att, value in attributes.items(): - self.attributes[att.lower()] = value - - if self.tagname is None: - self.tagname = self.__class__.__name__ - - def _dom_node(self, domroot): - element = domroot.createElement(self.tagname) - for attribute, value in self.attributes.items(): - if isinstance(value, ListType): - value = ' '.join(['%s' % v for v in value]) - element.setAttribute(attribute, '%s' % value) - for child in self.children: - element.appendChild(child._dom_node(domroot)) - return element - - def __repr__(self): - data = '' - for c in self.children: - data += c.shortrepr() - if len(data) > 60: - data = data[:56] + ' ...' - break - if self.hasattr('name'): - return '<%s "%s": %s>' % (self.__class__.__name__, - self.attributes['name'], data) - else: - return '<%s: %s>' % (self.__class__.__name__, data) - - def shortrepr(self): - if self.hasattr('name'): - return '<%s "%s"...>' % (self.__class__.__name__, - self.attributes['name']) - else: - return '<%s...>' % self.tagname - - def __str__(self): - return unicode(self).encode('raw_unicode_escape') - - def __unicode__(self): - if self.children: - return u'%s%s%s' % (self.starttag(), - ''.join([str(c) for c in self.children]), - self.endtag()) - else: - return self.emptytag() - - def starttag(self): - parts = [self.tagname] - for name, value in self.attlist(): - if value is None: # boolean attribute - parts.append(name) - elif isinstance(value, ListType): - values = ['%s' % v for v in value] - parts.append('%s="%s"' % (name, ' '.join(values))) - else: - parts.append('%s="%s"' % (name, value)) - return '<%s>' % ' '.join(parts) - - def endtag(self): - return '</%s>' % self.tagname - - def emptytag(self): - return u'<%s/>' % ' '.join([self.tagname] + - ['%s="%s"' % (n, v) - for n, v in self.attlist()]) - - def __len__(self): - return len(self.children) - - def __getitem__(self, key): - if isinstance(key, UnicodeType) or isinstance(key, StringType): - return self.attributes[key] - elif isinstance(key, IntType): - return self.children[key] - elif isinstance(key, SliceType): - assert key.step in (None, 1), 'cannot handle slice with stride' - return self.children[key.start:key.stop] - else: - raise TypeError, ('element index must be an integer, a slice, or ' - 'an attribute name string') - - def __setitem__(self, key, item): - if isinstance(key, UnicodeType) or isinstance(key, StringType): - self.attributes[str(key)] = item - elif isinstance(key, IntType): - self.setup_child(item) - self.children[key] = item - elif isinstance(key, SliceType): - assert key.step in (None, 1), 'cannot handle slice with stride' - for node in item: - self.setup_child(node) - self.children[key.start:key.stop] = item - else: - raise TypeError, ('element index must be an integer, a slice, or ' - 'an attribute name string') - - def __delitem__(self, key): - if isinstance(key, UnicodeType) or isinstance(key, StringType): - del self.attributes[key] - elif isinstance(key, IntType): - del self.children[key] - elif isinstance(key, SliceType): - assert key.step in (None, 1), 'cannot handle slice with stride' - del self.children[key.start:key.stop] - else: - raise TypeError, ('element index must be an integer, a simple ' - 'slice, or an attribute name string') - - def __add__(self, other): - return self.children + other - - def __radd__(self, other): - return other + self.children - - def __iadd__(self, other): - """Append a node or a list of nodes to `self.children`.""" - if isinstance(other, Node): - self.setup_child(other) - self.children.append(other) - elif other is not None: - for node in other: - self.setup_child(node) - self.children.extend(other) - return self - - def astext(self): - return self.child_text_separator.join( - [child.astext() for child in self.children]) - - def attlist(self): - attlist = self.attributes.items() - attlist.sort() - return attlist - - def get(self, key, failobj=None): - return self.attributes.get(key, failobj) - - def hasattr(self, attr): - return self.attributes.has_key(attr) - - def delattr(self, attr): - if self.attributes.has_key(attr): - del self.attributes[attr] - - def setdefault(self, key, failobj=None): - return self.attributes.setdefault(key, failobj) - - has_key = hasattr - - def append(self, item): - self.setup_child(item) - self.children.append(item) - - def extend(self, item): - for node in item: - self.setup_child(node) - self.children.extend(item) - - def insert(self, index, item): - if isinstance(item, Node): - self.setup_child(item) - self.children.insert(index, item) - elif item is not None: - self[index:index] = item - - def pop(self, i=-1): - return self.children.pop(i) - - def remove(self, item): - self.children.remove(item) - - def index(self, item): - return self.children.index(item) - - def replace(self, old, new): - """Replace one child `Node` with another child or children.""" - index = self.index(old) - if isinstance(new, Node): - self.setup_child(new) - self[index] = new - elif new is not None: - self[index:index+1] = new - - def first_child_matching_class(self, childclass, start=0, end=sys.maxint): - """ - Return the index of the first child whose class exactly matches. - - Parameters: - - - `childclass`: A `Node` subclass to search for, or a tuple of `Node` - classes. If a tuple, any of the classes may match. - - `start`: Initial index to check. - - `end`: Initial index to *not* check. - """ - if not isinstance(childclass, TupleType): - childclass = (childclass,) - for index in range(start, min(len(self), end)): - for c in childclass: - if isinstance(self[index], c): - return index - return None - - def first_child_not_matching_class(self, childclass, start=0, - end=sys.maxint): - """ - Return the index of the first child whose class does *not* match. - - Parameters: - - - `childclass`: A `Node` subclass to skip, or a tuple of `Node` - classes. If a tuple, none of the classes may match. - - `start`: Initial index to check. - - `end`: Initial index to *not* check. - """ - if not isinstance(childclass, TupleType): - childclass = (childclass,) - for index in range(start, min(len(self), end)): - match = 0 - for c in childclass: - if isinstance(self.children[index], c): - match = 1 - break - if not match: - return index - return None - - def pformat(self, indent=' ', level=0): - return ''.join(['%s%s\n' % (indent * level, self.starttag())] + - [child.pformat(indent, level+1) - for child in self.children]) - - def get_children(self): - """Return this element's children.""" - return self.children - - def copy(self): - return self.__class__(**self.attributes) - - def set_class(self, name): - """Add a new name to the "class" attribute.""" - self.attributes['class'] = (self.attributes.get('class', '') + ' ' - + name.lower()).strip() - - -class TextElement(Element): - - """ - An element which directly contains text. - - Its children are all Text or TextElement nodes. - """ - - child_text_separator = '' - """Separator for child nodes, used by `astext()` method.""" - - def __init__(self, rawsource='', text='', *children, **attributes): - if text != '': - textnode = Text(text) - Element.__init__(self, rawsource, textnode, *children, - **attributes) - else: - Element.__init__(self, rawsource, *children, **attributes) - - -class FixedTextElement(TextElement): - - """An element which directly contains preformatted text.""" - - def __init__(self, rawsource='', text='', *children, **attributes): - TextElement.__init__(self, rawsource, text, *children, **attributes) - self.attributes['xml:space'] = 'preserve' - - -# ======== -# Mixins -# ======== - -class Resolvable: - - resolved = 0 - - -class BackLinkable: - - def add_backref(self, refid): - self.setdefault('backrefs', []).append(refid) - - -# ==================== -# Element Categories -# ==================== - -class Root: pass - -class Titular: pass - -class PreDecorative: - """Category of Node which may occur before Decorative Nodes.""" - -class PreBibliographic(PreDecorative): - """Category of Node which may occur before Bibliographic Nodes.""" - -class Bibliographic(PreDecorative): pass - -class Decorative: pass - -class Structural: pass - -class Body: pass - -class General(Body): pass - -class Sequential(Body): pass - -class Admonition(Body): pass - -class Special(Body): - """Special internal body elements.""" - -class Invisible: - """Internal elements that don't appear in output.""" - -class Part: pass - -class Inline: pass - -class Referential(Resolvable): pass - -class Targetable(Resolvable): - - referenced = 0 - -class Labeled: - """Contains a `label` as its first element.""" - - -# ============== -# Root Element -# ============== - -class document(Root, Structural, Element): - - def __init__(self, settings, reporter, *args, **kwargs): - Element.__init__(self, *args, **kwargs) - - self.current_source = None - """Path to or description of the input source being processed.""" - - self.current_line = None - """Line number (1-based) of `current_source`.""" - - self.settings = settings - """Runtime settings data record.""" - - self.reporter = reporter - """System message generator.""" - - self.external_targets = [] - """List of external target nodes.""" - - self.internal_targets = [] - """List of internal target nodes.""" - - self.indirect_targets = [] - """List of indirect target nodes.""" - - self.substitution_defs = {} - """Mapping of substitution names to substitution_definition nodes.""" - - self.substitution_names = {} - """Mapping of case-normalized substitution names to case-sensitive - names.""" - - self.refnames = {} - """Mapping of names to lists of referencing nodes.""" - - self.refids = {} - """Mapping of ids to lists of referencing nodes.""" - - self.nameids = {} - """Mapping of names to unique id's.""" - - self.nametypes = {} - """Mapping of names to hyperlink type (boolean: True => explicit, - False => implicit.""" - - self.ids = {} - """Mapping of ids to nodes.""" - - self.substitution_refs = {} - """Mapping of substitution names to lists of substitution_reference - nodes.""" - - self.footnote_refs = {} - """Mapping of footnote labels to lists of footnote_reference nodes.""" - - self.citation_refs = {} - """Mapping of citation labels to lists of citation_reference nodes.""" - - self.anonymous_targets = [] - """List of anonymous target nodes.""" - - self.anonymous_refs = [] - """List of anonymous reference nodes.""" - - self.autofootnotes = [] - """List of auto-numbered footnote nodes.""" - - self.autofootnote_refs = [] - """List of auto-numbered footnote_reference nodes.""" - - self.symbol_footnotes = [] - """List of symbol footnote nodes.""" - - self.symbol_footnote_refs = [] - """List of symbol footnote_reference nodes.""" - - self.footnotes = [] - """List of manually-numbered footnote nodes.""" - - self.citations = [] - """List of citation nodes.""" - - self.autofootnote_start = 1 - """Initial auto-numbered footnote number.""" - - self.symbol_footnote_start = 0 - """Initial symbol footnote symbol index.""" - - self.id_start = 1 - """Initial ID number.""" - - self.parse_messages = [] - """System messages generated while parsing.""" - - self.transform_messages = [] - """System messages generated while applying transforms.""" - - import docutils.transforms - self.transformer = docutils.transforms.Transformer(self) - """Storage for transforms to be applied to this document.""" - - self.document = self - - def asdom(self, dom=xml.dom.minidom): - """Return a DOM representation of this document.""" - domroot = dom.Document() - domroot.appendChild(self._dom_node(domroot)) - return domroot - - def set_id(self, node, msgnode=None): - if node.has_key('id'): - id = node['id'] - if self.ids.has_key(id) and self.ids[id] is not node: - msg = self.reporter.severe('Duplicate ID: "%s".' % id) - if msgnode != None: - msgnode += msg - else: - if node.has_key('name'): - id = make_id(node['name']) - else: - id = '' - while not id or self.ids.has_key(id): - id = 'id%s' % self.id_start - self.id_start += 1 - node['id'] = id - self.ids[id] = node - return id - - def set_name_id_map(self, node, id, msgnode=None, explicit=None): - """ - `self.nameids` maps names to IDs, while `self.nametypes` maps names to - booleans representing hyperlink type (True==explicit, - False==implicit). This method updates the mappings. - - The following state transition table shows how `self.nameids` ("ids") - and `self.nametypes` ("types") change with new input (a call to this - method), and what actions are performed: - - ==== ===== ======== ======== ======= ==== ===== ===== - 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 [#]_ - 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 - ==== ===== ======== ======== ======= ==== ===== ===== - - .. [#] Do not clear the name-to-id map or invalidate the old target if - both old and new targets are external and refer to identical URIs. - The new target is invalidated regardless. - """ - if node.has_key('name'): - name = node['name'] - if self.nameids.has_key(name): - self.set_duplicate_name_id(node, id, name, msgnode, explicit) - else: - self.nameids[name] = id - self.nametypes[name] = explicit - - def set_duplicate_name_id(self, node, id, name, msgnode, explicit): - old_id = self.nameids[name] - old_explicit = self.nametypes[name] - self.nametypes[name] = old_explicit or explicit - if explicit: - if old_explicit: - level = 2 - if old_id is not None: - old_node = self.ids[old_id] - if node.has_key('refuri'): - refuri = node['refuri'] - if old_node.has_key('name') \ - and old_node.has_key('refuri') \ - and old_node['refuri'] == refuri: - level = 1 # just inform if refuri's identical - if level > 1: - dupname(old_node) - self.nameids[name] = None - msg = self.reporter.system_message( - level, 'Duplicate explicit target name: "%s".' % name, - backrefs=[id], base_node=node) - if msgnode != None: - msgnode += msg - dupname(node) - else: - self.nameids[name] = id - if old_id is not None: - old_node = self.ids[old_id] - dupname(old_node) - else: - if old_id is not None and not old_explicit: - self.nameids[name] = None - old_node = self.ids[old_id] - dupname(old_node) - dupname(node) - if not explicit or (not old_explicit and old_id is not None): - msg = self.reporter.info( - 'Duplicate implicit target name: "%s".' % name, - backrefs=[id], base_node=node) - if msgnode != None: - msgnode += msg - - def has_name(self, name): - return self.nameids.has_key(name) - - def note_implicit_target(self, target, msgnode=None): - id = self.set_id(target, msgnode) - self.set_name_id_map(target, id, msgnode, explicit=None) - - def note_explicit_target(self, target, msgnode=None): - id = self.set_id(target, msgnode) - self.set_name_id_map(target, id, msgnode, explicit=1) - - def note_refname(self, node): - self.refnames.setdefault(node['refname'], []).append(node) - - def note_refid(self, node): - self.refids.setdefault(node['refid'], []).append(node) - - def note_external_target(self, target): - self.external_targets.append(target) - - def note_internal_target(self, target): - self.internal_targets.append(target) - - def note_indirect_target(self, target): - self.indirect_targets.append(target) - if target.has_key('name'): - self.note_refname(target) - - def note_anonymous_target(self, target): - self.set_id(target) - self.anonymous_targets.append(target) - - def note_anonymous_ref(self, ref): - self.anonymous_refs.append(ref) - - def note_autofootnote(self, footnote): - self.set_id(footnote) - self.autofootnotes.append(footnote) - - def note_autofootnote_ref(self, ref): - self.set_id(ref) - self.autofootnote_refs.append(ref) - - def note_symbol_footnote(self, footnote): - self.set_id(footnote) - self.symbol_footnotes.append(footnote) - - def note_symbol_footnote_ref(self, ref): - self.set_id(ref) - self.symbol_footnote_refs.append(ref) - - def note_footnote(self, footnote): - self.set_id(footnote) - self.footnotes.append(footnote) - - def note_footnote_ref(self, ref): - self.set_id(ref) - self.footnote_refs.setdefault(ref['refname'], []).append(ref) - self.note_refname(ref) - - def note_citation(self, citation): - self.citations.append(citation) - - def note_citation_ref(self, ref): - self.set_id(ref) - self.citation_refs.setdefault(ref['refname'], []).append(ref) - self.note_refname(ref) - - def note_substitution_def(self, subdef, def_name, msgnode=None): - name = subdef['name'] = whitespace_normalize_name(def_name) - if self.substitution_defs.has_key(name): - msg = self.reporter.error( - 'Duplicate substitution definition name: "%s".' % name, - base_node=subdef) - if msgnode != None: - msgnode += msg - oldnode = self.substitution_defs[name] - dupname(oldnode) - # keep only the last definition: - self.substitution_defs[name] = subdef - # case-insensitive mapping: - self.substitution_names[fully_normalize_name(name)] = name - - def note_substitution_ref(self, subref, refname): - name = subref['refname'] = whitespace_normalize_name(refname) - self.substitution_refs.setdefault(name, []).append(subref) - - def note_pending(self, pending, priority=None): - self.transformer.add_pending(pending, priority) - - def note_parse_message(self, message): - self.parse_messages.append(message) - - def note_transform_message(self, message): - self.transform_messages.append(message) - - def note_source(self, source, offset): - self.current_source = source - if offset is None: - self.current_line = offset - else: - self.current_line = offset + 1 - - def copy(self): - return self.__class__(self.settings, self.reporter, - **self.attributes) - - -# ================ -# Title Elements -# ================ - -class title(Titular, PreBibliographic, TextElement): pass -class subtitle(Titular, PreBibliographic, TextElement): pass -class rubric(Titular, TextElement): pass - - -# ======================== -# Bibliographic Elements -# ======================== - -class docinfo(Bibliographic, Element): pass -class author(Bibliographic, TextElement): pass -class authors(Bibliographic, Element): pass -class organization(Bibliographic, TextElement): pass -class address(Bibliographic, FixedTextElement): pass -class contact(Bibliographic, TextElement): pass -class version(Bibliographic, TextElement): pass -class revision(Bibliographic, TextElement): pass -class status(Bibliographic, TextElement): pass -class date(Bibliographic, TextElement): pass -class copyright(Bibliographic, TextElement): pass - - -# ===================== -# Decorative Elements -# ===================== - -class decoration(Decorative, Element): pass -class header(Decorative, Element): pass -class footer(Decorative, Element): pass - - -# ===================== -# Structural Elements -# ===================== - -class section(Structural, Element): pass - - -class topic(Structural, Element): - - """ - Topics are terminal, "leaf" mini-sections, like block quotes with titles, - or textual figures. A topic is just like a section, except that it has no - subsections, and it doesn't have to conform to section placement rules. - - Topics are allowed wherever body elements (list, table, etc.) are allowed, - but only at the top level of a section or document. Topics cannot nest - inside topics, sidebars, or body elements; you can't have a topic inside a - table, list, block quote, etc. - """ - - -class sidebar(Structural, Element): - - """ - 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 are allowed wherever body elements (list, table, etc.) are - allowed, but only at the top level of a section or document. Sidebars - cannot nest inside sidebars, topics, or body elements; you can't have a - sidebar inside a table, list, block quote, etc. - """ - - -class transition(Structural, Element): pass - - -# =============== -# Body Elements -# =============== - -class paragraph(General, TextElement): pass -class bullet_list(Sequential, Element): pass -class enumerated_list(Sequential, Element): pass -class list_item(Part, Element): pass -class definition_list(Sequential, Element): pass -class definition_list_item(Part, Element): pass -class term(Part, TextElement): pass -class classifier(Part, TextElement): pass -class definition(Part, Element): pass -class field_list(Sequential, Element): pass -class field(Part, Element): pass -class field_name(Part, TextElement): pass -class field_body(Part, Element): pass - - -class option(Part, Element): - - child_text_separator = '' - - -class option_argument(Part, TextElement): - - def astext(self): - return self.get('delimiter', ' ') + TextElement.astext(self) - - -class option_group(Part, Element): - - child_text_separator = ', ' - - -class option_list(Sequential, Element): pass - - -class option_list_item(Part, Element): - - child_text_separator = ' ' - - -class option_string(Part, TextElement): pass -class description(Part, Element): pass -class literal_block(General, FixedTextElement): pass -class doctest_block(General, FixedTextElement): pass -class line_block(General, FixedTextElement): pass -class block_quote(General, Element): pass -class attribution(Part, TextElement): pass -class attention(Admonition, Element): pass -class caution(Admonition, Element): pass -class danger(Admonition, Element): pass -class error(Admonition, Element): pass -class important(Admonition, Element): pass -class note(Admonition, Element): pass -class tip(Admonition, Element): pass -class hint(Admonition, Element): pass -class warning(Admonition, Element): pass -class admonition(Admonition, Element): pass -class comment(Special, Invisible, PreBibliographic, FixedTextElement): pass -class substitution_definition(Special, Invisible, TextElement): pass -class target(Special, Invisible, Inline, TextElement, Targetable): pass -class footnote(General, Element, Labeled, BackLinkable): pass -class citation(General, Element, Labeled, BackLinkable): pass -class label(Part, TextElement): pass -class figure(General, Element): pass -class caption(Part, TextElement): pass -class legend(Part, Element): pass -class table(General, Element): pass -class tgroup(Part, Element): pass -class colspec(Part, Element): pass -class thead(Part, Element): pass -class tbody(Part, Element): pass -class row(Part, Element): pass -class entry(Part, Element): pass - - -class system_message(Special, PreBibliographic, Element, BackLinkable): - - def __init__(self, message=None, *children, **attributes): - if message: - p = paragraph('', message) - children = (p,) + children - try: - Element.__init__(self, '', *children, **attributes) - except: - print 'system_message: children=%r' % (children,) - raise - - def astext(self): - line = self.get('line', '') - return u'%s:%s: (%s/%s) %s' % (self['source'], line, self['type'], - self['level'], Element.astext(self)) - - -class pending(Special, Invisible, PreBibliographic, Element): - - """ - The "pending" element is used to encapsulate a pending operation: the - operation (transform), the point at which to apply it, and any data it - requires. Only the pending operation's location within the document is - stored in the public document tree (by the "pending" object itself); the - operation and its data are stored in the "pending" object's internal - instance attributes. - - For example, say you want a table of contents in your reStructuredText - document. The easiest way to specify where to put it is from within the - document, with a directive:: - - .. contents:: - - But the "contents" directive can't do its work until the entire document - has been parsed and possibly transformed to some extent. So the directive - code leaves a placeholder behind that will trigger the second phase of the - its processing, something like this:: - - <pending ...public attributes...> + internal attributes - - Use `document.note_pending()` so that the - `docutils.transforms.Transformer` stage of processing can run all pending - transforms. - """ - - def __init__(self, transform, details=None, - rawsource='', *children, **attributes): - Element.__init__(self, rawsource, *children, **attributes) - - self.transform = transform - """The `docutils.transforms.Transform` class implementing the pending - operation.""" - - self.details = details or {} - """Detail data (dictionary) required by the pending operation.""" - - def pformat(self, indent=' ', level=0): - internals = [ - '.. internal attributes:', - ' .transform: %s.%s' % (self.transform.__module__, - self.transform.__name__), - ' .details:'] - details = self.details.items() - details.sort() - for key, value in details: - if isinstance(value, Node): - internals.append('%7s%s:' % ('', key)) - internals.extend(['%9s%s' % ('', line) - for line in value.pformat().splitlines()]) - elif value and isinstance(value, ListType) \ - and isinstance(value[0], Node): - internals.append('%7s%s:' % ('', key)) - for v in value: - internals.extend(['%9s%s' % ('', line) - for line in v.pformat().splitlines()]) - else: - internals.append('%7s%s: %r' % ('', key, value)) - return (Element.pformat(self, indent, level) - + ''.join([(' %s%s\n' % (indent * level, line)) - for line in internals])) - - def copy(self): - return self.__class__(self.transform, self.details, self.rawsource, - **self.attribuates) - - -class raw(Special, Inline, PreBibliographic, FixedTextElement): - - """ - Raw data that is to be passed untouched to the Writer. - """ - - pass - - -# ================= -# Inline Elements -# ================= - -class emphasis(Inline, TextElement): pass -class strong(Inline, TextElement): pass -class literal(Inline, TextElement): pass -class reference(Inline, Referential, TextElement): pass -class footnote_reference(Inline, Referential, TextElement): pass -class citation_reference(Inline, Referential, TextElement): pass -class substitution_reference(Inline, TextElement): pass -class title_reference(Inline, TextElement): pass -class abbreviation(Inline, TextElement): pass -class acronym(Inline, TextElement): pass -class superscript(Inline, TextElement): pass -class subscript(Inline, TextElement): pass - - -class image(General, Inline, TextElement): - - def astext(self): - return self.get('alt', '') - - -class inline(Inline, TextElement): pass -class problematic(Inline, TextElement): pass -class generated(Inline, TextElement): pass - - -# ======================================== -# Auxiliary Classes, Functions, and Data -# ======================================== - -node_class_names = """ - Text - abbreviation acronym address admonition attention attribution author - authors - block_quote bullet_list - caption caution citation citation_reference classifier colspec comment - contact copyright - danger date decoration definition definition_list definition_list_item - description docinfo doctest_block document - emphasis entry enumerated_list error - field field_body field_list field_name figure footer - footnote footnote_reference - generated - header hint - image important inline - label legend line_block list_item literal literal_block - note - option option_argument option_group option_list option_list_item - option_string organization - paragraph pending problematic - raw reference revision row rubric - section sidebar status strong subscript substitution_definition - substitution_reference subtitle superscript system_message - table target tbody term tgroup thead tip title title_reference topic - transition - version - warning""".split() -"""A list of names of all concrete Node subclasses.""" - - -class NodeVisitor: - - """ - "Visitor" pattern [GoF95]_ abstract superclass implementation for document - tree traversals. - - Each node class has corresponding methods, doing nothing by default; - override individual methods for specific and useful behaviour. The - "``visit_`` + node class name" method is called by `Node.walk()` upon - entering a node. `Node.walkabout()` also calls the "``depart_`` + node - class name" method before exiting a node. - - This is a base class for visitors whose ``visit_...`` & ``depart_...`` - methods should be implemented for *all* node types encountered (such as - for `docutils.writers.Writer` subclasses). Unimplemented methods will - raise exceptions. - - For sparse traversals, where only certain node types are of interest, - subclass `SparseNodeVisitor` instead. When (mostly or entirely) uniform - processing is desired, subclass `GenericNodeVisitor`. - - .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of - Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA, - 1995. - """ - - def __init__(self, document): - self.document = document - - def unknown_visit(self, node): - """ - Called when entering unknown `Node` types. - - Raise an exception unless overridden. - """ - raise NotImplementedError('visiting unknown node type: %s' - % node.__class__.__name__) - - def unknown_departure(self, node): - """ - Called before exiting unknown `Node` types. - - Raise exception unless overridden. - """ - raise NotImplementedError('departing unknown node type: %s' - % node.__class__.__name__) - - -class SparseNodeVisitor(NodeVisitor): - - """ - Base class for sparse traversals, where only certain node types are of - interest. When ``visit_...`` & ``depart_...`` methods should be - implemented for *all* node types (such as for `docutils.writers.Writer` - subclasses), subclass `NodeVisitor` instead. - """ - - # Save typing with dynamic definitions. - for name in node_class_names: - exec """def visit_%s(self, node): pass\n""" % name - exec """def depart_%s(self, node): pass\n""" % name - del name - - -class GenericNodeVisitor(NodeVisitor): - - """ - Generic "Visitor" abstract superclass, for simple traversals. - - Unless overridden, each ``visit_...`` method calls `default_visit()`, and - each ``depart_...`` method (when using `Node.walkabout()`) calls - `default_departure()`. `default_visit()` (and `default_departure()`) must - be overridden in subclasses. - - Define fully generic visitors by overriding `default_visit()` (and - `default_departure()`) only. Define semi-generic visitors by overriding - individual ``visit_...()`` (and ``depart_...()``) methods also. - - `NodeVisitor.unknown_visit()` (`NodeVisitor.unknown_departure()`) should - be overridden for default behavior. - """ - - def default_visit(self, node): - """Override for generic, uniform traversals.""" - raise NotImplementedError - - def default_departure(self, node): - """Override for generic, uniform traversals.""" - raise NotImplementedError - - # Save typing with dynamic definitions. - for name in node_class_names: - exec """def visit_%s(self, node): - self.default_visit(node)\n""" % name - exec """def depart_%s(self, node): - self.default_departure(node)\n""" % name - del name - - -class TreeCopyVisitor(GenericNodeVisitor): - - """ - Make a complete copy of a tree or branch, including element attributes. - """ - - def __init__(self, document): - GenericNodeVisitor.__init__(self, document) - self.parent_stack = [] - self.parent = [] - - def get_tree_copy(self): - return self.parent[0] - - def default_visit(self, node): - """Copy the current node, and make it the new acting parent.""" - newnode = node.copy() - self.parent.append(newnode) - self.parent_stack.append(self.parent) - self.parent = newnode - - def default_departure(self, node): - """Restore the previous acting parent.""" - self.parent = self.parent_stack.pop() - - -class TreePruningException(Exception): - - """ - Base class for `NodeVisitor`-related tree pruning exceptions. - - Raise subclasses from within ``visit_...`` or ``depart_...`` methods - called from `Node.walk()` and `Node.walkabout()` tree traversals to prune - the tree traversed. - """ - - pass - - -class SkipChildren(TreePruningException): - - """ - Do not visit any children of the current node. The current node's - siblings and ``depart_...`` method are not affected. - """ - - pass - - -class SkipSiblings(TreePruningException): - - """ - Do not visit any more siblings (to the right) of the current node. The - current node's children and its ``depart_...`` method are not affected. - """ - - pass - - -class SkipNode(TreePruningException): - - """ - Do not visit the current node's children, and do not call the current - node's ``depart_...`` method. - """ - - pass - - -class SkipDeparture(TreePruningException): - - """ - Do not call the current node's ``depart_...`` method. The current node's - children and siblings are not affected. - """ - - pass - - -class NodeFound(TreePruningException): - - """ - Raise to indicate that the target of a search has been found. This - exception must be caught by the client; it is not caught by the traversal - code. - """ - - pass - - -def make_id(string): - """ - Convert `string` into an identifier and return it. - - Docutils identifiers will 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; "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 - """ - id = _non_id_chars.sub('-', ' '.join(string.lower().split())) - id = _non_id_at_ends.sub('', id) - return str(id) - -_non_id_chars = re.compile('[^a-z0-9]+') -_non_id_at_ends = re.compile('^[-0-9]+|-+$') - -def dupname(node): - node['dupname'] = node['name'] - del node['name'] - -def fully_normalize_name(name): - """Return a case- and whitespace-normalized name.""" - return ' '.join(name.lower().split()) - -def whitespace_normalize_name(name): - """Return a whitespace-normalized name.""" - return ' '.join(name.split()) diff --git a/docutils/docutils/parsers/__init__.py b/docutils/docutils/parsers/__init__.py deleted file mode 100644 index 5b1e964be..000000000 --- a/docutils/docutils/parsers/__init__.py +++ /dev/null @@ -1,48 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This package contains Docutils parser modules. -""" - -__docformat__ = 'reStructuredText' - -from docutils import Component - - -class Parser(Component): - - component_type = 'parser' - - def parse(self, inputstring, document): - """Override to parse `inputstring` into document tree `document`.""" - raise NotImplementedError('subclass must override this method') - - def setup_parse(self, inputstring, document): - """Initial parse setup. Call at start of `self.parse()`.""" - self.inputstring = inputstring - self.document = document - document.reporter.attach_observer(document.note_parse_message) - - def finish_parse(self): - """Finalize parse details. Call at end of `self.parse()`.""" - self.document.reporter.detach_observer( - self.document.note_parse_message) - - -_parser_aliases = { - 'restructuredtext': 'rst', - 'rest': 'rst', - 'restx': 'rst', - 'rtxt': 'rst',} - -def get_parser_class(parser_name): - """Return the Parser class from the `parser_name` module.""" - parser_name = parser_name.lower() - if _parser_aliases.has_key(parser_name): - parser_name = _parser_aliases[parser_name] - module = __import__(parser_name, globals(), locals()) - return module.Parser diff --git a/docutils/docutils/parsers/rst/__init__.py b/docutils/docutils/parsers/rst/__init__.py deleted file mode 100644 index 899a49bc8..000000000 --- a/docutils/docutils/parsers/rst/__init__.py +++ /dev/null @@ -1,123 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This is ``docutils.parsers.rst`` package. It exports a single class, `Parser`, -the reStructuredText parser. - - -Usage -===== - -1. Create a parser:: - - parser = docutils.parsers.rst.Parser() - - Several optional arguments may be passed to modify the parser's behavior. - Please see `Customizing the Parser`_ below for details. - -2. Gather input (a multi-line string), by reading a file or the standard - input:: - - input = sys.stdin.read() - -3. Create a new empty `docutils.nodes.document` tree:: - - document = docutils.utils.new_document(source, settings) - - See `docutils.utils.new_document()` for parameter details. - -4. Run the parser, populating the document tree:: - - parser.parse(input, document) - - -Parser Overview -=============== - -The reStructuredText parser is implemented as a state machine, examining its -input one line at a time. To understand how the parser works, please first -become familiar with the `docutils.statemachine` module, then see the -`states` module. - - -Customizing the Parser ----------------------- - -Anything that isn't already customizable is that way simply because that type -of customizability hasn't been implemented yet. Patches welcome! - -When instantiating an object of the `Parser` class, two parameters may be -passed: ``rfc2822`` and ``inliner``. Pass ``rfc2822=1`` to enable an initial -RFC-2822 style header block, parsed as a "field_list" element (with "class" -attribute set to "rfc2822"). Currently this is the only body-level element -which is customizable without subclassing. (Tip: subclass `Parser` and change -its "state_classes" and "initial_state" attributes to refer to new classes. -Contact the author if you need more details.) - -The ``inliner`` parameter takes an instance of `states.Inliner` or a subclass. -It handles inline markup recognition. A common extension is the addition of -further implicit hyperlinks, like "RFC 2822". This can be done by subclassing -`states.Inliner`, adding a new method for the implicit markup, and adding a -``(pattern, method)`` pair to the "implicit_dispatch" attribute of the -subclass. See `states.Inliner.implicit_inline()` for details. Explicit -inline markup can be customized in a `states.Inliner` subclass via the -``patterns.initial`` and ``dispatch`` attributes (and new methods as -appropriate). -""" - -__docformat__ = 'reStructuredText' - - -import docutils.parsers -import docutils.statemachine -from docutils.parsers.rst import states - - -class Parser(docutils.parsers.Parser): - - """The reStructuredText parser.""" - - supported = ('restructuredtext', 'rst', 'rest', 'restx', 'rtxt', 'rstx') - """Aliases this parser supports.""" - - settings_spec = ( - 'reStructuredText Parser Options', - None, - (('Recognize and link to PEP references (like "PEP 258").', - ['--pep-references'], - {'action': 'store_true'}), - ('Recognize and link to RFC references (like "RFC 822").', - ['--rfc-references'], - {'action': 'store_true'}), - ('Set number of spaces for tab expansion (default 8).', - ['--tab-width'], - {'metavar': '<width>', 'type': 'int', 'default': 8}), - ('Remove spaces before footnote references.', - ['--trim-footnote-reference-space'], - {'action': 'store_true'}),)) - - def __init__(self, rfc2822=None, inliner=None): - if rfc2822: - self.initial_state = 'RFC2822Body' - else: - self.initial_state = 'Body' - self.state_classes = states.state_classes - self.inliner = inliner - - def parse(self, inputstring, document): - """Parse `inputstring` and populate `document`, a document tree.""" - self.setup_parse(inputstring, document) - debug = document.reporter[''].debug - self.statemachine = states.RSTStateMachine( - state_classes=self.state_classes, - initial_state=self.initial_state, - debug=debug) - inputlines = docutils.statemachine.string2lines( - inputstring, tab_width=document.settings.tab_width, - convert_whitespace=1) - self.statemachine.run(inputlines, document, inliner=self.inliner) - self.finish_parse() diff --git a/docutils/docutils/parsers/rst/directives/__init__.py b/docutils/docutils/parsers/rst/directives/__init__.py deleted file mode 100644 index 1a113db2d..000000000 --- a/docutils/docutils/parsers/rst/directives/__init__.py +++ /dev/null @@ -1,252 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This package contains directive implementation modules. - -The interface for directive functions 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 = ... - -Parameters: - -- ``name`` is the directive type or name. - -- ``arguments`` is a list of positional arguments. - -- ``options`` is a dictionary mapping option names to values. - -- ``content`` is a list of strings, the 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. - -Function attributes, interpreted by the directive parser (which calls the -directive function): - -- ``arguments``: A 3-tuple specifying the expected positional arguments, or - ``None`` if the directive has no arguments. The 3 items in the tuple are - ``(required, optional, whitespace OK in last argument)``: - - 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 if the third item in the argument spec tuple - is 1/True. If the form of the arguments is more complex, specify only one - argument (either required or optional) and indicate that final whitespace is - OK; the client code must do any context-sensitive parsing. - -- ``options``: A dictionary, mapping known option names to conversion - functions such as `int` or `float`. ``None`` or an empty dict implies no - options to parse. - -- ``content``: A boolean; true if content is allowed. Client code must handle - the case where content is required but not supplied (an empty content list - will be supplied). - -Directive functions return a list of nodes which will be inserted into the -document tree at the point where the directive was encountered (can be an -empty list). - -See `Creating reStructuredText Directives`_ for more information. - -.. _Creating reStructuredText Directives: - http://docutils.sourceforge.net/spec/howto/rst-directives.html -""" - -__docformat__ = 'reStructuredText' - -from docutils import nodes -from docutils.parsers.rst.languages import en as _fallback_language_module - - -_directive_registry = { - 'attention': ('admonitions', 'attention'), - 'caution': ('admonitions', 'caution'), - 'danger': ('admonitions', 'danger'), - 'error': ('admonitions', 'error'), - 'important': ('admonitions', 'important'), - 'note': ('admonitions', 'note'), - 'tip': ('admonitions', 'tip'), - 'hint': ('admonitions', 'hint'), - 'warning': ('admonitions', 'warning'), - 'admonition': ('admonitions', 'admonition'), - 'sidebar': ('body', 'sidebar'), - 'topic': ('body', 'topic'), - 'line-block': ('body', 'line_block'), - 'parsed-literal': ('body', 'parsed_literal'), - 'rubric': ('body', 'rubric'), - 'epigraph': ('body', 'epigraph'), - 'highlights': ('body', 'highlights'), - 'pull-quote': ('body', 'pull_quote'), - #'questions': ('body', 'question_list'), - 'image': ('images', 'image'), - 'figure': ('images', 'figure'), - 'contents': ('parts', 'contents'), - 'sectnum': ('parts', 'sectnum'), - #'footnotes': ('parts', 'footnotes'), - #'citations': ('parts', 'citations'), - 'target-notes': ('references', 'target_notes'), - 'meta': ('html', 'meta'), - #'imagemap': ('html', 'imagemap'), - 'raw': ('misc', 'raw'), - 'include': ('misc', 'include'), - 'replace': ('misc', 'replace'), - 'unicode': ('misc', 'unicode_directive'), - 'class': ('misc', 'class_directive'), - 'restructuredtext-test-directive': ('misc', 'directive_test_function'),} -"""Mapping of directive name to (module name, function name). The directive -name is canonical & must be lowercase. Language-dependent names are defined -in the ``language`` subpackage.""" - -_modules = {} -"""Cache of imported directive modules.""" - -_directives = {} -"""Cache of imported directive functions.""" - -def directive(directive_name, language_module, document): - """ - Locate and return a directive function from its language-dependent name. - If not found in the current language, check English. Return None if the - named directive cannot be found. - """ - normname = directive_name.lower() - messages = [] - msg_text = [] - if _directives.has_key(normname): - return _directives[normname], messages - canonicalname = None - try: - canonicalname = language_module.directives[normname] - except AttributeError, error: - msg_text.append('Problem retrieving directive entry from language ' - 'module %r: %s.' % (language_module, error)) - except KeyError: - msg_text.append('No directive entry for "%s" in module "%s".' - % (directive_name, language_module.__name__)) - if not canonicalname: - try: - canonicalname = _fallback_language_module.directives[normname] - msg_text.append('Using English fallback for directive "%s".' - % directive_name) - except KeyError: - msg_text.append('Trying "%s" as canonical directive name.' - % directive_name) - # The canonical name should be an English name, but just in case: - canonicalname = normname - if msg_text: - message = document.reporter.info( - '\n'.join(msg_text), line=document.current_line) - messages.append(message) - try: - modulename, functionname = _directive_registry[canonicalname] - except KeyError: - return None, messages - if _modules.has_key(modulename): - module = _modules[modulename] - else: - try: - module = __import__(modulename, globals(), locals()) - except ImportError: - return None, messages - try: - function = getattr(module, functionname) - _directives[normname] = function - except AttributeError: - return None, messages - return function, messages - -def register_directive(name, directive): - """Register a nonstandard application-defined directive function.""" - _directives[name] = directive - -def flag(argument): - """ - Check for a valid flag option (no argument) and return ``None``. - - Raise ``ValueError`` if an argument is found. - """ - if argument and argument.strip(): - raise ValueError('no argument is allowed; "%s" supplied' % argument) - else: - return None - -def unchanged(argument): - """ - Return the argument, unchanged. - - Raise ``ValueError`` if no argument is found. - """ - if argument is None: - raise ValueError('argument required but none supplied') - else: - return argument # unchanged! - -def path(argument): - """ - Return the path argument unwrapped (with newlines removed). - - Raise ``ValueError`` if no argument is found or if the path contains - internal whitespace. - """ - if argument is None: - raise ValueError('argument required but none supplied') - else: - path = ''.join([s.strip() for s in argument.splitlines()]) - if path.find(' ') == -1: - return path - else: - raise ValueError('path contains whitespace') - -def nonnegative_int(argument): - """ - Check for a nonnegative integer argument; raise ``ValueError`` if not. - """ - value = int(argument) - if value < 0: - raise ValueError('negative value; must be positive or zero') - return value - -def format_values(values): - return '%s, or "%s"' % (', '.join(['"%s"' % s for s in values[:-1]]), - values[-1]) - -def choice(argument, values): - try: - value = argument.lower().strip() - except AttributeError: - raise ValueError('must supply an argument; choose from %s' - % format_values(values)) - if value in values: - return value - else: - raise ValueError('"%s" unknown; choose from %s' - % (argument, format_values(values))) - -def class_option(argument): - if argument is None: - raise ValueError('argument required but none supplied') - return nodes.make_id(argument) diff --git a/docutils/docutils/parsers/rst/directives/admonitions.py b/docutils/docutils/parsers/rst/directives/admonitions.py deleted file mode 100644 index 8e3a92895..000000000 --- a/docutils/docutils/parsers/rst/directives/admonitions.py +++ /dev/null @@ -1,90 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Admonition directives. -""" - -__docformat__ = 'reStructuredText' - - -from docutils.parsers.rst import states, directives -from docutils import nodes - - -def make_admonition(node_class, name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if not content: - error = state_machine.reporter.error( - 'The "%s" admonition is empty; content required.' % (name), - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - text = '\n'.join(content) - admonition_node = node_class(text) - if arguments: - title_text = arguments[0] - textnodes, messages = state.inline_text(title_text, lineno) - admonition_node += nodes.title(title_text, '', *textnodes) - admonition_node += messages - if options.has_key('class'): - class_value = options['class'] - else: - class_value = 'admonition-' + nodes.make_id(title_text) - admonition_node.set_class(class_value) - state.nested_parse(content, content_offset, admonition_node) - return [admonition_node] - -def admonition(*args): - return make_admonition(nodes.admonition, *args) - -admonition.arguments = (1, 0, 1) -admonition.options = {'class': directives.class_option} -admonition.content = 1 - -def attention(*args): - return make_admonition(nodes.attention, *args) - -attention.content = 1 - -def caution(*args): - return make_admonition(nodes.caution, *args) - -caution.content = 1 - -def danger(*args): - return make_admonition(nodes.danger, *args) - -danger.content = 1 - -def error(*args): - return make_admonition(nodes.error, *args) - -error.content = 1 - -def hint(*args): - return make_admonition(nodes.hint, *args) - -hint.content = 1 - -def important(*args): - return make_admonition(nodes.important, *args) - -important.content = 1 - -def note(*args): - return make_admonition(nodes.note, *args) - -note.content = 1 - -def tip(*args): - return make_admonition(nodes.tip, *args) - -tip.content = 1 - -def warning(*args): - return make_admonition(nodes.warning, *args) - -warning.content = 1 diff --git a/docutils/docutils/parsers/rst/directives/body.py b/docutils/docutils/parsers/rst/directives/body.py deleted file mode 100644 index c2fd6b99d..000000000 --- a/docutils/docutils/parsers/rst/directives/body.py +++ /dev/null @@ -1,122 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Directives for additional body elements. -""" - -__docformat__ = 'reStructuredText' - - -import sys -from docutils import nodes -from docutils.parsers.rst import directives - - -def topic(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine, - node_class=nodes.topic): - if not state_machine.match_titles: - error = state_machine.reporter.error( - 'The "%s" directive may not be used within topics, sidebars, ' - 'or body elements.' % name, - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - if not content: - warning = state_machine.reporter.warning( - 'Content block expected for the "%s" directive; none found.' - % name, nodes.literal_block(block_text, block_text), - line=lineno) - return [warning] - title_text = arguments[0] - textnodes, messages = state.inline_text(title_text, lineno) - titles = [nodes.title(title_text, '', *textnodes)] - if options.has_key('subtitle'): - textnodes, more_messages = state.inline_text(options['subtitle'], - lineno) - titles.append(nodes.subtitle(options['subtitle'], '', *textnodes)) - messages.extend(more_messages) - text = '\n'.join(content) - node = node_class(text, *(titles + messages)) - if options.has_key('class'): - node.set_class(options['class']) - if text: - state.nested_parse(content, content_offset, node) - return [node] - -topic.arguments = (1, 0, 1) -topic.options = {'class': directives.class_option} -topic.content = 1 - -def sidebar(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return topic(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine, - node_class=nodes.sidebar) - -sidebar.arguments = (1, 0, 1) -sidebar.options = {'subtitle': directives.unchanged, - 'class': directives.class_option} -sidebar.content = 1 - -def line_block(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine, - node_class=nodes.line_block): - if not content: - warning = state_machine.reporter.warning( - 'Content block expected for the "%s" directive; none found.' - % name, nodes.literal_block(block_text, block_text), line=lineno) - return [warning] - text = '\n'.join(content) - text_nodes, messages = state.inline_text(text, lineno) - node = node_class(text, '', *text_nodes, **options) - return [node] + messages - -line_block.options = {'class': directives.class_option} -line_block.content = 1 - -def parsed_literal(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return line_block(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine, - node_class=nodes.literal_block) - -parsed_literal.options = {'class': directives.class_option} -parsed_literal.content = 1 - -def rubric(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - rubric_text = arguments[0] - textnodes, messages = state.inline_text(rubric_text, lineno) - rubric = nodes.rubric(rubric_text, '', *textnodes, **options) - return [rubric] + messages - -rubric.arguments = (1, 0, 1) -rubric.options = {'class': directives.class_option} - -def epigraph(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - block_quote, messages = state.block_quote(content, content_offset) - block_quote.set_class('epigraph') - return [block_quote] + messages - -epigraph.content = 1 - -def highlights(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - block_quote, messages = state.block_quote(content, content_offset) - block_quote.set_class('highlights') - return [block_quote] + messages - -highlights.content = 1 - -def pull_quote(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - block_quote, messages = state.block_quote(content, content_offset) - block_quote.set_class('pull-quote') - return [block_quote] + messages - -pull_quote.content = 1 diff --git a/docutils/docutils/parsers/rst/directives/html.py b/docutils/docutils/parsers/rst/directives/html.py deleted file mode 100644 index a6e656994..000000000 --- a/docutils/docutils/parsers/rst/directives/html.py +++ /dev/null @@ -1,96 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Directives for typically HTML-specific constructs. -""" - -__docformat__ = 'reStructuredText' - -import sys -from docutils import nodes, utils -from docutils.parsers.rst import states -from docutils.transforms import components - - -def meta(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - node = nodes.Element() - if content: - new_line_offset, blank_finish = state.nested_list_parse( - content, content_offset, node, initial_state='MetaBody', - blank_finish=1, state_machine_kwargs=metaSMkwargs) - if (new_line_offset - content_offset) != len(content): - # incomplete parse of block? - error = state_machine.reporter.error( - 'Invalid meta directive.', - nodes.literal_block(block_text, block_text), line=lineno) - node += error - else: - error = state_machine.reporter.error( - 'Empty meta directive.', - nodes.literal_block(block_text, block_text), line=lineno) - node += error - return node.get_children() - -meta.content = 1 - -def imagemap(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return [] - - -class MetaBody(states.SpecializedBody): - - class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): - """HTML-specific "meta" element.""" - pass - - def field_marker(self, match, context, next_state): - """Meta element.""" - node, blank_finish = self.parsemeta(match) - self.parent += node - return [], next_state, [] - - def parsemeta(self, match): - name = self.parse_field_marker(match) - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - node = self.meta() - pending = nodes.pending(components.Filter, - {'component': 'writer', - 'format': 'html', - 'nodes': [node]}) - node['content'] = ' '.join(indented) - if not indented: - line = self.state_machine.line - msg = self.reporter.info( - 'No content for meta tag "%s".' % name, - nodes.literal_block(line, line), - line=self.state_machine.abs_line_number()) - return msg, blank_finish - tokens = name.split() - try: - attname, val = utils.extract_name_value(tokens[0])[0] - node[attname.lower()] = val - except utils.NameValueError: - node['name'] = tokens[0] - for token in tokens[1:]: - try: - attname, val = utils.extract_name_value(token)[0] - node[attname.lower()] = val - except utils.NameValueError, detail: - line = self.state_machine.line - msg = self.reporter.error( - 'Error parsing meta tag attribute "%s": %s.' - % (token, detail), nodes.literal_block(line, line), - line=self.state_machine.abs_line_number()) - return msg, blank_finish - self.document.note_pending(pending) - return pending, blank_finish - - -metaSMkwargs = {'state_classes': (MetaBody,)} diff --git a/docutils/docutils/parsers/rst/directives/images.py b/docutils/docutils/parsers/rst/directives/images.py deleted file mode 100644 index d193edffd..000000000 --- a/docutils/docutils/parsers/rst/directives/images.py +++ /dev/null @@ -1,100 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Directives for figures and simple images. -""" - -__docformat__ = 'reStructuredText' - - -import sys -from docutils import nodes, utils -from docutils.parsers.rst import directives - -try: - import Image # PIL -except ImportError: - Image = None - -align_values = ('top', 'middle', 'bottom', 'left', 'center', 'right') - -def align(argument): - return directives.choice(argument, align_values) - -def image(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - reference = ''.join(arguments[0].split('\n')) - if reference.find(' ') != -1: - error = state_machine.reporter.error( - 'Image URI contains whitespace.', - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - 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, - 'class': directives.class_option} - -def figure(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - figwidth = options.setdefault('figwidth') - figclass = options.setdefault('figclass') - del options['figwidth'] - del options['figclass'] - (image_node,) = image(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine) - if isinstance(image_node, nodes.system_message): - return [image_node] - figure_node = nodes.figure('', image_node) - if figwidth == 'image': - if Image: - # PIL doesn't like Unicode paths: - try: - i = Image.open(str(image_node['uri'])) - except (IOError, UnicodeError): - pass - else: - figure_node['width'] = i.size[0] - elif figwidth is not None: - figure_node['width'] = figwidth - if figclass: - figure_node.set_class(figclass) - if content: - node = nodes.Element() # anonymous container for parsing - state.nested_parse(content, content_offset, node) - first_node = node[0] - if isinstance(first_node, nodes.paragraph): - caption = nodes.caption(first_node.rawsource, '', - *first_node.children) - figure_node += caption - elif not (isinstance(first_node, nodes.comment) - and len(first_node) == 0): - error = state_machine.reporter.error( - 'Figure caption must be a paragraph or empty comment.', - nodes.literal_block(block_text, block_text), line=lineno) - return [figure_node, error] - if len(node) > 1: - figure_node += nodes.legend('', *node[1:]) - return [figure_node] - -def figwidth_value(argument): - if argument.lower() == 'image': - return 'image' - else: - return directives.nonnegative_int(argument) - -figure.arguments = (1, 0, 1) -figure.options = {'figwidth': figwidth_value, - 'figclass': directives.class_option} -figure.options.update(image.options) -figure.content = 1 diff --git a/docutils/docutils/parsers/rst/directives/misc.py b/docutils/docutils/parsers/rst/directives/misc.py deleted file mode 100644 index 581c10269..000000000 --- a/docutils/docutils/parsers/rst/directives/misc.py +++ /dev/null @@ -1,231 +0,0 @@ -# Authors: David Goodger, Dethe Elza -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -"""Miscellaneous directives.""" - -__docformat__ = 'reStructuredText' - -import sys -import os.path -import re -from urllib2 import urlopen, URLError -from docutils import io, nodes, statemachine, utils -from docutils.parsers.rst import directives, states -from docutils.transforms import misc - - -def include(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Include a reST file as part of the content of this reST file.""" - source = state_machine.input_lines.source( - lineno - state_machine.input_offset - 1) - source_dir = os.path.dirname(os.path.abspath(source)) - path = ''.join(arguments[0].splitlines()) - if path.find(' ') != -1: - error = state_machine.reporter.error( - '"%s" directive path contains whitespace.' % name, - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - path = os.path.normpath(os.path.join(source_dir, path)) - path = utils.relative_path(None, path) - try: - include_file = io.FileInput( - source_path=path, encoding=state.document.settings.input_encoding) - except IOError, error: - severe = state_machine.reporter.severe( - 'Problems with "%s" directive path:\n%s.' % (name, error), - nodes.literal_block(block_text, block_text), line=lineno) - return [severe] - include_text = include_file.read() - if options.has_key('literal'): - literal_block = nodes.literal_block(include_text, include_text, - source=path) - literal_block.line = 1 - return literal_block - else: - include_lines = statemachine.string2lines(include_text, - convert_whitespace=1) - state_machine.insert_input(include_lines, path) - return [] - -include.arguments = (1, 0, 1) -include.options = {'literal': directives.flag} - -def raw(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """ - Pass through content unchanged - - Content is included in output based on type argument - - Content may be included inline (content section of directive) or - imported from a file or url. - """ - attributes = {'format': arguments[0]} - if content: - if options.has_key('file') or options.has_key('url'): - error = state_machine.reporter.error( - '"%s" directive may not both specify an external file and ' - 'have content.' % name, - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - text = '\n'.join(content) - elif options.has_key('file'): - if options.has_key('url'): - error = state_machine.reporter.error( - 'The "file" and "url" options may not be simultaneously ' - 'specified for the "%s" directive.' % name, - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - source_dir = os.path.dirname( - os.path.abspath(state.document.current_source)) - path = os.path.normpath(os.path.join(source_dir, options['file'])) - path = utils.relative_path(None, path) - try: - raw_file = open(path) - except IOError, error: - severe = state_machine.reporter.severe( - 'Problems with "%s" directive path:\n%s.' % (name, error), - nodes.literal_block(block_text, block_text), line=lineno) - return [severe] - text = raw_file.read() - raw_file.close() - attributes['source'] = path - elif options.has_key('url'): - try: - raw_file = urlopen(options['url']) - except (URLError, IOError, OSError), error: - severe = state_machine.reporter.severe( - 'Problems with "%s" directive URL "%s":\n%s.' - % (name, options['url'], error), - nodes.literal_block(block_text, block_text), line=lineno) - return [severe] - text = raw_file.read() - raw_file.close() - attributes['source'] = options['file'] - else: - error = state_machine.reporter.warning( - 'The "%s" directive requires content; none supplied.' % (name), - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - raw_node = nodes.raw('', text, **attributes) - return [raw_node] - -raw.arguments = (1, 0, 1) -raw.options = {'file': directives.path, - 'url': directives.path} -raw.content = 1 - -def replace(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - 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] - text = '\n'.join(content) - element = nodes.Element(text) - if text: - state.nested_parse(content, content_offset, element) - if len(element) != 1 or not isinstance(element[0], nodes.paragraph): - messages = [] - for node in element: - if isinstance(node, nodes.system_message): - if node.has_key('backrefs'): - del node['backrefs'] - messages.append(node) - error = state_machine.reporter.error( - 'Error in "%s" directive: may contain a single paragraph ' - 'only.' % (name), line=lineno) - messages.append(error) - return messages - else: - return element[0].children - else: - error = state_machine.reporter.error( - 'The "%s" directive is empty; content required.' % (name), - line=lineno) - return [error] - -replace.content = 1 - -def unicode_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - r""" - Convert Unicode character codes (numbers) to characters. Codes may be - decimal numbers, hexadecimal numbers (prefixed by ``0x``, ``x``, ``\x``, - ``U+``, ``u``, or ``\u``; e.g. ``U+262E``), or XML-style numeric character - entities (e.g. ``☮``). Text following ".." is a comment and is - ignored. Spaces are ignored, and any other text remains as-is. - """ - 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] - codes = arguments[0].split('.. ')[0].split() - element = nodes.Element() - for code in codes: - try: - if code.isdigit(): - element += nodes.Text(unichr(int(code))) - else: - match = unicode_pattern.match(code) - if match: - value = match.group(1) or match.group(2) - element += nodes.Text(unichr(int(value, 16))) - else: - element += nodes.Text(code) - except ValueError, err: - error = state_machine.reporter.error( - 'Invalid character code: %s\n%s' % (code, err), - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - return element.children - -unicode_directive.arguments = (1, 0, 1) -unicode_pattern = re.compile( - r'(?:0x|x|\x00x|U\+?|\x00u)([0-9a-f]+)$|&#x([0-9a-f]+);$', re.IGNORECASE) - -def class_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """""" - class_value = nodes.make_id(arguments[0]) - if class_value: - pending = nodes.pending(misc.ClassAttribute, - {'class': class_value, 'directive': name}, - block_text) - state_machine.document.note_pending(pending) - return [pending] - else: - error = state_machine.reporter.error( - 'Invalid class attribute value for "%s" directive: %s' - % (name, arguments[0]), - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - -class_directive.arguments = (1, 0, 0) -class_directive.content = 1 - -def directive_test_function(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if content: - text = '\n'.join(content) - info = state_machine.reporter.info( - 'Directive processed. Type="%s", arguments=%r, options=%r, ' - 'content:' % (name, arguments, options), - nodes.literal_block(text, text), line=lineno) - else: - info = state_machine.reporter.info( - 'Directive processed. Type="%s", arguments=%r, options=%r, ' - 'content: None' % (name, arguments, options), line=lineno) - return [info] - -directive_test_function.arguments = (0, 1, 1) -directive_test_function.options = {'option': directives.unchanged} -directive_test_function.content = 1 diff --git a/docutils/docutils/parsers/rst/directives/parts.py b/docutils/docutils/parsers/rst/directives/parts.py deleted file mode 100644 index 2faaca44b..000000000 --- a/docutils/docutils/parsers/rst/directives/parts.py +++ /dev/null @@ -1,56 +0,0 @@ -# Author: David Goodger, Dmitry Jemerov -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Directives for document parts. -""" - -__docformat__ = 'reStructuredText' - -from docutils import nodes -from docutils.transforms import parts -from docutils.parsers.rst import directives - - -backlinks_values = ('top', 'entry', 'none') - -def backlinks(arg): - value = directives.choice(arg, backlinks_values) - if value == 'none': - return None - else: - return value - -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, - 'class': directives.class_option} - -def sectnum(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Automatic section numbering.""" - pending = nodes.pending(parts.SectNum) - pending.details.update(options) - state_machine.document.note_pending(pending) - return [pending] - -sectnum.options = {'depth': int} diff --git a/docutils/docutils/parsers/rst/directives/references.py b/docutils/docutils/parsers/rst/directives/references.py deleted file mode 100644 index 92966140f..000000000 --- a/docutils/docutils/parsers/rst/directives/references.py +++ /dev/null @@ -1,23 +0,0 @@ -# Author: David Goodger, Dmitry Jemerov -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Directives for references and targets. -""" - -__docformat__ = 'reStructuredText' - -from docutils import nodes -from docutils.transforms import references - - -def target_notes(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Target footnote generation.""" - pending = nodes.pending(references.TargetNotes) - state_machine.document.note_pending(pending) - nodelist = [pending] - return nodelist diff --git a/docutils/docutils/parsers/rst/languages/__init__.py b/docutils/docutils/parsers/rst/languages/__init__.py deleted file mode 100644 index ea4218657..000000000 --- a/docutils/docutils/parsers/rst/languages/__init__.py +++ /dev/null @@ -1,27 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# Internationalization details are documented in -# <http://docutils.sf.net/spec/howto/i18n.html>. - -""" -This package contains modules for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - -_languages = {} - -def get_language(language_code): - if _languages.has_key(language_code): - return _languages[language_code] - try: - module = __import__(language_code, globals(), locals()) - except ImportError: - return None - _languages[language_code] = module - return module diff --git a/docutils/docutils/parsers/rst/languages/af.py b/docutils/docutils/parsers/rst/languages/af.py deleted file mode 100644 index 8ad023ed1..000000000 --- a/docutils/docutils/parsers/rst/languages/af.py +++ /dev/null @@ -1,92 +0,0 @@ -# Author: Jannie Hofmeyr -# Contact: jhsh@sun.ac.za -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Afrikaans-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - 'aandag': 'attention', - 'versigtig': 'caution', - 'gevaar': 'danger', - 'fout': 'error', - 'wenk': 'hint', - 'belangrik': 'important', - 'nota': 'note', - 'tip': 'tip', # hint and tip both have the same translation: wenk - 'waarskuwing': 'warning', - 'vermaning': 'admonition', - 'kantstreep': 'sidebar', - 'onderwerp': 'topic', - 'lynblok': 'line-block', - 'parsed-literal (translation required)': 'parsed-literal', - 'rubriek': 'rubric', - 'epigraaf': 'epigraph', - 'hoogtepunte': 'highlights', - 'pull-quote (translation required)': 'pull-quote', - #'vrae': 'questions', - #'qa': 'questions', - #'faq': 'questions', - 'meta': 'meta', - #'beeldkaart': 'imagemap', - 'beeld': 'image', - 'figuur': 'figure', - 'insluiting': 'include', - 'rou': 'raw', - 'vervang': 'replace', - 'unicode': 'unicode', # should this be translated? unikode - 'klas': 'class', - 'inhoud': 'contents', - 'sectnum': 'sectnum', - 'section-numbering': 'sectnum', - #'voetnote': 'footnotes', - #'aanhalings': 'citations', - 'teikennotas': 'target-notes', - 'restructuredtext-test-directive': 'restructuredtext-test-directive'} -"""Afrikaans name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - 'afkorting': 'abbreviation', - 'ab': 'abbreviation', - 'akroniem': 'acronym', - 'ac': 'acronym', - 'indeks': 'index', - 'i': 'index', - 'voetskrif': 'subscript', - 'sub': 'subscript', - 'boskrif': 'superscript', - 'sup': 'superscript', - 'titelverwysing': 'title-reference', - 'titel': 'title-reference', - 't': 'title-reference', - 'pep-verwysing': 'pep-reference', - 'pep': 'pep-reference', - 'rfc-verwysing': 'rfc-reference', - 'rfc': 'rfc-reference', - 'nadruk': 'emphasis', - 'sterk': 'strong', - 'literal (translation required)': 'literal', - 'benoemde verwysing': 'named-reference', - 'anonieme verwysing': 'anonymous-reference', - 'voetnootverwysing': 'footnote-reference', - 'aanhalingverwysing': 'citation-reference', - 'vervangingsverwysing': 'substitution-reference', - 'teiken': 'target', - 'uri-verwysing': 'uri-reference', - 'uri': 'uri-reference', - 'url': 'uri-reference',} -"""Mapping of Afrikaans role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/de.py b/docutils/docutils/parsers/rst/languages/de.py deleted file mode 100644 index 017a2e851..000000000 --- a/docutils/docutils/parsers/rst/languages/de.py +++ /dev/null @@ -1,83 +0,0 @@ -# -*- coding: iso-8859-1 -*- -# Author: Engelbert Gruber -# Contact: grubert@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -German-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - 'achtung': 'attention', - 'vorsicht': 'caution', - 'gefahr': 'danger', - 'fehler': 'error', - 'hinweis': 'hint', - 'wichtig': 'important', - 'notiz': 'note', - 'tip': 'tip', - 'warnung': 'warning', - 'ermahnung': 'admonition', - 'kasten': 'sidebar', # seitenkasten ? - 'thema': 'topic', - 'line-block': 'line-block', - 'parsed-literal': 'parsed-literal', - 'rubrik': 'rubric', - 'epigraph (translation required)': 'epigraph', - 'highlights (translation required)': 'highlights', - 'pull-quote (translation required)': 'pull-quote', # kasten too ? - #'questions': 'questions', - #'qa': 'questions', - #'faq': 'questions', - 'meta': 'meta', - #'imagemap': 'imagemap', - 'bild': 'image', - 'abbildung': 'figure', - 'raw': 'raw', # unbearbeitet - 'include': 'include', # einfügen, "füge ein" would be more like a command. - # einfügung would be the noun. - 'ersetzung': 'replace', # ersetzen, ersetze - 'unicode': 'unicode', - 'klasse': 'class', # offer class too ? - 'inhalt': 'contents', - 'sectnum': 'sectnum', - 'section-numbering': 'sectnum', - 'target-notes': 'target-notes', - #'footnotes': 'footnotes', - #'citations': 'citations', - 'restructuredtext-test-directive': 'restructuredtext-test-directive'} -"""German name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - 'abbreviation (translation required)': 'abbreviation', - 'acronym (translation required)': 'acronym', - 'index (translation required)': 'index', - 'subscript (translation required)': 'subscript', - 'superscript (translation required)': 'superscript', - 'title-reference (translation required)': 'title-reference', - 'pep-reference (translation required)': 'pep-reference', - 'rfc-reference (translation required)': 'rfc-reference', - 'emphasis (translation required)': 'emphasis', - 'strong (translation required)': 'strong', - 'literal (translation required)': 'literal', - 'named-reference (translation required)': 'named-reference', - 'anonymous-reference (translation required)': 'anonymous-reference', - 'footnote-reference (translation required)': 'footnote-reference', - 'citation-reference (translation required)': 'citation-reference', - 'substitution-reference (translation required)': 'substitution-reference', - 'target (translation required)': 'target', - 'uri-reference (translation required)': 'uri-reference',} -"""Mapping of German role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/en.py b/docutils/docutils/parsers/rst/languages/en.py deleted file mode 100644 index a9b060f82..000000000 --- a/docutils/docutils/parsers/rst/languages/en.py +++ /dev/null @@ -1,94 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -English-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - # language-dependent: fixed - 'attention': 'attention', - 'caution': 'caution', - 'danger': 'danger', - 'error': 'error', - 'hint': 'hint', - 'important': 'important', - 'note': 'note', - 'tip': 'tip', - 'warning': 'warning', - 'admonition': 'admonition', - 'sidebar': 'sidebar', - 'topic': 'topic', - 'line-block': 'line-block', - 'parsed-literal': 'parsed-literal', - 'rubric': 'rubric', - 'epigraph': 'epigraph', - 'highlights': 'highlights', - 'pull-quote': 'pull-quote', - #'questions': 'questions', - #'qa': 'questions', - #'faq': 'questions', - 'meta': 'meta', - #'imagemap': 'imagemap', - 'image': 'image', - 'figure': 'figure', - 'include': 'include', - 'raw': 'raw', - 'replace': 'replace', - 'unicode': 'unicode', - 'class': 'class', - 'contents': 'contents', - 'sectnum': 'sectnum', - 'section-numbering': 'sectnum', - #'footnotes': 'footnotes', - #'citations': 'citations', - 'target-notes': 'target-notes', - 'restructuredtext-test-directive': 'restructuredtext-test-directive'} -"""English name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - # language-dependent: fixed - 'abbreviation': 'abbreviation', - 'ab': 'abbreviation', - 'acronym': 'acronym', - 'ac': 'acronym', - 'index': 'index', - 'i': 'index', - 'subscript': 'subscript', - 'sub': 'subscript', - 'superscript': 'superscript', - 'sup': 'superscript', - 'title-reference': 'title-reference', - 'title': 'title-reference', - 't': 'title-reference', - 'pep-reference': 'pep-reference', - 'pep': 'pep-reference', - 'rfc-reference': 'rfc-reference', - 'rfc': 'rfc-reference', - 'emphasis': 'emphasis', - 'strong': 'strong', - 'literal': 'literal', - 'named-reference': 'named-reference', - 'anonymous-reference': 'anonymous-reference', - 'footnote-reference': 'footnote-reference', - 'citation-reference': 'citation-reference', - 'substitution-reference': 'substitution-reference', - 'target': 'target', - 'uri-reference': 'uri-reference', - 'uri': 'uri-reference', - 'url': 'uri-reference',} -"""Mapping of English role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/es.py b/docutils/docutils/parsers/rst/languages/es.py deleted file mode 100644 index 53bb9ff77..000000000 --- a/docutils/docutils/parsers/rst/languages/es.py +++ /dev/null @@ -1,102 +0,0 @@ -# Author: Marcelo Huerta San Martín -# Contact: mghsm@uol.com.ar -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Spanish-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - u'atenci\u00f3n': 'attention', - u'atencion': 'attention', - u'precauci\u00f3n': 'caution', - u'precaucion': 'caution', - u'peligro': 'danger', - u'error': 'error', - u'sugerencia': 'hint', - u'importante': 'important', - u'nota': 'note', - u'consejo': 'tip', - u'advertencia': 'warning', - u'exhortacion': 'admonition', - u'exhortaci\u00f3n': 'admonition', - u'nota-al-margen': 'sidebar', - u'tema': 'topic', - u'bloque-de-lineas': 'line-block', - u'bloque-de-l\u00edneas': 'line-block', - u'literal-evaluado': 'parsed-literal', - u'firma': 'rubric', - u'ep\u00edgrafe': 'epigraph', - u'epigrafe': 'epigraph', - u'destacado': 'highlights', - u'cita-destacada': 'pull-quote', - #'questions': 'questions', - #'qa': 'questions', - #'faq': 'questions', - u'meta': 'meta', - #'imagemap': 'imagemap', - u'imagen': 'image', - u'figura': 'figure', - u'incluir': 'include', - u'raw': 'raw', - u'reemplazar': 'replace', - u'unicode': 'unicode', - u'clase': 'class', - u'contenido': 'contents', - u'numseccion': 'sectnum', - u'numsecci\u00f3n': 'sectnum', - u'numeracion-seccion': 'sectnum', - u'numeraci\u00f3n-secci\u00f3n': 'sectnum', - u'notas-destino': 'target-notes', - #'footnotes': 'footnotes', - #'citations': 'citations', - u'restructuredtext-test-directive': 'restructuredtext-test-directive'} -"""Spanish name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - u'abreviatura': 'abbreviation', - u'ab': 'abbreviation', - u'acronimo': 'acronym', - u'acronimo': 'acronym', - u'ac': 'acronym', - u'indice': 'index', - u'i': 'index', - u'subscript (translation required)': 'subscript', - u'superscript (translation required)': 'superscript', - u'referencia-titulo': 'title-reference', - u'titulo': 'title-reference', - u't': 'title-reference', - u'referencia-pep': 'pep-reference', - u'pep': 'pep-reference', - u'referencia-rfc': 'rfc-reference', - u'rfc': 'rfc-reference', - u'enfasis': 'emphasis', - u'\u00e9nfasis': 'emphasis', - u'destacado': 'strong', - u'literal': 'literal', - u'referencia-con-nombre': 'named-reference', - u'referencia-anonima': 'anonymous-reference', - u'referencia-an\u00f3nima': 'anonymous-reference', - u'referencia-nota-al-pie': 'footnote-reference', - u'referencia-cita': 'citation-reference', - u'referencia-sustitucion': 'substitution-reference', - u'referencia-sustituci\u00f3n': 'substitution-reference', - u'destino': 'target', - u'referencia-uri': 'uri-reference', - u'uri': 'uri-reference', - u'url': 'uri-reference', - } -"""Mapping of Spanish role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/fr.py b/docutils/docutils/parsers/rst/languages/fr.py deleted file mode 100644 index ba0bcb014..000000000 --- a/docutils/docutils/parsers/rst/languages/fr.py +++ /dev/null @@ -1,89 +0,0 @@ -# Authors: David Goodger; William Dode -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -French-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - u'attention': 'attention', - u'pr\u00E9caution': 'caution', - u'danger': 'danger', - u'erreur': 'error', - u'conseil': 'hint', - u'important': 'important', - u'note': 'note', - u'astuce': 'tip', - u'avertissement': 'warning', - u'admonition': 'admonition', - u'encadr\u00E9': 'sidebar', - u'sujet': 'topic', - u'bloc-textuel': 'line-block', - u'bloc-interpr\u00E9t\u00E9': 'parsed-literal', - u'code-interpr\u00E9t\u00E9': 'parsed-literal', - u'intertitre': 'rubric', - u'exergue': 'epigraph', - u'\u00E9pigraphe': 'epigraph', - u'chapeau': 'highlights', - u'accroche': 'pull-quote', - #u'questions': 'questions', - #u'qr': 'questions', - #u'faq': 'questions', - u'm\u00E9ta': 'meta', - #u'imagemap (translation required)': 'imagemap', - u'image': 'image', - u'figure': 'figure', - u'inclure': 'include', - u'brut': 'raw', - u'remplacer': 'replace', - u'remplace': 'replace', - u'unicode': 'unicode', - u'classe': 'class', - u'sommaire': 'contents', - u'table-des-mati\u00E8res': 'contents', - u'sectnum': 'sectnum', - u'section-num\u00E9rot\u00E9e': 'sectnum', - u'liens': 'target-notes', - #u'footnotes (translation required)': 'footnotes', - #u'citations (translation required)': 'citations', - } -"""French name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - u'abr\u00E9viation': 'abbreviation', - u'acronyme': 'acronym', - u'sigle': 'acronym', - u'index': 'index', - u'indice': 'subscript', - u'ind': 'subscript', - u'exposant': 'superscript', - u'exp': 'superscript', - u'titre-r\u00E9f\u00E9rence': 'title-reference', - u'titre': 'title-reference', - u'pep-r\u00E9f\u00E9rence': 'pep-reference', - u'rfc-r\u00E9f\u00E9rence': 'rfc-reference', - u'emphase': 'emphasis', - u'fort': 'strong', - u'litt\u00E9ral': 'literal', - u'nomm\u00E9e-r\u00E9f\u00E9rence': 'named-reference', - u'anonyme-r\u00E9f\u00E9rence': 'anonymous-reference', - u'note-r\u00E9f\u00E9rence': 'footnote-reference', - u'citation-r\u00E9f\u00E9rence': 'citation-reference', - u'substitution-r\u00E9f\u00E9rence': 'substitution-reference', - u'lien': 'target', - u'uri-r\u00E9f\u00E9rence': 'uri-reference',} -"""Mapping of French role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/it.py b/docutils/docutils/parsers/rst/languages/it.py deleted file mode 100644 index 911c69a66..000000000 --- a/docutils/docutils/parsers/rst/languages/it.py +++ /dev/null @@ -1,81 +0,0 @@ -# Author: Nicola Larosa -# Contact: docutils@tekNico.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Italian-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - 'attenzione': 'attention', - 'cautela': 'caution', - 'pericolo': 'danger', - 'errore': 'error', - 'suggerimento': 'hint', - 'importante': 'important', - 'nota': 'note', - 'consiglio': 'tip', - 'avvertenza': 'warning', - 'admonition (translation required)': 'admonition', - 'sidebar (translation required)': 'sidebar', - 'argomento': 'topic', - 'blocco di linee': 'line-block', - 'parsed-literal': 'parsed-literal', - 'rubric (translation required)': 'rubric', - 'epigraph (translation required)': 'epigraph', - 'highlights (translation required)': 'highlights', - 'pull-quote (translation required)': 'pull-quote', - #'questions': 'questions', - #'qa': 'questions', - #'faq': 'questions', - 'meta': 'meta', - #'imagemap': 'imagemap', - 'immagine': 'image', - 'figura': 'figure', - 'includi': 'include', - 'grezzo': 'raw', - 'sostituisci': 'replace', - 'unicode': 'unicode', - 'class (translation required)': 'class', - 'indice': 'contents', - 'seznum': 'sectnum', - 'section-numbering': 'sectnum', - 'target-notes': 'target-notes', - #'footnotes': 'footnotes', - #'citations': 'citations', - 'restructuredtext-test-directive': 'restructuredtext-test-directive'} -"""Italian name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - 'abbreviation (translation required)': 'abbreviation', - 'acronym (translation required)': 'acronym', - 'index (translation required)': 'index', - 'subscript (translation required)': 'subscript', - 'superscript (translation required)': 'superscript', - 'title-reference (translation required)': 'title-reference', - 'pep-reference (translation required)': 'pep-reference', - 'rfc-reference (translation required)': 'rfc-reference', - 'emphasis (translation required)': 'emphasis', - 'strong (translation required)': 'strong', - 'literal (translation required)': 'literal', - 'named-reference (translation required)': 'named-reference', - 'anonymous-reference (translation required)': 'anonymous-reference', - 'footnote-reference (translation required)': 'footnote-reference', - 'citation-reference (translation required)': 'citation-reference', - 'substitution-reference (translation required)': 'substitution-reference', - 'target (translation required)': 'target', - 'uri-reference (translation required)': 'uri-reference',} -"""Mapping of Italian role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/ru.py b/docutils/docutils/parsers/rst/languages/ru.py deleted file mode 100644 index 366f4505f..000000000 --- a/docutils/docutils/parsers/rst/languages/ru.py +++ /dev/null @@ -1,93 +0,0 @@ -# Author: Roman Suzi -# Contact: rnd@onego.ru -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Russian-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - -directives = { - u'\u0431\u043b\u043e\u043a-\u0441\u0442\u0440\u043e\u043a': u'line-block', - u'meta': u'meta', - u'\u043e\u0431\u0440\u0430\u0431\u043e\u0442\u0430\u043d\u043d\u044b\u0439-\u043b\u0438\u0442\u0435\u0440\u0430\u043b': - u'parsed-literal', - u'\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u043d\u0430\u044f-\u0446\u0438\u0442\u0430\u0442\u0430': - u'pull-quote', - u'\u0441\u044b\u0440\u043e\u0439': u'raw', - u'\u0437\u0430\u043c\u0435\u043d\u0430': u'replace', - u'\u0442\u0435\u0441\u0442\u043e\u0432\u0430\u044f-\u0434\u0438\u0440\u0435\u043a\u0442\u0438\u0432\u0430-restructuredtext': - u'restructuredtext-test-directive', - u'\u0446\u0435\u043b\u0435\u0432\u044b\u0435-\u0441\u043d\u043e\u0441\u043a\u0438': - u'target-notes', - u'unicode': u'unicode', - u'\u0431\u043e\u043a\u043e\u0432\u0430\u044f-\u043f\u043e\u043b\u043e\u0441\u0430': - u'sidebar', - u'\u0432\u0430\u0436\u043d\u043e': u'important', - u'\u0432\u043a\u043b\u044e\u0447\u0430\u0442\u044c': u'include', - u'\u0432\u043d\u0438\u043c\u0430\u043d\u0438\u0435': u'attention', - u'\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u0438\u0435': u'highlights', - u'\u0437\u0430\u043c\u0435\u0447\u0430\u043d\u0438\u0435': u'admonition', - u'\u0438\u0437\u043e\u0431\u0440\u0430\u0436\u0435\u043d\u0438\u0435': - u'image', - u'\u043a\u043b\u0430\u0441\u0441': u'class', - u'\u043d\u043e\u043c\u0435\u0440-\u0440\u0430\u0437\u0434\u0435\u043b\u0430': - u'sectnum', - u'\u043d\u0443\u043c\u0435\u0440\u0430\u0446\u0438\u044f-\u0440\u0430\u0437' - u'\u0434\u0435\u043b\u043e\u0432': u'sectnum', - u'\u043e\u043f\u0430\u0441\u043d\u043e': u'danger', - u'\u043e\u0441\u0442\u043e\u0440\u043e\u0436\u043d\u043e': u'caution', - u'\u043e\u0448\u0438\u0431\u043a\u0430': u'error', - u'\u043f\u043e\u0434\u0441\u043a\u0430\u0437\u043a\u0430': u'tip', - u'\u043f\u0440\u0435\u0434\u0443\u043f\u0440\u0435\u0436\u0434\u0435\u043d' - u'\u0438\u0435': u'warning', - u'\u043f\u0440\u0438\u043c\u0435\u0447\u0430\u043d\u0438\u0435': u'note', - u'\u0440\u0438\u0441\u0443\u043d\u043e\u043a': u'figure', - u'\u0440\u0443\u0431\u0440\u0438\u043a\u0430': u'rubric', - u'\u0441\u043e\u0432\u0435\u0442': u'hint', - u'\u0441\u043e\u0434\u0435\u0440\u0436\u0430\u043d\u0438\u0435': u'contents', - u'\u0442\u0435\u043c\u0430': u'topic', - u'\u044d\u043f\u0438\u0433\u0440\u0430\u0444': u'epigraph'} -"""Russian name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - u'\u0430\u043a\u0440\u043e\u043d\u0438\u043c': 'acronym', - u'\u0430\u043d\u043e\u043d\u0438\u043c\u043d\u0430\u044f-\u0441\u0441\u044b\u043b\u043a\u0430': - 'anonymous-reference', - u'\u0431\u0443\u043a\u0432\u0430\u043b\u044c\u043d\u043e': 'literal', - u'\u0432\u0435\u0440\u0445\u043d\u0438\u0439-\u0438\u043d\u0434\u0435\u043a\u0441': - 'superscript', - u'\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u0438\u0435': 'emphasis', - u'\u0438\u043c\u0435\u043d\u043e\u0432\u0430\u043d\u043d\u0430\u044f-\u0441\u0441\u044b\u043b\u043a\u0430': - 'named-reference', - u'\u0438\u043d\u0434\u0435\u043a\u0441': 'index', - u'\u043d\u0438\u0436\u043d\u0438\u0439-\u0438\u043d\u0434\u0435\u043a\u0441': - 'subscript', - u'\u0441\u0438\u043b\u044c\u043d\u043e\u0435-\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u0438\u0435': - 'strong', - u'\u0441\u043e\u043a\u0440\u0430\u0449\u0435\u043d\u0438\u0435': - 'abbreviation', - u'\u0441\u0441\u044b\u043b\u043a\u0430-\u0437\u0430\u043c\u0435\u043d\u0430': - 'substitution-reference', - u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-pep': 'pep-reference', - u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-rfc': 'rfc-reference', - u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-uri': 'uri-reference', - u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-\u0437\u0430\u0433\u043b\u0430\u0432\u0438\u0435': - 'title-reference', - u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-\u0441\u043d\u043e\u0441\u043a\u0443': - 'footnote-reference', - u'\u0446\u0438\u0442\u0430\u0442\u043d\u0430\u044f-\u0441\u0441\u044b\u043b\u043a\u0430': - 'citation-reference', - u'\u0446\u0435\u043b\u044c': 'target'} -"""Mapping of Russian role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/sk.py b/docutils/docutils/parsers/rst/languages/sk.py deleted file mode 100644 index caf3ed5c4..000000000 --- a/docutils/docutils/parsers/rst/languages/sk.py +++ /dev/null @@ -1,81 +0,0 @@ -# Author: Miroslav Vasko -# Contact: zemiak@zoznam.sk -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Slovak-language mappings for language-dependent features of -reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - u'pozor': 'attention', - u'opatrne': 'caution', - u'nebezpe\xe8enstvo': 'danger', - u'chyba': 'error', - u'rada': 'hint', - u'd\xf4le\x9eit\xe9': 'important', - u'pozn\xe1mka': 'note', - u'tip': 'tip', - u'varovanie': 'warning', - u'admonition (translation required)': 'admonition', - u'sidebar (translation required)': 'sidebar', - u't\xe9ma': 'topic', - u'blok-riadkov': 'line-block', - u'parsed-literal': 'parsed-literal', - u'rubric (translation required)': 'rubric', - u'epigraph (translation required)': 'epigraph', - u'highlights (translation required)': 'highlights', - u'pull-quote (translation required)': 'pull-quote', - #u'questions': 'questions', - #u'qa': 'questions', - #u'faq': 'questions', - u'meta': 'meta', - #u'imagemap': 'imagemap', - u'obr\xe1zok': 'image', - u'tvar': 'figure', - u'vlo\x9ei\x9d': 'include', - u'raw': 'raw', - u'nahradi\x9d': 'replace', - u'unicode': 'unicode', - u'class (translation required)': 'class', - u'obsah': 'contents', - u'\xe8as\x9d': 'sectnum', - u'\xe8as\x9d-\xe8\xedslovanie': 'sectnum', - u'cie\xbeov\xe9-pozn\xe1mky': 'target-notes', - #u'footnotes': 'footnotes', - #u'citations': 'citations', - } -"""Slovak name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - u'abbreviation (translation required)': 'abbreviation', - u'acronym (translation required)': 'acronym', - u'index (translation required)': 'index', - u'subscript (translation required)': 'subscript', - u'superscript (translation required)': 'superscript', - u'title-reference (translation required)': 'title-reference', - u'pep-reference (translation required)': 'pep-reference', - u'rfc-reference (translation required)': 'rfc-reference', - u'emphasis (translation required)': 'emphasis', - u'strong (translation required)': 'strong', - u'literal (translation required)': 'literal', - u'named-reference (translation required)': 'named-reference', - u'anonymous-reference (translation required)': 'anonymous-reference', - u'footnote-reference (translation required)': 'footnote-reference', - u'citation-reference (translation required)': 'citation-reference', - u'substitution-reference (translation required)': 'substitution-reference', - u'target (translation required)': 'target', - u'uri-reference (translation required)': 'uri-reference',} -"""Mapping of Slovak role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/languages/sv.py b/docutils/docutils/parsers/rst/languages/sv.py deleted file mode 100644 index 04d105f90..000000000 --- a/docutils/docutils/parsers/rst/languages/sv.py +++ /dev/null @@ -1,80 +0,0 @@ -# Author: Adam Chodorowski -# Contact: chodorowski@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -# New language mappings are welcome. Before doing a new translation, please -# read <http://docutils.sf.net/spec/howto/i18n.html>. Two files must be -# translated for each language: one in docutils/languages, the other in -# docutils/parsers/rst/languages. - -""" -Swedish language mappings for language-dependent features of reStructuredText. -""" - -__docformat__ = 'reStructuredText' - - -directives = { - u'observera': 'attention', - u'caution (translation required)': 'caution', - u'fara': 'danger', - u'fel': 'error', - u'v\u00e4gledning': 'hint', - u'viktigt': 'important', - u'notera': 'note', - u'tips': 'tip', - u'varning': 'warning', - u'admonition (translation required)': 'admonition', - u'sidebar (translation required)': 'sidebar', - u'\u00e4mne': 'topic', - u'line-block (translation required)': 'line-block', - u'parsed-literal (translation required)': 'parsed-literal', - u'mellanrubrik': 'rubric', - u'epigraph (translation required)': 'epigraph', - u'highlights (translation required)': 'highlights', - u'pull-quote (translation required)': 'pull-quote', - # u'fr\u00e5gor': 'questions', - # NOTE: A bit long, but recommended by http://www.nada.kth.se/dataterm/: - # u'fr\u00e5gor-och-svar': 'questions', - # u'vanliga-fr\u00e5gor': 'questions', - u'meta': 'meta', - # u'bildkarta': 'imagemap', # FIXME: Translation might be too literal. - u'bild': 'image', - u'figur': 'figure', - u'inkludera': 'include', - u'r\u00e5': 'raw', # FIXME: Translation might be too literal. - u'ers\u00e4tt': 'replace', - u'unicode': 'unicode', - u'class (translation required)': 'class', - u'inneh\u00e5ll': 'contents', - u'sektionsnumrering': 'sectnum', - u'target-notes (translation required)': 'target-notes', - # u'fotnoter': 'footnotes', - # u'citeringar': 'citations', - } -"""Swedish name to registered (in directives/__init__.py) directive name -mapping.""" - -roles = { - u'abbreviation (translation required)': 'abbreviation', - u'acronym (translation required)': 'acronym', - u'index (translation required)': 'index', - u'subscript (translation required)': 'subscript', - u'superscript (translation required)': 'superscript', - u'title-reference (translation required)': 'title-reference', - u'pep-reference (translation required)': 'pep-reference', - u'rfc-reference (translation required)': 'rfc-reference', - u'emphasis (translation required)': 'emphasis', - u'strong (translation required)': 'strong', - u'literal (translation required)': 'literal', - u'named-reference (translation required)': 'named-reference', - u'anonymous-reference (translation required)': 'anonymous-reference', - u'footnote-reference (translation required)': 'footnote-reference', - u'citation-reference (translation required)': 'citation-reference', - u'substitution-reference (translation required)': 'substitution-reference', - u'target (translation required)': 'target', - u'uri-reference (translation required)': 'uri-reference',} -"""Mapping of Swedish role names to canonical role names for interpreted text. -""" diff --git a/docutils/docutils/parsers/rst/states.py b/docutils/docutils/parsers/rst/states.py deleted file mode 100644 index c8d04325f..000000000 --- a/docutils/docutils/parsers/rst/states.py +++ /dev/null @@ -1,2913 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This is the ``docutils.parsers.restructuredtext.states`` module, the core of -the reStructuredText parser. It defines the following: - -:Classes: - - `RSTStateMachine`: reStructuredText parser's entry point. - - `NestedStateMachine`: recursive StateMachine. - - `RSTState`: reStructuredText State superclass. - - `Inliner`: For parsing inline markup. - - `Body`: Generic classifier of the first line of a block. - - `SpecializedBody`: Superclass for compound element members. - - `BulletList`: Second and subsequent bullet_list list_items - - `DefinitionList`: Second+ definition_list_items. - - `EnumeratedList`: Second+ enumerated_list list_items. - - `FieldList`: Second+ fields. - - `OptionList`: Second+ option_list_items. - - `RFC2822List`: Second+ RFC2822-style fields. - - `ExtensionOptions`: Parses directive option fields. - - `Explicit`: Second+ explicit markup constructs. - - `SubstitutionDef`: For embedded directives in substitution definitions. - - `Text`: Classifier of second line of a text block. - - `SpecializedText`: Superclass for continuation lines of Text-variants. - - `Definition`: Second line of potential definition_list_item. - - `Line`: Second line of overlined section title or transition marker. - - `Struct`: An auxiliary collection class. - -:Exception classes: - - `MarkupError` - - `ParserError` - - `MarkupMismatch` - -:Functions: - - `escape2null()`: Return a string, escape-backslashes converted to nulls. - - `unescape()`: Return a string, nulls removed or restored to backslashes. - -:Attributes: - - `state_classes`: set of State classes used with `RSTStateMachine`. - -Parser Overview -=============== - -The reStructuredText parser is implemented as a recursive state machine, -examining its input one line at a time. To understand how the parser works, -please first become familiar with the `docutils.statemachine` module. In the -description below, references are made to classes defined in this module; -please see the individual classes for details. - -Parsing proceeds as follows: - -1. The state machine examines each line of input, checking each of the - transition patterns of the state `Body`, in order, looking for a match. - The implicit transitions (blank lines and indentation) are checked before - any others. The 'text' transition is a catch-all (matches anything). - -2. The method associated with the matched transition pattern is called. - - A. Some transition methods are self-contained, appending elements to the - document tree (`Body.doctest` parses a doctest block). The parser's - current line index is advanced to the end of the element, and parsing - continues with step 1. - - B. Other transition methods trigger the creation of a nested state machine, - whose job is to parse a compound construct ('indent' does a block quote, - 'bullet' does a bullet list, 'overline' does a section [first checking - for a valid section header], etc.). - - - In the case of lists and explicit markup, a one-off state machine is - created and run to parse contents of the first item. - - - A new state machine is created and its initial state is set to the - appropriate specialized state (`BulletList` in the case of the - 'bullet' transition; see `SpecializedBody` for more detail). This - state machine is run to parse the compound element (or series of - explicit markup elements), and returns as soon as a non-member element - is encountered. For example, the `BulletList` state machine ends as - soon as it encounters an element which is not a list item of that - bullet list. The optional omission of inter-element blank lines is - enabled by this nested state machine. - - - The current line index is advanced to the end of the elements parsed, - and parsing continues with step 1. - - C. The result of the 'text' transition depends on the next line of text. - The current state is changed to `Text`, under which the second line is - examined. If the second line is: - - - Indented: The element is a definition list item, and parsing proceeds - similarly to step 2.B, using the `DefinitionList` state. - - - A line of uniform punctuation characters: The element is a section - header; again, parsing proceeds as in step 2.B, and `Body` is still - used. - - - Anything else: The element is a paragraph, which is examined for - inline markup and appended to the parent element. Processing - continues with step 1. -""" - -__docformat__ = 'reStructuredText' - - -import sys -import re -import roman -from types import TupleType -from docutils import nodes, statemachine, utils, urischemes -from docutils import ApplicationError, DataError -from docutils.statemachine import StateMachineWS, StateWS -from docutils.nodes import fully_normalize_name as normalize_name -from docutils.parsers.rst import directives, languages, tableparser -from docutils.parsers.rst.languages import en as _fallback_language_module - - -class MarkupError(DataError): pass -class UnknownInterpretedRoleError(DataError): pass -class InterpretedRoleNotImplementedError(DataError): pass -class ParserError(ApplicationError): pass -class MarkupMismatch(Exception): pass - - -class Struct: - - """Stores data attributes for dotted-attribute access.""" - - def __init__(self, **keywordargs): - self.__dict__.update(keywordargs) - - -class RSTStateMachine(StateMachineWS): - - """ - reStructuredText's master StateMachine. - - The entry point to reStructuredText parsing is the `run()` method. - """ - - def run(self, input_lines, document, input_offset=0, match_titles=1, - inliner=None): - """ - Parse `input_lines` and return a `docutils.nodes.document` instance. - - Extend `StateMachineWS.run()`: set up parse-global data, run the - StateMachine, and return the resulting - document. - """ - self.language = languages.get_language( - document.settings.language_code) - self.match_titles = match_titles - if inliner is None: - inliner = Inliner() - inliner.init_customizations(document.settings) - self.memo = Struct(document=document, - reporter=document.reporter, - language=self.language, - title_styles=[], - section_level=0, - section_bubble_up_kludge=0, - inliner=inliner) - self.document = document - self.attach_observer(document.note_source) - self.reporter = self.memo.reporter - self.node = document - results = StateMachineWS.run(self, input_lines, input_offset, - input_source=document['source']) - assert results == [], 'RSTStateMachine.run() results should be empty!' - self.check_document() - self.node = self.memo = None # remove unneeded references - - def check_document(self): - """Check for illegal structure: empty document.""" - if len(self.document) == 0: - error = self.reporter.error( - 'Document empty; must have contents.', line=0) - self.document += error - - -class NestedStateMachine(StateMachineWS): - - """ - StateMachine run from within other StateMachine runs, to parse nested - document structures. - """ - - def run(self, input_lines, input_offset, memo, node, match_titles=1): - """ - Parse `input_lines` and populate a `docutils.nodes.document` instance. - - Extend `StateMachineWS.run()`: set up document-wide data. - """ - self.match_titles = match_titles - self.memo = memo - self.document = memo.document - self.attach_observer(self.document.note_source) - self.reporter = memo.reporter - self.node = node - results = StateMachineWS.run(self, input_lines, input_offset) - assert results == [], ('NestedStateMachine.run() results should be ' - 'empty!') - return results - - -class RSTState(StateWS): - - """ - reStructuredText State superclass. - - Contains methods used by all State subclasses. - """ - - nested_sm = NestedStateMachine - - def __init__(self, state_machine, debug=0): - self.nested_sm_kwargs = {'state_classes': state_classes, - 'initial_state': 'Body'} - StateWS.__init__(self, state_machine, debug) - - def runtime_init(self): - StateWS.runtime_init(self) - memo = self.state_machine.memo - self.memo = memo - self.reporter = memo.reporter - self.inliner = memo.inliner - self.document = memo.document - self.parent = self.state_machine.node - - def goto_line(self, abs_line_offset): - """ - Jump to input line `abs_line_offset`, ignoring jumps past the end. - """ - try: - self.state_machine.goto_line(abs_line_offset) - except EOFError: - pass - - def no_match(self, context, transitions): - """ - Override `StateWS.no_match` to generate a system message. - - This code should never be run. - """ - self.reporter.severe( - 'Internal error: no transition pattern match. State: "%s"; ' - 'transitions: %s; context: %s; current line: %r.' - % (self.__class__.__name__, transitions, context, - self.state_machine.line), - line=self.state_machine.abs_line_number()) - return context, None, [] - - def bof(self, context): - """Called at beginning of file.""" - return [], [] - - def nested_parse(self, block, input_offset, node, match_titles=0, - state_machine_class=None, state_machine_kwargs=None): - """ - Create a new StateMachine rooted at `node` and run it over the input - `block`. - """ - if state_machine_class is None: - state_machine_class = self.nested_sm - if state_machine_kwargs is None: - state_machine_kwargs = self.nested_sm_kwargs - block_length = len(block) - state_machine = state_machine_class(debug=self.debug, - **state_machine_kwargs) - state_machine.run(block, input_offset, memo=self.memo, - node=node, match_titles=match_titles) - state_machine.unlink() - new_offset = state_machine.abs_line_offset() - # Adjustment for block if modified in nested parse: - self.state_machine.next_line(len(block) - block_length) - return new_offset - - def nested_list_parse(self, block, input_offset, node, initial_state, - blank_finish, - blank_finish_state=None, - extra_settings={}, - match_titles=0, - state_machine_class=None, - state_machine_kwargs=None): - """ - Create a new StateMachine rooted at `node` and run it over the input - `block`. Also keep track of optional intermdediate blank lines and the - required final one. - """ - if state_machine_class is None: - state_machine_class = self.nested_sm - if state_machine_kwargs is None: - state_machine_kwargs = self.nested_sm_kwargs.copy() - state_machine_kwargs['initial_state'] = initial_state - state_machine = state_machine_class(debug=self.debug, - **state_machine_kwargs) - if blank_finish_state is None: - blank_finish_state = initial_state - state_machine.states[blank_finish_state].blank_finish = blank_finish - for key, value in extra_settings.items(): - setattr(state_machine.states[initial_state], key, value) - state_machine.run(block, input_offset, memo=self.memo, - node=node, match_titles=match_titles) - blank_finish = state_machine.states[blank_finish_state].blank_finish - state_machine.unlink() - return state_machine.abs_line_offset(), blank_finish - - def section(self, title, source, style, lineno, messages): - """Check for a valid subsection and create one if it checks out.""" - if self.check_subsection(source, style, lineno): - self.new_subsection(title, lineno, messages) - - def check_subsection(self, source, style, lineno): - """ - Check for a valid subsection header. Return 1 (true) or None (false). - - When a new section is reached that isn't a subsection of the current - section, back up the line count (use ``previous_line(-x)``), then - ``raise EOFError``. The current StateMachine will finish, then the - calling StateMachine can re-examine the title. This will work its way - back up the calling chain until the correct section level isreached. - - @@@ Alternative: Evaluate the title, store the title info & level, and - back up the chain until that level is reached. Store in memo? Or - return in results? - - :Exception: `EOFError` when a sibling or supersection encountered. - """ - memo = self.memo - title_styles = memo.title_styles - mylevel = memo.section_level - try: # check for existing title style - level = title_styles.index(style) + 1 - except ValueError: # new title style - if len(title_styles) == memo.section_level: # new subsection - title_styles.append(style) - return 1 - else: # not at lowest level - self.parent += self.title_inconsistent(source, lineno) - return None - if level <= mylevel: # sibling or supersection - memo.section_level = level # bubble up to parent section - if len(style) == 2: - memo.section_bubble_up_kludge = 1 - # back up 2 lines for underline title, 3 for overline title - self.state_machine.previous_line(len(style) + 1) - raise EOFError # let parent section re-evaluate - if level == mylevel + 1: # immediate subsection - return 1 - else: # invalid subsection - self.parent += self.title_inconsistent(source, lineno) - return None - - def title_inconsistent(self, sourcetext, lineno): - error = self.reporter.severe( - 'Title level inconsistent:', nodes.literal_block('', sourcetext), - line=lineno) - return error - - def new_subsection(self, title, lineno, messages): - """Append new subsection to document tree. On return, check level.""" - memo = self.memo - mylevel = memo.section_level - memo.section_level += 1 - section_node = nodes.section() - self.parent += section_node - textnodes, title_messages = self.inline_text(title, lineno) - titlenode = nodes.title(title, '', *textnodes) - name = normalize_name(titlenode.astext()) - section_node['name'] = name - section_node += titlenode - section_node += messages - section_node += title_messages - self.document.note_implicit_target(section_node, section_node) - offset = self.state_machine.line_offset + 1 - absoffset = self.state_machine.abs_line_offset() + 1 - newabsoffset = self.nested_parse( - self.state_machine.input_lines[offset:], input_offset=absoffset, - node=section_node, match_titles=1) - self.goto_line(newabsoffset) - self.check_section(section_node) - if memo.section_level <= mylevel: # can't handle next section? - raise EOFError # bubble up to supersection - # reset section_level; next pass will detect it properly - memo.section_level = mylevel - - def check_section(self, section): - """ - Check for illegal structure: empty section, misplaced transitions. - """ - lineno = section.line - if len(section) <= 1: - error = self.reporter.error( - 'Section empty; must have contents.', line=lineno) - section += error - return - if not isinstance(section[0], nodes.title): # shouldn't ever happen - error = self.reporter.error( - 'First element of section must be a title.', line=lineno) - section.insert(0, error) - if isinstance(section[1], nodes.transition): - error = self.reporter.error( - 'Section may not begin with a transition.', - line=section[1].line) - section.insert(1, error) - if len(section) > 2 and isinstance(section[-1], nodes.transition): - error = self.reporter.error( - 'Section may not end with a transition.', - line=section[-1].line) - section += error - - def paragraph(self, lines, lineno): - """ - Return a list (paragraph & messages) & a boolean: literal_block next? - """ - data = '\n'.join(lines).rstrip() - if data[-2:] == '::': - if len(data) == 2: - return [], 1 - elif data[-3] in ' \n': - text = data[:-3].rstrip() - else: - text = data[:-1] - literalnext = 1 - else: - text = data - literalnext = 0 - textnodes, messages = self.inline_text(text, lineno) - p = nodes.paragraph(data, '', *textnodes) - p.line = lineno - return [p] + messages, literalnext - - def inline_text(self, text, lineno): - """ - Return 2 lists: nodes (text and inline elements), and system_messages. - """ - return self.inliner.parse(text, lineno, self.memo, self.parent) - - def unindent_warning(self, node_name): - return self.reporter.warning( - '%s ends without a blank line; unexpected unindent.' % node_name, - line=(self.state_machine.abs_line_number() + 1)) - - -def build_regexp(definition, compile=1): - """ - Build, compile and return a regular expression based on `definition`. - - :Parameter: `definition`: a 4-tuple (group name, prefix, suffix, parts), - where "parts" is a list of regular expressions and/or regular - expression definitions to be joined into an or-group. - """ - name, prefix, suffix, parts = definition - part_strings = [] - for part in parts: - if type(part) is TupleType: - part_strings.append(build_regexp(part, None)) - else: - part_strings.append(part) - or_group = '|'.join(part_strings) - regexp = '%(prefix)s(?P<%(name)s>%(or_group)s)%(suffix)s' % locals() - if compile: - return re.compile(regexp, re.UNICODE) - else: - return regexp - - -class Inliner: - - """ - Parse inline markup; call the `parse()` method. - """ - - _interpreted_roles = { - # Values of ``None`` mean "not implemented yet": - 'title-reference': 'generic_interpreted_role', - 'abbreviation': 'generic_interpreted_role', - 'acronym': 'generic_interpreted_role', - 'index': None, - 'subscript': 'generic_interpreted_role', - 'superscript': 'generic_interpreted_role', - 'emphasis': 'generic_interpreted_role', - 'strong': 'generic_interpreted_role', - 'literal': 'generic_interpreted_role', - 'named-reference': None, - 'anonymous-reference': None, - 'uri-reference': None, - 'pep-reference': 'pep_reference_role', - 'rfc-reference': 'rfc_reference_role', - 'footnote-reference': None, - 'citation-reference': None, - 'substitution-reference': None, - 'target': None, - 'restructuredtext-unimplemented-role': None} - """Mapping of canonical interpreted text role name to method name. - Initializes a name to bound-method mapping in `__init__`.""" - - default_interpreted_role = 'title-reference' - """The role to use when no explicit role is given. - Override in subclasses.""" - - generic_roles = {'abbreviation': nodes.abbreviation, - 'acronym': nodes.acronym, - 'emphasis': nodes.emphasis, - 'literal': nodes.literal, - 'strong': nodes.strong, - 'subscript': nodes.subscript, - 'superscript': nodes.superscript, - 'title-reference': nodes.title_reference,} - """Mapping of canonical interpreted text role name to node class. - Used by the `generic_interpreted_role` method for simple, straightforward - roles (simple wrapping; no extra processing).""" - - def __init__(self, roles=None): - """ - `roles` is a mapping of canonical role name to role function or bound - method, which enables additional interpreted text roles. - """ - - self.implicit_dispatch = [(self.patterns.uri, self.standalone_uri),] - """List of (pattern, bound method) tuples, used by - `self.implicit_inline`.""" - - self.interpreted_roles = {} - """Mapping of canonical role name to role function or bound method. - Items removed from this mapping will be disabled.""" - - for canonical, method in self._interpreted_roles.items(): - if method: - self.interpreted_roles[canonical] = getattr(self, method) - else: - self.interpreted_roles[canonical] = None - self.interpreted_roles.update(roles or {}) - - def init_customizations(self, settings): - """Setting-based customizations; run when parsing begins.""" - if settings.pep_references: - self.implicit_dispatch.append((self.patterns.pep, - self.pep_reference)) - if settings.rfc_references: - self.implicit_dispatch.append((self.patterns.rfc, - self.rfc_reference)) - - def parse(self, text, lineno, memo, parent): - """ - Return 2 lists: nodes (text and inline elements), and system_messages. - - Using `self.patterns.initial`, a pattern which matches start-strings - (emphasis, strong, interpreted, phrase reference, literal, - substitution reference, and inline target) and complete constructs - (simple reference, footnote reference), search for a candidate. When - one is found, check for validity (e.g., not a quoted '*' character). - If valid, search for the corresponding end string if applicable, and - check it for validity. If not found or invalid, generate a warning - and ignore the start-string. Implicit inline markup (e.g. standalone - URIs) is found last. - """ - self.reporter = memo.reporter - self.document = memo.document - self.language = memo.language - self.parent = parent - pattern_search = self.patterns.initial.search - dispatch = self.dispatch - remaining = escape2null(text) - processed = [] - unprocessed = [] - messages = [] - while remaining: - match = pattern_search(remaining) - if match: - groups = match.groupdict() - method = dispatch[groups['start'] or groups['backquote'] - or groups['refend'] or groups['fnend']] - before, inlines, remaining, sysmessages = method(self, match, - lineno) - unprocessed.append(before) - messages += sysmessages - if inlines: - processed += self.implicit_inline(''.join(unprocessed), - lineno) - processed += inlines - unprocessed = [] - else: - break - remaining = ''.join(unprocessed) + remaining - if remaining: - processed += self.implicit_inline(remaining, lineno) - return processed, messages - - openers = '\'"([{<' - closers = '\'")]}>' - start_string_prefix = (r'((?<=^)|(?<=[-/: \n%s]))' % re.escape(openers)) - end_string_suffix = (r'((?=$)|(?=[-/:.,;!? \n\x00%s]))' - % re.escape(closers)) - non_whitespace_before = r'(?<![ \n])' - non_whitespace_escape_before = r'(?<![ \n\x00])' - non_whitespace_after = r'(?![ \n])' - # Alphanumerics with isolated internal [-._] chars (i.e. not 2 together): - simplename = r'(?:(?!_)\w)+(?:[-._](?:(?!_)\w)+)*' - # Valid URI characters (see RFC 2396 & RFC 2732): - uric = r"""[-_.!~*'()[\];/:@&=+$,%a-zA-Z0-9]""" - # Last URI character; same as uric but no punctuation: - urilast = r"""[_~/a-zA-Z0-9]""" - emailc = r"""[-_!~*'{|}/#?^`&=+$%a-zA-Z0-9]""" - email_pattern = r""" - %(emailc)s+(?:\.%(emailc)s+)* # name - @ # at - %(emailc)s+(?:\.%(emailc)s*)* # host - %(urilast)s # final URI char - """ - parts = ('initial_inline', start_string_prefix, '', - [('start', '', non_whitespace_after, # simple start-strings - [r'\*\*', # strong - r'\*(?!\*)', # emphasis but not strong - r'``', # literal - r'_`', # inline internal target - r'\|(?!\|)'] # substitution reference - ), - ('whole', '', end_string_suffix, # whole constructs - [# reference name & end-string - r'(?P<refname>%s)(?P<refend>__?)' % simplename, - ('footnotelabel', r'\[', r'(?P<fnend>\]_)', - [r'[0-9]+', # manually numbered - r'\#(%s)?' % simplename, # auto-numbered (w/ label?) - r'\*', # auto-symbol - r'(?P<citationlabel>%s)' % simplename] # citation reference - ) - ] - ), - ('backquote', # interpreted text or phrase reference - '(?P<role>(:%s:)?)' % simplename, # optional role - non_whitespace_after, - ['`(?!`)'] # but not literal - ) - ] - ) - patterns = Struct( - initial=build_regexp(parts), - emphasis=re.compile(non_whitespace_escape_before - + r'(\*)' + end_string_suffix), - strong=re.compile(non_whitespace_escape_before - + r'(\*\*)' + end_string_suffix), - interpreted_or_phrase_ref=re.compile( - r""" - %(non_whitespace_escape_before)s - ( - ` - (?P<suffix> - (?P<role>:%(simplename)s:)? - (?P<refend>__?)? - ) - ) - %(end_string_suffix)s - """ % locals(), re.VERBOSE | re.UNICODE), - embedded_uri=re.compile( - r""" - ( - [ \n]+ # spaces or beginning of line - < # open bracket - %(non_whitespace_after)s - ([^<>\0]+) # anything but angle brackets & nulls - %(non_whitespace_before)s - > # close bracket w/o whitespace before - ) - $ # end of string - """ % locals(), re.VERBOSE), - literal=re.compile(non_whitespace_before + '(``)' - + end_string_suffix), - target=re.compile(non_whitespace_escape_before - + r'(`)' + end_string_suffix), - substitution_ref=re.compile(non_whitespace_escape_before - + r'(\|_{0,2})' - + end_string_suffix), - email=re.compile(email_pattern % locals() + '$', re.VERBOSE), - uri=re.compile( - (r""" - %(start_string_prefix)s - (?P<whole> - (?P<absolute> # absolute URI - (?P<scheme> # scheme (http, ftp, mailto) - [a-zA-Z][a-zA-Z0-9.+-]* - ) - : - ( - ( # either: - (//?)? # hierarchical URI - %(uric)s* # URI characters - %(urilast)s # final URI char - ) - ( # optional query - \?%(uric)s* - %(urilast)s - )? - ( # optional fragment - \#%(uric)s* - %(urilast)s - )? - ) - ) - | # *OR* - (?P<email> # email address - """ + email_pattern + r""" - ) - ) - %(end_string_suffix)s - """) % locals(), re.VERBOSE), - pep=re.compile( - r""" - %(start_string_prefix)s - ( - (pep-(?P<pepnum1>\d+)(.txt)?) # reference to source file - | - (PEP\s+(?P<pepnum2>\d+)) # reference by name - ) - %(end_string_suffix)s""" % locals(), re.VERBOSE), - rfc=re.compile( - r""" - %(start_string_prefix)s - (RFC(-|\s+)?(?P<rfcnum>\d+)) - %(end_string_suffix)s""" % locals(), re.VERBOSE)) - - def quoted_start(self, match): - """Return 1 if inline markup start-string is 'quoted', 0 if not.""" - string = match.string - start = match.start() - end = match.end() - if start == 0: # start-string at beginning of text - return 0 - prestart = string[start - 1] - try: - poststart = string[end] - if self.openers.index(prestart) \ - == self.closers.index(poststart): # quoted - return 1 - except IndexError: # start-string at end of text - return 1 - except ValueError: # not quoted - pass - return 0 - - def inline_obj(self, match, lineno, end_pattern, nodeclass, - restore_backslashes=0): - string = match.string - matchstart = match.start('start') - matchend = match.end('start') - if self.quoted_start(match): - return (string[:matchend], [], string[matchend:], [], '') - endmatch = end_pattern.search(string[matchend:]) - if endmatch and endmatch.start(1): # 1 or more chars - text = unescape(endmatch.string[:endmatch.start(1)], - restore_backslashes) - textend = matchend + endmatch.end(1) - rawsource = unescape(string[matchstart:textend], 1) - return (string[:matchstart], [nodeclass(rawsource, text)], - string[textend:], [], endmatch.group(1)) - msg = self.reporter.warning( - 'Inline %s start-string without end-string.' - % nodeclass.__name__, line=lineno) - text = unescape(string[matchstart:matchend], 1) - rawsource = unescape(string[matchstart:matchend], 1) - prb = self.problematic(text, rawsource, msg) - return string[:matchstart], [prb], string[matchend:], [msg], '' - - def problematic(self, text, rawsource, message): - msgid = self.document.set_id(message, self.parent) - problematic = nodes.problematic(rawsource, text, refid=msgid) - prbid = self.document.set_id(problematic) - message.add_backref(prbid) - return problematic - - def emphasis(self, match, lineno): - before, inlines, remaining, sysmessages, endstring = self.inline_obj( - match, lineno, self.patterns.emphasis, nodes.emphasis) - return before, inlines, remaining, sysmessages - - def strong(self, match, lineno): - before, inlines, remaining, sysmessages, endstring = self.inline_obj( - match, lineno, self.patterns.strong, nodes.strong) - return before, inlines, remaining, sysmessages - - def interpreted_or_phrase_ref(self, match, lineno): - end_pattern = self.patterns.interpreted_or_phrase_ref - string = match.string - matchstart = match.start('backquote') - matchend = match.end('backquote') - rolestart = match.start('role') - role = match.group('role') - position = '' - if role: - role = role[1:-1] - position = 'prefix' - elif self.quoted_start(match): - return (string[:matchend], [], string[matchend:], []) - endmatch = end_pattern.search(string[matchend:]) - if endmatch and endmatch.start(1): # 1 or more chars - textend = matchend + endmatch.end() - if endmatch.group('role'): - if role: - msg = self.reporter.warning( - 'Multiple roles in interpreted text (both ' - 'prefix and suffix present; only one allowed).', - line=lineno) - text = unescape(string[rolestart:textend], 1) - prb = self.problematic(text, text, msg) - return string[:rolestart], [prb], string[textend:], [msg] - role = endmatch.group('suffix')[1:-1] - position = 'suffix' - escaped = endmatch.string[:endmatch.start(1)] - text = unescape(escaped, 0) - rawsource = unescape(string[matchstart:textend], 1) - if rawsource[-1:] == '_': - if role: - msg = self.reporter.warning( - 'Mismatch: both interpreted text role %s and ' - 'reference suffix.' % position, line=lineno) - text = unescape(string[rolestart:textend], 1) - prb = self.problematic(text, text, msg) - return string[:rolestart], [prb], string[textend:], [msg] - return self.phrase_ref(string[:matchstart], string[textend:], - rawsource, escaped, text) - else: - try: - return self.interpreted( - string[:rolestart], string[textend:], - rawsource, text, role, lineno) - except UnknownInterpretedRoleError, detail: - msg = self.reporter.error( - 'Unknown interpreted text role "%s".' % role, - line=lineno) - text = unescape(string[rolestart:textend], 1) - prb = self.problematic(text, text, msg) - return (string[:rolestart], [prb], string[textend:], - detail.args[0] + [msg]) - except InterpretedRoleNotImplementedError, detail: - msg = self.reporter.error( - 'Interpreted text role "%s" not implemented.' % role, - line=lineno) - text = unescape(string[rolestart:textend], 1) - prb = self.problematic(text, text, msg) - return (string[:rolestart], [prb], string[textend:], - detail.args[0] + [msg]) - msg = self.reporter.warning( - 'Inline interpreted text or phrase reference start-string ' - 'without end-string.', line=lineno) - text = unescape(string[matchstart:matchend], 1) - prb = self.problematic(text, text, msg) - return string[:matchstart], [prb], string[matchend:], [msg] - - def phrase_ref(self, before, after, rawsource, escaped, text): - match = self.patterns.embedded_uri.search(escaped) - if match: - text = unescape(escaped[:match.start(0)]) - uri_text = match.group(2) - uri = ''.join(uri_text.split()) - uri = self.adjust_uri(uri) - if uri: - target = nodes.target(match.group(1), refuri=uri) - else: - raise ApplicationError('problem with URI: %r' % uri_text) - else: - target = None - refname = normalize_name(text) - reference = nodes.reference(rawsource, text) - node_list = [reference] - if rawsource[-2:] == '__': - if target: - reference['refuri'] = uri - else: - reference['anonymous'] = 1 - self.document.note_anonymous_ref(reference) - else: - if target: - reference['refuri'] = uri - target['name'] = refname - self.document.note_external_target(target) - self.document.note_explicit_target(target, self.parent) - node_list.append(target) - else: - reference['refname'] = refname - self.document.note_refname(reference) - return before, node_list, after, [] - - def adjust_uri(self, uri): - match = self.patterns.email.match(uri) - if match: - return 'mailto:' + uri - else: - return uri - - def interpreted(self, before, after, rawsource, text, role, lineno): - role_function, canonical, messages = self.get_role_function(role, - lineno) - if role_function: - nodelist, messages2 = role_function(canonical, rawsource, text, - lineno) - messages.extend(messages2) - return before, nodelist, after, messages - else: - raise InterpretedRoleNotImplementedError(messages) - - def get_role_function(self, role, lineno): - messages = [] - msg_text = [] - if role: - name = role.lower() - else: - name = self.default_interpreted_role - canonical = None - try: - canonical = self.language.roles[name] - except AttributeError, error: - msg_text.append('Problem retrieving role entry from language ' - 'module %r: %s.' % (self.language, error)) - except KeyError: - msg_text.append('No role entry for "%s" in module "%s".' - % (name, self.language.__name__)) - if not canonical: - try: - canonical = _fallback_language_module.roles[name] - msg_text.append('Using English fallback for role "%s".' - % name) - except KeyError: - msg_text.append('Trying "%s" as canonical role name.' - % name) - # Should be an English name, but just in case: - canonical = name - if msg_text: - message = self.reporter.info('\n'.join(msg_text), line=lineno) - messages.append(message) - try: - return self.interpreted_roles[canonical], canonical, messages - except KeyError: - raise UnknownInterpretedRoleError(messages) - - def literal(self, match, lineno): - before, inlines, remaining, sysmessages, endstring = self.inline_obj( - match, lineno, self.patterns.literal, nodes.literal, - restore_backslashes=1) - return before, inlines, remaining, sysmessages - - def inline_internal_target(self, match, lineno): - before, inlines, remaining, sysmessages, endstring = self.inline_obj( - match, lineno, self.patterns.target, nodes.target) - if inlines and isinstance(inlines[0], nodes.target): - assert len(inlines) == 1 - target = inlines[0] - name = normalize_name(target.astext()) - target['name'] = name - self.document.note_explicit_target(target, self.parent) - return before, inlines, remaining, sysmessages - - def substitution_reference(self, match, lineno): - before, inlines, remaining, sysmessages, endstring = self.inline_obj( - match, lineno, self.patterns.substitution_ref, - nodes.substitution_reference) - if len(inlines) == 1: - subref_node = inlines[0] - if isinstance(subref_node, nodes.substitution_reference): - subref_text = subref_node.astext() - self.document.note_substitution_ref(subref_node, subref_text) - if endstring[-1:] == '_': - reference_node = nodes.reference( - '|%s%s' % (subref_text, endstring), '') - if endstring[-2:] == '__': - reference_node['anonymous'] = 1 - self.document.note_anonymous_ref( - reference_node) - else: - reference_node['refname'] = normalize_name(subref_text) - self.document.note_refname(reference_node) - reference_node += subref_node - inlines = [reference_node] - return before, inlines, remaining, sysmessages - - def footnote_reference(self, match, lineno): - """ - Handles `nodes.footnote_reference` and `nodes.citation_reference` - elements. - """ - label = match.group('footnotelabel') - refname = normalize_name(label) - string = match.string - before = string[:match.start('whole')] - remaining = string[match.end('whole'):] - if match.group('citationlabel'): - refnode = nodes.citation_reference('[%s]_' % label, - refname=refname) - refnode += nodes.Text(label) - self.document.note_citation_ref(refnode) - else: - refnode = nodes.footnote_reference('[%s]_' % label) - if refname[0] == '#': - refname = refname[1:] - refnode['auto'] = 1 - self.document.note_autofootnote_ref(refnode) - elif refname == '*': - refname = '' - refnode['auto'] = '*' - self.document.note_symbol_footnote_ref( - refnode) - else: - refnode += nodes.Text(label) - if refname: - refnode['refname'] = refname - self.document.note_footnote_ref(refnode) - if self.document.settings.trim_footnote_reference_space: - before = before.rstrip() - return (before, [refnode], remaining, []) - - def reference(self, match, lineno, anonymous=None): - referencename = match.group('refname') - refname = normalize_name(referencename) - referencenode = nodes.reference(referencename + match.group('refend'), - referencename) - if anonymous: - referencenode['anonymous'] = 1 - self.document.note_anonymous_ref(referencenode) - else: - referencenode['refname'] = refname - self.document.note_refname(referencenode) - string = match.string - matchstart = match.start('whole') - matchend = match.end('whole') - return (string[:matchstart], [referencenode], string[matchend:], []) - - def anonymous_reference(self, match, lineno): - return self.reference(match, lineno, anonymous=1) - - def standalone_uri(self, match, lineno): - if not match.group('scheme') or urischemes.schemes.has_key( - match.group('scheme').lower()): - if match.group('email'): - addscheme = 'mailto:' - else: - addscheme = '' - text = match.group('whole') - unescaped = unescape(text, 0) - return [nodes.reference(unescape(text, 1), unescaped, - refuri=addscheme + unescaped)] - else: # not a valid scheme - raise MarkupMismatch - - pep_url_local = 'pep-%04d.html' - pep_url_absolute = 'http://www.python.org/peps/pep-%04d.html' - pep_url = pep_url_absolute - - def pep_reference(self, match, lineno): - text = match.group(0) - if text.startswith('pep-'): - pepnum = int(match.group('pepnum1')) - elif text.startswith('PEP'): - pepnum = int(match.group('pepnum2')) - else: - raise MarkupMismatch - ref = self.pep_url % pepnum - unescaped = unescape(text, 0) - return [nodes.reference(unescape(text, 1), unescaped, refuri=ref)] - - rfc_url = 'http://www.faqs.org/rfcs/rfc%d.html' - - def rfc_reference(self, match, lineno): - text = match.group(0) - if text.startswith('RFC'): - rfcnum = int(match.group('rfcnum')) - ref = self.rfc_url % rfcnum - else: - raise MarkupMismatch - unescaped = unescape(text, 0) - return [nodes.reference(unescape(text, 1), unescaped, refuri=ref)] - - def implicit_inline(self, text, lineno): - """ - Check each of the patterns in `self.implicit_dispatch` for a match, - and dispatch to the stored method for the pattern. Recursively check - the text before and after the match. Return a list of `nodes.Text` - and inline element nodes. - """ - if not text: - return [] - for pattern, method in self.implicit_dispatch: - match = pattern.search(text) - if match: - try: - # Must recurse on strings before *and* after the match; - # there may be multiple patterns. - return (self.implicit_inline(text[:match.start()], lineno) - + method(match, lineno) + - self.implicit_inline(text[match.end():], lineno)) - except MarkupMismatch: - pass - return [nodes.Text(unescape(text), rawsource=unescape(text, 1))] - - dispatch = {'*': emphasis, - '**': strong, - '`': interpreted_or_phrase_ref, - '``': literal, - '_`': inline_internal_target, - ']_': footnote_reference, - '|': substitution_reference, - '_': reference, - '__': anonymous_reference} - - def generic_interpreted_role(self, role, rawtext, text, lineno): - try: - role_class = self.generic_roles[role] - except KeyError: - msg = self.reporter.error('Unknown interpreted text role: "%s".' - % role, line=lineno) - prb = self.problematic(text, text, msg) - return [prb], [msg] - return [role_class(rawtext, text)], [] - - def pep_reference_role(self, role, rawtext, text, lineno): - try: - pepnum = int(text) - if pepnum < 0 or pepnum > 9999: - raise ValueError - except ValueError: - msg = self.reporter.error( - 'PEP number must be a number from 0 to 9999; "%s" is invalid.' - % text, line=lineno) - prb = self.problematic(text, text, msg) - return [prb], [msg] - ref = self.pep_url % pepnum - return [nodes.reference(rawtext, 'PEP ' + text, refuri=ref)], [] - - def rfc_reference_role(self, role, rawtext, text, lineno): - try: - rfcnum = int(text) - if rfcnum <= 0: - raise ValueError - except ValueError: - msg = self.reporter.error( - 'RFC number must be a number greater than or equal to 1; ' - '"%s" is invalid.' % text, line=lineno) - prb = self.problematic(text, text, msg) - return [prb], [msg] - ref = self.rfc_url % rfcnum - return [nodes.reference(rawtext, 'RFC ' + text, refuri=ref)], [] - - -class Body(RSTState): - - """ - Generic classifier of the first line of a block. - """ - - enum = Struct() - """Enumerated list parsing information.""" - - enum.formatinfo = { - 'parens': Struct(prefix='(', suffix=')', start=1, end=-1), - 'rparen': Struct(prefix='', suffix=')', start=0, end=-1), - 'period': Struct(prefix='', suffix='.', start=0, end=-1)} - enum.formats = enum.formatinfo.keys() - enum.sequences = ['arabic', 'loweralpha', 'upperalpha', - 'lowerroman', 'upperroman'] # ORDERED! - enum.sequencepats = {'arabic': '[0-9]+', - 'loweralpha': '[a-z]', - 'upperalpha': '[A-Z]', - 'lowerroman': '[ivxlcdm]+', - 'upperroman': '[IVXLCDM]+',} - enum.converters = {'arabic': int, - 'loweralpha': - lambda s, zero=(ord('a')-1): ord(s) - zero, - 'upperalpha': - lambda s, zero=(ord('A')-1): ord(s) - zero, - 'lowerroman': - lambda s: roman.fromRoman(s.upper()), - 'upperroman': roman.fromRoman} - - enum.sequenceregexps = {} - for sequence in enum.sequences: - enum.sequenceregexps[sequence] = re.compile( - enum.sequencepats[sequence] + '$') - - grid_table_top_pat = re.compile(r'\+-[-+]+-\+ *$') - """Matches the top (& bottom) of a full table).""" - - simple_table_top_pat = re.compile('=+( +=+)+ *$') - """Matches the top of a simple table.""" - - simple_table_border_pat = re.compile('=+[ =]*$') - """Matches the bottom & header bottom of a simple table.""" - - pats = {} - """Fragments of patterns used by transitions.""" - - pats['nonalphanum7bit'] = '[!-/:-@[-`{-~]' - pats['alpha'] = '[a-zA-Z]' - pats['alphanum'] = '[a-zA-Z0-9]' - pats['alphanumplus'] = '[a-zA-Z0-9_-]' - pats['enum'] = ('(%(arabic)s|%(loweralpha)s|%(upperalpha)s|%(lowerroman)s' - '|%(upperroman)s)' % enum.sequencepats) - pats['optname'] = '%(alphanum)s%(alphanumplus)s*' % pats - # @@@ Loosen up the pattern? Allow Unicode? - pats['optarg'] = '%(alpha)s%(alphanumplus)s*' % pats - pats['option'] = r'(--?|\+|/)%(optname)s([ =]%(optarg)s)?' % pats - - for format in enum.formats: - pats[format] = '(?P<%s>%s%s%s)' % ( - format, re.escape(enum.formatinfo[format].prefix), - pats['enum'], re.escape(enum.formatinfo[format].suffix)) - - patterns = { - 'bullet': r'[-+*]( +|$)', - 'enumerator': r'(%(parens)s|%(rparen)s|%(period)s)( +|$)' % pats, - 'field_marker': r':[^: ]([^:]*[^: ])?:( +|$)', - 'option_marker': r'%(option)s(, %(option)s)*( +| ?$)' % pats, - 'doctest': r'>>>( +|$)', - 'grid_table_top': grid_table_top_pat, - 'simple_table_top': simple_table_top_pat, - 'explicit_markup': r'\.\.( +|$)', - 'anonymous': r'__( +|$)', - 'line': r'(%(nonalphanum7bit)s)\1* *$' % pats, - 'text': r''} - initial_transitions = ( - 'bullet', - 'enumerator', - 'field_marker', - 'option_marker', - 'doctest', - 'grid_table_top', - 'simple_table_top', - 'explicit_markup', - 'anonymous', - 'line', - 'text') - - def indent(self, match, context, next_state): - """Block quote.""" - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_indented() - blockquote, messages = self.block_quote(indented, line_offset) - self.parent += blockquote - self.parent += messages - if not blank_finish: - self.parent += self.unindent_warning('Block quote') - return context, next_state, [] - - def block_quote(self, indented, line_offset): - blockquote_lines, attribution_lines, attribution_offset = \ - self.check_attribution(indented, line_offset) - blockquote = nodes.block_quote() - self.nested_parse(blockquote_lines, line_offset, blockquote) - messages = [] - if attribution_lines: - attribution, messages = self.parse_attribution(attribution_lines, - attribution_offset) - blockquote += attribution - return blockquote, messages - - attribution_pattern = re.compile(r'--(?![-\n]) *(?=[^ \n])') - - def check_attribution(self, indented, line_offset): - """ - Check for an attribution in the last contiguous block of `indented`. - - * First line after last blank line must begin with "--" (etc.). - * Every line after that must have consistent indentation. - - Return a 3-tuple: (block quote lines, attribution lines, - attribution offset). - """ - blank = None - nonblank_seen = None - indent = 0 - for i in range(len(indented) - 1, 0, -1): # don't check first line - this_line_blank = not indented[i].strip() - if nonblank_seen and this_line_blank: - match = self.attribution_pattern.match(indented[i + 1]) - if match: - blank = i - break - elif not this_line_blank: - nonblank_seen = 1 - if blank and len(indented) - blank > 2: # multi-line attribution - indent = (len(indented[blank + 2]) - - len(indented[blank + 2].lstrip())) - for j in range(blank + 3, len(indented)): - if indent != (len(indented[j]) - - len(indented[j].lstrip())): # bad shape - blank = None - break - if blank: - a_lines = indented[blank + 1:] - a_lines.strip_indent(match.end(), end=1) - a_lines.strip_indent(indent, start=1) - return (indented[:blank], a_lines, line_offset + blank + 1) - else: - return (indented, None, None) - - def parse_attribution(self, indented, line_offset): - text = '\n'.join(indented).rstrip() - lineno = self.state_machine.abs_line_number() + line_offset - textnodes, messages = self.inline_text(text, lineno) - node = nodes.attribution(text, '', *textnodes) - node.line = lineno - return node, messages - - def bullet(self, match, context, next_state): - """Bullet list item.""" - bulletlist = nodes.bullet_list() - self.parent += bulletlist - bulletlist['bullet'] = match.string[0] - i, blank_finish = self.list_item(match.end()) - bulletlist += i - offset = self.state_machine.line_offset + 1 # next line - newline_offset, blank_finish = self.nested_list_parse( - self.state_machine.input_lines[offset:], - input_offset=self.state_machine.abs_line_offset() + 1, - node=bulletlist, initial_state='BulletList', - blank_finish=blank_finish) - self.goto_line(newline_offset) - if not blank_finish: - self.parent += self.unindent_warning('Bullet list') - return [], next_state, [] - - def list_item(self, indent): - indented, line_offset, blank_finish = \ - self.state_machine.get_known_indented(indent) - listitem = nodes.list_item('\n'.join(indented)) - if indented: - self.nested_parse(indented, input_offset=line_offset, - node=listitem) - return listitem, blank_finish - - def enumerator(self, match, context, next_state): - """Enumerated List Item""" - format, sequence, text, ordinal = self.parse_enumerator(match) - if not self.is_enumerated_list_item(ordinal, sequence, format): - raise statemachine.TransitionCorrection('text') - if ordinal != 1: - msg = self.reporter.info( - 'Enumerated list start value not ordinal-1: "%s" (ordinal %s)' - % (text, ordinal), line=self.state_machine.abs_line_number()) - self.parent += msg - enumlist = nodes.enumerated_list() - self.parent += enumlist - enumlist['enumtype'] = sequence - if ordinal != 1: - enumlist['start'] = ordinal - enumlist['prefix'] = self.enum.formatinfo[format].prefix - enumlist['suffix'] = self.enum.formatinfo[format].suffix - listitem, blank_finish = self.list_item(match.end()) - enumlist += listitem - offset = self.state_machine.line_offset + 1 # next line - newline_offset, blank_finish = self.nested_list_parse( - self.state_machine.input_lines[offset:], - input_offset=self.state_machine.abs_line_offset() + 1, - node=enumlist, initial_state='EnumeratedList', - blank_finish=blank_finish, - extra_settings={'lastordinal': ordinal, 'format': format}) - self.goto_line(newline_offset) - if not blank_finish: - self.parent += self.unindent_warning('Enumerated list') - return [], next_state, [] - - def parse_enumerator(self, match, expected_sequence=None): - """ - Analyze an enumerator and return the results. - - :Return: - - the enumerator format ('period', 'parens', or 'rparen'), - - the sequence used ('arabic', 'loweralpha', 'upperroman', etc.), - - the text of the enumerator, stripped of formatting, and - - the ordinal value of the enumerator ('a' -> 1, 'ii' -> 2, etc.; - ``None`` is returned for invalid enumerator text). - - The enumerator format has already been determined by the regular - expression match. If `expected_sequence` is given, that sequence is - tried first. If not, we check for Roman numeral 1. This way, - single-character Roman numerals (which are also alphabetical) can be - matched. If no sequence has been matched, all sequences are checked in - order. - """ - groupdict = match.groupdict() - sequence = '' - for format in self.enum.formats: - if groupdict[format]: # was this the format matched? - break # yes; keep `format` - else: # shouldn't happen - raise ParserError('enumerator format not matched') - text = groupdict[format][self.enum.formatinfo[format].start - :self.enum.formatinfo[format].end] - if expected_sequence: - try: - if self.enum.sequenceregexps[expected_sequence].match(text): - sequence = expected_sequence - except KeyError: # shouldn't happen - raise ParserError('unknown enumerator sequence: %s' - % sequence) - elif text == 'i': - sequence = 'lowerroman' - elif text == 'I': - sequence = 'upperroman' - if not sequence: - for sequence in self.enum.sequences: - if self.enum.sequenceregexps[sequence].match(text): - break - else: # shouldn't happen - raise ParserError('enumerator sequence not matched') - try: - ordinal = self.enum.converters[sequence](text) - except roman.InvalidRomanNumeralError: - ordinal = None - return format, sequence, text, ordinal - - def is_enumerated_list_item(self, ordinal, sequence, format): - """ - Check validity based on the ordinal value and the second line. - - Return true iff the ordinal is valid and the second line is blank, - indented, or starts with the next enumerator. - """ - if ordinal is None: - return None - try: - next_line = self.state_machine.next_line() - except EOFError: # end of input lines - self.state_machine.previous_line() - return 1 - else: - self.state_machine.previous_line() - if not next_line[:1].strip(): # blank or indented - return 1 - next_enumerator = self.make_enumerator(ordinal + 1, sequence, format) - try: - if next_line.startswith(next_enumerator): - return 1 - except TypeError: - pass - return None - - def make_enumerator(self, ordinal, sequence, format): - """ - Construct and return an enumerated list item marker. - - Return ``None`` for invalid (out of range) ordinals. - """ - if sequence == 'arabic': - enumerator = str(ordinal) - else: - if sequence.endswith('alpha'): - if ordinal > 26: - return None - enumerator = chr(ordinal + ord('a') - 1) - elif sequence.endswith('roman'): - try: - enumerator = roman.toRoman(ordinal) - except roman.RomanError: - return None - else: # shouldn't happen - raise ParserError('unknown enumerator sequence: "%s"' - % sequence) - if sequence.startswith('lower'): - enumerator = enumerator.lower() - elif sequence.startswith('upper'): - enumerator = enumerator.upper() - else: # shouldn't happen - raise ParserError('unknown enumerator sequence: "%s"' - % sequence) - formatinfo = self.enum.formatinfo[format] - return formatinfo.prefix + enumerator + formatinfo.suffix + ' ' - - def field_marker(self, match, context, next_state): - """Field list item.""" - fieldlist = nodes.field_list() - self.parent += fieldlist - field, blank_finish = self.field(match) - fieldlist += field - offset = self.state_machine.line_offset + 1 # next line - newline_offset, blank_finish = self.nested_list_parse( - self.state_machine.input_lines[offset:], - input_offset=self.state_machine.abs_line_offset() + 1, - node=fieldlist, initial_state='FieldList', - blank_finish=blank_finish) - self.goto_line(newline_offset) - if not blank_finish: - self.parent += self.unindent_warning('Field list') - return [], next_state, [] - - def field(self, match): - name = self.parse_field_marker(match) - lineno = self.state_machine.abs_line_number() - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - fieldnode = nodes.field() - fieldnode.line = lineno - fieldnode += nodes.field_name(name, name) - fieldbody = nodes.field_body('\n'.join(indented)) - fieldnode += fieldbody - if indented: - self.parse_field_body(indented, line_offset, fieldbody) - return fieldnode, blank_finish - - def parse_field_marker(self, match): - """Extract & return field name from a field marker match.""" - field = match.string[1:] # strip off leading ':' - field = field[:field.find(':')] # strip off trailing ':' etc. - return field - - def parse_field_body(self, indented, offset, node): - self.nested_parse(indented, input_offset=offset, node=node) - - def option_marker(self, match, context, next_state): - """Option list item.""" - optionlist = nodes.option_list() - try: - listitem, blank_finish = self.option_list_item(match) - except MarkupError, (message, lineno): - # This shouldn't happen; pattern won't match. - msg = self.reporter.error( - 'Invalid option list marker: %s' % message, line=lineno) - self.parent += msg - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - blockquote, messages = self.block_quote(indented, line_offset) - self.parent += blockquote - self.parent += messages - if not blank_finish: - self.parent += self.unindent_warning('Option list') - return [], next_state, [] - self.parent += optionlist - optionlist += listitem - offset = self.state_machine.line_offset + 1 # next line - newline_offset, blank_finish = self.nested_list_parse( - self.state_machine.input_lines[offset:], - input_offset=self.state_machine.abs_line_offset() + 1, - node=optionlist, initial_state='OptionList', - blank_finish=blank_finish) - self.goto_line(newline_offset) - if not blank_finish: - self.parent += self.unindent_warning('Option list') - return [], next_state, [] - - def option_list_item(self, match): - offset = self.state_machine.abs_line_offset() - options = self.parse_option_marker(match) - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - if not indented: # not an option list item - self.goto_line(offset) - raise statemachine.TransitionCorrection('text') - option_group = nodes.option_group('', *options) - description = nodes.description('\n'.join(indented)) - option_list_item = nodes.option_list_item('', option_group, - description) - if indented: - self.nested_parse(indented, input_offset=line_offset, - node=description) - return option_list_item, blank_finish - - def parse_option_marker(self, match): - """ - Return a list of `node.option` and `node.option_argument` objects, - parsed from an option marker match. - - :Exception: `MarkupError` for invalid option markers. - """ - optlist = [] - optionstrings = match.group().rstrip().split(', ') - for optionstring in optionstrings: - tokens = optionstring.split() - delimiter = ' ' - firstopt = tokens[0].split('=') - if len(firstopt) > 1: - tokens[:1] = firstopt - delimiter = '=' - if 0 < len(tokens) <= 2: - option = nodes.option(optionstring) - option += nodes.option_string(tokens[0], tokens[0]) - if len(tokens) > 1: - option += nodes.option_argument(tokens[1], tokens[1], - delimiter=delimiter) - optlist.append(option) - else: - raise MarkupError( - 'wrong numer of option tokens (=%s), should be 1 or 2: ' - '"%s"' % (len(tokens), optionstring), - self.state_machine.abs_line_number() + 1) - return optlist - - def doctest(self, match, context, next_state): - data = '\n'.join(self.state_machine.get_text_block()) - self.parent += nodes.doctest_block(data, data) - return [], next_state, [] - - def grid_table_top(self, match, context, next_state): - """Top border of a full table.""" - return self.table_top(match, context, next_state, - self.isolate_grid_table, - tableparser.GridTableParser) - - def simple_table_top(self, match, context, next_state): - """Top border of a simple table.""" - return self.table_top(match, context, next_state, - self.isolate_simple_table, - tableparser.SimpleTableParser) - - def table_top(self, match, context, next_state, - isolate_function, parser_class): - """Top border of a generic table.""" - nodelist, blank_finish = self.table(isolate_function, parser_class) - self.parent += nodelist - if not blank_finish: - msg = self.reporter.warning( - 'Blank line required after table.', - line=self.state_machine.abs_line_number() + 1) - self.parent += msg - return [], next_state, [] - - def table(self, isolate_function, parser_class): - """Parse a table.""" - block, messages, blank_finish = isolate_function() - if block: - try: - parser = parser_class() - tabledata = parser.parse(block) - tableline = (self.state_machine.abs_line_number() - len(block) - + 1) - table = self.build_table(tabledata, tableline) - nodelist = [table] + messages - except tableparser.TableMarkupError, detail: - nodelist = self.malformed_table(block, str(detail)) + messages - else: - nodelist = messages - return nodelist, blank_finish - - def isolate_grid_table(self): - messages = [] - blank_finish = 1 - try: - block = self.state_machine.get_text_block(flush_left=1) - except statemachine.UnexpectedIndentationError, instance: - block, source, lineno = instance.args - messages.append(self.reporter.error('Unexpected indentation.', - source=source, line=lineno)) - blank_finish = 0 - block.disconnect() - width = len(block[0].strip()) - for i in range(len(block)): - block[i] = block[i].strip() - if block[i][0] not in '+|': # check left edge - blank_finish = 0 - self.state_machine.previous_line(len(block) - i) - del block[i:] - break - if not self.grid_table_top_pat.match(block[-1]): # find bottom - blank_finish = 0 - # from second-last to third line of table: - for i in range(len(block) - 2, 1, -1): - if self.grid_table_top_pat.match(block[i]): - self.state_machine.previous_line(len(block) - i + 1) - del block[i+1:] - break - else: - messages.extend(self.malformed_table(block)) - return [], messages, blank_finish - for i in range(len(block)): # check right edge - if len(block[i]) != width or block[i][-1] not in '+|': - messages.extend(self.malformed_table(block)) - return [], messages, blank_finish - return block, messages, blank_finish - - def isolate_simple_table(self): - start = self.state_machine.line_offset - lines = self.state_machine.input_lines - limit = len(lines) - 1 - toplen = len(lines[start].strip()) - pattern_match = self.simple_table_border_pat.match - found = 0 - found_at = None - i = start + 1 - while i <= limit: - line = lines[i] - match = pattern_match(line) - if match: - if len(line.strip()) != toplen: - self.state_machine.next_line(i - start) - messages = self.malformed_table( - lines[start:i+1], 'Bottom/header table border does ' - 'not match top border.') - return [], messages, i == limit or not lines[i+1].strip() - found += 1 - found_at = i - if found == 2 or i == limit or not lines[i+1].strip(): - end = i - break - i += 1 - else: # reached end of input_lines - if found: - extra = ' or no blank line after table bottom' - self.state_machine.next_line(found_at - start) - block = lines[start:found_at+1] - else: - extra = '' - self.state_machine.next_line(i - start - 1) - block = lines[start:] - messages = self.malformed_table( - block, 'No bottom table border found%s.' % extra) - return [], messages, not extra - self.state_machine.next_line(end - start) - block = lines[start:end+1] - return block, [], end == limit or not lines[end+1].strip() - - def malformed_table(self, block, detail=''): - data = '\n'.join(block) - message = 'Malformed table.' - lineno = self.state_machine.abs_line_number() - len(block) + 1 - if detail: - message += '\n' + detail - error = self.reporter.error(message, nodes.literal_block(data, data), - line=lineno) - return [error] - - def build_table(self, tabledata, tableline): - colspecs, headrows, bodyrows = tabledata - table = nodes.table() - tgroup = nodes.tgroup(cols=len(colspecs)) - table += tgroup - for colspec in colspecs: - tgroup += nodes.colspec(colwidth=colspec) - if headrows: - thead = nodes.thead() - tgroup += thead - for row in headrows: - thead += self.build_table_row(row, tableline) - tbody = nodes.tbody() - tgroup += tbody - for row in bodyrows: - tbody += self.build_table_row(row, tableline) - return table - - def build_table_row(self, rowdata, tableline): - row = nodes.row() - for cell in rowdata: - if cell is None: - continue - morerows, morecols, offset, cellblock = cell - attributes = {} - if morerows: - attributes['morerows'] = morerows - if morecols: - attributes['morecols'] = morecols - entry = nodes.entry(**attributes) - row += entry - if ''.join(cellblock): - self.nested_parse(cellblock, input_offset=tableline+offset, - node=entry) - return row - - - explicit = Struct() - """Patterns and constants used for explicit markup recognition.""" - - explicit.patterns = Struct( - target=re.compile(r""" - ( - _ # anonymous target - | # *OR* - (?P<quote>`?) # optional open quote - (?![ `]) # first char. not space or - # backquote - (?P<name> # reference name - .+? - ) - %(non_whitespace_escape_before)s - (?P=quote) # close quote if open quote used - ) - %(non_whitespace_escape_before)s - [ ]? # optional space - : # end of reference name - ([ ]+|$) # followed by whitespace - """ % vars(Inliner), re.VERBOSE), - reference=re.compile(r""" - ( - (?P<simple>%(simplename)s)_ - | # *OR* - ` # open backquote - (?![ ]) # not space - (?P<phrase>.+?) # hyperlink phrase - %(non_whitespace_escape_before)s - `_ # close backquote, - # reference mark - ) - $ # end of string - """ % vars(Inliner), re.VERBOSE | re.UNICODE), - substitution=re.compile(r""" - ( - (?![ ]) # first char. not space - (?P<name>.+?) # substitution text - %(non_whitespace_escape_before)s - \| # close delimiter - ) - ([ ]+|$) # followed by whitespace - """ % vars(Inliner), re.VERBOSE),) - - def footnote(self, match): - lineno = self.state_machine.abs_line_number() - indented, indent, offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - label = match.group(1) - name = normalize_name(label) - footnote = nodes.footnote('\n'.join(indented)) - footnote.line = lineno - if name[0] == '#': # auto-numbered - name = name[1:] # autonumber label - footnote['auto'] = 1 - if name: - footnote['name'] = name - self.document.note_autofootnote(footnote) - elif name == '*': # auto-symbol - name = '' - footnote['auto'] = '*' - self.document.note_symbol_footnote(footnote) - else: # manually numbered - footnote += nodes.label('', label) - footnote['name'] = name - self.document.note_footnote(footnote) - if name: - self.document.note_explicit_target(footnote, footnote) - else: - self.document.set_id(footnote, footnote) - if indented: - self.nested_parse(indented, input_offset=offset, node=footnote) - return [footnote], blank_finish - - def citation(self, match): - lineno = self.state_machine.abs_line_number() - indented, indent, offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - label = match.group(1) - name = normalize_name(label) - citation = nodes.citation('\n'.join(indented)) - citation.line = lineno - citation += nodes.label('', label) - citation['name'] = name - self.document.note_citation(citation) - self.document.note_explicit_target(citation, citation) - if indented: - self.nested_parse(indented, input_offset=offset, node=citation) - return [citation], blank_finish - - def hyperlink_target(self, match): - pattern = self.explicit.patterns.target - lineno = self.state_machine.abs_line_number() - block, indent, offset, blank_finish = \ - self.state_machine.get_first_known_indented( - match.end(), until_blank=1, strip_indent=0) - blocktext = match.string[:match.end()] + '\n'.join(block) - block = [escape2null(line) for line in block] - escaped = block[0] - blockindex = 0 - while 1: - targetmatch = pattern.match(escaped) - if targetmatch: - break - blockindex += 1 - try: - escaped += block[blockindex] - except IndexError: - raise MarkupError('malformed hyperlink target.', lineno) - del block[:blockindex] - block[0] = (block[0] + ' ')[targetmatch.end()-len(escaped)-1:].strip() - if block and block[-1].strip()[-1:] == '_': # possible indirect target - reference = ' '.join([line.strip() for line in block]) - refname = self.is_reference(reference) - if refname: - target = nodes.target(blocktext, '', refname=refname) - target.line = lineno - self.add_target(targetmatch.group('name'), '', target) - self.document.note_indirect_target(target) - return [target], blank_finish - nodelist = [] - reference = ''.join([line.strip() for line in block]) - if reference.find(' ') != -1: - warning = self.reporter.warning( - 'Hyperlink target contains whitespace. Perhaps a footnote ' - 'was intended?', - nodes.literal_block(blocktext, blocktext), line=lineno) - nodelist.append(warning) - else: - unescaped = unescape(reference) - target = nodes.target(blocktext, '') - target.line = lineno - self.add_target(targetmatch.group('name'), unescaped, target) - nodelist.append(target) - return nodelist, blank_finish - - def is_reference(self, reference): - match = self.explicit.patterns.reference.match( - normalize_name(reference)) - if not match: - return None - return unescape(match.group('simple') or match.group('phrase')) - - def add_target(self, targetname, refuri, target): - if targetname: - name = normalize_name(unescape(targetname)) - target['name'] = name - if refuri: - uri = self.inliner.adjust_uri(refuri) - if uri: - target['refuri'] = uri - self.document.note_external_target(target) - else: - raise ApplicationError('problem with URI: %r' % refuri) - else: - self.document.note_internal_target(target) - self.document.note_explicit_target(target, self.parent) - else: # anonymous target - if refuri: - target['refuri'] = refuri - target['anonymous'] = 1 - self.document.note_anonymous_target(target) - - def substitution_def(self, match): - pattern = self.explicit.patterns.substitution - lineno = self.state_machine.abs_line_number() - block, indent, offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end(), - strip_indent=0) - blocktext = (match.string[:match.end()] + '\n'.join(block)) - block.disconnect() - for i in range(len(block)): - block[i] = escape2null(block[i]) - escaped = block[0].rstrip() - blockindex = 0 - while 1: - subdefmatch = pattern.match(escaped) - if subdefmatch: - break - blockindex += 1 - try: - escaped = escaped + ' ' + block[blockindex].strip() - except IndexError: - raise MarkupError('malformed substitution definition.', - lineno) - del block[:blockindex] # strip out the substitution marker - block[0] = (block[0] + ' ')[subdefmatch.end()-len(escaped)-1:].strip() - if not block[0]: - del block[0] - offset += 1 - while block and not block[-1].strip(): - block.pop() - subname = subdefmatch.group('name') - substitution_node = nodes.substitution_definition(blocktext) - substitution_node.line = lineno - self.document.note_substitution_def( - substitution_node,subname, self.parent) - if block: - block[0] = block[0].strip() - new_abs_offset, blank_finish = self.nested_list_parse( - block, input_offset=offset, node=substitution_node, - initial_state='SubstitutionDef', blank_finish=blank_finish) - i = 0 - for node in substitution_node[:]: - if not (isinstance(node, nodes.Inline) or - isinstance(node, nodes.Text)): - self.parent += substitution_node[i] - del substitution_node[i] - else: - i += 1 - if len(substitution_node) == 0: - msg = self.reporter.warning( - 'Substitution definition "%s" empty or invalid.' - % subname, - nodes.literal_block(blocktext, blocktext), line=lineno) - return [msg], blank_finish - else: - return [substitution_node], blank_finish - else: - msg = self.reporter.warning( - 'Substitution definition "%s" missing contents.' % subname, - nodes.literal_block(blocktext, blocktext), line=lineno) - return [msg], blank_finish - - def directive(self, match, **option_presets): - type_name = match.group(1) - directive_function, messages = directives.directive( - type_name, self.memo.language, self.document) - self.parent += messages - if directive_function: - return self.parse_directive( - directive_function, match, type_name, option_presets) - else: - return self.unknown_directive(type_name) - - def parse_directive(self, directive_fn, match, type_name, option_presets): - """ - Parse a directive then run its directive function. - - Parameters: - - - `directive_fn`: The function implementing the directive. Uses - function attributes ``arguments``, ``options``, and/or ``content`` - if present. - - - `match`: A regular expression match object which matched the first - line of the directive. - - - `type_name`: The directive name, as used in the source text. - - - `option_presets`: A dictionary of preset options, defaults for the - directive options. Currently, only an "alt" option is passed by - substitution definitions (value: the substitution name), which may - be used by an embedded image directive. - - Returns a 2-tuple: list of nodes, and a "blank finish" boolean. - """ - arguments = [] - options = {} - argument_spec = getattr(directive_fn, 'arguments', None) - if argument_spec and argument_spec[:2] == (0, 0): - argument_spec = None - option_spec = getattr(directive_fn, 'options', None) - content_spec = getattr(directive_fn, 'content', None) - lineno = self.state_machine.abs_line_number() - initial_line_offset = self.state_machine.line_offset - indented, indent, line_offset, blank_finish \ - = self.state_machine.get_first_known_indented(match.end(), - strip_top=0) - block_text = '\n'.join(self.state_machine.input_lines[ - initial_line_offset : self.state_machine.line_offset + 1]) - if indented and not indented[0].strip(): - indented.trim_start() - line_offset += 1 - while indented and not indented[-1].strip(): - indented.trim_end() - if indented and (argument_spec or option_spec): - for i in range(len(indented)): - if not indented[i].strip(): - break - else: - i += 1 - arg_block = indented[:i] - content = indented[i+1:] - content_offset = line_offset + i + 1 - else: - content = indented - content_offset = line_offset - arg_block = [] - while content and not content[0].strip(): - content.trim_start() - content_offset += 1 - try: - if option_spec: - options, arg_block = self.parse_directive_options( - option_presets, option_spec, arg_block) - if argument_spec: - arguments = self.parse_directive_arguments(argument_spec, - arg_block) - if content and not content_spec: - raise MarkupError('no content permitted') - except MarkupError, detail: - error = self.reporter.error( - 'Error in "%s" directive:\n%s.' % (type_name, detail), - nodes.literal_block(block_text, block_text), line=lineno) - return [error], blank_finish - result = directive_fn( - type_name, arguments, options, content, lineno, content_offset, - block_text, self, self.state_machine) - return result, blank_finish or self.state_machine.is_next_line_blank() - - def parse_directive_options(self, option_presets, option_spec, arg_block): - options = option_presets.copy() - for i in range(len(arg_block)): - if arg_block[i][:1] == ':': - opt_block = arg_block[i:] - arg_block = arg_block[:i] - break - else: - opt_block = [] - if opt_block: - success, data = self.parse_extension_options(option_spec, - opt_block) - if success: # data is a dict of options - options.update(data) - else: # data is an error string - raise MarkupError(data) - return options, arg_block - - def parse_directive_arguments(self, argument_spec, arg_block): - required, optional, last_whitespace = argument_spec - arg_text = '\n'.join(arg_block) - arguments = arg_text.split() - if len(arguments) < required: - raise MarkupError('%s argument(s) required, %s supplied' - % (required, len(arguments))) - elif len(arguments) > required + optional: - if last_whitespace: - arguments = arg_text.split(None, required + optional - 1) - else: - raise MarkupError( - 'maximum %s argument(s) allowed, %s supplied' - % (required + optional, len(arguments))) - return arguments - - def parse_extension_options(self, option_spec, datalines): - """ - Parse `datalines` for a field list containing extension options - matching `option_spec`. - - :Parameters: - - `option_spec`: a mapping of option name to conversion - function, which should raise an exception on bad input. - - `datalines`: a list of input strings. - - :Return: - - Success value, 1 or 0. - - An option dictionary on success, an error string on failure. - """ - node = nodes.field_list() - newline_offset, blank_finish = self.nested_list_parse( - datalines, 0, node, initial_state='ExtensionOptions', - blank_finish=1) - if newline_offset != len(datalines): # incomplete parse of block - return 0, 'invalid option block' - try: - options = utils.extract_extension_options(node, option_spec) - except KeyError, detail: - return 0, ('unknown option: "%s"' % detail.args[0]) - except (ValueError, TypeError), detail: - return 0, ('invalid option value: %s' % detail) - except utils.ExtensionOptionError, detail: - return 0, ('invalid option data: %s' % detail) - if blank_finish: - return 1, options - else: - return 0, 'option data incompletely parsed' - - def unknown_directive(self, type_name): - lineno = self.state_machine.abs_line_number() - indented, indent, offset, blank_finish = \ - self.state_machine.get_first_known_indented(0, strip_indent=0) - text = '\n'.join(indented) - error = self.reporter.error( - 'Unknown directive type "%s".' % type_name, - nodes.literal_block(text, text), line=lineno) - return [error], blank_finish - - def comment(self, match): - if not match.string[match.end():].strip() \ - and self.state_machine.is_next_line_blank(): # an empty comment? - return [nodes.comment()], 1 # "A tiny but practical wart." - indented, indent, offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - while indented and not indented[-1].strip(): - indented.trim_end() - text = '\n'.join(indented) - return [nodes.comment(text, text)], blank_finish - - explicit.constructs = [ - (footnote, - re.compile(r""" - \.\.[ ]+ # explicit markup start - \[ - ( # footnote label: - [0-9]+ # manually numbered footnote - | # *OR* - \# # anonymous auto-numbered footnote - | # *OR* - \#%s # auto-number ed?) footnote label - | # *OR* - \* # auto-symbol footnote - ) - \] - ([ ]+|$) # whitespace or end of line - """ % Inliner.simplename, re.VERBOSE | re.UNICODE)), - (citation, - re.compile(r""" - \.\.[ ]+ # explicit markup start - \[(%s)\] # citation label - ([ ]+|$) # whitespace or end of line - """ % Inliner.simplename, re.VERBOSE | re.UNICODE)), - (hyperlink_target, - re.compile(r""" - \.\.[ ]+ # explicit markup start - _ # target indicator - (?![ ]) # first char. not space - """, re.VERBOSE)), - (substitution_def, - re.compile(r""" - \.\.[ ]+ # explicit markup start - \| # substitution indicator - (?![ ]) # first char. not space - """, re.VERBOSE)), - (directive, - re.compile(r""" - \.\.[ ]+ # explicit markup start - (%s) # directive name - [ ]? # optional space - :: # directive delimiter - ([ ]+|$) # whitespace or end of line - """ % Inliner.simplename, re.VERBOSE | re.UNICODE))] - - def explicit_markup(self, match, context, next_state): - """Footnotes, hyperlink targets, directives, comments.""" - nodelist, blank_finish = self.explicit_construct(match) - self.parent += nodelist - self.explicit_list(blank_finish) - return [], next_state, [] - - def explicit_construct(self, match): - """Determine which explicit construct this is, parse & return it.""" - errors = [] - for method, pattern in self.explicit.constructs: - expmatch = pattern.match(match.string) - if expmatch: - try: - return method(self, expmatch) - except MarkupError, (message, lineno): # never reached? - errors.append(self.reporter.warning(message, line=lineno)) - break - nodelist, blank_finish = self.comment(match) - return nodelist + errors, blank_finish - - def explicit_list(self, blank_finish): - """ - Create a nested state machine for a series of explicit markup - constructs (including anonymous hyperlink targets). - """ - offset = self.state_machine.line_offset + 1 # next line - newline_offset, blank_finish = self.nested_list_parse( - self.state_machine.input_lines[offset:], - input_offset=self.state_machine.abs_line_offset() + 1, - node=self.parent, initial_state='Explicit', - blank_finish=blank_finish, - match_titles=self.state_machine.match_titles) - self.goto_line(newline_offset) - if not blank_finish: - self.parent += self.unindent_warning('Explicit markup') - - def anonymous(self, match, context, next_state): - """Anonymous hyperlink targets.""" - nodelist, blank_finish = self.anonymous_target(match) - self.parent += nodelist - self.explicit_list(blank_finish) - return [], next_state, [] - - def anonymous_target(self, match): - block, indent, offset, blank_finish \ - = self.state_machine.get_first_known_indented(match.end(), - until_blank=1) - blocktext = match.string[:match.end()] + '\n'.join(block) - if block and block[-1].strip()[-1:] == '_': # possible indirect target - reference = escape2null(' '.join([line.strip() - for line in block])) - refname = self.is_reference(reference) - if refname: - target = nodes.target(blocktext, '', refname=refname, - anonymous=1) - self.document.note_anonymous_target(target) - self.document.note_indirect_target(target) - return [target], blank_finish - nodelist = [] - reference = escape2null(''.join([line.strip() for line in block])) - if reference.find(' ') != -1: - lineno = self.state_machine.abs_line_number() - len(block) + 1 - warning = self.reporter.warning( - 'Anonymous hyperlink target contains whitespace. Perhaps a ' - 'footnote was intended?', - nodes.literal_block(blocktext, blocktext), - line=lineno) - nodelist.append(warning) - else: - target = nodes.target(blocktext, '', anonymous=1) - if reference: - unescaped = unescape(reference) - target['refuri'] = unescaped - self.document.note_anonymous_target(target) - nodelist.append(target) - return nodelist, blank_finish - - def line(self, match, context, next_state): - """Section title overline or transition marker.""" - if self.state_machine.match_titles: - return [match.string], 'Line', [] - elif match.string.strip() == '::': - raise statemachine.TransitionCorrection('text') - elif len(match.string.strip()) < 4: - msg = self.reporter.info( - 'Unexpected possible title overline or transition.\n' - "Treating it as ordinary text because it's so short.", - line=self.state_machine.abs_line_number()) - self.parent += msg - raise statemachine.TransitionCorrection('text') - else: - blocktext = self.state_machine.line - msg = self.reporter.severe( - 'Unexpected section title or transition.', - nodes.literal_block(blocktext, blocktext), - line=self.state_machine.abs_line_number()) - self.parent += msg - return [], next_state, [] - - def text(self, match, context, next_state): - """Titles, definition lists, paragraphs.""" - return [match.string], 'Text', [] - - -class RFC2822Body(Body): - - """ - RFC2822 headers are only valid as the first constructs in documents. As - soon as anything else appears, the `Body` state should take over. - """ - - patterns = Body.patterns.copy() # can't modify the original - patterns['rfc2822'] = r'[!-9;-~]+:( +|$)' - initial_transitions = [(name, 'Body') - for name in Body.initial_transitions] - initial_transitions.insert(-1, ('rfc2822', 'Body')) # just before 'text' - - def rfc2822(self, match, context, next_state): - """RFC2822-style field list item.""" - fieldlist = nodes.field_list(CLASS='rfc2822') - self.parent += fieldlist - field, blank_finish = self.rfc2822_field(match) - fieldlist += field - offset = self.state_machine.line_offset + 1 # next line - newline_offset, blank_finish = self.nested_list_parse( - self.state_machine.input_lines[offset:], - input_offset=self.state_machine.abs_line_offset() + 1, - node=fieldlist, initial_state='RFC2822List', - blank_finish=blank_finish) - self.goto_line(newline_offset) - if not blank_finish: - self.parent += self.unindent_warning( - 'RFC2822-style field list') - return [], next_state, [] - - def rfc2822_field(self, match): - name = match.string[:match.string.find(':')] - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end(), - until_blank=1) - fieldnode = nodes.field() - fieldnode += nodes.field_name(name, name) - fieldbody = nodes.field_body('\n'.join(indented)) - fieldnode += fieldbody - if indented: - self.nested_parse(indented, input_offset=line_offset, - node=fieldbody) - return fieldnode, blank_finish - - -class SpecializedBody(Body): - - """ - Superclass for second and subsequent compound element members. Compound - elements are lists and list-like constructs. - - All transition methods are disabled (redefined as `invalid_input`). - Override individual methods in subclasses to re-enable. - - For example, once an initial bullet list item, say, is recognized, the - `BulletList` subclass takes over, with a "bullet_list" node as its - container. Upon encountering the initial bullet list item, `Body.bullet` - calls its ``self.nested_list_parse`` (`RSTState.nested_list_parse`), which - starts up a nested parsing session with `BulletList` as the initial state. - Only the ``bullet`` transition method is enabled in `BulletList`; as long - as only bullet list items are encountered, they are parsed and inserted - into the container. The first construct which is *not* a bullet list item - triggers the `invalid_input` method, which ends the nested parse and - closes the container. `BulletList` needs to recognize input that is - invalid in the context of a bullet list, which means everything *other - than* bullet list items, so it inherits the transition list created in - `Body`. - """ - - def invalid_input(self, match=None, context=None, next_state=None): - """Not a compound element member. Abort this state machine.""" - self.state_machine.previous_line() # back up so parent SM can reassess - raise EOFError - - indent = invalid_input - bullet = invalid_input - enumerator = invalid_input - field_marker = invalid_input - option_marker = invalid_input - doctest = invalid_input - grid_table_top = invalid_input - simple_table_top = invalid_input - explicit_markup = invalid_input - anonymous = invalid_input - line = invalid_input - text = invalid_input - - -class BulletList(SpecializedBody): - - """Second and subsequent bullet_list list_items.""" - - def bullet(self, match, context, next_state): - """Bullet list item.""" - if match.string[0] != self.parent['bullet']: - # different bullet: new list - self.invalid_input() - listitem, blank_finish = self.list_item(match.end()) - self.parent += listitem - self.blank_finish = blank_finish - return [], next_state, [] - - -class DefinitionList(SpecializedBody): - - """Second and subsequent definition_list_items.""" - - def text(self, match, context, next_state): - """Definition lists.""" - return [match.string], 'Definition', [] - - -class EnumeratedList(SpecializedBody): - - """Second and subsequent enumerated_list list_items.""" - - def enumerator(self, match, context, next_state): - """Enumerated list item.""" - format, sequence, text, ordinal = self.parse_enumerator( - match, self.parent['enumtype']) - if (sequence != self.parent['enumtype'] or - format != self.format or - ordinal != (self.lastordinal + 1) or - not self.is_enumerated_list_item(ordinal, sequence, format)): - # different enumeration: new list - self.invalid_input() - listitem, blank_finish = self.list_item(match.end()) - self.parent += listitem - self.blank_finish = blank_finish - self.lastordinal = ordinal - return [], next_state, [] - - -class FieldList(SpecializedBody): - - """Second and subsequent field_list fields.""" - - def field_marker(self, match, context, next_state): - """Field list field.""" - field, blank_finish = self.field(match) - self.parent += field - self.blank_finish = blank_finish - return [], next_state, [] - - -class OptionList(SpecializedBody): - - """Second and subsequent option_list option_list_items.""" - - def option_marker(self, match, context, next_state): - """Option list item.""" - try: - option_list_item, blank_finish = self.option_list_item(match) - except MarkupError, (message, lineno): - self.invalid_input() - self.parent += option_list_item - self.blank_finish = blank_finish - return [], next_state, [] - - -class RFC2822List(SpecializedBody, RFC2822Body): - - """Second and subsequent RFC2822-style field_list fields.""" - - patterns = RFC2822Body.patterns - initial_transitions = RFC2822Body.initial_transitions - - def rfc2822(self, match, context, next_state): - """RFC2822-style field list item.""" - field, blank_finish = self.rfc2822_field(match) - self.parent += field - self.blank_finish = blank_finish - return [], 'RFC2822List', [] - - blank = SpecializedBody.invalid_input - - -class ExtensionOptions(FieldList): - - """ - Parse field_list fields for extension options. - - No nested parsing is done (including inline markup parsing). - """ - - def parse_field_body(self, indented, offset, node): - """Override `Body.parse_field_body` for simpler parsing.""" - lines = [] - for line in list(indented) + ['']: - if line.strip(): - lines.append(line) - elif lines: - text = '\n'.join(lines) - node += nodes.paragraph(text, text) - lines = [] - - -class Explicit(SpecializedBody): - - """Second and subsequent explicit markup construct.""" - - def explicit_markup(self, match, context, next_state): - """Footnotes, hyperlink targets, directives, comments.""" - nodelist, blank_finish = self.explicit_construct(match) - self.parent += nodelist - self.blank_finish = blank_finish - return [], next_state, [] - - def anonymous(self, match, context, next_state): - """Anonymous hyperlink targets.""" - nodelist, blank_finish = self.anonymous_target(match) - self.parent += nodelist - self.blank_finish = blank_finish - return [], next_state, [] - - blank = SpecializedBody.invalid_input - - -class SubstitutionDef(Body): - - """ - Parser for the contents of a substitution_definition element. - """ - - patterns = { - 'embedded_directive': re.compile(r'(%s)::( +|$)' - % Inliner.simplename, re.UNICODE), - 'text': r''} - initial_transitions = ['embedded_directive', 'text'] - - def embedded_directive(self, match, context, next_state): - nodelist, blank_finish = self.directive(match, - alt=self.parent['name']) - self.parent += nodelist - if not self.state_machine.at_eof(): - self.blank_finish = blank_finish - raise EOFError - - def text(self, match, context, next_state): - if not self.state_machine.at_eof(): - self.blank_finish = self.state_machine.is_next_line_blank() - raise EOFError - - -class Text(RSTState): - - """ - Classifier of second line of a text block. - - Could be a paragraph, a definition list item, or a title. - """ - - patterns = {'underline': Body.patterns['line'], - 'text': r''} - initial_transitions = [('underline', 'Body'), ('text', 'Body')] - - def blank(self, match, context, next_state): - """End of paragraph.""" - paragraph, literalnext = self.paragraph( - context, self.state_machine.abs_line_number() - 1) - self.parent += paragraph - if literalnext: - self.parent += self.literal_block() - return [], 'Body', [] - - def eof(self, context): - if context: - self.blank(None, context, None) - return [] - - def indent(self, match, context, next_state): - """Definition list item.""" - definitionlist = nodes.definition_list() - definitionlistitem, blank_finish = self.definition_list_item(context) - definitionlist += definitionlistitem - self.parent += definitionlist - offset = self.state_machine.line_offset + 1 # next line - newline_offset, blank_finish = self.nested_list_parse( - self.state_machine.input_lines[offset:], - input_offset=self.state_machine.abs_line_offset() + 1, - node=definitionlist, initial_state='DefinitionList', - blank_finish=blank_finish, blank_finish_state='Definition') - self.goto_line(newline_offset) - if not blank_finish: - self.parent += self.unindent_warning('Definition list') - return [], 'Body', [] - - def underline(self, match, context, next_state): - """Section title.""" - lineno = self.state_machine.abs_line_number() - title = context[0].rstrip() - underline = match.string.rstrip() - source = title + '\n' + underline - messages = [] - if len(title) > len(underline): - if len(underline) < 4: - if self.state_machine.match_titles: - msg = self.reporter.info( - 'Possible title underline, too short for the title.\n' - "Treating it as ordinary text because it's so short.", - line=lineno) - self.parent += msg - raise statemachine.TransitionCorrection('text') - else: - blocktext = context[0] + '\n' + self.state_machine.line - msg = self.reporter.warning( - 'Title underline too short.', - nodes.literal_block(blocktext, blocktext), line=lineno) - messages.append(msg) - if not self.state_machine.match_titles: - blocktext = context[0] + '\n' + self.state_machine.line - msg = self.reporter.severe( - 'Unexpected section title.', - nodes.literal_block(blocktext, blocktext), line=lineno) - self.parent += messages - self.parent += msg - return [], next_state, [] - style = underline[0] - context[:] = [] - self.section(title, source, style, lineno - 1, messages) - return [], next_state, [] - - def text(self, match, context, next_state): - """Paragraph.""" - startline = self.state_machine.abs_line_number() - 1 - msg = None - try: - block = self.state_machine.get_text_block(flush_left=1) - except statemachine.UnexpectedIndentationError, instance: - block, source, lineno = instance.args - msg = self.reporter.error('Unexpected indentation.', - source=source, line=lineno) - lines = context + list(block) - paragraph, literalnext = self.paragraph(lines, startline) - self.parent += paragraph - self.parent += msg - if literalnext: - try: - self.state_machine.next_line() - except EOFError: - pass - self.parent += self.literal_block() - return [], next_state, [] - - def literal_block(self): - """Return a list of nodes.""" - indented, indent, offset, blank_finish = \ - self.state_machine.get_indented() - nodelist = [] - while indented and not indented[-1].strip(): - indented.trim_end() - if indented: - data = '\n'.join(indented) - nodelist.append(nodes.literal_block(data, data)) - if not blank_finish: - nodelist.append(self.unindent_warning('Literal block')) - else: - nodelist.append(self.reporter.warning( - 'Literal block expected; none found.', - line=self.state_machine.abs_line_number())) - return nodelist - - def definition_list_item(self, termline): - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_indented() - definitionlistitem = nodes.definition_list_item( - '\n'.join(termline + list(indented))) - lineno = self.state_machine.abs_line_number() - 1 - definitionlistitem.line = lineno - termlist, messages = self.term(termline, lineno) - definitionlistitem += termlist - definition = nodes.definition('', *messages) - definitionlistitem += definition - if termline[0][-2:] == '::': - definition += self.reporter.info( - 'Blank line missing before literal block? Interpreted as a ' - 'definition list item.', line=line_offset + 1) - self.nested_parse(indented, input_offset=line_offset, node=definition) - return definitionlistitem, blank_finish - - def term(self, lines, lineno): - """Return a definition_list's term and optional classifier.""" - assert len(lines) == 1 - text_nodes, messages = self.inline_text(lines[0], lineno) - term_node = nodes.term() - node_list = [term_node] - for i in range(len(text_nodes)): - node = text_nodes[i] - if isinstance(node, nodes.Text): - parts = node.rawsource.split(' : ', 1) - if len(parts) == 1: - term_node += node - else: - term_node += nodes.Text(parts[0].rstrip()) - classifier_node = nodes.classifier('', parts[1]) - classifier_node += text_nodes[i+1:] - node_list.append(classifier_node) - break - else: - term_node += node - return node_list, messages - - -class SpecializedText(Text): - - """ - Superclass for second and subsequent lines of Text-variants. - - All transition methods are disabled. Override individual methods in - subclasses to re-enable. - """ - - def eof(self, context): - """Incomplete construct.""" - return [] - - def invalid_input(self, match=None, context=None, next_state=None): - """Not a compound element member. Abort this state machine.""" - raise EOFError - - blank = invalid_input - indent = invalid_input - underline = invalid_input - text = invalid_input - - -class Definition(SpecializedText): - - """Second line of potential definition_list_item.""" - - def eof(self, context): - """Not a definition.""" - self.state_machine.previous_line(2) # so parent SM can reassess - return [] - - def indent(self, match, context, next_state): - """Definition list item.""" - definitionlistitem, blank_finish = self.definition_list_item(context) - self.parent += definitionlistitem - self.blank_finish = blank_finish - return [], 'DefinitionList', [] - - -class Line(SpecializedText): - - """ - Second line of over- & underlined section title or transition marker. - """ - - eofcheck = 1 # @@@ ??? - """Set to 0 while parsing sections, so that we don't catch the EOF.""" - - def eof(self, context): - """Transition marker at end of section or document.""" - marker = context[0].strip() - if self.memo.section_bubble_up_kludge: - self.memo.section_bubble_up_kludge = 0 - elif len(marker) < 4: - self.state_correction(context) - if self.eofcheck: # ignore EOFError with sections - lineno = self.state_machine.abs_line_number() - 1 - transition = nodes.transition(context[0]) - transition.line = lineno - self.parent += transition - msg = self.reporter.error( - 'Document or section may not end with a transition.', - line=lineno) - self.parent += msg - self.eofcheck = 1 - return [] - - def blank(self, match, context, next_state): - """Transition marker.""" - lineno = self.state_machine.abs_line_number() - 1 - marker = context[0].strip() - if len(marker) < 4: - self.state_correction(context) - transition = nodes.transition(marker) - transition.line = lineno - if len(self.parent) == 0: - msg = self.reporter.error( - 'Document or section may not begin with a transition.', - line=lineno) - self.parent += msg - elif isinstance(self.parent[-1], nodes.transition): - msg = self.reporter.error( - 'At least one body element must separate transitions; ' - 'adjacent transitions not allowed.', - line=lineno) - self.parent += msg - self.parent += transition - return [], 'Body', [] - - def text(self, match, context, next_state): - """Potential over- & underlined title.""" - lineno = self.state_machine.abs_line_number() - 1 - overline = context[0] - title = match.string - underline = '' - try: - underline = self.state_machine.next_line() - except EOFError: - blocktext = overline + '\n' + title - if len(overline.rstrip()) < 4: - self.short_overline(context, blocktext, lineno, 2) - else: - msg = self.reporter.severe( - 'Incomplete section title.', - nodes.literal_block(blocktext, blocktext), line=lineno) - self.parent += msg - return [], 'Body', [] - source = '%s\n%s\n%s' % (overline, title, underline) - overline = overline.rstrip() - underline = underline.rstrip() - if not self.transitions['underline'][0].match(underline): - blocktext = overline + '\n' + title + '\n' + underline - if len(overline.rstrip()) < 4: - self.short_overline(context, blocktext, lineno, 2) - else: - msg = self.reporter.severe( - 'Missing matching underline for section title overline.', - nodes.literal_block(source, source), line=lineno) - self.parent += msg - return [], 'Body', [] - elif overline != underline: - blocktext = overline + '\n' + title + '\n' + underline - if len(overline.rstrip()) < 4: - self.short_overline(context, blocktext, lineno, 2) - else: - msg = self.reporter.severe( - 'Title overline & underline mismatch.', - nodes.literal_block(source, source), line=lineno) - self.parent += msg - return [], 'Body', [] - title = title.rstrip() - messages = [] - if len(title) > len(overline): - blocktext = overline + '\n' + title + '\n' + underline - if len(overline.rstrip()) < 4: - self.short_overline(context, blocktext, lineno, 2) - else: - msg = self.reporter.warning( - 'Title overline too short.', - nodes.literal_block(source, source), line=lineno) - messages.append(msg) - style = (overline[0], underline[0]) - self.eofcheck = 0 # @@@ not sure this is correct - self.section(title.lstrip(), source, style, lineno + 1, messages) - self.eofcheck = 1 - return [], 'Body', [] - - indent = text # indented title - - def underline(self, match, context, next_state): - overline = context[0] - blocktext = overline + '\n' + self.state_machine.line - lineno = self.state_machine.abs_line_number() - 1 - if len(overline.rstrip()) < 4: - self.short_overline(context, blocktext, lineno, 1) - msg = self.reporter.error( - 'Invalid section title or transition marker.', - nodes.literal_block(blocktext, blocktext), line=lineno) - self.parent += msg - return [], 'Body', [] - - def short_overline(self, context, blocktext, lineno, lines=1): - msg = self.reporter.info( - 'Possible incomplete section title.\nTreating the overline as ' - "ordinary text because it's so short.", line=lineno) - self.parent += msg - self.state_correction(context, lines) - - def state_correction(self, context, lines=1): - self.state_machine.previous_line(lines) - context[:] = [] - raise statemachine.StateCorrection('Body', 'text') - - -state_classes = (Body, BulletList, DefinitionList, EnumeratedList, FieldList, - OptionList, ExtensionOptions, Explicit, Text, Definition, - Line, SubstitutionDef, RFC2822Body, RFC2822List) -"""Standard set of State classes used to start `RSTStateMachine`.""" - - -def escape2null(text): - """Return a string with escape-backslashes converted to nulls.""" - parts = [] - start = 0 - while 1: - found = text.find('\\', start) - if found == -1: - parts.append(text[start:]) - return ''.join(parts) - parts.append(text[start:found]) - parts.append('\x00' + text[found+1:found+2]) - start = found + 2 # skip character after escape - -def unescape(text, restore_backslashes=0): - """ - Return a string with nulls removed or restored to backslashes. - Backslash-escaped spaces are also removed. - """ - if restore_backslashes: - return text.replace('\x00', '\\') - else: - for sep in ['\x00 ', '\x00\n', '\x00']: - text = ''.join(text.split(sep)) - return text diff --git a/docutils/docutils/parsers/rst/tableparser.py b/docutils/docutils/parsers/rst/tableparser.py deleted file mode 100644 index 35b52e578..000000000 --- a/docutils/docutils/parsers/rst/tableparser.py +++ /dev/null @@ -1,530 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This module defines table parser classes,which parse plaintext-graphic tables -and produce a well-formed data structure suitable for building a CALS table. - -:Classes: - - `GridTableParser`: Parse fully-formed tables represented with a grid. - - `SimpleTableParser`: Parse simple tables, delimited by top & bottom - borders. - -:Exception class: `TableMarkupError` - -:Function: - `update_dict_of_lists()`: Merge two dictionaries containing list values. -""" - -__docformat__ = 'reStructuredText' - - -import re -import sys -from docutils import DataError - - -class TableMarkupError(DataError): pass - - -class TableParser: - - """ - Abstract superclass for the common parts of the syntax-specific parsers. - """ - - head_body_separator_pat = None - """Matches the row separator between head rows and body rows.""" - - def parse(self, block): - """ - Analyze the text `block` and return a table data structure. - - Given a plaintext-graphic table in `block` (list of lines of text; no - whitespace padding), parse the table, construct and return the data - necessary to construct a CALS table or equivalent. - - Raise `TableMarkupError` if there is any problem with the markup. - """ - self.setup(block) - self.find_head_body_sep() - self.parse_table() - structure = self.structure_from_cells() - return structure - - def find_head_body_sep(self): - """Look for a head/body row separator line; store the line index.""" - for i in range(len(self.block)): - line = self.block[i] - if self.head_body_separator_pat.match(line): - if self.head_body_sep: - raise TableMarkupError( - 'Multiple head/body row separators in table (at line ' - 'offset %s and %s); only one allowed.' - % (self.head_body_sep, i)) - else: - self.head_body_sep = i - self.block[i] = line.replace('=', '-') - if self.head_body_sep == 0 or self.head_body_sep == (len(self.block) - - 1): - raise TableMarkupError('The head/body row separator may not be ' - 'the first or last line of the table.') - - -class GridTableParser(TableParser): - - """ - Parse a grid table using `parse()`. - - Here's an example of a grid table:: - - +------------------------+------------+----------+----------+ - | 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. | - +------------------------+------------+---------------------+ - - Intersections use '+', row separators use '-' (except for one optional - head/body row separator, which uses '='), and column separators use '|'. - - Passing the above table to the `parse()` method will result in the - following data structure:: - - ([24, 12, 10, 10], - [[(0, 0, 1, ['Header row, column 1']), - (0, 0, 1, ['Header 2']), - (0, 0, 1, ['Header 3']), - (0, 0, 1, ['Header 4'])]], - [[(0, 0, 3, ['body row 1, column 1']), - (0, 0, 3, ['column 2']), - (0, 0, 3, ['column 3']), - (0, 0, 3, ['column 4'])], - [(0, 0, 5, ['body row 2']), - (0, 2, 5, ['Cells may span columns.']), - None, - None], - [(0, 0, 7, ['body row 3']), - (1, 0, 7, ['Cells may', 'span rows.', '']), - (1, 1, 7, ['- Table cells', '- contain', '- body elements.']), - None], - [(0, 0, 9, ['body row 4']), None, None, None]]) - - The first item is a list containing column widths (colspecs). The second - item is a list of head rows, and the third is a list of body rows. Each - row contains a list of cells. Each cell is either None (for a cell unused - because of another cell's span), or a tuple. A cell tuple contains four - items: the number of extra rows used by the cell in a vertical span - (morerows); the number of extra columns used by the cell in a horizontal - span (morecols); the line offset of the first line of the cell contents; - and the cell contents, a list of lines of text. - """ - - head_body_separator_pat = re.compile(r'\+=[=+]+=\+ *$') - - def setup(self, block): - self.block = list(block) # make a copy; it may be modified - self.bottom = len(block) - 1 - self.right = len(block[0]) - 1 - self.head_body_sep = None - self.done = [-1] * len(block[0]) - self.cells = [] - self.rowseps = {0: [0]} - self.colseps = {0: [0]} - - def parse_table(self): - """ - Start with a queue of upper-left corners, containing the upper-left - corner of the table itself. Trace out one rectangular cell, remember - it, and add its upper-right and lower-left corners to the queue of - potential upper-left corners of further cells. Process the queue in - top-to-bottom order, keeping track of how much of each text column has - been seen. - - We'll end up knowing all the row and column boundaries, cell positions - and their dimensions. - """ - corners = [(0, 0)] - while corners: - top, left = corners.pop(0) - if top == self.bottom or left == self.right \ - or top <= self.done[left]: - continue - result = self.scan_cell(top, left) - if not result: - continue - bottom, right, rowseps, colseps = result - update_dict_of_lists(self.rowseps, rowseps) - update_dict_of_lists(self.colseps, colseps) - self.mark_done(top, left, bottom, right) - cellblock = self.get_cell_block(top, left, bottom, right) - self.cells.append((top, left, bottom, right, cellblock)) - corners.extend([(top, right), (bottom, left)]) - corners.sort() - if not self.check_parse_complete(): - raise TableMarkupError('Malformed table; parse incomplete.') - - def mark_done(self, top, left, bottom, right): - """For keeping track of how much of each text column has been seen.""" - before = top - 1 - after = bottom - 1 - for col in range(left, right): - assert self.done[col] == before - self.done[col] = after - - def check_parse_complete(self): - """Each text column should have been completely seen.""" - last = self.bottom - 1 - for col in range(self.right): - if self.done[col] != last: - return None - return 1 - - def get_cell_block(self, top, left, bottom, right): - """Given the corners, extract the text of a cell.""" - cellblock = [] - margin = right - for lineno in range(top + 1, bottom): - line = self.block[lineno][left + 1 : right].rstrip() - cellblock.append(line) - if line: - margin = min(margin, len(line) - len(line.lstrip())) - if 0 < margin < right: - cellblock = [line[margin:] for line in cellblock] - return cellblock - - def scan_cell(self, top, left): - """Starting at the top-left corner, start tracing out a cell.""" - assert self.block[top][left] == '+' - result = self.scan_right(top, left) - return result - - def scan_right(self, top, left): - """ - Look for the top-right corner of the cell, and make note of all column - boundaries ('+'). - """ - colseps = {} - line = self.block[top] - for i in range(left + 1, self.right + 1): - if line[i] == '+': - colseps[i] = [top] - result = self.scan_down(top, left, i) - if result: - bottom, rowseps, newcolseps = result - update_dict_of_lists(colseps, newcolseps) - return bottom, i, rowseps, colseps - elif line[i] != '-': - return None - return None - - def scan_down(self, top, left, right): - """ - Look for the bottom-right corner of the cell, making note of all row - boundaries. - """ - rowseps = {} - for i in range(top + 1, self.bottom + 1): - if self.block[i][right] == '+': - rowseps[i] = [right] - result = self.scan_left(top, left, i, right) - if result: - newrowseps, colseps = result - update_dict_of_lists(rowseps, newrowseps) - return i, rowseps, colseps - elif self.block[i][right] != '|': - return None - return None - - def scan_left(self, top, left, bottom, right): - """ - Noting column boundaries, look for the bottom-left corner of the cell. - It must line up with the starting point. - """ - colseps = {} - line = self.block[bottom] - for i in range(right - 1, left, -1): - if line[i] == '+': - colseps[i] = [bottom] - elif line[i] != '-': - return None - if line[left] != '+': - return None - result = self.scan_up(top, left, bottom, right) - if result is not None: - rowseps = result - return rowseps, colseps - return None - - def scan_up(self, top, left, bottom, right): - """ - Noting row boundaries, see if we can return to the starting point. - """ - rowseps = {} - for i in range(bottom - 1, top, -1): - if self.block[i][left] == '+': - rowseps[i] = [left] - elif self.block[i][left] != '|': - return None - return rowseps - - def structure_from_cells(self): - """ - From the data colledted by `scan_cell()`, convert to the final data - structure. - """ - rowseps = self.rowseps.keys() # list of row boundaries - rowseps.sort() - rowindex = {} - for i in range(len(rowseps)): - rowindex[rowseps[i]] = i # row boundary -> row number mapping - colseps = self.colseps.keys() # list of column boundaries - colseps.sort() - colindex = {} - for i in range(len(colseps)): - colindex[colseps[i]] = i # column boundary -> col number map - colspecs = [(colseps[i] - colseps[i - 1] - 1) - for i in range(1, len(colseps))] # list of column widths - # prepare an empty table with the correct number of rows & columns - onerow = [None for i in range(len(colseps) - 1)] - rows = [onerow[:] for i in range(len(rowseps) - 1)] - # keep track of # of cells remaining; should reduce to zero - remaining = (len(rowseps) - 1) * (len(colseps) - 1) - for top, left, bottom, right, block in self.cells: - rownum = rowindex[top] - colnum = colindex[left] - assert rows[rownum][colnum] is None, ( - 'Cell (row %s, column %s) already used.' - % (rownum + 1, colnum + 1)) - morerows = rowindex[bottom] - rownum - 1 - morecols = colindex[right] - colnum - 1 - remaining -= (morerows + 1) * (morecols + 1) - # write the cell into the table - rows[rownum][colnum] = (morerows, morecols, top + 1, block) - assert remaining == 0, 'Unused cells remaining.' - if self.head_body_sep: # separate head rows from body rows - numheadrows = rowindex[self.head_body_sep] - headrows = rows[:numheadrows] - bodyrows = rows[numheadrows:] - else: - headrows = [] - bodyrows = rows - return (colspecs, headrows, bodyrows) - - -class SimpleTableParser(TableParser): - - """ - Parse a simple table using `parse()`. - - Here's an example of a simple 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). - 4 is a span - ------------ - 5 - ===== ===== - - Top and bottom borders use '=', column span underlines use '-', column - separation is indicated with spaces. - - Passing the above table to the `parse()` method will result in the - following data structure, whose interpretation is the same as for - `GridTableParser`:: - - ([5, 25], - [[(0, 0, 1, ['col 1']), - (0, 0, 1, ['col 2'])]], - [[(0, 0, 3, ['1']), - (0, 0, 3, ['Second column of row 1.'])], - [(0, 0, 4, ['2']), - (0, 0, 4, ['Second column of row 2.', - 'Second line of paragraph.'])], - [(0, 0, 6, ['3']), - (0, 0, 6, ['- Second column of row 3.', - '', - '- Second item in bullet', - ' list (row 3, column 2).'])], - [(0, 1, 10, ['4 is a span'])], - [(0, 0, 12, ['5']), - (0, 0, 12, [''])]]) - """ - - head_body_separator_pat = re.compile('=[ =]*$') - span_pat = re.compile('-[ -]*$') - - def setup(self, block): - self.block = list(block) # make a copy; it will be modified - # Convert top & bottom borders to column span underlines: - self.block[0] = self.block[0].replace('=', '-') - self.block[-1] = self.block[-1].replace('=', '-') - self.head_body_sep = None - self.columns = [] - self.border_end = None - self.table = [] - self.done = [-1] * len(block[0]) - self.rowseps = {0: [0]} - self.colseps = {0: [0]} - - def parse_table(self): - """ - First determine the column boundaries from the top border, then - process rows. Each row may consist of multiple lines; accumulate - lines until a row is complete. Call `self.parse_row` to finish the - job. - """ - # Top border must fully describe all table columns. - self.columns = self.parse_columns(self.block[0], 0) - self.border_end = self.columns[-1][1] - firststart, firstend = self.columns[0] - block = self.block[1:] - offset = 0 - # Container for accumulating text lines until a row is complete: - rowlines = [] - while block: - line = block.pop(0) - offset += 1 - if self.span_pat.match(line): - # Column span underline or border; row is complete. - self.parse_row(rowlines, (line.rstrip(), offset)) - rowlines = [] - elif line[firststart:firstend].strip(): - # First column not blank, therefore it's a new row. - if rowlines: - self.parse_row(rowlines) - rowlines = [(line.rstrip(), offset)] - else: - # Accumulate lines of incomplete row. - rowlines.append((line.rstrip(), offset)) - - def parse_columns(self, line, offset): - """ - Given a column span underline, return a list of (begin, end) pairs. - """ - cols = [] - end = 0 - while 1: - begin = line.find('-', end) - end = line.find(' ', begin) - if begin < 0: - break - if end < 0: - end = len(line) - cols.append((begin, end)) - if self.columns: - if cols[-1][1] != self.border_end: - raise TableMarkupError('Column span incomplete at line ' - 'offset %s.' % offset) - # Allow for an unbounded rightmost column: - cols[-1] = (cols[-1][0], self.columns[-1][1]) - return cols - - def init_row(self, colspec, offset): - i = 0 - cells = [] - for start, end in colspec: - morecols = 0 - try: - assert start == self.columns[i][0] - while end != self.columns[i][1]: - i += 1 - morecols += 1 - except (AssertionError, IndexError): - raise TableMarkupError('Column span alignment problem at ' - 'line offset %s.' % offset) - cells.append((0, morecols, offset, [])) - i += 1 - return cells - - def parse_row(self, lines, spanline=None): - """ - Given the text `lines` of a row, parse it and append to `self.table`. - - The row is parsed according to the current column spec (either - `spanline` if provided or `self.columns`). For each column, extract - text from each line, and check for text in column margins. Finally, - adjust for insigificant whitespace. - """ - while lines and not lines[-1][0]: - lines.pop() # Remove blank trailing lines. - if lines: - offset = lines[0][1] - elif spanline: - offset = spanline[1] - else: - # No new row, just blank lines. - return - if spanline: - columns = self.parse_columns(*spanline) - else: - columns = self.columns[:] - row = self.init_row(columns, offset) - # "Infinite" value for a dummy last column's beginning, used to - # check for text overflow: - columns.append((sys.maxint, None)) - lastcol = len(columns) - 2 - for i in range(len(columns) - 1): - start, end = columns[i] - nextstart = columns[i+1][0] - block = [] - margin = sys.maxint - for line, offset in lines: - if i == lastcol and line[end:].strip(): - text = line[start:].rstrip() - columns[lastcol] = (start, start + len(text)) - self.adjust_last_column(start + len(text)) - elif line[end:nextstart].strip(): - raise TableMarkupError('Text in column margin at line ' - 'offset %s.' % offset) - else: - text = line[start:end].rstrip() - block.append(text) - if text: - margin = min(margin, len(text) - len(text.lstrip())) - if 0 < margin < sys.maxint: - block = [line[margin:] for line in block] - row[i][3].extend(block) - self.table.append(row) - - def adjust_last_column(self, new_end): - start, end = self.columns[-1] - if new_end > end: - self.columns[-1] = (start, new_end) - - def structure_from_cells(self): - colspecs = [end - start for start, end in self.columns] - first_body_row = 0 - if self.head_body_sep: - for i in range(len(self.table)): - if self.table[i][0][2] > self.head_body_sep: - first_body_row = i - break - return (colspecs, self.table[:first_body_row], - self.table[first_body_row:]) - - -def update_dict_of_lists(master, newdata): - """ - Extend the list values of `master` with those from `newdata`. - - Both parameters must be dictionaries containing list values. - """ - for key, values in newdata.items(): - master.setdefault(key, []).extend(values) diff --git a/docutils/docutils/readers/__init__.py b/docutils/docutils/readers/__init__.py deleted file mode 100644 index f12401ff0..000000000 --- a/docutils/docutils/readers/__init__.py +++ /dev/null @@ -1,88 +0,0 @@ -# Authors: David Goodger; Ueli Schlaepfer -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This package contains Docutils Reader modules. -""" - -__docformat__ = 'reStructuredText' - - -import sys -from docutils import utils, parsers, Component -from docutils.transforms import universal - - -class Reader(Component): - - """ - Abstract base class for docutils Readers. - - Each reader module or package must export a subclass also called 'Reader'. - - The three steps of a Reader's responsibility are defined: `scan()`, - `parse()`, and `transform()`. Call `read()` to process a document. - """ - - component_type = 'reader' - - def __init__(self, parser=None, parser_name='restructuredtext'): - """ - Initialize the Reader instance. - - Several instance attributes are defined with dummy initial values. - Subclasses may use these attributes as they wish. - """ - - self.parser = parser - """A `parsers.Parser` instance shared by all doctrees. May be left - unspecified if the document source determines the parser.""" - - if parser is None and parser_name: - self.set_parser(parser_name) - - self.source = None - """`docutils.io` IO object, source of input data.""" - - self.input = None - """Raw text input; either a single string or, for more complex cases, - a collection of strings.""" - - def set_parser(self, parser_name): - """Set `self.parser` by name.""" - parser_class = parsers.get_parser_class(parser_name) - self.parser = parser_class() - - def read(self, source, parser, settings): - self.source = source - if not self.parser: - self.parser = parser - self.settings = settings - self.input = self.source.read() - self.parse() - return self.document - - def parse(self): - """Parse `self.input` into a document tree.""" - self.document = document = self.new_document() - self.parser.parse(self.input, document) - document.current_source = document.current_line = None - - def new_document(self): - """Create and return a new empty document tree (root node).""" - document = utils.new_document(self.source.source_path, self.settings) - return document - - -_reader_aliases = {} - -def get_reader_class(reader_name): - """Return the Reader class from the `reader_name` module.""" - reader_name = reader_name.lower() - if _reader_aliases.has_key(reader_name): - reader_name = _reader_aliases[reader_name] - module = __import__(reader_name, globals(), locals()) - return module.Reader diff --git a/docutils/docutils/readers/pep.py b/docutils/docutils/readers/pep.py deleted file mode 100644 index e21d8f213..000000000 --- a/docutils/docutils/readers/pep.py +++ /dev/null @@ -1,58 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Python Enhancement Proposal (PEP) Reader. -""" - -__docformat__ = 'reStructuredText' - - -from docutils.readers import standalone -from docutils.transforms import peps, references -from docutils.parsers import rst - - -class Inliner(rst.states.Inliner): - - """ - Extend `rst.Inliner` for local PEP references. - """ - - pep_url = rst.states.Inliner.pep_url_local - - -class Reader(standalone.Reader): - - supported = ('pep',) - """Contexts this reader supports.""" - - settings_spec = ( - 'PEP Reader Option Defaults', - 'The --pep-references and --rfc-references options (for the ' - 'reStructuredText parser) are on by default.', - ()) - - default_transforms = (references.Substitutions, - peps.Headers, - peps.Contents, - references.ChainedTargets, - references.AnonymousHyperlinks, - references.IndirectHyperlinks, - peps.TargetNotes, - references.Footnotes, - references.ExternalTargets, - references.InternalTargets,) - - settings_default_overrides = {'pep_references': 1, 'rfc_references': 1} - - inliner_class = Inliner - - def __init__(self, parser=None, parser_name=None): - """`parser` should be ``None``.""" - if parser is None: - parser = rst.Parser(rfc2822=1, inliner=self.inliner_class()) - standalone.Reader.__init__(self, parser, '') diff --git a/docutils/docutils/readers/python/__init__.py b/docutils/docutils/readers/python/__init__.py deleted file mode 100644 index a346ce32a..000000000 --- a/docutils/docutils/readers/python/__init__.py +++ /dev/null @@ -1,19 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This package contains the Python Source Reader modules. -""" - -__docformat__ = 'reStructuredText' - - -import sys -import docutils.readers - - -class Reader(docutils.readers.Reader): - pass diff --git a/docutils/docutils/readers/python/moduleparser.py b/docutils/docutils/readers/python/moduleparser.py deleted file mode 100644 index 9fcd1ec07..000000000 --- a/docutils/docutils/readers/python/moduleparser.py +++ /dev/null @@ -1,784 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Parser for Python modules. - -The `parse_module()` function takes a module's text and file name, runs it -through the module parser (using compiler.py and tokenize.py) and produces a -"module documentation tree": a high-level AST full of nodes that are -interesting from an auto-documentation standpoint. For example, given this -module (x.py):: - - # comment - - '''Docstring''' - - '''Additional docstring''' - - __docformat__ = 'reStructuredText' - - a = 1 - '''Attribute docstring''' - - class C(Super): - - '''C's docstring''' - - class_attribute = 1 - '''class_attribute's docstring''' - - def __init__(self, text=None): - '''__init__'s docstring''' - - self.instance_attribute = (text * 7 - + ' whaddyaknow') - '''instance_attribute's docstring''' - - - def f(x, # parameter x - y=a*5, # parameter y - *args): # parameter args - '''f's docstring''' - return [x + item for item in args] - - f.function_attribute = 1 - '''f.function_attribute's docstring''' - -The module parser will produce this module documentation tree:: - - <Module filename="test data"> - <Comment lineno=1> - comment - <Docstring> - Docstring - <Docstring lineno="5"> - Additional docstring - <Attribute lineno="7" name="__docformat__"> - <Expression lineno="7"> - 'reStructuredText' - <Attribute lineno="9" name="a"> - <Expression lineno="9"> - 1 - <Docstring lineno="10"> - Attribute docstring - <Class bases="Super" lineno="12" name="C"> - <Docstring lineno="12"> - C's docstring - <Attribute lineno="16" name="class_attribute"> - <Expression lineno="16"> - 1 - <Docstring lineno="17"> - class_attribute's docstring - <Method lineno="19" name="__init__"> - <Docstring lineno="19"> - __init__'s docstring - <ParameterList lineno="19"> - <Parameter lineno="19" name="self"> - <Parameter lineno="19" name="text"> - <Default lineno="19"> - None - <Attribute lineno="22" name="self.instance_attribute"> - <Expression lineno="22"> - (text * 7 + ' whaddyaknow') - <Docstring lineno="24"> - instance_attribute's docstring - <Function lineno="27" name="f"> - <Docstring lineno="27"> - f's docstring - <ParameterList lineno="27"> - <Parameter lineno="27" name="x"> - <Comment> - # parameter x - <Parameter lineno="27" name="y"> - <Default lineno="27"> - a * 5 - <Comment> - # parameter y - <ExcessPositionalArguments lineno="27" name="args"> - <Comment> - # parameter args - <Attribute lineno="33" name="f.function_attribute"> - <Expression lineno="33"> - 1 - <Docstring lineno="34"> - f.function_attribute's docstring - -(Comments are not implemented yet.) - -compiler.parse() provides most of what's needed for this doctree, and -"tokenize" can be used to get the rest. We can determine the line number from -the compiler.parse() AST, and the TokenParser.rhs(lineno) method provides the -rest. - -The Docutils Python reader component will transform this module doctree into a -Python-specific Docutils doctree, and then a `stylist transform`_ will -further transform it into a generic doctree. Namespaces will have to be -compiled for each of the scopes, but I'm not certain at what stage of -processing. - -It's very important to keep all docstring processing out of this, so that it's -a completely generic and not tool-specific. - -> Why perform all of those transformations? Why not go from the AST to a -> generic doctree? Or, even from the AST to the final output? - -I want the docutils.readers.python.moduleparser.parse_module() function to -produce a standard documentation-oriented tree that can be used by any tool. -We can develop it together without having to compromise on the rest of our -design (i.e., HappyDoc doesn't have to be made to work like Docutils, and -vice-versa). It would be a higher-level version of what compiler.py provides. - -The Python reader component transforms this generic AST into a Python-specific -doctree (it knows about modules, classes, functions, etc.), but this is -specific to Docutils and cannot be used by HappyDoc or others. The stylist -transform does the final layout, converting Python-specific structures -("class" sections, etc.) into a generic doctree using primitives (tables, -sections, lists, etc.). This generic doctree does *not* know about Python -structures any more. The advantage is that this doctree can be handed off to -any of the output writers to create any output format we like. - -The latter two transforms are separate because I want to be able to have -multiple independent layout styles (multiple runtime-selectable "stylist -transforms"). Each of the existing tools (HappyDoc, pydoc, epydoc, Crystal, -etc.) has its own fixed format. I personally don't like the tables-based -format produced by these tools, and I'd like to be able to customize the -format easily. That's the goal of stylist transforms, which are independent -from the Reader component itself. One stylist transform could produce -HappyDoc-like output, another could produce output similar to module docs in -the Python library reference manual, and so on. - -It's for exactly this reason: - ->> It's very important to keep all docstring processing out of this, so that ->> it's a completely generic and not tool-specific. - -... but it goes past docstring processing. It's also important to keep style -decisions and tool-specific data transforms out of this module parser. - - -Issues -====== - -* At what point should namespaces be computed? Should they be part of the - basic AST produced by the ASTVisitor walk, or generated by another tree - traversal? - -* At what point should a distinction be made between local variables & - instance attributes in __init__ methods? - -* Docstrings are getting their lineno from their parents. Should the - TokenParser find the real line no's? - -* Comments: include them? How and when? Only full-line comments, or - parameter comments too? (See function "f" above for an example.) - -* Module could use more docstrings & refactoring in places. - -""" - -__docformat__ = 'reStructuredText' - -import sys -import compiler -import compiler.ast -import tokenize -import token -from compiler.consts import OP_ASSIGN -from compiler.visitor import ASTVisitor -from types import StringType, UnicodeType, TupleType - - -def parse_module(module_text, filename): - """Return a module documentation tree from `module_text`.""" - ast = compiler.parse(module_text) - token_parser = TokenParser(module_text) - visitor = ModuleVisitor(filename, token_parser) - compiler.walk(ast, visitor, walker=visitor) - return visitor.module - - -class Node: - - """ - Base class for module documentation tree nodes. - """ - - def __init__(self, node): - self.children = [] - """List of child nodes.""" - - self.lineno = node.lineno - """Line number of this node (or ``None``).""" - - def __str__(self, indent=' ', level=0): - return ''.join(['%s%s\n' % (indent * level, repr(self))] + - [child.__str__(indent, level+1) - for child in self.children]) - - def __repr__(self): - parts = [self.__class__.__name__] - for name, value in self.attlist(): - parts.append('%s="%s"' % (name, value)) - return '<%s>' % ' '.join(parts) - - def attlist(self, **atts): - if self.lineno is not None: - atts['lineno'] = self.lineno - attlist = atts.items() - attlist.sort() - return attlist - - def append(self, node): - self.children.append(node) - - def extend(self, node_list): - self.children.extend(node_list) - - -class TextNode(Node): - - def __init__(self, node, text): - Node.__init__(self, node) - self.text = trim_docstring(text) - - def __str__(self, indent=' ', level=0): - prefix = indent * (level + 1) - text = '\n'.join([prefix + line for line in self.text.splitlines()]) - return Node.__str__(self, indent, level) + text + '\n' - - -class Module(Node): - - def __init__(self, node, filename): - Node.__init__(self, node) - self.filename = filename - - def attlist(self): - return Node.attlist(self, filename=self.filename) - - -class Docstring(TextNode): pass - - -class Comment(TextNode): pass - - -class Import(Node): - - def __init__(self, node, names, from_name=None): - Node.__init__(self, node) - self.names = names - self.from_name = from_name - - def __str__(self, indent=' ', level=0): - prefix = indent * (level + 1) - lines = [] - for name, as in self.names: - if as: - lines.append('%s%s as %s' % (prefix, name, as)) - else: - lines.append('%s%s' % (prefix, name)) - text = '\n'.join(lines) - return Node.__str__(self, indent, level) + text + '\n' - - def attlist(self): - if self.from_name: - atts = {'from': self.from_name} - else: - atts = {} - return Node.attlist(self, **atts) - - -class Attribute(Node): - - def __init__(self, node, name): - Node.__init__(self, node) - self.name = name - - def attlist(self): - return Node.attlist(self, name=self.name) - - -class AttributeTuple(Node): - - def __init__(self, node, names): - Node.__init__(self, node) - self.names = names - - def attlist(self): - return Node.attlist(self, names=' '.join(self.names)) - - -class Expression(TextNode): - - def __str__(self, indent=' ', level=0): - prefix = indent * (level + 1) - return '%s%s%s\n' % (Node.__str__(self, indent, level), - prefix, self.text.encode('unicode-escape')) - - -class Function(Attribute): pass - - -class ParameterList(Node): pass - - -class Parameter(Attribute): pass - - -class ParameterTuple(AttributeTuple): - - def attlist(self): - return Node.attlist(self, names=normalize_parameter_name(self.names)) - - -class ExcessPositionalArguments(Parameter): pass - - -class ExcessKeywordArguments(Parameter): pass - - -class Default(Expression): pass - - -class Class(Node): - - def __init__(self, node, name, bases=None): - Node.__init__(self, node) - self.name = name - self.bases = bases or [] - - def attlist(self): - atts = {'name': self.name} - if self.bases: - atts['bases'] = ' '.join(self.bases) - return Node.attlist(self, **atts) - - -class Method(Function): pass - - -class BaseVisitor(ASTVisitor): - - def __init__(self, token_parser): - ASTVisitor.__init__(self) - self.token_parser = token_parser - self.context = [] - self.documentable = None - - def default(self, node, *args): - self.documentable = None - #print 'in default (%s)' % node.__class__.__name__ - #ASTVisitor.default(self, node, *args) - - def default_visit(self, node, *args): - #print 'in default_visit (%s)' % node.__class__.__name__ - ASTVisitor.default(self, node, *args) - - -class DocstringVisitor(BaseVisitor): - - def visitDiscard(self, node): - if self.documentable: - self.visit(node.expr) - - def visitConst(self, node): - if self.documentable: - if type(node.value) in (StringType, UnicodeType): - self.documentable.append(Docstring(node, node.value)) - else: - self.documentable = None - - def visitStmt(self, node): - self.default_visit(node) - - -class AssignmentVisitor(DocstringVisitor): - - def visitAssign(self, node): - visitor = AttributeVisitor(self.token_parser) - compiler.walk(node, visitor, walker=visitor) - if visitor.attributes: - self.context[-1].extend(visitor.attributes) - if len(visitor.attributes) == 1: - self.documentable = visitor.attributes[0] - else: - self.documentable = None - - -class ModuleVisitor(AssignmentVisitor): - - def __init__(self, filename, token_parser): - AssignmentVisitor.__init__(self, token_parser) - self.filename = filename - self.module = None - - def visitModule(self, node): - self.module = module = Module(node, self.filename) - if node.doc is not None: - module.append(Docstring(node, node.doc)) - self.context.append(module) - self.documentable = module - self.visit(node.node) - self.context.pop() - - def visitImport(self, node): - self.context[-1].append(Import(node, node.names)) - self.documentable = None - - def visitFrom(self, node): - self.context[-1].append( - Import(node, node.names, from_name=node.modname)) - self.documentable = None - - def visitFunction(self, node): - visitor = FunctionVisitor(self.token_parser) - compiler.walk(node, visitor, walker=visitor) - self.context[-1].append(visitor.function) - - def visitClass(self, node): - visitor = ClassVisitor(self.token_parser) - compiler.walk(node, visitor, walker=visitor) - self.context[-1].append(visitor.klass) - - -class AttributeVisitor(BaseVisitor): - - def __init__(self, token_parser): - BaseVisitor.__init__(self, token_parser) - self.attributes = [] - - def visitAssign(self, node): - # Don't visit the expression itself, just the attribute nodes: - for child in node.nodes: - self.dispatch(child) - expression_text = self.token_parser.rhs(node.lineno) - expression = Expression(node, expression_text) - for attribute in self.attributes: - attribute.append(expression) - - def visitAssName(self, node): - self.attributes.append(Attribute(node, node.name)) - - def visitAssTuple(self, node): - attributes = self.attributes - self.attributes = [] - self.default_visit(node) - names = [attribute.name for attribute in self.attributes] - att_tuple = AttributeTuple(node, names) - att_tuple.lineno = self.attributes[0].lineno - self.attributes = attributes - self.attributes.append(att_tuple) - - def visitAssAttr(self, node): - self.default_visit(node, node.attrname) - - def visitGetattr(self, node, suffix): - self.default_visit(node, node.attrname + '.' + suffix) - - def visitName(self, node, suffix): - self.attributes.append(Attribute(node, node.name + '.' + suffix)) - - -class FunctionVisitor(DocstringVisitor): - - in_function = 0 - function_class = Function - - def visitFunction(self, node): - if self.in_function: - self.documentable = None - # Don't bother with nested function definitions. - return - self.in_function = 1 - self.function = function = self.function_class(node, node.name) - if node.doc is not None: - function.append(Docstring(node, node.doc)) - self.context.append(function) - self.documentable = function - self.parse_parameter_list(node) - self.visit(node.code) - self.context.pop() - - def parse_parameter_list(self, node): - parameters = [] - special = [] - argnames = list(node.argnames) - if node.kwargs: - special.append(ExcessKeywordArguments(node, argnames[-1])) - argnames.pop() - if node.varargs: - special.append(ExcessPositionalArguments(node, argnames[-1])) - argnames.pop() - defaults = list(node.defaults) - defaults = [None] * (len(argnames) - len(defaults)) + defaults - function_parameters = self.token_parser.function_parameters( - node.lineno) - #print >>sys.stderr, function_parameters - for argname, default in zip(argnames, defaults): - if type(argname) is TupleType: - parameter = ParameterTuple(node, argname) - argname = normalize_parameter_name(argname) - else: - parameter = Parameter(node, argname) - if default: - parameter.append(Default(node, function_parameters[argname])) - parameters.append(parameter) - if parameters or special: - special.reverse() - parameters.extend(special) - parameter_list = ParameterList(node) - parameter_list.extend(parameters) - self.function.append(parameter_list) - - -class ClassVisitor(AssignmentVisitor): - - in_class = 0 - - def __init__(self, token_parser): - AssignmentVisitor.__init__(self, token_parser) - self.bases = [] - - def visitClass(self, node): - if self.in_class: - self.documentable = None - # Don't bother with nested class definitions. - return - self.in_class = 1 - #import mypdb as pdb - #pdb.set_trace() - for base in node.bases: - self.visit(base) - self.klass = klass = Class(node, node.name, self.bases) - if node.doc is not None: - klass.append(Docstring(node, node.doc)) - self.context.append(klass) - self.documentable = klass - self.visit(node.code) - self.context.pop() - - def visitGetattr(self, node, suffix=None): - if suffix: - name = node.attrname + '.' + suffix - else: - name = node.attrname - self.default_visit(node, name) - - def visitName(self, node, suffix=None): - if suffix: - name = node.name + '.' + suffix - else: - name = node.name - self.bases.append(name) - - def visitFunction(self, node): - if node.name == '__init__': - visitor = InitMethodVisitor(self.token_parser) - else: - visitor = MethodVisitor(self.token_parser) - compiler.walk(node, visitor, walker=visitor) - self.context[-1].append(visitor.function) - - -class MethodVisitor(FunctionVisitor): - - function_class = Method - - -class InitMethodVisitor(MethodVisitor, AssignmentVisitor): pass - - -class TokenParser: - - def __init__(self, text): - self.text = text + '\n\n' - self.lines = self.text.splitlines(1) - self.generator = tokenize.generate_tokens(iter(self.lines).next) - self.next() - - def __iter__(self): - return self - - def next(self): - self.token = self.generator.next() - self.type, self.string, self.start, self.end, self.line = self.token - return self.token - - def goto_line(self, lineno): - while self.start[0] < lineno: - self.next() - return token - - def rhs(self, lineno): - """ - Return a whitespace-normalized expression string from the right-hand - side of an assignment at line `lineno`. - """ - self.goto_line(lineno) - while self.string != '=': - self.next() - self.stack = None - while self.type != token.NEWLINE and self.string != ';': - if self.string == '=' and not self.stack: - self.tokens = [] - self.stack = [] - self._type = None - self._string = None - self._backquote = 0 - else: - self.note_token() - self.next() - self.next() - text = ''.join(self.tokens) - return text.strip() - - closers = {')': '(', ']': '[', '}': '{'} - openers = {'(': 1, '[': 1, '{': 1} - del_ws_prefix = {'.': 1, '=': 1, ')': 1, ']': 1, '}': 1, ':': 1, ',': 1} - no_ws_suffix = {'.': 1, '=': 1, '(': 1, '[': 1, '{': 1} - - def note_token(self): - if self.type == tokenize.NL: - return - del_ws = self.del_ws_prefix.has_key(self.string) - append_ws = not self.no_ws_suffix.has_key(self.string) - if self.openers.has_key(self.string): - self.stack.append(self.string) - if (self._type == token.NAME - or self.closers.has_key(self._string)): - del_ws = 1 - elif self.closers.has_key(self.string): - assert self.stack[-1] == self.closers[self.string] - self.stack.pop() - elif self.string == '`': - if self._backquote: - del_ws = 1 - assert self.stack[-1] == '`' - self.stack.pop() - else: - append_ws = 0 - self.stack.append('`') - self._backquote = not self._backquote - if del_ws and self.tokens and self.tokens[-1] == ' ': - del self.tokens[-1] - self.tokens.append(self.string) - self._type = self.type - self._string = self.string - if append_ws: - self.tokens.append(' ') - - def function_parameters(self, lineno): - """ - Return a dictionary mapping parameters to defaults - (whitespace-normalized strings). - """ - self.goto_line(lineno) - while self.string != 'def': - self.next() - while self.string != '(': - self.next() - name = None - default = None - parameter_tuple = None - self.tokens = [] - parameters = {} - self.stack = [self.string] - self.next() - while 1: - if len(self.stack) == 1: - if parameter_tuple: - # Just encountered ")". - #print >>sys.stderr, 'parameter_tuple: %r' % self.tokens - name = ''.join(self.tokens).strip() - self.tokens = [] - parameter_tuple = None - if self.string in (')', ','): - if name: - if self.tokens: - default_text = ''.join(self.tokens).strip() - else: - default_text = None - parameters[name] = default_text - self.tokens = [] - name = None - default = None - if self.string == ')': - break - elif self.type == token.NAME: - if name and default: - self.note_token() - else: - assert name is None, ( - 'token=%r name=%r parameters=%r stack=%r' - % (self.token, name, parameters, self.stack)) - name = self.string - #print >>sys.stderr, 'name=%r' % name - elif self.string == '=': - assert name is not None, 'token=%r' % (self.token,) - assert default is None, 'token=%r' % (self.token,) - assert self.tokens == [], 'token=%r' % (self.token,) - default = 1 - self._type = None - self._string = None - self._backquote = 0 - elif name: - self.note_token() - elif self.string == '(': - parameter_tuple = 1 - self._type = None - self._string = None - self._backquote = 0 - self.note_token() - else: # ignore these tokens: - assert (self.string in ('*', '**', '\n') - or self.type == tokenize.COMMENT), ( - 'token=%r' % (self.token,)) - else: - self.note_token() - self.next() - return parameters - - -def trim_docstring(text): - """ - Trim indentation and blank lines from docstring text & return it. - - See PEP 257. - """ - if not text: - return text - # Convert tabs to spaces (following the normal Python rules) - # and split into a list of lines: - lines = text.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) - -def normalize_parameter_name(name): - """ - Converts a tuple like ``('a', ('b', 'c'), 'd')`` into ``'(a, (b, c), d)'`` - """ - if type(name) is TupleType: - return '(%s)' % ', '.join([normalize_parameter_name(n) for n in name]) - else: - return name diff --git a/docutils/docutils/readers/standalone.py b/docutils/docutils/readers/standalone.py deleted file mode 100644 index 14b75e3d7..000000000 --- a/docutils/docutils/readers/standalone.py +++ /dev/null @@ -1,49 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Standalone file Reader for the reStructuredText markup syntax. -""" - -__docformat__ = 'reStructuredText' - - -import sys -from docutils import readers -from docutils.transforms import frontmatter, references -from docutils.parsers.rst import Parser - - -class Reader(readers.Reader): - - supported = ('standalone',) - """Contexts this reader supports.""" - - document = None - """A single document tree.""" - - settings_spec = ( - 'Standalone Reader', - None, - (('Disable the promotion of a lone top-level section title to ' - 'document title (and subsequent section title to document ' - 'subtitle promotion; enabled by default).', - ['--no-doc-title'], - {'dest': 'doctitle_xform', 'action': 'store_false', 'default': 1}), - ('Disable the bibliographic field list transform (enabled by ' - 'default).', - ['--no-doc-info'], - {'dest': 'docinfo_xform', 'action': 'store_false', 'default': 1}),)) - - default_transforms = (references.Substitutions, - frontmatter.DocTitle, - frontmatter.DocInfo, - references.ChainedTargets, - references.AnonymousHyperlinks, - references.IndirectHyperlinks, - references.Footnotes, - references.ExternalTargets, - references.InternalTargets,) diff --git a/docutils/docutils/statemachine.py b/docutils/docutils/statemachine.py deleted file mode 100644 index 060347ade..000000000 --- a/docutils/docutils/statemachine.py +++ /dev/null @@ -1,1451 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -A finite state machine specialized for regular-expression-based text filters, -this module defines the following classes: - -- `StateMachine`, a state machine -- `State`, a state superclass -- `StateMachineWS`, a whitespace-sensitive version of `StateMachine` -- `StateWS`, a state superclass for use with `StateMachineWS` -- `SearchStateMachine`, uses `re.search()` instead of `re.match()` -- `SearchStateMachineWS`, uses `re.search()` instead of `re.match()` -- `ViewList`, extends standard Python lists. -- `StringList`, string-specific ViewList. - -Exception classes: - -- `StateMachineError` -- `UnknownStateError` -- `DuplicateStateError` -- `UnknownTransitionError` -- `DuplicateTransitionError` -- `TransitionPatternNotFound` -- `TransitionMethodNotFound` -- `UnexpectedIndentationError` -- `TransitionCorrection`: Raised to switch to another transition. -- `StateCorrection`: Raised to switch to another state & transition. - -Functions: - -- `string2lines()`: split a multi-line string into a list of one-line strings - - -How To Use This Module -====================== -(See the individual classes, methods, and attributes for details.) - -1. Import it: ``import statemachine`` or ``from statemachine import ...``. - You will also need to ``import re``. - -2. Derive a subclass of `State` (or `StateWS`) for each state in your state - machine:: - - class MyState(statemachine.State): - - Within the state's class definition: - - a) Include a pattern for each transition, in `State.patterns`:: - - patterns = {'atransition': r'pattern', ...} - - b) Include a list of initial transitions to be set up automatically, in - `State.initial_transitions`:: - - initial_transitions = ['atransition', ...] - - c) Define a method for each transition, with the same name as the - transition pattern:: - - def atransition(self, match, context, next_state): - # do something - result = [...] # a list - return context, next_state, result - # context, next_state may be altered - - Transition methods may raise an `EOFError` to cut processing short. - - d) You may wish to override the `State.bof()` and/or `State.eof()` implicit - transition methods, which handle the beginning- and end-of-file. - - e) In order to handle nested processing, you may wish to override the - attributes `State.nested_sm` and/or `State.nested_sm_kwargs`. - - If you are using `StateWS` as a base class, in order to handle nested - indented blocks, you may wish to: - - - override the attributes `StateWS.indent_sm`, - `StateWS.indent_sm_kwargs`, `StateWS.known_indent_sm`, and/or - `StateWS.known_indent_sm_kwargs`; - - override the `StateWS.blank()` method; and/or - - override or extend the `StateWS.indent()`, `StateWS.known_indent()`, - and/or `StateWS.firstknown_indent()` methods. - -3. Create a state machine object:: - - sm = StateMachine(state_classes=[MyState, ...], - initial_state='MyState') - -4. Obtain the input text, which needs to be converted into a tab-free list of - one-line strings. For example, to read text from a file called - 'inputfile':: - - input_string = open('inputfile').read() - input_lines = statemachine.string2lines(input_string) - -5. Run the state machine on the input text and collect the results, a list:: - - results = sm.run(input_lines) - -6. Remove any lingering circular references:: - - sm.unlink() -""" - -__docformat__ = 'restructuredtext' - -import sys -import re -from types import SliceType as _SliceType - - -class StateMachine: - - """ - A finite state machine for text filters using regular expressions. - - The input is provided in the form of a list of one-line strings (no - newlines). States are subclasses of the `State` class. Transitions consist - of regular expression patterns and transition methods, and are defined in - each state. - - The state machine is started with the `run()` method, which returns the - results of processing in a list. - """ - - def __init__(self, state_classes, initial_state, debug=0): - """ - Initialize a `StateMachine` object; add state objects. - - Parameters: - - - `state_classes`: a list of `State` (sub)classes. - - `initial_state`: a string, the class name of the initial state. - - `debug`: a boolean; produce verbose output if true (nonzero). - """ - - self.input_lines = None - """`StringList` of input lines (without newlines). - Filled by `self.run()`.""" - - self.input_offset = 0 - """Offset of `self.input_lines` from the beginning of the file.""" - - self.line = None - """Current input line.""" - - self.line_offset = -1 - """Current input line offset from beginning of `self.input_lines`.""" - - self.debug = debug - """Debugging mode on/off.""" - - self.initial_state = initial_state - """The name of the initial state (key to `self.states`).""" - - self.current_state = initial_state - """The name of the current state (key to `self.states`).""" - - self.states = {} - """Mapping of {state_name: State_object}.""" - - self.add_states(state_classes) - - self.observers = [] - """List of bound methods or functions to call whenever the current - line changes. Observers are called with one argument, ``self``. - Cleared at the end of `run()`.""" - - def unlink(self): - """Remove circular references to objects no longer required.""" - for state in self.states.values(): - state.unlink() - self.states = None - - def run(self, input_lines, input_offset=0, context=None, - input_source=None): - """ - Run the state machine on `input_lines`. Return results (a list). - - Reset `self.line_offset` and `self.current_state`. Run the - beginning-of-file transition. Input one line at a time and check for a - matching transition. If a match is found, call the transition method - and possibly change the state. Store the context returned by the - transition method to be passed on to the next transition matched. - Accumulate the results returned by the transition methods in a list. - Run the end-of-file transition. Finally, return the accumulated - results. - - Parameters: - - - `input_lines`: a list of strings without newlines, or `StringList`. - - `input_offset`: the line offset of `input_lines` from the beginning - of the file. - - `context`: application-specific storage. - - `input_source`: name or path of source of `input_lines`. - """ - self.runtime_init() - if isinstance(input_lines, StringList): - self.input_lines = input_lines - else: - self.input_lines = StringList(input_lines, source=input_source) - self.input_offset = input_offset - self.line_offset = -1 - self.current_state = self.initial_state - if self.debug: - print >>sys.stderr, ( - '\nStateMachine.run: input_lines (line_offset=%s):\n| %s' - % (self.line_offset, '\n| '.join(self.input_lines))) - transitions = None - results = [] - state = self.get_state() - try: - if self.debug: - print >>sys.stderr, ('\nStateMachine.run: bof transition') - context, result = state.bof(context) - results.extend(result) - while 1: - try: - try: - self.next_line() - if self.debug: - source, offset = self.input_lines.info( - self.line_offset) - print >>sys.stderr, ( - '\nStateMachine.run: line (source=%r, ' - 'offset=%r):\n| %s' - % (source, offset, self.line)) - context, next_state, result = self.check_line( - context, state, transitions) - except EOFError: - if self.debug: - print >>sys.stderr, ( - '\nStateMachine.run: %s.eof transition' - % state.__class__.__name__) - result = state.eof(context) - results.extend(result) - break - else: - results.extend(result) - except TransitionCorrection, exception: - self.previous_line() # back up for another try - transitions = (exception.args[0],) - if self.debug: - print >>sys.stderr, ( - '\nStateMachine.run: TransitionCorrection to ' - 'state "%s", transition %s.' - % (state.__class__.__name__, transitions[0])) - continue - except StateCorrection, exception: - self.previous_line() # back up for another try - next_state = exception.args[0] - if len(exception.args) == 1: - transitions = None - else: - transitions = (exception.args[1],) - if self.debug: - print >>sys.stderr, ( - '\nStateMachine.run: StateCorrection to state ' - '"%s", transition %s.' - % (next_state, transitions[0])) - else: - transitions = None - state = self.get_state(next_state) - except: - if self.debug: - self.error() - raise - self.observers = [] - return results - - def get_state(self, next_state=None): - """ - Return current state object; set it first if `next_state` given. - - Parameter `next_state`: a string, the name of the next state. - - Exception: `UnknownStateError` raised if `next_state` unknown. - """ - if next_state: - if self.debug and next_state != self.current_state: - print >>sys.stderr, \ - ('\nStateMachine.get_state: Changing state from ' - '"%s" to "%s" (input line %s).' - % (self.current_state, next_state, - self.abs_line_number())) - self.current_state = next_state - try: - return self.states[self.current_state] - except KeyError: - raise UnknownStateError(self.current_state) - - def next_line(self, n=1): - """Load `self.line` with the `n`'th next line and return it.""" - try: - try: - self.line_offset += n - self.line = self.input_lines[self.line_offset] - except IndexError: - self.line = None - raise EOFError - return self.line - finally: - self.notify_observers() - - def is_next_line_blank(self): - """Return 1 if the next line is blank or non-existant.""" - try: - return not self.input_lines[self.line_offset + 1].strip() - except IndexError: - return 1 - - def at_eof(self): - """Return 1 if the input is at or past end-of-file.""" - return self.line_offset >= len(self.input_lines) - 1 - - def at_bof(self): - """Return 1 if the input is at or before beginning-of-file.""" - return self.line_offset <= 0 - - def previous_line(self, n=1): - """Load `self.line` with the `n`'th previous line and return it.""" - self.line_offset -= n - if self.line_offset < 0: - self.line = None - else: - self.line = self.input_lines[self.line_offset] - self.notify_observers() - return self.line - - def goto_line(self, line_offset): - """Jump to absolute line offset `line_offset`, load and return it.""" - try: - try: - self.line_offset = line_offset - self.input_offset - self.line = self.input_lines[self.line_offset] - except IndexError: - self.line = None - raise EOFError - return self.line - finally: - self.notify_observers() - - def abs_line_offset(self): - """Return line offset of current line, from beginning of file.""" - return self.line_offset + self.input_offset - - def abs_line_number(self): - """Return line number of current line (counting from 1).""" - return self.line_offset + self.input_offset + 1 - - def insert_input(self, input_lines, source): - self.input_lines.insert(self.line_offset + 1, '', - source='internal padding') - self.input_lines.insert(self.line_offset + 1, '', - source='internal padding') - self.input_lines.insert(self.line_offset + 2, - StringList(input_lines, source)) - - def get_text_block(self, flush_left=0): - """ - Return a contiguous block of text. - - If `flush_left` is true, raise `UnexpectedIndentationError` if an - indented line is encountered before the text block ends (with a blank - line). - """ - try: - block = self.input_lines.get_text_block(self.line_offset, - flush_left) - self.next_line(len(block) - 1) - return block - except UnexpectedIndentationError, error: - block, source, lineno = error - self.next_line(len(block) - 1) # advance to last line of block - raise - - def check_line(self, context, state, transitions=None): - """ - Examine one line of input for a transition match & execute its method. - - Parameters: - - - `context`: application-dependent storage. - - `state`: a `State` object, the current state. - - `transitions`: an optional ordered list of transition names to try, - instead of ``state.transition_order``. - - Return the values returned by the transition method: - - - context: possibly modified from the parameter `context`; - - next state name (`State` subclass name); - - the result output of the transition, a list. - - When there is no match, ``state.no_match()`` is called and its return - value is returned. - """ - if transitions is None: - transitions = state.transition_order - state_correction = None - if self.debug: - print >>sys.stderr, ( - '\nStateMachine.check_line: state="%s", transitions=%r.' - % (state.__class__.__name__, transitions)) - for name in transitions: - pattern, method, next_state = state.transitions[name] - match = self.match(pattern) - if match: - if self.debug: - print >>sys.stderr, ( - '\nStateMachine.check_line: Matched transition ' - '"%s" in state "%s".' - % (name, state.__class__.__name__)) - return method(match, context, next_state) - else: - if self.debug: - print >>sys.stderr, ( - '\nStateMachine.check_line: No match in state "%s".' - % state.__class__.__name__) - return state.no_match(context, transitions) - - def match(self, pattern): - """ - Return the result of a regular expression match. - - Parameter `pattern`: an `re` compiled regular expression. - """ - return pattern.match(self.line) - - def add_state(self, state_class): - """ - Initialize & add a `state_class` (`State` subclass) object. - - Exception: `DuplicateStateError` raised if `state_class` was already - added. - """ - statename = state_class.__name__ - if self.states.has_key(statename): - raise DuplicateStateError(statename) - self.states[statename] = state_class(self, self.debug) - - def add_states(self, state_classes): - """ - Add `state_classes` (a list of `State` subclasses). - """ - for state_class in state_classes: - self.add_state(state_class) - - def runtime_init(self): - """ - Initialize `self.states`. - """ - for state in self.states.values(): - state.runtime_init() - - def error(self): - """Report error details.""" - type, value, module, line, function = _exception_data() - print >>sys.stderr, '%s: %s' % (type, value) - print >>sys.stderr, 'input line %s' % (self.abs_line_number()) - print >>sys.stderr, ('module %s, line %s, function %s' - % (module, line, function)) - - def attach_observer(self, observer): - """ - The `observer` parameter is a function or bound method which takes two - arguments, the source and offset of the current line. - """ - self.observers.append(observer) - - def detach_observer(self, observer): - self.observers.remove(observer) - - def notify_observers(self): - for observer in self.observers: - try: - info = self.input_lines.info(self.line_offset) - except IndexError: - info = (None, None) - observer(*info) - - -class State: - - """ - State superclass. Contains a list of transitions, and transition methods. - - Transition methods all have the same signature. They take 3 parameters: - - - An `re` match object. ``match.string`` contains the matched input line, - ``match.start()`` gives the start index of the match, and - ``match.end()`` gives the end index. - - A context object, whose meaning is application-defined (initial value - ``None``). It can be used to store any information required by the state - machine, and the retured context is passed on to the next transition - method unchanged. - - The name of the next state, a string, taken from the transitions list; - normally it is returned unchanged, but it may be altered by the - transition method if necessary. - - Transition methods all return a 3-tuple: - - - A context object, as (potentially) modified by the transition method. - - The next state name (a return value of ``None`` means no state change). - - The processing result, a list, which is accumulated by the state - machine. - - Transition methods may raise an `EOFError` to cut processing short. - - There are two implicit transitions, and corresponding transition methods - are defined: `bof()` handles the beginning-of-file, and `eof()` handles - the end-of-file. These methods have non-standard signatures and return - values. `bof()` returns the initial context and results, and may be used - to return a header string, or do any other processing needed. `eof()` - should handle any remaining context and wrap things up; it returns the - final processing result. - - Typical applications need only subclass `State` (or a subclass), set the - `patterns` and `initial_transitions` class attributes, and provide - corresponding transition methods. The default object initialization will - take care of constructing the list of transitions. - """ - - patterns = None - """ - {Name: pattern} mapping, used by `make_transition()`. Each pattern may - be a string or a compiled `re` pattern. Override in subclasses. - """ - - initial_transitions = None - """ - A list of transitions to initialize when a `State` is instantiated. - Each entry is either a transition name string, or a (transition name, next - state name) pair. See `make_transitions()`. Override in subclasses. - """ - - nested_sm = None - """ - The `StateMachine` class for handling nested processing. - - If left as ``None``, `nested_sm` defaults to the class of the state's - controlling state machine. Override it in subclasses to avoid the default. - """ - - nested_sm_kwargs = None - """ - Keyword arguments dictionary, passed to the `nested_sm` constructor. - - Two keys must have entries in the dictionary: - - - Key 'state_classes' must be set to a list of `State` classes. - - Key 'initial_state' must be set to the name of the initial state class. - - If `nested_sm_kwargs` is left as ``None``, 'state_classes' defaults to the - class of the current state, and 'initial_state' defaults to the name of - the class of the current state. Override in subclasses to avoid the - defaults. - """ - - def __init__(self, state_machine, debug=0): - """ - Initialize a `State` object; make & add initial transitions. - - Parameters: - - - `statemachine`: the controlling `StateMachine` object. - - `debug`: a boolean; produce verbose output if true (nonzero). - """ - - self.transition_order = [] - """A list of transition names in search order.""" - - self.transitions = {} - """ - A mapping of transition names to 3-tuples containing - (compiled_pattern, transition_method, next_state_name). Initialized as - an instance attribute dynamically (instead of as a class attribute) - because it may make forward references to patterns and methods in this - or other classes. - """ - - self.add_initial_transitions() - - self.state_machine = state_machine - """A reference to the controlling `StateMachine` object.""" - - self.debug = debug - """Debugging mode on/off.""" - - if self.nested_sm is None: - self.nested_sm = self.state_machine.__class__ - if self.nested_sm_kwargs is None: - self.nested_sm_kwargs = {'state_classes': [self.__class__], - 'initial_state': self.__class__.__name__} - - def runtime_init(self): - """ - Initialize this `State` before running the state machine; called from - `self.state_machine.run()`. - """ - pass - - def unlink(self): - """Remove circular references to objects no longer required.""" - self.state_machine = None - - def add_initial_transitions(self): - """Make and add transitions listed in `self.initial_transitions`.""" - if self.initial_transitions: - names, transitions = self.make_transitions( - self.initial_transitions) - self.add_transitions(names, transitions) - - def add_transitions(self, names, transitions): - """ - Add a list of transitions to the start of the transition list. - - Parameters: - - - `names`: a list of transition names. - - `transitions`: a mapping of names to transition tuples. - - Exceptions: `DuplicateTransitionError`, `UnknownTransitionError`. - """ - for name in names: - if self.transitions.has_key(name): - raise DuplicateTransitionError(name) - if not transitions.has_key(name): - raise UnknownTransitionError(name) - self.transition_order[:0] = names - self.transitions.update(transitions) - - def add_transition(self, name, transition): - """ - Add a transition to the start of the transition list. - - Parameter `transition`: a ready-made transition 3-tuple. - - Exception: `DuplicateTransitionError`. - """ - if self.transitions.has_key(name): - raise DuplicateTransitionError(name) - self.transition_order[:0] = [name] - self.transitions[name] = transition - - def remove_transition(self, name): - """ - Remove a transition by `name`. - - Exception: `UnknownTransitionError`. - """ - try: - del self.transitions[name] - self.transition_order.remove(name) - except: - raise UnknownTransitionError(name) - - def make_transition(self, name, next_state=None): - """ - Make & return a transition tuple based on `name`. - - This is a convenience function to simplify transition creation. - - Parameters: - - - `name`: a string, the name of the transition pattern & method. This - `State` object must have a method called '`name`', and a dictionary - `self.patterns` containing a key '`name`'. - - `next_state`: a string, the name of the next `State` object for this - transition. A value of ``None`` (or absent) implies no state change - (i.e., continue with the same state). - - Exceptions: `TransitionPatternNotFound`, `TransitionMethodNotFound`. - """ - if next_state is None: - next_state = self.__class__.__name__ - try: - pattern = self.patterns[name] - if not hasattr(pattern, 'match'): - pattern = re.compile(pattern) - except KeyError: - raise TransitionPatternNotFound( - '%s.patterns[%r]' % (self.__class__.__name__, name)) - try: - method = getattr(self, name) - except AttributeError: - raise TransitionMethodNotFound( - '%s.%s' % (self.__class__.__name__, name)) - return (pattern, method, next_state) - - def make_transitions(self, name_list): - """ - Return a list of transition names and a transition mapping. - - Parameter `name_list`: a list, where each entry is either a transition - name string, or a 1- or 2-tuple (transition name, optional next state - name). - """ - stringtype = type('') - names = [] - transitions = {} - for namestate in name_list: - if type(namestate) is stringtype: - transitions[namestate] = self.make_transition(namestate) - names.append(namestate) - else: - transitions[namestate[0]] = self.make_transition(*namestate) - names.append(namestate[0]) - return names, transitions - - def no_match(self, context, transitions): - """ - Called when there is no match from `StateMachine.check_line()`. - - Return the same values returned by transition methods: - - - context: unchanged; - - next state name: ``None``; - - empty result list. - - Override in subclasses to catch this event. - """ - return context, None, [] - - def bof(self, context): - """ - Handle beginning-of-file. Return unchanged `context`, empty result. - - Override in subclasses. - - Parameter `context`: application-defined storage. - """ - return context, [] - - def eof(self, context): - """ - Handle end-of-file. Return empty result. - - Override in subclasses. - - Parameter `context`: application-defined storage. - """ - return [] - - def nop(self, match, context, next_state): - """ - A "do nothing" transition method. - - Return unchanged `context` & `next_state`, empty result. Useful for - simple state changes (actionless transitions). - """ - return context, next_state, [] - - -class StateMachineWS(StateMachine): - - """ - `StateMachine` subclass specialized for whitespace recognition. - - There are three methods provided for extracting indented text blocks: - - - `get_indented()`: use when the indent is unknown. - - `get_known_indented()`: use when the indent is known for all lines. - - `get_first_known_indented()`: use when only the first line's indent is - known. - """ - - def get_indented(self, until_blank=0, strip_indent=1): - """ - Return a block of indented lines of text, and info. - - Extract an indented block where the indent is unknown for all lines. - - :Parameters: - - `until_blank`: Stop collecting at the first blank line if true - (1). - - `strip_indent`: Strip common leading indent if true (1, - default). - - :Return: - - the indented block (a list of lines of text), - - its indent, - - its first line offset from BOF, and - - whether or not it finished with a blank line. - """ - offset = self.abs_line_offset() - indented, indent, blank_finish = self.input_lines.get_indented( - self.line_offset, until_blank, strip_indent) - if indented: - self.next_line(len(indented) - 1) # advance to last indented line - while indented and not indented[0].strip(): - indented.trim_start() - offset += 1 - return indented, indent, offset, blank_finish - - def get_known_indented(self, indent, until_blank=0, strip_indent=1): - """ - Return an indented block and info. - - Extract an indented block where the indent is known for all lines. - Starting with the current line, extract the entire text block with at - least `indent` indentation (which must be whitespace, except for the - first line). - - :Parameters: - - `indent`: The number of indent columns/characters. - - `until_blank`: Stop collecting at the first blank line if true - (1). - - `strip_indent`: Strip `indent` characters of indentation if true - (1, default). - - :Return: - - the indented block, - - its first line offset from BOF, and - - whether or not it finished with a blank line. - """ - offset = self.abs_line_offset() - indented, indent, blank_finish = self.input_lines.get_indented( - self.line_offset, until_blank, strip_indent, - block_indent=indent) - self.next_line(len(indented) - 1) # advance to last indented line - while indented and not indented[0].strip(): - indented.trim_start() - offset += 1 - return indented, offset, blank_finish - - def get_first_known_indented(self, indent, until_blank=0, strip_indent=1, - strip_top=1): - """ - Return an indented block and info. - - Extract an indented block where the indent is known for the first line - and unknown for all other lines. - - :Parameters: - - `indent`: The first line's indent (# of columns/characters). - - `until_blank`: Stop collecting at the first blank line if true - (1). - - `strip_indent`: Strip `indent` characters of indentation if true - (1, default). - - `strip_top`: Strip blank lines from the beginning of the block. - - :Return: - - the indented block, - - its indent, - - its first line offset from BOF, and - - whether or not it finished with a blank line. - """ - offset = self.abs_line_offset() - indented, indent, blank_finish = self.input_lines.get_indented( - self.line_offset, until_blank, strip_indent, - first_indent=indent) - self.next_line(len(indented) - 1) # advance to last indented line - if strip_top: - while indented and not indented[0].strip(): - indented.trim_start() - offset += 1 - return indented, indent, offset, blank_finish - - -class StateWS(State): - - """ - State superclass specialized for whitespace (blank lines & indents). - - Use this class with `StateMachineWS`. The transitions 'blank' (for blank - lines) and 'indent' (for indented text blocks) are added automatically, - before any other transitions. The transition method `blank()` handles - blank lines and `indent()` handles nested indented blocks. Indented - blocks trigger a new state machine to be created by `indent()` and run. - The class of the state machine to be created is in `indent_sm`, and the - constructor keyword arguments are in the dictionary `indent_sm_kwargs`. - - The methods `known_indent()` and `firstknown_indent()` are provided for - indented blocks where the indent (all lines' and first line's only, - respectively) is known to the transition method, along with the attributes - `known_indent_sm` and `known_indent_sm_kwargs`. Neither transition method - is triggered automatically. - """ - - indent_sm = None - """ - The `StateMachine` class handling indented text blocks. - - If left as ``None``, `indent_sm` defaults to the value of - `State.nested_sm`. Override it in subclasses to avoid the default. - """ - - indent_sm_kwargs = None - """ - Keyword arguments dictionary, passed to the `indent_sm` constructor. - - If left as ``None``, `indent_sm_kwargs` defaults to the value of - `State.nested_sm_kwargs`. Override it in subclasses to avoid the default. - """ - - known_indent_sm = None - """ - The `StateMachine` class handling known-indented text blocks. - - If left as ``None``, `known_indent_sm` defaults to the value of - `indent_sm`. Override it in subclasses to avoid the default. - """ - - known_indent_sm_kwargs = None - """ - Keyword arguments dictionary, passed to the `known_indent_sm` constructor. - - If left as ``None``, `known_indent_sm_kwargs` defaults to the value of - `indent_sm_kwargs`. Override it in subclasses to avoid the default. - """ - - ws_patterns = {'blank': ' *$', - 'indent': ' +'} - """Patterns for default whitespace transitions. May be overridden in - subclasses.""" - - ws_initial_transitions = ('blank', 'indent') - """Default initial whitespace transitions, added before those listed in - `State.initial_transitions`. May be overridden in subclasses.""" - - def __init__(self, state_machine, debug=0): - """ - Initialize a `StateSM` object; extends `State.__init__()`. - - Check for indent state machine attributes, set defaults if not set. - """ - State.__init__(self, state_machine, debug) - if self.indent_sm is None: - self.indent_sm = self.nested_sm - if self.indent_sm_kwargs is None: - self.indent_sm_kwargs = self.nested_sm_kwargs - if self.known_indent_sm is None: - self.known_indent_sm = self.indent_sm - if self.known_indent_sm_kwargs is None: - self.known_indent_sm_kwargs = self.indent_sm_kwargs - - def add_initial_transitions(self): - """ - Add whitespace-specific transitions before those defined in subclass. - - Extends `State.add_initial_transitions()`. - """ - State.add_initial_transitions(self) - if self.patterns is None: - self.patterns = {} - self.patterns.update(self.ws_patterns) - names, transitions = self.make_transitions( - self.ws_initial_transitions) - self.add_transitions(names, transitions) - - def blank(self, match, context, next_state): - """Handle blank lines. Does nothing. Override in subclasses.""" - return self.nop(match, context, next_state) - - def indent(self, match, context, next_state): - """ - Handle an indented text block. Extend or override in subclasses. - - Recursively run the registered state machine for indented blocks - (`self.indent_sm`). - """ - indented, indent, line_offset, blank_finish = \ - self.state_machine.get_indented() - sm = self.indent_sm(debug=self.debug, **self.indent_sm_kwargs) - results = sm.run(indented, input_offset=line_offset) - return context, next_state, results - - def known_indent(self, match, context, next_state): - """ - Handle a known-indent text block. Extend or override in subclasses. - - Recursively run the registered state machine for known-indent indented - blocks (`self.known_indent_sm`). The indent is the length of the - match, ``match.end()``. - """ - indented, line_offset, blank_finish = \ - self.state_machine.get_known_indented(match.end()) - sm = self.known_indent_sm(debug=self.debug, - **self.known_indent_sm_kwargs) - results = sm.run(indented, input_offset=line_offset) - return context, next_state, results - - def first_known_indent(self, match, context, next_state): - """ - Handle an indented text block (first line's indent known). - - Extend or override in subclasses. - - Recursively run the registered state machine for known-indent indented - blocks (`self.known_indent_sm`). The indent is the length of the - match, ``match.end()``. - """ - indented, line_offset, blank_finish = \ - self.state_machine.get_first_known_indented(match.end()) - sm = self.known_indent_sm(debug=self.debug, - **self.known_indent_sm_kwargs) - results = sm.run(indented, input_offset=line_offset) - return context, next_state, results - - -class _SearchOverride: - - """ - Mix-in class to override `StateMachine` regular expression behavior. - - Changes regular expression matching, from the default `re.match()` - (succeeds only if the pattern matches at the start of `self.line`) to - `re.search()` (succeeds if the pattern matches anywhere in `self.line`). - When subclassing a `StateMachine`, list this class **first** in the - inheritance list of the class definition. - """ - - def match(self, pattern): - """ - Return the result of a regular expression search. - - Overrides `StateMachine.match()`. - - Parameter `pattern`: `re` compiled regular expression. - """ - return pattern.search(self.line) - - -class SearchStateMachine(_SearchOverride, StateMachine): - """`StateMachine` which uses `re.search()` instead of `re.match()`.""" - pass - - -class SearchStateMachineWS(_SearchOverride, StateMachineWS): - """`StateMachineWS` which uses `re.search()` instead of `re.match()`.""" - pass - - -class ViewList: - - """ - List with extended functionality: slices of ViewList objects are child - lists, linked to their parents. Changes made to a child list also affect - the parent list. A child list is effectively a "view" (in the SQL sense) - of the parent list. Changes to parent lists, however, do *not* affect - active child lists. If a parent list is changed, any active child lists - should be recreated. - - The start and end of the slice can be trimmed using the `trim_start()` and - `trim_end()` methods, without affecting the parent list. The link between - child and parent lists can be broken by calling `disconnect()` on the - child list. - - Also, ViewList objects keep track of the source & offset of each item. - This information is accessible via the `source()`, `offset()`, and - `info()` methods. - """ - - def __init__(self, initlist=None, source=None, items=None, - parent=None, parent_offset=None): - self.data = [] - """The actual list of data, flattened from various sources.""" - - self.items = [] - """A list of (source, offset) pairs, same length as `self.data`: the - source of each line and the offset of each line from the beginning of - its source.""" - - self.parent = parent - """The parent list.""" - - self.parent_offset = parent_offset - """Offset of this list from the beginning of the parent list.""" - - if isinstance(initlist, ViewList): - self.data = initlist.data[:] - self.items = initlist.items[:] - elif initlist is not None: - self.data = list(initlist) - if items: - self.items = items - else: - self.items = [(source, i) for i in range(len(initlist))] - assert len(self.data) == len(self.items), 'data mismatch' - - def __str__(self): - return str(self.data) - - def __repr__(self): - return '%s(%s, items=%s)' % (self.__class__.__name__, - self.data, self.items) - - def __lt__(self, other): return self.data < self.__cast(other) - def __le__(self, other): return self.data <= self.__cast(other) - def __eq__(self, other): return self.data == self.__cast(other) - def __ne__(self, other): return self.data != self.__cast(other) - def __gt__(self, other): return self.data > self.__cast(other) - def __ge__(self, other): return self.data >= self.__cast(other) - def __cmp__(self, other): return cmp(self.data, self.__cast(other)) - - def __cast(self, other): - if isinstance(other, ViewList): - return other.data - else: - return other - - def __contains__(self, item): return item in self.data - def __len__(self): return len(self.data) - - # The __getitem__()/__setitem__() methods check whether the index - # is a slice first, since native list objects start supporting - # them directly in Python 2.3 (no exception is raised when - # indexing a list with a slice object; they just work). - - def __getitem__(self, i): - if isinstance(i, _SliceType): - assert i.step in (None, 1), 'cannot handle slice with stride' - return self.__class__(self.data[i.start:i.stop], - items=self.items[i.start:i.stop], - parent=self, parent_offset=i.start) - else: - return self.data[i] - - def __setitem__(self, i, item): - if isinstance(i, _SliceType): - assert i.step in (None, 1), 'cannot handle slice with stride' - if not isinstance(item, ViewList): - raise TypeError('assigning non-ViewList to ViewList slice') - self.data[i.start:i.stop] = item.data - self.items[i.start:i.stop] = item.items - assert len(self.data) == len(self.items), 'data mismatch' - if self.parent: - self.parent[i.start + self.parent_offset - : i.stop + self.parent_offset] = item - else: - self.data[i] = item - if self.parent: - self.parent[i + self.parent_offset] = item - - def __delitem__(self, i): - try: - del self.data[i] - del self.items[i] - if self.parent: - del self.parent[i + self.parent_offset] - except TypeError: - assert i.step is None, 'cannot handle slice with stride' - del self.data[i.start:i.stop] - del self.items[i.start:i.stop] - if self.parent: - del self.parent[i.start + self.parent_offset - : i.stop + self.parent_offset] - - def __add__(self, other): - if isinstance(other, ViewList): - return self.__class__(self.data + other.data, - items=(self.items + other.items)) - else: - raise TypeError('adding non-ViewList to a ViewList') - - def __radd__(self, other): - if isinstance(other, ViewList): - return self.__class__(other.data + self.data, - items=(other.items + self.items)) - else: - raise TypeError('adding ViewList to a non-ViewList') - - def __iadd__(self, other): - if isinstance(other, ViewList): - self.data += other.data - else: - raise TypeError('argument to += must be a ViewList') - return self - - def __mul__(self, n): - return self.__class__(self.data * n, items=(self.items * n)) - - __rmul__ = __mul__ - - def __imul__(self, n): - self.data *= n - self.items *= n - return self - - def extend(self, other): - if not isinstance(other, ViewList): - raise TypeError('extending a ViewList with a non-ViewList') - if self.parent: - self.parent.insert(len(self.data) + self.parent_offset, other) - self.data.extend(other.data) - self.items.extend(other.items) - - def append(self, item, source=None, offset=0): - if source is None: - self.extend(item) - else: - if self.parent: - self.parent.insert(len(self.data) + self.parent_offset, item, - source, offset) - self.data.append(item) - self.items.append((source, offset)) - - def insert(self, i, item, source=None, offset=0): - if source is None: - if not isinstance(item, ViewList): - raise TypeError('inserting non-ViewList with no source given') - self.data[i:i] = item.data - self.items[i:i] = item.items - if self.parent: - index = (len(self.data) + i) % len(self.data) - self.parent.insert(index + self.parent_offset, item) - else: - self.data.insert(i, item) - self.items.insert(i, (source, offset)) - if self.parent: - index = (len(self.data) + i) % len(self.data) - self.parent.insert(index + self.parent_offset, item, - source, offset) - - def pop(self, i=-1): - if self.parent: - index = (len(self.data) + i) % len(self.data) - self.parent.pop(index + self.parent_offset) - self.items.pop(i) - return self.data.pop(i) - - def trim_start(self, n=1): - """ - Remove items from the start of the list, without touching the parent. - """ - if n > len(self.data): - raise IndexError("Size of trim too large; can't trim %s items " - "from a list of size %s." % (n, len(self.data))) - elif n < 0: - raise IndexError('Trim size must be >= 0.') - del self.data[:n] - del self.items[:n] - if self.parent: - self.parent_offset += n - - def trim_end(self, n=1): - """ - Remove items from the end of the list, without touching the parent. - """ - if n > len(self.data): - raise IndexError("Size of trim too large; can't trim %s items " - "from a list of size %s." % (n, len(self.data))) - elif n < 0: - raise IndexError('Trim size must be >= 0.') - del self.data[-n:] - del self.items[-n:] - - def remove(self, item): - index = self.index(item) - del self[index] - - def count(self, item): return self.data.count(item) - def index(self, item): return self.data.index(item) - - def reverse(self): - self.data.reverse() - self.items.reverse() - self.parent = None - - def sort(self, *args): - tmp = zip(self.data, self.items) - tmp.sort(*args) - self.data = [entry[0] for entry in tmp] - self.items = [entry[1] for entry in tmp] - self.parent = None - - def info(self, i): - """Return source & offset for index `i`.""" - try: - return self.items[i] - except IndexError: - if i == len(self.data): # Just past the end - return self.items[i - 1][0], None - else: - raise - - def source(self, i): - """Return source for index `i`.""" - return self.info(i)[0] - - def offset(self, i): - """Return offset for index `i`.""" - return self.info(i)[1] - - def disconnect(self): - """Break link between this list and parent list.""" - self.parent = None - - -class StringList(ViewList): - - """A `ViewList` with string-specific methods.""" - - def strip_indent(self, length, start=0, end=sys.maxint): - """ - Strip `length` characters off the beginning of each item, in-place, - from index `start` to `end`. No whitespace-checking is done on the - stripped text. Does not affect slice parent. - """ - self.data[start:end] = [line[length:] - for line in self.data[start:end]] - - def get_text_block(self, start, flush_left=0): - """ - Return a contiguous block of text. - - If `flush_left` is true, raise `UnexpectedIndentationError` if an - indented line is encountered before the text block ends (with a blank - line). - """ - end = start - last = len(self.data) - while end < last: - line = self.data[end] - if not line.strip(): - break - if flush_left and (line[0] == ' '): - source, offset = self.info(end) - raise UnexpectedIndentationError(self[start:end], source, - offset + 1) - end += 1 - return self[start:end] - - def get_indented(self, start=0, until_blank=0, strip_indent=1, - block_indent=None, first_indent=None): - """ - Extract and return a StringList of indented lines of text. - - Collect all lines with indentation, determine the minimum indentation, - remove the minimum indentation from all indented lines (unless - `strip_indent` is false), and return them. All lines up to but not - including the first unindented line will be returned. - - :Parameters: - - `start`: The index of the first line to examine. - - `until_blank`: Stop collecting at the first blank line if true. - - `strip_indent`: Strip common leading indent if true (default). - - `block_indent`: The indent of the entire block, if known. - - `first_indent`: The indent of the first line, if known. - - :Return: - - a StringList of indented lines with mininum indent removed; - - the amount of the indent; - - a boolean: did the indented block finish with a blank line or EOF? - """ - indent = block_indent # start with None if unknown - end = start - if block_indent is not None and first_indent is None: - first_indent = block_indent - if first_indent is not None: - end += 1 - last = len(self.data) - while end < last: - line = self.data[end] - if line and (line[0] != ' ' - or (block_indent is not None - and line[:block_indent].strip())): - # Line not indented or insufficiently indented. - # Block finished properly iff the last indented line blank: - blank_finish = ((end > start) - and not self.data[end - 1].strip()) - break - stripped = line.lstrip() - if not stripped: # blank line - if until_blank: - blank_finish = 1 - break - elif block_indent is None: - line_indent = len(line) - len(stripped) - if indent is None: - indent = line_indent - else: - indent = min(indent, line_indent) - end += 1 - else: - blank_finish = 1 # block ends at end of lines - block = self[start:end] - if first_indent is not None and block: - block.data[0] = block.data[0][first_indent:] - if indent and strip_indent: - block.strip_indent(indent, start=(first_indent is not None)) - return block, indent or 0, blank_finish - - -class StateMachineError(Exception): pass -class UnknownStateError(StateMachineError): pass -class DuplicateStateError(StateMachineError): pass -class UnknownTransitionError(StateMachineError): pass -class DuplicateTransitionError(StateMachineError): pass -class TransitionPatternNotFound(StateMachineError): pass -class TransitionMethodNotFound(StateMachineError): pass -class UnexpectedIndentationError(StateMachineError): pass - - -class TransitionCorrection(Exception): - - """ - Raise from within a transition method to switch to another transition. - - Raise with one argument, the new transition name. - """ - - -class StateCorrection(Exception): - - """ - Raise from within a transition method to switch to another state. - - Raise with one or two arguments: new state name, and an optional new - transition name. - """ - - -def string2lines(astring, tab_width=8, convert_whitespace=0, - whitespace=re.compile('[\v\f]')): - """ - Return a list of one-line strings with tabs expanded and no newlines. - - Each tab is expanded with between 1 and `tab_width` spaces, so that the - next character's index becomes a multiple of `tab_width` (8 by default). - - Parameters: - - - `astring`: a multi-line string. - - `tab_width`: the number of columns between tab stops. - - `convert_whitespace`: convert form feeds and vertical tabs to spaces? - """ - if convert_whitespace: - astring = whitespace.sub(' ', astring) - return [s.expandtabs(tab_width) for s in astring.splitlines()] - -def _exception_data(): - """ - Return exception information: - - - the exception's class name; - - the exception object; - - the name of the file containing the offending code; - - the line number of the offending code; - - the function name of the offending code. - """ - type, value, traceback = sys.exc_info() - while traceback.tb_next: - traceback = traceback.tb_next - code = traceback.tb_frame.f_code - return (type.__name__, value, code.co_filename, traceback.tb_lineno, - code.co_name) diff --git a/docutils/docutils/transforms/__init__.py b/docutils/docutils/transforms/__init__.py deleted file mode 100644 index 24cc4771f..000000000 --- a/docutils/docutils/transforms/__init__.py +++ /dev/null @@ -1,166 +0,0 @@ -# Authors: David Goodger, Ueli Schlaepfer -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This package contains modules for standard tree transforms available -to Docutils components. Tree transforms serve a variety of purposes: - -- To tie up certain syntax-specific "loose ends" that remain after the - initial parsing of the input plaintext. These transforms are used to - supplement a limited syntax. - -- To automate the internal linking of the document tree (hyperlink - references, footnote references, etc.). - -- To extract useful information from the document tree. These - transforms may be used to construct (for example) indexes and tables - of contents. - -Each transform is an optional step that a Docutils Reader may choose to -perform on the parsed document, depending on the input context. A Docutils -Reader may also perform Reader-specific transforms before or after performing -these standard transforms. -""" - -__docformat__ = 'reStructuredText' - - -from docutils import languages, ApplicationError, TransformSpec - - -class TransformError(ApplicationError): pass - - -class Transform: - - """ - Docutils transform component abstract base class. - """ - - default_priority = None - """Numerical priority of this transform, 0 through 999 (override).""" - - def __init__(self, document, startnode=None): - """ - Initial setup for in-place document transforms. - """ - - self.document = document - """The document tree to transform.""" - - self.startnode = startnode - """Node from which to begin the transform. For many transforms which - apply to the document as a whole, `startnode` is not set (i.e. its - value is `None`).""" - - self.language = languages.get_language( - document.settings.language_code) - """Language module local to this document.""" - - def apply(self): - """Override to apply the transform to the document tree.""" - raise NotImplementedError('subclass must override this method') - - -class Transformer(TransformSpec): - - """ - Stores transforms (`Transform` classes) and applies them to document - trees. Also keeps track of components by component type name. - """ - - from docutils.transforms import universal - - default_transforms = (universal.Decorations, - universal.FinalChecks, - universal.Messages) - """These transforms are applied to all document trees.""" - - def __init__(self, document): - self.transforms = [] - """List of transforms to apply. Each item is a 3-tuple: - ``(priority string, transform class, pending node or None)``.""" - - self.document = document - """The `nodes.document` object this Transformer is attached to.""" - - self.applied = [] - """Transforms already applied, in order.""" - - self.sorted = 0 - """Boolean: is `self.tranforms` sorted?""" - - self.components = {} - """Mapping of component type name to component object. Set by - `self.populate_from_components()`.""" - - self.serialno = 0 - """Internal serial number to keep track of the add order of - transforms.""" - - def add_transform(self, transform_class, priority=None): - """ - Store a single transform. Use `priority` to override the default. - """ - if priority is None: - priority = transform_class.default_priority - priority_string = self.get_priority_string(priority) - self.transforms.append((priority_string, transform_class, None)) - self.sorted = 0 - - def add_transforms(self, transform_list): - """Store multiple transforms, with default priorities.""" - for transform_class in transform_list: - priority_string = self.get_priority_string( - transform_class.default_priority) - self.transforms.append((priority_string, transform_class, None)) - self.sorted = 0 - - def add_pending(self, pending, priority=None): - """Store a transform with an associated `pending` node.""" - transform_class = pending.transform - if priority is None: - priority = transform_class.default_priority - priority_string = self.get_priority_string(priority) - self.transforms.append((priority_string, transform_class, pending)) - self.sorted = 0 - - def get_priority_string(self, priority): - """ - Return a string, `priority` combined with `self.serialno`. - - This ensures FIFO order on transforms with identical priority. - """ - self.serialno += 1 - return '%03d-%03d' % (priority, self.serialno) - - def populate_from_components(self, components): - """ - Store each component's default transforms, with default priorities. - Also, store components by type name in a mapping for later lookup. - """ - self.add_transforms(self.default_transforms) - for component in components: - if component is None: - continue - self.add_transforms(component.default_transforms) - self.components[component.component_type] = component - self.sorted = 0 - - def apply_transforms(self): - """Apply all of the stored transforms, in priority order.""" - self.document.reporter.attach_observer( - self.document.note_transform_message) - while self.transforms: - if not self.sorted: - # Unsorted initially, and whenever a transform is added. - self.transforms.sort() - self.transforms.reverse() - self.sorted = 1 - priority, transform_class, pending = self.transforms.pop() - transform = transform_class(self.document, startnode=pending) - transform.apply() - self.applied.append((priority, transform_class, pending)) diff --git a/docutils/docutils/transforms/components.py b/docutils/docutils/transforms/components.py deleted file mode 100644 index 8f4a267e1..000000000 --- a/docutils/docutils/transforms/components.py +++ /dev/null @@ -1,54 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Docutils component-related transforms. -""" - -__docformat__ = 'reStructuredText' - -import sys -import os -import re -import time -from docutils import nodes, utils -from docutils import ApplicationError, DataError -from docutils.transforms import Transform, TransformError - - -class Filter(Transform): - - """ - Include or exclude elements which depend on a specific Docutils component. - - For use with `nodes.pending` elements. A "pending" element's dictionary - attribute ``details`` must contain the keys "component" and "format". The - value of ``details['component']`` must match the type name of the - component the elements depend on (e.g. "writer"). The value of - ``details['format']`` is the name of a specific format or context of that - component (e.g. "html"). If the matching Docutils component supports that - format or context, the "pending" element is replaced by the contents of - ``details['nodes']`` (a list of nodes); otherwise, the "pending" element - is removed. - - For example, the reStructuredText "meta" directive creates a "pending" - element containing a "meta" element (in ``pending.details['nodes']``). - Only writers (``pending.details['component'] == 'writer'``) supporting the - "html" format (``pending.details['format'] == 'html'``) will include the - "meta" element; it will be deleted from the output of all other writers. - """ - - default_priority = 780 - - def apply(self): - pending = self.startnode - component_type = pending.details['component'] # 'reader' or 'writer' - format = pending.details['format'] - component = self.document.transformer.components[component_type] - if component.supports(format): - pending.parent.replace(pending, pending.details['nodes']) - else: - pending.parent.remove(pending) diff --git a/docutils/docutils/transforms/frontmatter.py b/docutils/docutils/transforms/frontmatter.py deleted file mode 100644 index 00afc6fd2..000000000 --- a/docutils/docutils/transforms/frontmatter.py +++ /dev/null @@ -1,399 +0,0 @@ -# Authors: David Goodger, Ueli Schlaepfer -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Transforms related to the front matter of a document (information -found before the main text): - -- `DocTitle`: Used to transform a lone top level section's title to - the document title, and promote a remaining lone top-level section's - title to the document subtitle. - -- `DocInfo`: Used to transform a bibliographic field list into docinfo - elements. -""" - -__docformat__ = 'reStructuredText' - -import re -from docutils import nodes, utils -from docutils.transforms import TransformError, Transform - - -class DocTitle(Transform): - - """ - In reStructuredText_, there is no way to specify a document title - and subtitle explicitly. Instead, we can supply the document title - (and possibly the subtitle as well) implicitly, and use this - two-step transform to "raise" or "promote" the title(s) (and their - corresponding section contents) to the document level. - - 1. If the document contains a single top-level section as its - first non-comment element, the top-level section's title - becomes the document's title, and the top-level section's - contents become the document's immediate contents. The lone - top-level section header must be the first non-comment element - in the document. - - For example, take this input text:: - - ================= - Top-Level Title - ================= - - A paragraph. - - Once parsed, it looks like this:: - - <document> - <section name="top-level title"> - <title> - Top-Level Title - <paragraph> - A paragraph. - - After running the DocTitle transform, we have:: - - <document name="top-level title"> - <title> - Top-Level Title - <paragraph> - A paragraph. - - 2. If step 1 successfully determines the document title, we - continue by checking for a subtitle. - - If the lone top-level section itself contains a single - second-level section as its first non-comment element, that - section's title is promoted to the document's subtitle, and - that section's contents become the document's immediate - contents. Given this input text:: - - ================= - Top-Level Title - ================= - - Second-Level Title - ~~~~~~~~~~~~~~~~~~ - - A paragraph. - - After parsing and running the Section Promotion transform, the - result is:: - - <document name="top-level title"> - <title> - Top-Level Title - <subtitle name="second-level title"> - Second-Level Title - <paragraph> - A paragraph. - - (Note that the implicit hyperlink target generated by the - "Second-Level Title" is preserved on the "subtitle" element - itself.) - - Any comment elements occurring before the document title or - subtitle are accumulated and inserted as the first body elements - after the title(s). - """ - - default_priority = 320 - - def apply(self): - if not getattr(self.document.settings, 'doctitle_xform', 1): - return - if self.promote_document_title(): - self.promote_document_subtitle() - - def promote_document_title(self): - section, index = self.candidate_index() - if index is None: - return None - document = self.document - # Transfer the section's attributes to the document element (at root): - document.attributes.update(section.attributes) - document[:] = (section[:1] # section title - + document[:index] # everything that was in the - # document before the section - + section[1:]) # everything that was in the section - return 1 - - def promote_document_subtitle(self): - subsection, index = self.candidate_index() - if index is None: - return None - subtitle = nodes.subtitle() - # Transfer the subsection's attributes to the new subtitle: - subtitle.attributes.update(subsection.attributes) - # Transfer the contents of the subsection's title to the subtitle: - subtitle[:] = subsection[0][:] - document = self.document - document[:] = (document[:1] # document title - + [subtitle] - # everything that was before the section: - + document[1:index] - # everything that was in the subsection: - + subsection[1:]) - return 1 - - def candidate_index(self): - """ - Find and return the promotion candidate and its index. - - Return (None, None) if no valid candidate was found. - """ - document = self.document - index = document.first_child_not_matching_class( - nodes.PreBibliographic) - if index is None or len(document) > (index + 1) or \ - not isinstance(document[index], nodes.section): - return None, None - else: - return document[index], index - - -class DocInfo(Transform): - - """ - This transform is specific to the reStructuredText_ markup syntax; - see "Bibliographic Fields" in the `reStructuredText Markup - Specification`_ for a high-level description. This transform - should be run *after* the `DocTitle` transform. - - Given a field list as the first non-comment element after the - document title and subtitle (if present), registered bibliographic - field names are transformed to the corresponding DTD elements, - becoming child elements of the "docinfo" element (except for a - dedication and/or an abstract, which become "topic" elements after - "docinfo"). - - For example, given this document fragment after parsing:: - - <document> - <title> - Document Title - <field_list> - <field> - <field_name> - Author - <field_body> - <paragraph> - A. Name - <field> - <field_name> - Status - <field_body> - <paragraph> - $RCSfile$ - ... - - After running the bibliographic field list transform, the - resulting document tree would look like this:: - - <document> - <title> - Document Title - <docinfo> - <author> - A. Name - <status> - frontmatter.py - ... - - The "Status" field contained an expanded RCS keyword, which is - normally (but optionally) cleaned up by the transform. The sole - contents of the field body must be a paragraph containing an - expanded RCS keyword of the form "$keyword: expansion text $". Any - RCS keyword can be processed in any bibliographic field. The - dollar signs and leading RCS keyword name are removed. Extra - processing is done for the following RCS keywords: - - - "RCSfile" expands to the name of the file in the RCS or CVS - repository, which is the name of the source file with a ",v" - suffix appended. The transform will remove the ",v" suffix. - - - "Date" expands to the format "YYYY/MM/DD hh:mm:ss" (in the UTC - time zone). The RCS Keywords transform will extract just the - date itself and transform it to an ISO 8601 format date, as in - "2000-12-31". - - (Since the source file for this text is itself stored under CVS, - we can't show an example of the "Date" RCS keyword because we - can't prevent any RCS keywords used in this explanation from - being expanded. Only the "RCSfile" keyword is stable; its - expansion text changes only if the file name changes.) - """ - - default_priority = 340 - - biblio_nodes = { - 'author': nodes.author, - 'authors': nodes.authors, - 'organization': nodes.organization, - 'address': nodes.address, - 'contact': nodes.contact, - 'version': nodes.version, - 'revision': nodes.revision, - 'status': nodes.status, - 'date': nodes.date, - 'copyright': nodes.copyright, - 'dedication': nodes.topic, - 'abstract': nodes.topic} - """Canonical field name (lowcased) to node class name mapping for - bibliographic fields (field_list).""" - - def apply(self): - if not getattr(self.document.settings, 'docinfo_xform', 1): - return - document = self.document - index = document.first_child_not_matching_class( - nodes.PreBibliographic) - if index is None: - return - candidate = document[index] - if isinstance(candidate, nodes.field_list): - biblioindex = document.first_child_not_matching_class( - nodes.Titular) - nodelist = self.extract_bibliographic(candidate) - del document[index] # untransformed field list (candidate) - document[biblioindex:biblioindex] = nodelist - return - - def extract_bibliographic(self, field_list): - docinfo = nodes.docinfo() - bibliofields = self.language.bibliographic_fields - labels = self.language.labels - topics = {'dedication': None, 'abstract': None} - for field in field_list: - try: - name = field[0][0].astext() - normedname = nodes.fully_normalize_name(name) - if not (len(field) == 2 and bibliofields.has_key(normedname) - and self.check_empty_biblio_field(field, name)): - raise TransformError - canonical = bibliofields[normedname] - biblioclass = self.biblio_nodes[canonical] - if issubclass(biblioclass, nodes.TextElement): - if not self.check_compound_biblio_field(field, name): - raise TransformError - utils.clean_rcs_keywords( - field[1][0], self.rcs_keyword_substitutions) - docinfo.append(biblioclass('', '', *field[1][0])) - elif issubclass(biblioclass, nodes.authors): - self.extract_authors(field, name, docinfo) - elif issubclass(biblioclass, nodes.topic): - if topics[canonical]: - field[-1] += self.document.reporter.warning( - 'There can only be one "%s" field.' % name, - base_node=field) - raise TransformError - title = nodes.title(name, labels[canonical]) - topics[canonical] = biblioclass( - '', title, CLASS=canonical, *field[1].children) - else: - docinfo.append(biblioclass('', *field[1].children)) - except TransformError: - if len(field[-1]) == 1 \ - and isinstance(field[-1][0], nodes.paragraph): - utils.clean_rcs_keywords( - field[-1][0], self.rcs_keyword_substitutions) - docinfo.append(field) - nodelist = [] - if len(docinfo) != 0: - nodelist.append(docinfo) - for name in ('dedication', 'abstract'): - if topics[name]: - nodelist.append(topics[name]) - return nodelist - - def check_empty_biblio_field(self, field, name): - if len(field[-1]) < 1: - field[-1] += self.document.reporter.warning( - 'Cannot extract empty bibliographic field "%s".' % name, - base_node=field) - return None - return 1 - - def check_compound_biblio_field(self, field, name): - if len(field[-1]) > 1: - field[-1] += self.document.reporter.warning( - 'Cannot extract compound bibliographic field "%s".' % name, - base_node=field) - return None - if not isinstance(field[-1][0], nodes.paragraph): - field[-1] += self.document.reporter.warning( - 'Cannot extract bibliographic field "%s" containing ' - 'anything other than a single paragraph.' % name, - base_node=field) - return None - return 1 - - rcs_keyword_substitutions = [ - (re.compile(r'\$' r'Date: (\d\d\d\d)/(\d\d)/(\d\d) [\d:]+ \$$', - re.IGNORECASE), r'\1-\2-\3'), - (re.compile(r'\$' r'RCSfile: (.+),v \$$', re.IGNORECASE), r'\1'), - (re.compile(r'\$[a-zA-Z]+: (.+) \$$'), r'\1'),] - - def extract_authors(self, field, name, docinfo): - try: - if len(field[1]) == 1: - if isinstance(field[1][0], nodes.paragraph): - authors = self.authors_from_one_paragraph(field) - elif isinstance(field[1][0], nodes.bullet_list): - authors = self.authors_from_bullet_list(field) - else: - raise TransformError - else: - authors = self.authors_from_paragraphs(field) - authornodes = [nodes.author('', '', *author) - for author in authors if author] - if len(authornodes) > 1: - docinfo.append(nodes.authors('', *authornodes)) - elif len(authornodes) == 1: - docinfo.append(authornodes[0]) - else: - raise TransformError - except TransformError: - field[-1] += self.document.reporter.warning( - 'Bibliographic field "%s" incompatible with extraction: ' - 'it must contain either a single paragraph (with authors ' - 'separated by one of "%s"), multiple paragraphs (one per ' - 'author), or a bullet list with one paragraph (one author) ' - 'per item.' - % (name, ''.join(self.language.author_separators)), - base_node=field) - raise - - def authors_from_one_paragraph(self, field): - text = field[1][0].astext().strip() - if not text: - raise TransformError - for authorsep in self.language.author_separators: - authornames = text.split(authorsep) - if len(authornames) > 1: - break - authornames = [author.strip() for author in authornames] - authors = [[nodes.Text(author)] for author in authornames if author] - return authors - - def authors_from_bullet_list(self, field): - authors = [] - for item in field[1][0]: - if len(item) != 1 or not isinstance(item[0], nodes.paragraph): - raise TransformError - authors.append(item[0].children) - if not authors: - raise TransformError - return authors - - def authors_from_paragraphs(self, field): - for item in field[1]: - if not isinstance(item, nodes.paragraph): - raise TransformError - authors = [item.children for item in field[1]] - return authors diff --git a/docutils/docutils/transforms/misc.py b/docutils/docutils/transforms/misc.py deleted file mode 100644 index 4f6e2670b..000000000 --- a/docutils/docutils/transforms/misc.py +++ /dev/null @@ -1,62 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Miscellaneous transforms. -""" - -__docformat__ = 'reStructuredText' - -from docutils import nodes -from docutils.transforms import Transform, TransformError - - -class CallBack(Transform): - - """ - Inserts a callback into a document. The callback is called when the - transform is applied, which is determined by its priority. - - For use with `nodes.pending` elements. Requires a ``details['callback']`` - entry, a bound method or function which takes one parameter: the pending - node. Other data can be stored in the ``details`` attribute or in the - object hosting the callback method. - """ - - default_priority = 990 - - def apply(self): - pending = self.startnode - pending.details['callback'](pending) - pending.parent.remove(pending) - - -class ClassAttribute(Transform): - - default_priority = 210 - - def apply(self): - pending = self.startnode - class_value = pending.details['class'] - parent = pending.parent - child = pending - while parent: - for index in range(parent.index(child) + 1, len(parent)): - element = parent[index] - if isinstance(element, nodes.comment): - continue - element.set_class(class_value) - pending.parent.remove(pending) - return - else: - child = parent - parent = parent.parent - error = self.document.reporter.error( - 'No suitable element following "%s" directive' - % pending.details['directive'], - nodes.literal_block(pending.rawsource, pending.rawsource), - line=pending.line) - pending.parent.replace(pending, error) diff --git a/docutils/docutils/transforms/parts.py b/docutils/docutils/transforms/parts.py deleted file mode 100644 index 016f4e1d8..000000000 --- a/docutils/docutils/transforms/parts.py +++ /dev/null @@ -1,176 +0,0 @@ -# Authors: David Goodger, Ueli Schlaepfer, Dmitry Jemerov -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Transforms related to document parts. -""" - -__docformat__ = 'reStructuredText' - - -import re -import sys -from docutils import nodes, utils -from docutils.transforms import TransformError, Transform - - -class SectNum(Transform): - - """ - Automatically assigns numbers to the titles of document sections. - - It is possible to limit the maximum section level for which the numbers - are added. For those sections that are auto-numbered, the "autonum" - attribute is set, informing the contents table generator that a different - form of the TOC should be used. - """ - - default_priority = 710 - """Should be applied before `Contents`.""" - - def apply(self): - self.maxdepth = self.startnode.details.get('depth', sys.maxint) - self.startnode.parent.remove(self.startnode) - self.update_section_numbers(self.document) - - def update_section_numbers(self, node, prefix=(), depth=0): - depth += 1 - sectnum = 1 - for child in node: - if isinstance(child, nodes.section): - numbers = prefix + (str(sectnum),) - title = child[0] - # Use for spacing: - generated = nodes.generated( - '', '.'.join(numbers) + u'\u00a0' * 3, CLASS='sectnum') - title.insert(0, generated) - title['auto'] = 1 - if depth < self.maxdepth: - self.update_section_numbers(child, numbers, depth) - sectnum += 1 - - -class Contents(Transform): - - """ - This transform generates a table of contents from the entire document tree - or from a single branch. It locates "section" elements and builds them - into a nested bullet list, which is placed within a "topic". A title is - either explicitly specified, taken from the appropriate language module, - or omitted (local table of contents). The depth may be specified. - Two-way references between the table of contents and section titles are - generated (requires Writer support). - - This transform requires a startnode, which which contains generation - options and provides the location for the generated table of contents (the - startnode is replaced by the table of contents "topic"). - """ - - default_priority = 720 - - def apply(self): - topic = nodes.topic(CLASS='contents') - details = self.startnode.details - if details.has_key('class'): - topic.set_class(details['class']) - title = details['title'] - if details.has_key('local'): - startnode = self.startnode.parent - # @@@ generate an error if the startnode (directive) not at - # section/document top-level? Drag it up until it is? - while not isinstance(startnode, nodes.Structural): - startnode = startnode.parent - else: - startnode = self.document - if not title: - title = nodes.title('', self.language.labels['contents']) - if title: - name = title.astext() - topic += title - else: - name = self.language.labels['contents'] - name = nodes.fully_normalize_name(name) - if not self.document.has_name(name): - topic['name'] = name - self.document.note_implicit_target(topic) - self.toc_id = topic['id'] - if details.has_key('backlinks'): - self.backlinks = details['backlinks'] - else: - self.backlinks = self.document.settings.toc_backlinks - contents = self.build_contents(startnode) - if len(contents): - topic += contents - self.startnode.parent.replace(self.startnode, topic) - else: - self.startnode.parent.remove(self.startnode) - - def build_contents(self, node, level=0): - level += 1 - sections = [] - i = len(node) - 1 - while i >= 0 and isinstance(node[i], nodes.section): - sections.append(node[i]) - i -= 1 - sections.reverse() - entries = [] - autonum = 0 - depth = self.startnode.details.get('depth', sys.maxint) - for section in sections: - title = section[0] - auto = title.get('auto') # May be set by SectNum. - entrytext = self.copy_and_filter(title) - reference = nodes.reference('', '', refid=section['id'], - *entrytext) - ref_id = self.document.set_id(reference) - entry = nodes.paragraph('', '', reference) - item = nodes.list_item('', entry) - if self.backlinks == 'entry': - title['refid'] = ref_id - elif self.backlinks == 'top': - title['refid'] = self.toc_id - if level < depth: - subsects = self.build_contents(section, level) - item += subsects - entries.append(item) - if entries: - contents = nodes.bullet_list('', *entries) - if auto: - contents.set_class('auto-toc') - return contents - else: - return [] - - def copy_and_filter(self, node): - """Return a copy of a title, with references, images, etc. removed.""" - visitor = ContentsFilter(self.document) - node.walkabout(visitor) - return visitor.get_entry_text() - - -class ContentsFilter(nodes.TreeCopyVisitor): - - def get_entry_text(self): - return self.get_tree_copy().get_children() - - def visit_citation_reference(self, node): - raise nodes.SkipNode - - def visit_footnote_reference(self, node): - raise nodes.SkipNode - - def visit_image(self, node): - if node.hasattr('alt'): - self.parent.append(nodes.Text(node['alt'])) - raise nodes.SkipNode - - def ignore_node_but_process_children(self, node): - raise nodes.SkipDeparture - - visit_interpreted = ignore_node_but_process_children - visit_problematic = ignore_node_but_process_children - visit_reference = ignore_node_but_process_children - visit_target = ignore_node_but_process_children diff --git a/docutils/docutils/transforms/peps.py b/docutils/docutils/transforms/peps.py deleted file mode 100644 index 9ae7fa80b..000000000 --- a/docutils/docutils/transforms/peps.py +++ /dev/null @@ -1,294 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Transforms for PEP processing. - -- `Headers`: Used to transform a PEP's initial RFC-2822 header. It remains a - field list, but some entries get processed. -- `Contents`: Auto-inserts a table of contents. -- `PEPZero`: Special processing for PEP 0. -""" - -__docformat__ = 'reStructuredText' - -import sys -import os -import re -import time -from docutils import nodes, utils -from docutils import ApplicationError, DataError -from docutils.transforms import Transform, TransformError -from docutils.transforms import parts, references, misc - - -class Headers(Transform): - - """ - Process fields in a PEP's initial RFC-2822 header. - """ - - default_priority = 360 - - pep_url = 'pep-%04d.html' - pep_cvs_url = ('http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/' - 'python/nondist/peps/pep-%04d.txt') - rcs_keyword_substitutions = ( - (re.compile(r'\$' r'RCSfile: (.+),v \$$', re.IGNORECASE), r'\1'), - (re.compile(r'\$[a-zA-Z]+: (.+) \$$'), r'\1'),) - - def apply(self): - if not len(self.document): - # @@@ replace these DataErrors with proper system messages - raise DataError('Document tree is empty.') - header = self.document[0] - if not isinstance(header, nodes.field_list) or \ - header.get('class') != 'rfc2822': - raise DataError('Document does not begin with an RFC-2822 ' - 'header; it is not a PEP.') - pep = None - for field in header: - if field[0].astext().lower() == 'pep': # should be the first field - value = field[1].astext() - try: - pep = int(value) - cvs_url = self.pep_cvs_url % pep - except ValueError: - pep = value - cvs_url = None - msg = self.document.reporter.warning( - '"PEP" header must contain an integer; "%s" is an ' - 'invalid value.' % pep, base_node=field) - msgid = self.document.set_id(msg) - prb = nodes.problematic(value, value or '(none)', - refid=msgid) - prbid = self.document.set_id(prb) - msg.add_backref(prbid) - if len(field[1]): - field[1][0][:] = [prb] - else: - field[1] += nodes.paragraph('', '', prb) - break - if pep is None: - raise DataError('Document does not contain an RFC-2822 "PEP" ' - 'header.') - if pep == 0: - # Special processing for PEP 0. - pending = nodes.pending(PEPZero) - self.document.insert(1, pending) - self.document.note_pending(pending) - if len(header) < 2 or header[1][0].astext().lower() != 'title': - raise DataError('No title!') - for field in header: - name = field[0].astext().lower() - body = field[1] - if len(body) > 1: - raise DataError('PEP header field body contains multiple ' - 'elements:\n%s' % field.pformat(level=1)) - elif len(body) == 1: - if not isinstance(body[0], nodes.paragraph): - raise DataError('PEP header field body may only contain ' - 'a single paragraph:\n%s' - % field.pformat(level=1)) - elif name == 'last-modified': - date = time.strftime( - '%d-%b-%Y', - time.localtime(os.stat(self.document['source'])[8])) - if cvs_url: - body += nodes.paragraph( - '', '', nodes.reference('', date, refuri=cvs_url)) - else: - # empty - continue - para = body[0] - if name == 'author': - for node in para: - if isinstance(node, nodes.reference): - node.parent.replace(node, mask_email(node)) - elif name == 'discussions-to': - for node in para: - if isinstance(node, nodes.reference): - node.parent.replace(node, mask_email(node, pep)) - elif name in ('replaces', 'replaced-by', 'requires'): - newbody = [] - space = nodes.Text(' ') - for refpep in re.split(',?\s+', body.astext()): - pepno = int(refpep) - newbody.append(nodes.reference( - refpep, refpep, refuri=self.pep_url % pepno)) - newbody.append(space) - para[:] = newbody[:-1] # drop trailing space - elif name == 'last-modified': - utils.clean_rcs_keywords(para, self.rcs_keyword_substitutions) - if cvs_url: - date = para.astext() - para[:] = [nodes.reference('', date, refuri=cvs_url)] - elif name == 'content-type': - pep_type = para.astext() - uri = self.pep_url % 12 - para[:] = [nodes.reference('', pep_type, refuri=uri)] - elif name == 'version' and len(body): - utils.clean_rcs_keywords(para, self.rcs_keyword_substitutions) - - -class Contents(Transform): - - """ - Insert a table of contents transform placeholder into the document after - the RFC 2822 header. - """ - - default_priority = 380 - - def apply(self): - pending = nodes.pending(parts.Contents, {'title': None}) - self.document.insert(1, pending) - self.document.note_pending(pending) - - -class TargetNotes(Transform): - - """ - Locate the "References" section, insert a placeholder for an external - target footnote insertion transform at the end, and schedule the - transform to run immediately. - """ - - default_priority = 520 - - def apply(self): - doc = self.document - i = len(doc) - 1 - refsect = copyright = None - while i >= 0 and isinstance(doc[i], nodes.section): - title_words = doc[i][0].astext().lower().split() - if 'references' in title_words: - refsect = doc[i] - break - elif 'copyright' in title_words: - copyright = i - i -= 1 - if not refsect: - refsect = nodes.section() - refsect += nodes.title('', 'References') - doc.set_id(refsect) - if copyright: - # Put the new "References" section before "Copyright": - doc.insert(copyright, refsect) - else: - # Put the new "References" section at end of doc: - doc.append(refsect) - pending = nodes.pending(references.TargetNotes) - refsect.append(pending) - self.document.note_pending(pending, 0) - pending = nodes.pending(misc.CallBack, - details={'callback': self.cleanup_callback}) - refsect.append(pending) - self.document.note_pending(pending, 1) - - def cleanup_callback(self, pending): - """ - Remove an empty "References" section. - - Called after the `references.TargetNotes` transform is complete. - """ - if len(pending.parent) == 2: # <title> and <pending> - pending.parent.parent.remove(pending.parent) - - -class PEPZero(Transform): - - """ - Special processing for PEP 0. - """ - - default_priority =760 - - def apply(self): - visitor = PEPZeroSpecial(self.document) - self.document.walk(visitor) - self.startnode.parent.remove(self.startnode) - - -class PEPZeroSpecial(nodes.SparseNodeVisitor): - - """ - Perform the special processing needed by PEP 0: - - - Mask email addresses. - - - Link PEP numbers in the second column of 4-column tables to the PEPs - themselves. - """ - - pep_url = Headers.pep_url - - def unknown_visit(self, node): - pass - - def visit_reference(self, node): - node.parent.replace(node, mask_email(node)) - - def visit_field_list(self, node): - if node.hasattr('class') and node['class'] == 'rfc2822': - raise nodes.SkipNode - - def visit_tgroup(self, node): - self.pep_table = node['cols'] == 4 - self.entry = 0 - - def visit_colspec(self, node): - self.entry += 1 - if self.pep_table and self.entry == 2: - node['class'] = 'num' - - def visit_row(self, node): - self.entry = 0 - - def visit_entry(self, node): - self.entry += 1 - if self.pep_table and self.entry == 2 and len(node) == 1: - node['class'] = 'num' - p = node[0] - if isinstance(p, nodes.paragraph) and len(p) == 1: - text = p.astext() - try: - pep = int(text) - ref = self.pep_url % pep - p[0] = nodes.reference(text, text, refuri=ref) - except ValueError: - pass - - -non_masked_addresses = ('peps@python.org', - 'python-list@python.org', - 'python-dev@python.org') - -def mask_email(ref, pepno=None): - """ - Mask the email address in `ref` and return a replacement node. - - `ref` is returned unchanged if it contains no email address. - - For email addresses such as "user@host", mask the address as "user at - host" (text) to thwart simple email address harvesters (except for those - listed in `non_masked_addresses`). If a PEP number (`pepno`) is given, - return a reference including a default email subject. - """ - if ref.hasattr('refuri') and ref['refuri'].startswith('mailto:'): - if ref['refuri'][8:] in non_masked_addresses: - replacement = ref[0] - else: - replacement_text = ref.astext().replace('@', ' at ') - replacement = nodes.raw('', replacement_text, format='html') - if pepno is None: - return replacement - else: - ref['refuri'] += '?subject=PEP%%20%s' % pepno - ref[:] = [replacement] - return ref - else: - return ref diff --git a/docutils/docutils/transforms/references.py b/docutils/docutils/transforms/references.py deleted file mode 100644 index c754ee05c..000000000 --- a/docutils/docutils/transforms/references.py +++ /dev/null @@ -1,762 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Transforms for resolving references. -""" - -__docformat__ = 'reStructuredText' - -import sys -import re -from docutils import nodes, utils -from docutils.transforms import TransformError, Transform - - -indices = xrange(sys.maxint) - - -class ChainedTargets(Transform): - - """ - Attributes "refuri" and "refname" are migrated from the final direct - target up the chain of contiguous adjacent internal targets, using - `ChainedTargetResolver`. - """ - - default_priority = 420 - - def apply(self): - visitor = ChainedTargetResolver(self.document) - self.document.walk(visitor) - - -class ChainedTargetResolver(nodes.SparseNodeVisitor): - - """ - Copy reference attributes up the length of a hyperlink target chain. - - "Chained targets" are multiple adjacent internal hyperlink targets which - "point to" an external or indirect target. After the transform, all - chained targets will effectively point to the same place. - - Given the following ``document`` as input:: - - <document> - <target id="a" name="a"> - <target id="b" name="b"> - <target id="c" name="c" refuri="http://chained.external.targets"> - <target id="d" name="d"> - <paragraph> - I'm known as "d". - <target id="e" name="e"> - <target id="id1"> - <target id="f" name="f" refname="d"> - - ``ChainedTargetResolver(document).walk()`` will transform the above into:: - - <document> - <target id="a" name="a" refuri="http://chained.external.targets"> - <target id="b" name="b" refuri="http://chained.external.targets"> - <target id="c" name="c" refuri="http://chained.external.targets"> - <target id="d" name="d"> - <paragraph> - I'm known as "d". - <target id="e" name="e" refname="d"> - <target id="id1" refname="d"> - <target id="f" name="f" refname="d"> - """ - - def unknown_visit(self, node): - pass - - def visit_target(self, node): - if node.hasattr('refuri'): - attname = 'refuri' - call_if_named = self.document.note_external_target - elif node.hasattr('refname'): - attname = 'refname' - call_if_named = self.document.note_indirect_target - elif node.hasattr('refid'): - attname = 'refid' - call_if_named = None - else: - return - attval = node[attname] - index = node.parent.index(node) - for i in range(index - 1, -1, -1): - sibling = node.parent[i] - if not isinstance(sibling, nodes.target) \ - or sibling.hasattr('refuri') \ - or sibling.hasattr('refname') \ - or sibling.hasattr('refid'): - break - sibling[attname] = attval - if sibling.hasattr('name') and call_if_named: - call_if_named(sibling) - - -class AnonymousHyperlinks(Transform): - - """ - Link anonymous references to targets. Given:: - - <paragraph> - <reference anonymous="1"> - internal - <reference anonymous="1"> - external - <target anonymous="1" id="id1"> - <target anonymous="1" id="id2" refuri="http://external"> - - Corresponding references are linked via "refid" or resolved via "refuri":: - - <paragraph> - <reference anonymous="1" refid="id1"> - text - <reference anonymous="1" refuri="http://external"> - external - <target anonymous="1" id="id1"> - <target anonymous="1" id="id2" refuri="http://external"> - """ - - default_priority = 440 - - def apply(self): - if len(self.document.anonymous_refs) \ - != len(self.document.anonymous_targets): - msg = self.document.reporter.error( - 'Anonymous hyperlink mismatch: %s references but %s ' - 'targets.\nSee "backrefs" attribute for IDs.' - % (len(self.document.anonymous_refs), - len(self.document.anonymous_targets))) - msgid = self.document.set_id(msg) - for ref in self.document.anonymous_refs: - prb = nodes.problematic( - ref.rawsource, ref.rawsource, refid=msgid) - prbid = self.document.set_id(prb) - msg.add_backref(prbid) - ref.parent.replace(ref, prb) - return - for ref, target in zip(self.document.anonymous_refs, - self.document.anonymous_targets): - if target.hasattr('refuri'): - ref['refuri'] = target['refuri'] - ref.resolved = 1 - else: - ref['refid'] = target['id'] - self.document.note_refid(ref) - target.referenced = 1 - - -class IndirectHyperlinks(Transform): - - """ - a) Indirect external references:: - - <paragraph> - <reference refname="indirect external"> - indirect external - <target id="id1" name="direct external" - refuri="http://indirect"> - <target id="id2" name="indirect external" - refname="direct external"> - - The "refuri" attribute is migrated back to all indirect targets - from the final direct target (i.e. a target not referring to - another indirect target):: - - <paragraph> - <reference refname="indirect external"> - indirect external - <target id="id1" name="direct external" - refuri="http://indirect"> - <target id="id2" name="indirect external" - refuri="http://indirect"> - - Once the attribute is migrated, the preexisting "refname" attribute - is dropped. - - b) Indirect internal references:: - - <target id="id1" name="final target"> - <paragraph> - <reference refname="indirect internal"> - indirect internal - <target id="id2" name="indirect internal 2" - refname="final target"> - <target id="id3" name="indirect internal" - refname="indirect internal 2"> - - Targets which indirectly refer to an internal target become one-hop - indirect (their "refid" attributes are directly set to the internal - target's "id"). References which indirectly refer to an internal - target become direct internal references:: - - <target id="id1" name="final target"> - <paragraph> - <reference refid="id1"> - indirect internal - <target id="id2" name="indirect internal 2" refid="id1"> - <target id="id3" name="indirect internal" refid="id1"> - """ - - default_priority = 460 - - def apply(self): - for target in self.document.indirect_targets: - if not target.resolved: - self.resolve_indirect_target(target) - self.resolve_indirect_references(target) - - def resolve_indirect_target(self, target): - refname = target['refname'] - reftarget_id = self.document.nameids.get(refname) - if not reftarget_id: - self.nonexistent_indirect_target(target) - return - reftarget = self.document.ids[reftarget_id] - if isinstance(reftarget, nodes.target) \ - and not reftarget.resolved and reftarget.hasattr('refname'): - if hasattr(target, 'multiply_indirect'): - #and target.multiply_indirect): - #del target.multiply_indirect - self.circular_indirect_reference(target) - return - target.multiply_indirect = 1 - self.resolve_indirect_target(reftarget) # multiply indirect - del target.multiply_indirect - if reftarget.hasattr('refuri'): - target['refuri'] = reftarget['refuri'] - if target.hasattr('name'): - self.document.note_external_target(target) - elif reftarget.hasattr('refid'): - target['refid'] = reftarget['refid'] - self.document.note_refid(target) - else: - try: - target['refid'] = reftarget['id'] - self.document.note_refid(target) - except KeyError: - self.nonexistent_indirect_target(target) - return - del target['refname'] - target.resolved = 1 - reftarget.referenced = 1 - - def nonexistent_indirect_target(self, target): - self.indirect_target_error(target, 'which does not exist') - - def circular_indirect_reference(self, target): - self.indirect_target_error(target, 'forming a circular reference') - - def indirect_target_error(self, target, explanation): - naming = '' - if target.hasattr('name'): - naming = '"%s" ' % target['name'] - reflist = self.document.refnames.get(target['name'], []) - else: - reflist = self.document.refids.get(target['id'], []) - naming += '(id="%s")' % target['id'] - msg = self.document.reporter.error( - 'Indirect hyperlink target %s refers to target "%s", %s.' - % (naming, target['refname'], explanation), - base_node=target) - msgid = self.document.set_id(msg) - for ref in reflist: - prb = nodes.problematic( - ref.rawsource, ref.rawsource, refid=msgid) - prbid = self.document.set_id(prb) - msg.add_backref(prbid) - ref.parent.replace(ref, prb) - target.resolved = 1 - - def resolve_indirect_references(self, target): - if target.hasattr('refid'): - attname = 'refid' - call_if_named = 0 - call_method = self.document.note_refid - elif target.hasattr('refuri'): - attname = 'refuri' - call_if_named = 1 - call_method = self.document.note_external_target - else: - return - attval = target[attname] - if target.hasattr('name'): - name = target['name'] - try: - reflist = self.document.refnames[name] - except KeyError, instance: - if target.referenced: - return - msg = self.document.reporter.info( - 'Indirect hyperlink target "%s" is not referenced.' - % name, base_node=target) - target.referenced = 1 - return - delatt = 'refname' - else: - id = target['id'] - try: - reflist = self.document.refids[id] - except KeyError, instance: - if target.referenced: - return - msg = self.document.reporter.info( - 'Indirect hyperlink target id="%s" is not referenced.' - % id, base_node=target) - target.referenced = 1 - return - delatt = 'refid' - for ref in reflist: - if ref.resolved: - continue - del ref[delatt] - ref[attname] = attval - if not call_if_named or ref.hasattr('name'): - call_method(ref) - ref.resolved = 1 - if isinstance(ref, nodes.target): - self.resolve_indirect_references(ref) - target.referenced = 1 - - -class ExternalTargets(Transform): - - """ - Given:: - - <paragraph> - <reference refname="direct external"> - direct external - <target id="id1" name="direct external" refuri="http://direct"> - - The "refname" attribute is replaced by the direct "refuri" attribute:: - - <paragraph> - <reference refuri="http://direct"> - direct external - <target id="id1" name="direct external" refuri="http://direct"> - """ - - default_priority = 640 - - def apply(self): - for target in self.document.external_targets: - if target.hasattr('refuri') and target.hasattr('name'): - name = target['name'] - refuri = target['refuri'] - try: - reflist = self.document.refnames[name] - except KeyError, instance: - if target.referenced: - continue - msg = self.document.reporter.info( - 'External hyperlink target "%s" is not referenced.' - % name, base_node=target) - target.referenced = 1 - continue - for ref in reflist: - if ref.resolved: - continue - del ref['refname'] - ref['refuri'] = refuri - ref.resolved = 1 - target.referenced = 1 - - -class InternalTargets(Transform): - - """ - Given:: - - <paragraph> - <reference refname="direct internal"> - direct internal - <target id="id1" name="direct internal"> - - The "refname" attribute is replaced by "refid" linking to the target's - "id":: - - <paragraph> - <reference refid="id1"> - direct internal - <target id="id1" name="direct internal"> - """ - - default_priority = 660 - - def apply(self): - for target in self.document.internal_targets: - if target.hasattr('refuri') or target.hasattr('refid') \ - or not target.hasattr('name'): - continue - name = target['name'] - refid = target['id'] - try: - reflist = self.document.refnames[name] - except KeyError, instance: - if target.referenced: - continue - msg = self.document.reporter.info( - 'Internal hyperlink target "%s" is not referenced.' - % name, base_node=target) - target.referenced = 1 - continue - for ref in reflist: - if ref.resolved: - continue - del ref['refname'] - ref['refid'] = refid - ref.resolved = 1 - target.referenced = 1 - - -class Footnotes(Transform): - - """ - Assign numbers to autonumbered footnotes, and resolve links to footnotes, - citations, and their references. - - Given the following ``document`` as input:: - - <document> - <paragraph> - A labeled autonumbered footnote referece: - <footnote_reference auto="1" id="id1" refname="footnote"> - <paragraph> - An unlabeled autonumbered footnote referece: - <footnote_reference auto="1" id="id2"> - <footnote auto="1" id="id3"> - <paragraph> - Unlabeled autonumbered footnote. - <footnote auto="1" id="footnote" name="footnote"> - <paragraph> - Labeled autonumbered footnote. - - Auto-numbered footnotes have attribute ``auto="1"`` and no label. - Auto-numbered footnote_references have no reference text (they're - empty elements). When resolving the numbering, a ``label`` element - is added to the beginning of the ``footnote``, and reference text - to the ``footnote_reference``. - - The transformed result will be:: - - <document> - <paragraph> - A labeled autonumbered footnote referece: - <footnote_reference auto="1" id="id1" refid="footnote"> - 2 - <paragraph> - An unlabeled autonumbered footnote referece: - <footnote_reference auto="1" id="id2" refid="id3"> - 1 - <footnote auto="1" id="id3" backrefs="id2"> - <label> - 1 - <paragraph> - Unlabeled autonumbered footnote. - <footnote auto="1" id="footnote" name="footnote" backrefs="id1"> - <label> - 2 - <paragraph> - Labeled autonumbered footnote. - - Note that the footnotes are not in the same order as the references. - - The labels and reference text are added to the auto-numbered ``footnote`` - and ``footnote_reference`` elements. Footnote elements are backlinked to - their references via "refids" attributes. References are assigned "id" - and "refid" attributes. - - After adding labels and reference text, the "auto" attributes can be - ignored. - """ - - default_priority = 620 - - autofootnote_labels = None - """Keep track of unlabeled autonumbered footnotes.""" - - symbols = [ - # Entries 1-4 and 6 below are from section 12.51 of - # The Chicago Manual of Style, 14th edition. - '*', # asterisk/star - u'\u2020', # dagger † - u'\u2021', # double dagger ‡ - u'\u00A7', # section mark § - u'\u00B6', # paragraph mark (pilcrow) ¶ - # (parallels ['||'] in CMoS) - '#', # number sign - # The entries below were chosen arbitrarily. - u'\u2660', # spade suit ♠ - u'\u2665', # heart suit ♥ - u'\u2666', # diamond suit ♦ - u'\u2663', # club suit ♣ - ] - - def apply(self): - self.autofootnote_labels = [] - startnum = self.document.autofootnote_start - self.document.autofootnote_start = self.number_footnotes(startnum) - self.number_footnote_references(startnum) - self.symbolize_footnotes() - self.resolve_footnotes_and_citations() - - def number_footnotes(self, startnum): - """ - Assign numbers to autonumbered footnotes. - - For labeled autonumbered footnotes, copy the number over to - corresponding footnote references. - """ - for footnote in self.document.autofootnotes: - while 1: - label = str(startnum) - startnum += 1 - if not self.document.nameids.has_key(label): - break - footnote.insert(0, nodes.label('', label)) - if footnote.hasattr('dupname'): - continue - if footnote.hasattr('name'): - name = footnote['name'] - for ref in self.document.footnote_refs.get(name, []): - ref += nodes.Text(label) - ref.delattr('refname') - ref['refid'] = footnote['id'] - footnote.add_backref(ref['id']) - self.document.note_refid(ref) - ref.resolved = 1 - else: - footnote['name'] = label - self.document.note_explicit_target(footnote, footnote) - self.autofootnote_labels.append(label) - return startnum - - def number_footnote_references(self, startnum): - """Assign numbers to autonumbered footnote references.""" - i = 0 - for ref in self.document.autofootnote_refs: - if ref.resolved or ref.hasattr('refid'): - continue - try: - label = self.autofootnote_labels[i] - except IndexError: - msg = self.document.reporter.error( - 'Too many autonumbered footnote references: only %s ' - 'corresponding footnotes available.' - % len(self.autofootnote_labels), base_node=ref) - msgid = self.document.set_id(msg) - for ref in self.document.autofootnote_refs[i:]: - if ref.resolved or ref.hasattr('refname'): - continue - prb = nodes.problematic( - ref.rawsource, ref.rawsource, refid=msgid) - prbid = self.document.set_id(prb) - msg.add_backref(prbid) - ref.parent.replace(ref, prb) - break - ref += nodes.Text(label) - id = self.document.nameids[label] - footnote = self.document.ids[id] - ref['refid'] = id - self.document.note_refid(ref) - footnote.add_backref(ref['id']) - ref.resolved = 1 - i += 1 - - def symbolize_footnotes(self): - """Add symbols indexes to "[*]"-style footnotes and references.""" - labels = [] - for footnote in self.document.symbol_footnotes: - reps, index = divmod(self.document.symbol_footnote_start, - len(self.symbols)) - labeltext = self.symbols[index] * (reps + 1) - labels.append(labeltext) - footnote.insert(0, nodes.label('', labeltext)) - self.document.symbol_footnote_start += 1 - self.document.set_id(footnote) - i = 0 - for ref in self.document.symbol_footnote_refs: - try: - ref += nodes.Text(labels[i]) - except IndexError: - msg = self.document.reporter.error( - 'Too many symbol footnote references: only %s ' - 'corresponding footnotes available.' % len(labels), - base_node=ref) - msgid = self.document.set_id(msg) - for ref in self.document.symbol_footnote_refs[i:]: - if ref.resolved or ref.hasattr('refid'): - continue - prb = nodes.problematic( - ref.rawsource, ref.rawsource, refid=msgid) - prbid = self.document.set_id(prb) - msg.add_backref(prbid) - ref.parent.replace(ref, prb) - break - footnote = self.document.symbol_footnotes[i] - ref['refid'] = footnote['id'] - self.document.note_refid(ref) - footnote.add_backref(ref['id']) - i += 1 - - def resolve_footnotes_and_citations(self): - """ - Link manually-labeled footnotes and citations to/from their - references. - """ - for footnote in self.document.footnotes: - label = footnote['name'] - if self.document.footnote_refs.has_key(label): - reflist = self.document.footnote_refs[label] - self.resolve_references(footnote, reflist) - for citation in self.document.citations: - label = citation['name'] - if self.document.citation_refs.has_key(label): - reflist = self.document.citation_refs[label] - self.resolve_references(citation, reflist) - - def resolve_references(self, note, reflist): - id = note['id'] - for ref in reflist: - if ref.resolved: - continue - ref.delattr('refname') - ref['refid'] = id - note.add_backref(ref['id']) - ref.resolved = 1 - note.resolved = 1 - - -class Substitutions(Transform): - - """ - Given the following ``document`` as input:: - - <document> - <paragraph> - The - <substitution_reference refname="biohazard"> - biohazard - symbol is deservedly scary-looking. - <substitution_definition name="biohazard"> - <image alt="biohazard" uri="biohazard.png"> - - The ``substitution_reference`` will simply be replaced by the - contents of the corresponding ``substitution_definition``. - - The transformed result will be:: - - <document> - <paragraph> - The - <image alt="biohazard" uri="biohazard.png"> - symbol is deservedly scary-looking. - <substitution_definition name="biohazard"> - <image alt="biohazard" uri="biohazard.png"> - """ - - default_priority = 220 - """The Substitutions transform has to be applied very early, before - `docutils.tranforms.frontmatter.DocTitle` and others.""" - - def apply(self): - defs = self.document.substitution_defs - normed = self.document.substitution_names - for refname, refs in self.document.substitution_refs.items(): - for ref in refs: - key = None - if defs.has_key(refname): - key = refname - else: - normed_name = refname.lower() - if normed.has_key(normed_name): - key = normed[normed_name] - if key is None: - msg = self.document.reporter.error( - 'Undefined substitution referenced: "%s".' - % refname, base_node=ref) - msgid = self.document.set_id(msg) - prb = nodes.problematic( - ref.rawsource, ref.rawsource, refid=msgid) - prbid = self.document.set_id(prb) - msg.add_backref(prbid) - ref.parent.replace(ref, prb) - else: - ref.parent.replace(ref, defs[key].get_children()) - self.document.substitution_refs = None # release replaced references - - -class TargetNotes(Transform): - - """ - Creates a footnote for each external target in the text, and corresponding - footnote references after each reference. - """ - - default_priority = 540 - """The TargetNotes transform has to be applied after `IndirectHyperlinks` - but before `Footnotes`.""" - - def apply(self): - notes = {} - nodelist = [] - for target in self.document.external_targets: - name = target.get('name') - if not name: - print >>sys.stderr, 'no name on target: %r' % target - continue - refs = self.document.refnames.get(name, []) - if not refs: - continue - footnote = self.make_target_footnote(target, refs, notes) - if not notes.has_key(target['refuri']): - notes[target['refuri']] = footnote - nodelist.append(footnote) - if len(self.document.anonymous_targets) \ - == len(self.document.anonymous_refs): - for target, ref in zip(self.document.anonymous_targets, - self.document.anonymous_refs): - if target.hasattr('refuri'): - footnote = self.make_target_footnote(target, [ref], notes) - if not notes.has_key(target['refuri']): - notes[target['refuri']] = footnote - nodelist.append(footnote) - self.startnode.parent.replace(self.startnode, nodelist) - - def make_target_footnote(self, target, refs, notes): - refuri = target['refuri'] - if notes.has_key(refuri): # duplicate? - footnote = notes[refuri] - footnote_name = footnote['name'] - else: # original - footnote = nodes.footnote() - footnote_id = self.document.set_id(footnote) - # Use a colon; they can't be produced inside names by the parser: - footnote_name = 'target_note: ' + footnote_id - footnote['auto'] = 1 - footnote['name'] = footnote_name - footnote_paragraph = nodes.paragraph() - footnote_paragraph += nodes.reference('', refuri, refuri=refuri) - footnote += footnote_paragraph - self.document.note_autofootnote(footnote) - self.document.note_explicit_target(footnote, footnote) - for ref in refs: - if isinstance(ref, nodes.target): - continue - refnode = nodes.footnote_reference( - refname=footnote_name, auto=1) - self.document.note_autofootnote_ref(refnode) - self.document.note_footnote_ref(refnode) - index = ref.parent.index(ref) + 1 - reflist = [refnode] - if not self.document.settings.trim_footnote_reference_space: - reflist.insert(0, nodes.Text(' ')) - ref.parent.insert(index, reflist) - return footnote diff --git a/docutils/docutils/transforms/universal.py b/docutils/docutils/transforms/universal.py deleted file mode 100644 index 4523304f2..000000000 --- a/docutils/docutils/transforms/universal.py +++ /dev/null @@ -1,185 +0,0 @@ -# Authors: David Goodger, Ueli Schlaepfer -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Transforms needed by most or all documents: - -- `Decorations`: Generate a document's header & footer. -- `Messages`: Placement of system messages stored in - `nodes.document.transform_messages`. -- `TestMessages`: Like `Messages`, used on test runs. -- `FinalReferences`: Resolve remaining references. -""" - -__docformat__ = 'reStructuredText' - -import re -import sys -import time -from docutils import nodes, utils -from docutils.transforms import TransformError, Transform - - -class Decorations(Transform): - - """ - Populate a document's decoration element (header, footer). - """ - - default_priority = 820 - - def apply(self): - header = self.generate_header() - footer = self.generate_footer() - if header or footer: - decoration = nodes.decoration() - decoration += header - decoration += footer - document = self.document - index = document.first_child_not_matching_class( - nodes.PreDecorative) - if index is None: - document += decoration - else: - document[index:index] = [decoration] - - def generate_header(self): - return None - - def generate_footer(self): - # @@@ Text is hard-coded for now. - # Should be made dynamic (language-dependent). - settings = self.document.settings - if settings.generator or settings.datestamp or settings.source_link \ - or settings.source_url: - text = [] - if settings.source_link and settings._source \ - or settings.source_url: - if settings.source_url: - source = settings.source_url - else: - source = utils.relative_path(settings._destination, - settings._source) - text.extend([ - nodes.reference('', 'View document source', - refuri=source), - nodes.Text('.\n')]) - if settings.datestamp: - datestamp = time.strftime(settings.datestamp, time.gmtime()) - text.append(nodes.Text('Generated on: ' + datestamp + '.\n')) - if settings.generator: - text.extend([ - nodes.Text('Generated by '), - nodes.reference('', 'Docutils', refuri= - 'http://docutils.sourceforge.net/'), - nodes.Text(' from '), - nodes.reference('', 'reStructuredText', refuri='http://' - 'docutils.sourceforge.net/rst.html'), - nodes.Text(' source.\n')]) - footer = nodes.footer() - footer += nodes.paragraph('', '', *text) - return footer - else: - return None - - -class Messages(Transform): - - """ - Place any system messages generated after parsing into a dedicated section - of the document. - """ - - default_priority = 860 - - def apply(self): - unfiltered = self.document.transform_messages - threshold = self.document.reporter['writer'].report_level - messages = [] - for msg in unfiltered: - if msg['level'] >= threshold and not msg.parent: - messages.append(msg) - if messages: - section = nodes.section(CLASS='system-messages') - # @@@ get this from the language module? - section += nodes.title('', 'Docutils System Messages') - section += messages - self.document.transform_messages[:] = [] - self.document += section - - -class TestMessages(Transform): - - """ - Append all post-parse system messages to the end of the document. - """ - - default_priority = 890 - - def apply(self): - for msg in self.document.transform_messages: - if not msg.parent: - self.document += msg - - -class FinalChecks(Transform): - - """ - Perform last-minute checks. - - - Check for dangling references (incl. footnote & citation). - """ - - default_priority = 840 - - def apply(self): - visitor = FinalCheckVisitor(self.document) - self.document.walk(visitor) - if self.document.settings.expose_internals: - visitor = InternalAttributeExposer(self.document) - self.document.walk(visitor) - - -class FinalCheckVisitor(nodes.SparseNodeVisitor): - - def unknown_visit(self, node): - pass - - def visit_reference(self, node): - if node.resolved or not node.hasattr('refname'): - return - refname = node['refname'] - id = self.document.nameids.get(refname) - if id is None: - msg = self.document.reporter.error( - 'Unknown target name: "%s".' % (node['refname']), - base_node=node) - msgid = self.document.set_id(msg) - prb = nodes.problematic( - node.rawsource, node.rawsource, refid=msgid) - prbid = self.document.set_id(prb) - msg.add_backref(prbid) - node.parent.replace(node, prb) - else: - del node['refname'] - node['refid'] = id - self.document.ids[id].referenced = 1 - node.resolved = 1 - - visit_footnote_reference = visit_citation_reference = visit_reference - - -class InternalAttributeExposer(nodes.GenericNodeVisitor): - - def __init__(self, document): - nodes.GenericNodeVisitor.__init__(self, document) - self.internal_attributes = document.settings.expose_internals - - def default_visit(self, node): - for att in self.internal_attributes: - value = getattr(node, att, None) - if value is not None: - node['internal:' + att] = value diff --git a/docutils/docutils/urischemes.py b/docutils/docutils/urischemes.py deleted file mode 100644 index 6eb45820a..000000000 --- a/docutils/docutils/urischemes.py +++ /dev/null @@ -1,105 +0,0 @@ -""" -`schemes` is a dictionary with lowercase URI addressing schemes as -keys and descriptions as values. It was compiled from the index at -http://www.w3.org/Addressing/schemes.html (revised 2001-08-20). -""" - -# Many values are blank and should be filled in with useful descriptions. - -schemes = { - 'about': 'provides information on Navigator', - 'acap': 'Application Configuration Access Protocol', - 'addbook': "To add vCard entries to Communicator's Address Book", - 'afp': 'Apple Filing Protocol', - 'afs': 'Andrew File System global file names', - 'aim': 'AOL Instant Messenger', - 'callto': 'for NetMeeting links', - 'castanet': 'Castanet Tuner URLs for Netcaster', - 'chttp': 'cached HTTP supported by RealPlayer', - 'cid': 'content identifier', - 'data': ('allows inclusion of small data items as "immediate" data; ' - 'RFC 2397'), - 'dav': 'Distributed Authoring and Versioning Protocol; RFC 2518', - 'dns': 'Domain Name System resources', - 'eid': ('External ID; non-URL data; general escape mechanism to allow ' - 'access to information for applications that are too ' - 'specialized to justify their own schemes'), - 'fax': ('a connection to a terminal that can handle telefaxes ' - '(facsimiles); RFC 2806'), - 'file': 'Host-specific file names', - 'finger': '', - 'freenet': '', - 'ftp': 'File Transfer Protocol', - 'gopher': 'The Gopher Protocol', - 'gsm-sms': ('Global System for Mobile Communications Short Message ' - 'Service'), - 'h323': 'video (audiovisual) communication on local area networks', - 'h324': ('video and audio communications over low bitrate connections ' - 'such as POTS modem connections'), - 'hdl': 'CNRI handle system', - 'hnews': 'an HTTP-tunneling variant of the NNTP news protocol', - 'http': 'Hypertext Transfer Protocol', - 'https': 'HTTP over SSL', - 'iioploc': 'Internet Inter-ORB Protocol Location?', - 'ilu': 'Inter-Language Unification', - 'imap': 'Internet Message Access Protocol', - 'ior': 'CORBA interoperable object reference', - 'ipp': 'Internet Printing Protocol', - 'irc': 'Internet Relay Chat', - 'jar': 'Java archive', - 'javascript': ('JavaScript code; evaluates the expression after the ' - 'colon'), - 'jdbc': '', - 'ldap': 'Lightweight Directory Access Protocol', - 'lifn': '', - 'livescript': '', - 'lrq': '', - 'mailbox': 'Mail folder access', - 'mailserver': 'Access to data available from mail servers', - 'mailto': 'Electronic mail address', - 'md5': '', - 'mid': 'message identifier', - 'mocha': '', - 'modem': ('a connection to a terminal that can handle incoming data ' - 'calls; RFC 2806'), - 'news': 'USENET news', - 'nfs': 'Network File System protocol', - 'nntp': 'USENET news using NNTP access', - 'opaquelocktoken': '', - 'phone': '', - 'pop': 'Post Office Protocol', - 'pop3': 'Post Office Protocol v3', - 'printer': '', - 'prospero': 'Prospero Directory Service', - 'res': '', - 'rtsp': 'real time streaming protocol', - 'rvp': '', - 'rwhois': '', - 'rx': 'Remote Execution', - 'sdp': '', - 'service': 'service location', - 'shttp': 'secure hypertext transfer protocol', - 'sip': 'Session Initiation Protocol', - 'smb': '', - 'snews': 'For NNTP postings via SSL', - 't120': 'real time data conferencing (audiographics)', - 'tcp': '', - 'tel': ('a connection to a terminal that handles normal voice ' - 'telephone calls, a voice mailbox or another voice messaging ' - 'system or a service that can be operated using DTMF tones; ' - 'RFC 2806.'), - 'telephone': 'telephone', - 'telnet': 'Reference to interactive sessions', - 'tip': 'Transaction Internet Protocol', - 'tn3270': 'Interactive 3270 emulation sessions', - 'tv': '', - 'urn': 'Uniform Resource Name', - 'uuid': '', - 'vemmi': 'versatile multimedia interface', - 'videotex': '', - 'view-source': 'displays HTML code that was generated with JavaScript', - 'wais': 'Wide Area Information Servers', - 'whodp': '', - 'whois++': 'Distributed directory service.', - 'z39.50r': 'Z39.50 Retrieval', - 'z39.50s': 'Z39.50 Session',} diff --git a/docutils/docutils/utils.py b/docutils/docutils/utils.py deleted file mode 100644 index 2e60a6c6f..000000000 --- a/docutils/docutils/utils.py +++ /dev/null @@ -1,447 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Miscellaneous utilities for the documentation utilities. -""" - -__docformat__ = 'reStructuredText' - -import sys -import os -import os.path -from types import StringType, UnicodeType -from docutils import ApplicationError, DataError -from docutils import frontend, nodes - - -class SystemMessage(ApplicationError): - - def __init__(self, system_message, level): - Exception.__init__(self, system_message.astext()) - self.level = level - - -class Reporter: - - """ - Info/warning/error reporter and ``system_message`` element generator. - - Five levels of system messages are defined, along with corresponding - methods: `debug()`, `info()`, `warning()`, `error()`, and `severe()`. - - There is typically one Reporter object per process. A Reporter object is - instantiated with thresholds for reporting (generating warnings) and - halting processing (raising exceptions), a switch to turn debug output on - or off, and an I/O stream for warnings. These are stored in the default - reporting category, '' (zero-length string). - - Multiple reporting categories [#]_ may be set, each with its own reporting - and halting thresholds, debugging switch, and warning stream - (collectively a `ConditionSet`). Categories are hierarchical dotted-name - strings that look like attribute references: 'spam', 'spam.eggs', - 'neeeow.wum.ping'. The 'spam' category is the ancestor of - 'spam.bacon.eggs'. Unset categories inherit stored conditions from their - closest ancestor category that has been set. - - When a system message is generated, the stored conditions from its - category (or ancestor if unset) are retrieved. The system message level - is compared to the thresholds stored in the category, and a warning or - error is generated as appropriate. Debug messages are produced iff the - stored debug switch is on. Message output is sent to the stored warning - stream. - - The default category is '' (empty string). By convention, Writers should - retrieve reporting conditions from the 'writer' category (which, unless - explicitly set, defaults to the conditions of the default category). - - The Reporter class also employs a modified form of the "Observer" pattern - [GoF95]_ to track system messages generated. The `attach_observer` method - should be called before parsing, with a bound method or function which - accepts system messages. The observer can be removed with - `detach_observer`, and another added in its place. - - .. [#] The concept of "categories" was inspired by the log4j project: - http://jakarta.apache.org/log4j/. - - .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of - Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA, - 1995. - """ - - levels = 'DEBUG INFO WARNING ERROR SEVERE'.split() - """List of names for system message levels, indexed by level.""" - - def __init__(self, source, report_level, halt_level, stream=None, - debug=0, encoding='ascii', error_handler='replace'): - """ - Initialize the `ConditionSet` forthe `Reporter`'s default category. - - :Parameters: - - - `source`: The path to or description of the source data. - - `report_level`: The level at or above which warning output will - be sent to `stream`. - - `halt_level`: The level at or above which `SystemMessage` - exceptions will be raised, halting execution. - - `debug`: Show debug (level=0) system messages? - - `stream`: Where warning output is sent. Can be file-like (has a - ``.write`` method), a string (file name, opened for writing), or - `None` (implies `sys.stderr`; default). - - `encoding`: The encoding for stderr output. - - `error_handler`: The error handler for stderr output encoding. - """ - self.source = source - """The path to or description of the source data.""" - - if stream is None: - stream = sys.stderr - elif type(stream) in (StringType, UnicodeType): - raise NotImplementedError('This should open a file for writing.') - - self.encoding = encoding - """The character encoding for the stderr output.""" - - self.error_handler = error_handler - """The character encoding error handler.""" - - self.categories = {'': ConditionSet(debug, report_level, halt_level, - stream)} - """Mapping of category names to conditions. Default category is ''.""" - - self.observers = [] - """List of bound methods or functions to call with each system_message - created.""" - - self.max_level = -1 - """The highest level system message generated so far.""" - - def set_conditions(self, category, report_level, halt_level, - stream=None, debug=0): - if stream is None: - stream = sys.stderr - self.categories[category] = ConditionSet(debug, report_level, - halt_level, stream) - - def unset_conditions(self, category): - if category and self.categories.has_key(category): - del self.categories[category] - - __delitem__ = unset_conditions - - def get_conditions(self, category): - while not self.categories.has_key(category): - category = category[:category.rfind('.') + 1][:-1] - return self.categories[category] - - __getitem__ = get_conditions - - def attach_observer(self, observer): - """ - The `observer` parameter is a function or bound method which takes one - argument, a `nodes.system_message` instance. - """ - self.observers.append(observer) - - def detach_observer(self, observer): - self.observers.remove(observer) - - def notify_observers(self, message): - for observer in self.observers: - observer(message) - - def system_message(self, level, message, *children, **kwargs): - """ - Return a system_message object. - - Raise an exception or generate a warning if appropriate. - """ - attributes = kwargs.copy() - category = kwargs.get('category', '') - if kwargs.has_key('category'): - del attributes['category'] - if kwargs.has_key('base_node'): - source, line = get_source_line(kwargs['base_node']) - del attributes['base_node'] - if source is not None: - attributes.setdefault('source', source) - if line is not None: - attributes.setdefault('line', line) - attributes.setdefault('source', self.source) - msg = nodes.system_message(message, level=level, - type=self.levels[level], - *children, **attributes) - debug, report_level, halt_level, stream = self[category].astuple() - if level >= report_level or debug and level == 0: - msgtext = msg.astext().encode(self.encoding, self.error_handler) - if category: - print >>stream, msgtext, '[%s]' % category - else: - print >>stream, msgtext - if level >= halt_level: - raise SystemMessage(msg, level) - if level > 0 or debug: - self.notify_observers(msg) - self.max_level = max(level, self.max_level) - return msg - - def debug(self, *args, **kwargs): - """ - Level-0, "DEBUG": an internal reporting issue. Typically, there is no - effect on the processing. Level-0 system messages are handled - separately from the others. - """ - return self.system_message(0, *args, **kwargs) - - def info(self, *args, **kwargs): - """ - Level-1, "INFO": a minor issue that can be ignored. Typically there is - no effect on processing, and level-1 system messages are not reported. - """ - return self.system_message(1, *args, **kwargs) - - def warning(self, *args, **kwargs): - """ - Level-2, "WARNING": an issue that should be addressed. If ignored, - there may be unpredictable problems with the output. - """ - return self.system_message(2, *args, **kwargs) - - def error(self, *args, **kwargs): - """ - Level-3, "ERROR": an error that should be addressed. If ignored, the - output will contain errors. - """ - return self.system_message(3, *args, **kwargs) - - def severe(self, *args, **kwargs): - """ - Level-4, "SEVERE": a severe error that must be addressed. If ignored, - the output will contain severe errors. Typically level-4 system - messages are turned into exceptions which halt processing. - """ - return self.system_message(4, *args, **kwargs) - - -class ConditionSet: - - """ - A set of two thresholds (`report_level` & `halt_level`), a switch - (`debug`), and an I/O stream (`stream`), corresponding to one `Reporter` - category. - """ - - def __init__(self, debug, report_level, halt_level, stream): - self.debug = debug - self.report_level = report_level - self.halt_level = halt_level - self.stream = stream - - def astuple(self): - return (self.debug, self.report_level, self.halt_level, - self.stream) - - -class ExtensionOptionError(DataError): pass -class BadOptionError(ExtensionOptionError): pass -class BadOptionDataError(ExtensionOptionError): pass -class DuplicateOptionError(ExtensionOptionError): pass - - -def extract_extension_options(field_list, options_spec): - """ - Return a dictionary mapping extension option names to converted values. - - :Parameters: - - `field_list`: A flat field list without field arguments, where each - field body consists of a single paragraph only. - - `options_spec`: Dictionary mapping known option names to a - conversion function such as `int` or `float`. - - :Exceptions: - - `KeyError` for unknown option names. - - `ValueError` for invalid option values (raised by the conversion - function). - - `DuplicateOptionError` for duplicate options. - - `BadOptionError` for invalid fields. - - `BadOptionDataError` for invalid option data (missing name, - missing data, bad quotes, etc.). - """ - option_list = extract_options(field_list) - option_dict = assemble_option_dict(option_list, options_spec) - return option_dict - -def extract_options(field_list): - """ - Return a list of option (name, value) pairs from field names & bodies. - - :Parameter: - `field_list`: A flat field list, where each field name is a single - word and each field body consists of a single paragraph only. - - :Exceptions: - - `BadOptionError` for invalid fields. - - `BadOptionDataError` for invalid option data (missing name, - missing data, bad quotes, etc.). - """ - option_list = [] - for field in field_list: - if len(field[0].astext().split()) != 1: - raise BadOptionError( - 'extension option field name may not contain multiple words') - name = str(field[0].astext().lower()) - body = field[1] - if len(body) == 0: - data = None - elif len(body) > 1 or not isinstance(body[0], nodes.paragraph) \ - or len(body[0]) != 1 or not isinstance(body[0][0], nodes.Text): - raise BadOptionDataError( - 'extension option field body may contain\n' - 'a single paragraph only (option "%s")' % name) - else: - data = body[0][0].astext() - option_list.append((name, data)) - return option_list - -def assemble_option_dict(option_list, options_spec): - """ - Return a mapping of option names to values. - - :Parameters: - - `option_list`: A list of (name, value) pairs (the output of - `extract_options()`). - - `options_spec`: Dictionary mapping known option names to a - conversion function such as `int` or `float`. - - :Exceptions: - - `KeyError` for unknown option names. - - `DuplicateOptionError` for duplicate options. - - `ValueError` for invalid option values (raised by conversion - function). - """ - options = {} - for name, value in option_list: - convertor = options_spec[name] # raises KeyError if unknown - if options.has_key(name): - raise DuplicateOptionError('duplicate option "%s"' % name) - try: - options[name] = convertor(value) - except (ValueError, TypeError), detail: - raise detail.__class__('(option: "%s"; value: %r)\n%s' - % (name, value, detail)) - return options - - -class NameValueError(DataError): pass - - -def extract_name_value(line): - """ - Return a list of (name, value) from a line of the form "name=value ...". - - :Exception: - `NameValueError` for invalid input (missing name, missing data, bad - quotes, etc.). - """ - attlist = [] - while line: - equals = line.find('=') - if equals == -1: - raise NameValueError('missing "="') - attname = line[:equals].strip() - if equals == 0 or not attname: - raise NameValueError( - 'missing attribute name before "="') - line = line[equals+1:].lstrip() - if not line: - raise NameValueError( - 'missing value after "%s="' % attname) - if line[0] in '\'"': - endquote = line.find(line[0], 1) - if endquote == -1: - raise NameValueError( - 'attribute "%s" missing end quote (%s)' - % (attname, line[0])) - if len(line) > endquote + 1 and line[endquote + 1].strip(): - raise NameValueError( - 'attribute "%s" end quote (%s) not followed by ' - 'whitespace' % (attname, line[0])) - data = line[1:endquote] - line = line[endquote+1:].lstrip() - else: - space = line.find(' ') - if space == -1: - data = line - line = '' - else: - data = line[:space] - line = line[space+1:].lstrip() - attlist.append((attname.lower(), data)) - return attlist - -def new_document(source, settings=None): - """ - Return a new empty document object. - - :Parameters: - `source` : string - The path to or description of the source text of the document. - `settings` : optparse.Values object - Runtime settings. If none provided, a default set will be used. - """ - if settings is None: - settings = frontend.OptionParser().get_default_values() - reporter = Reporter(source, settings.report_level, settings.halt_level, - stream=settings.warning_stream, debug=settings.debug, - encoding=settings.error_encoding, - error_handler=settings.error_encoding_error_handler) - document = nodes.document(settings, reporter, source=source) - document.note_source(source, -1) - return document - -def clean_rcs_keywords(paragraph, keyword_substitutions): - if len(paragraph) == 1 and isinstance(paragraph[0], nodes.Text): - textnode = paragraph[0] - for pattern, substitution in keyword_substitutions: - match = pattern.match(textnode.data) - if match: - textnode.data = pattern.sub(substitution, textnode.data) - return - -def relative_path(source, target): - """ - Build and return a path to `target`, relative to `source` (both files). - - If there is no common prefix, return the absolute path to `target`. - """ - source_parts = os.path.abspath(source or 'dummy_file').split(os.sep) - target_parts = os.path.abspath(target).split(os.sep) - # Check first 2 parts because '/dir'.split('/') == ['', 'dir']: - if source_parts[:2] != target_parts[:2]: - # Nothing in common between paths. - # Return absolute path, using '/' for URLs: - return '/'.join(target_parts) - source_parts.reverse() - target_parts.reverse() - while (source_parts and target_parts - and source_parts[-1] == target_parts[-1]): - # Remove path components in common: - source_parts.pop() - target_parts.pop() - target_parts.reverse() - parts = ['..'] * (len(source_parts) - 1) + target_parts - return '/'.join(parts) - -def get_source_line(node): - """ - Return the "source" and "line" attributes from the `node` given or from - its closest ancestor. - """ - while node: - if node.source or node.line: - return node.source, node.line - node = node.parent - return None, None diff --git a/docutils/docutils/writers/__init__.py b/docutils/docutils/writers/__init__.py deleted file mode 100644 index d8183dc37..000000000 --- a/docutils/docutils/writers/__init__.py +++ /dev/null @@ -1,83 +0,0 @@ -# Authors: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -This package contains Docutils Writer modules. -""" - -__docformat__ = 'reStructuredText' - - -import sys -import docutils -from docutils import languages, Component -from docutils.transforms import universal - - -class Writer(Component): - - """ - Abstract base class for docutils Writers. - - Each writer module or package must export a subclass also called 'Writer'. - Each writer must support all standard node types listed in - `docutils.nodes.node_class_names`. - - Call `write()` to process a document. - """ - - component_type = 'writer' - - document = None - """The document to write.""" - - language = None - """Language module for the document.""" - - destination = None - """`docutils.io` IO object; where to write the document.""" - - def __init__(self): - """Initialize the Writer instance.""" - - def write(self, document, destination): - self.document = document - self.language = languages.get_language( - document.settings.language_code) - self.destination = destination - self.translate() - output = self.destination.write(self.output) - return output - - def translate(self): - """ - Override to do final document tree translation. - - This is usually done with a `docutils.nodes.NodeVisitor` subclass, in - combination with a call to `docutils.nodes.Node.walk()` or - `docutils.nodes.Node.walkabout()`. The ``NodeVisitor`` subclass must - support all standard elements (listed in - `docutils.nodes.node_class_names`) and possibly non-standard elements - used by the current Reader as well. - """ - raise NotImplementedError('subclass must override this method') - - -_writer_aliases = { - 'html': 'html4css1', - 'latex': 'latex2e', - 'pprint': 'pseudoxml', - 'pformat': 'pseudoxml', - 'pdf': 'rlpdf', - 'xml': 'docutils_xml',} - -def get_writer_class(writer_name): - """Return the Writer class from the `writer_name` module.""" - writer_name = writer_name.lower() - if _writer_aliases.has_key(writer_name): - writer_name = _writer_aliases[writer_name] - module = __import__(writer_name, globals(), locals()) - return module.Writer diff --git a/docutils/docutils/writers/docutils_xml.py b/docutils/docutils/writers/docutils_xml.py deleted file mode 100644 index 4ecbfb6c2..000000000 --- a/docutils/docutils/writers/docutils_xml.py +++ /dev/null @@ -1,66 +0,0 @@ -# Authors: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Simple internal document tree Writer, writes Docutils XML. -""" - -__docformat__ = 'reStructuredText' - - -import docutils -from docutils import writers - - -class Writer(writers.Writer): - - supported = ('xml',) - """Formats this writer supports.""" - - settings_spec = ( - '"Docutils XML" Writer Options', - 'Warning: the --newlines and --indents options may adversely affect ' - 'whitespace; use them only for reading convenience.', - (('Generate XML with newlines before and after tags.', - ['--newlines'], {'action': 'store_true'}), - ('Generate XML with indents and newlines.', - ['--indents'], {'action': 'store_true'}), - ('Omit the XML declaration. Use with caution.', - ['--no-xml-declaration'], {'dest': 'xml_declaration', 'default': 1, - 'action': 'store_false'}), - ('Omit the DOCTYPE declaration.', - ['--no-doctype'], {'dest': 'doctype_declaration', 'default': 1, - 'action': 'store_false'}),)) - - output = None - """Final translated form of `document`.""" - - xml_declaration = '<?xml version="1.0" encoding="%s"?>\n' - #xml_stylesheet = '<?xml-stylesheet type="text/xsl" href="%s"?>\n' - doctype = ( - '<!DOCTYPE document PUBLIC' - ' "+//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML"' - ' "http://docutils.sourceforge.net/spec/docutils.dtd">\n') - generator = '<!-- Generated by Docutils %s -->\n' - - def translate(self): - settings = self.document.settings - indent = newline = '' - if settings.newlines: - newline = '\n' - if settings.indents: - newline = '\n' - indent = ' ' - output_prefix = [] - if settings.xml_declaration: - output_prefix.append( - self.xml_declaration % settings.output_encoding) - if settings.doctype_declaration: - output_prefix.append(self.doctype) - output_prefix.append(self.generator % docutils.__version__) - docnode = self.document.asdom().childNodes[0] - self.output = (''.join(output_prefix) - + docnode.toprettyxml(indent, newline)) diff --git a/docutils/docutils/writers/html4css1.py b/docutils/docutils/writers/html4css1.py deleted file mode 100644 index b73a622ad..000000000 --- a/docutils/docutils/writers/html4css1.py +++ /dev/null @@ -1,1244 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Simple HyperText Markup Language document tree Writer. - -The output conforms to the HTML 4.01 Transitional DTD and to the Extensible -HTML version 1.0 Transitional DTD (*almost* strict). The output contains a -minimum of formatting information. A cascading style sheet ("default.css" by -default) is required for proper viewing with a modern graphical browser. -""" - -__docformat__ = 'reStructuredText' - - -import sys -import os -import os.path -import time -import re -from types import ListType -import docutils -from docutils import nodes, utils, writers, languages - - -class Writer(writers.Writer): - - supported = ('html', 'html4css1', 'xhtml') - """Formats this writer supports.""" - - settings_spec = ( - 'HTML-Specific Options', - None, - (('Specify a stylesheet URL, used verbatim. Default is ' - '"default.css". Overridden by --stylesheet-path.', - ['--stylesheet'], - {'default': 'default.css', 'metavar': '<URL>'}), - ('Specify a stylesheet file, relative to the current working ' - 'directory. The path is adjusted relative to the output HTML ' - 'file. Overrides --stylesheet.', - ['--stylesheet-path'], - {'metavar': '<file>'}), - ('Link to the stylesheet in the output HTML file. This is the ' - 'default.', - ['--link-stylesheet'], - {'dest': 'embed_stylesheet', 'action': 'store_false'}), - ('Embed the stylesheet in the output HTML file. The stylesheet ' - 'file must be accessible during processing (--stylesheet-path is ' - 'recommended). The stylesheet is embedded inside a comment, so it ' - 'must not contain the text "--" (two hyphens). Default: link the ' - 'stylesheet, do not embed it.', - ['--embed-stylesheet'], - {'action': 'store_true'}), - ('Format for footnote references: one of "superscript" or ' - '"brackets". Default is "superscript".', - ['--footnote-references'], - {'choices': ['superscript', 'brackets'], 'default': 'superscript', - 'metavar': '<format>'}), - ('Format for block quote attributions: one of "dash" (em-dash ' - 'prefix), "parentheses"/"parens", or "none". Default is "dash".', - ['--attribution'], - {'choices': ['dash', 'parentheses', 'parens', 'none'], - 'default': 'dash', 'metavar': '<format>'}), - ('Remove extra vertical whitespace between items of bullet lists ' - 'and enumerated lists, when list items are "simple" (i.e., all ' - 'items each contain one paragraph and/or one "simple" sublist ' - 'only). Default: enabled.', - ['--compact-lists'], - {'default': 1, 'action': 'store_true'}), - ('Disable compact simple bullet and enumerated lists.', - ['--no-compact-lists'], - {'dest': 'compact_lists', 'action': 'store_false'}), - ('Omit the XML declaration. Use with caution.', - ['--no-xml-declaration'], {'dest': 'xml_declaration', 'default': 1, - 'action': 'store_false'}),)) - - relative_path_settings = ('stylesheet_path',) - - output = None - """Final translated form of `document`.""" - - def __init__(self): - writers.Writer.__init__(self) - self.translator_class = HTMLTranslator - - def translate(self): - visitor = self.translator_class(self.document) - self.document.walkabout(visitor) - self.output = visitor.astext() - self.head_prefix = visitor.head_prefix - self.stylesheet = visitor.stylesheet - self.head = visitor.head - self.body_prefix = visitor.body_prefix - self.body_pre_docinfo = visitor.body_pre_docinfo - self.docinfo = visitor.docinfo - self.body = visitor.body - self.body_suffix = visitor.body_suffix - - -class HTMLTranslator(nodes.NodeVisitor): - - """ - This HTML writer has been optimized to produce visually compact - lists (less vertical whitespace). HTML's mixed content models - allow list items to contain "<li><p>body elements</p></li>" or - "<li>just text</li>" or even "<li>text<p>and body - elements</p>combined</li>", each with different effects. It would - be best to stick with strict body elements in list items, but they - affect vertical spacing in browsers (although they really - shouldn't). - - Here is an outline of the optimization: - - - Check for and omit <p> tags in "simple" lists: list items - contain either a single paragraph, a nested simple list, or a - paragraph followed by a nested simple list. This means that - this list can be compact: - - - Item 1. - - Item 2. - - But this list cannot be compact: - - - Item 1. - - This second paragraph forces space between list items. - - - Item 2. - - - In non-list contexts, omit <p> tags on a paragraph if that - paragraph is the only child of its parent (footnotes & citations - are allowed a label first). - - - Regardless of the above, in definitions, table cells, field bodies, - option descriptions, and list items, mark the first child with - 'class="first"' and the last child with 'class="last"'. The stylesheet - sets the margins (top & bottom respecively) to 0 for these elements. - - The ``no_compact_lists`` setting (``--no-compact-lists`` command-line - option) disables list whitespace optimization. - """ - - xml_declaration = '<?xml version="1.0" encoding="%s" ?>\n' - doctype = ('<!DOCTYPE html' - ' PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"' - ' "http://www.w3.org/TR/xhtml1/DTD/' - 'xhtml1-transitional.dtd">\n') - html_head = ('<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="%s" ' - 'lang="%s">\n<head>\n') - content_type = ('<meta http-equiv="Content-Type" content="text/html; ' - 'charset=%s" />\n') - generator = ('<meta name="generator" content="Docutils %s: ' - 'http://docutils.sourceforge.net/" />\n') - stylesheet_link = '<link rel="stylesheet" href="%s" type="text/css" />\n' - embedded_stylesheet = '<style type="text/css"><!--\n\n%s\n--></style>\n' - named_tags = {'a': 1, 'applet': 1, 'form': 1, 'frame': 1, 'iframe': 1, - 'img': 1, 'map': 1} - words_and_spaces = re.compile(r'\S+| +|\n') - - def __init__(self, document): - nodes.NodeVisitor.__init__(self, document) - self.settings = settings = document.settings - lcode = settings.language_code - self.language = languages.get_language(lcode) - self.head_prefix = [ - self.doctype, - self.html_head % (lcode, lcode), - self.content_type % settings.output_encoding, - self.generator % docutils.__version__] - if settings.xml_declaration: - self.head_prefix.insert(0, self.xml_declaration - % settings.output_encoding) - self.head = [] - if settings.embed_stylesheet: - stylesheet = self.get_stylesheet_reference( - os.path.join(os.getcwd(), 'dummy')) - stylesheet_text = open(stylesheet).read() - self.stylesheet = [self.embedded_stylesheet % stylesheet_text] - else: - stylesheet = self.get_stylesheet_reference() - if stylesheet: - self.stylesheet = [self.stylesheet_link % stylesheet] - else: - self.stylesheet = [] - self.body_prefix = ['</head>\n<body>\n'] - self.body_pre_docinfo = [] - self.docinfo = [] - self.body = [] - self.body_suffix = ['</body>\n</html>\n'] - self.section_level = 0 - self.context = [] - self.topic_class = '' - self.colspecs = [] - self.compact_p = 1 - self.compact_simple = None - self.in_docinfo = None - self.in_sidebar = None - - def get_stylesheet_reference(self, relative_to=None): - settings = self.settings - if settings.stylesheet_path: - if relative_to == None: - relative_to = settings._destination - return utils.relative_path(relative_to, settings.stylesheet_path) - else: - return settings.stylesheet - - def astext(self): - return ''.join(self.head_prefix + self.head - + self.stylesheet + self.body_prefix - + self.body_pre_docinfo + self.docinfo - + self.body + self.body_suffix) - - def encode(self, text): - """Encode special characters in `text` & return.""" - # @@@ A codec to do these and all other HTML entities would be nice. - text = text.replace("&", "&") - text = text.replace("<", "<") - text = text.replace('"', """) - text = text.replace(">", ">") - text = text.replace("@", "@") # may thwart some address harvesters - return text - - def attval(self, text, - whitespace=re.compile('[\n\r\t\v\f]')): - """Cleanse, HTML encode, and return attribute value text.""" - return self.encode(whitespace.sub(' ', text)) - - def starttag(self, node, tagname, suffix='\n', infix='', **attributes): - """ - Construct and return a start tag given a node (id & class attributes - are extracted), tag name, and optional attributes. - """ - tagname = tagname.lower() - atts = {} - for (name, value) in attributes.items(): - atts[name.lower()] = value - for att in ('class',): # append to node attribute - if node.has_key(att) or atts.has_key(att): - atts[att] = \ - (node.get(att, '') + ' ' + atts.get(att, '')).strip() - for att in ('id',): # node attribute overrides - if node.has_key(att): - atts[att] = node[att] - if atts.has_key('id') and self.named_tags.has_key(tagname): - atts['name'] = atts['id'] # for compatibility with old browsers - attlist = atts.items() - attlist.sort() - parts = [tagname] - for name, value in attlist: - if value is None: # boolean attribute - # According to the HTML spec, ``<element boolean>`` is good, - # ``<element boolean="boolean">`` is bad. - # (But the XHTML (XML) spec says the opposite. <sigh>) - parts.append(name.lower()) - elif isinstance(value, ListType): - values = [unicode(v) for v in value] - parts.append('%s="%s"' % (name.lower(), - self.attval(' '.join(values)))) - else: - parts.append('%s="%s"' % (name.lower(), - self.attval(unicode(value)))) - return '<%s%s>%s' % (' '.join(parts), infix, suffix) - - def emptytag(self, node, tagname, suffix='\n', **attributes): - """Construct and return an XML-compatible empty tag.""" - return self.starttag(node, tagname, suffix, infix=' /', **attributes) - - def visit_Text(self, node): - self.body.append(self.encode(node.astext())) - - def depart_Text(self, node): - pass - - def visit_abbreviation(self, node): - # @@@ implementation incomplete ("title" attribute) - self.body.append(self.starttag(node, 'abbr', '')) - - def depart_abbreviation(self, node): - self.body.append('</abbr>') - - def visit_acronym(self, node): - # @@@ implementation incomplete ("title" attribute) - self.body.append(self.starttag(node, 'acronym', '')) - - def depart_acronym(self, node): - self.body.append('</acronym>') - - def visit_address(self, node): - self.visit_docinfo_item(node, 'address', meta=None) - self.body.append(self.starttag(node, 'pre', CLASS='address')) - - def depart_address(self, node): - self.body.append('\n</pre>\n') - self.depart_docinfo_item() - - def visit_admonition(self, node, name=''): - self.body.append(self.starttag(node, 'div', - CLASS=(name or 'admonition'))) - if name: - self.body.append('<p class="admonition-title">' - + self.language.labels[name] + '</p>\n') - - def depart_admonition(self, node=None): - self.body.append('</div>\n') - - def visit_attention(self, node): - self.visit_admonition(node, 'attention') - - def depart_attention(self, node): - self.depart_admonition() - - attribution_formats = {'dash': ('—', ''), - 'parentheses': ('(', ')'), - 'parens': ('(', ')'), - 'none': ('', '')} - - def visit_attribution(self, node): - prefix, suffix = self.attribution_formats[self.settings.attribution] - self.context.append(suffix) - self.body.append( - self.starttag(node, 'p', prefix, CLASS='attribution')) - - def depart_attribution(self, node): - self.body.append(self.context.pop() + '</p>\n') - - def visit_author(self, node): - self.visit_docinfo_item(node, 'author') - - def depart_author(self, node): - self.depart_docinfo_item() - - def visit_authors(self, node): - pass - - def depart_authors(self, node): - pass - - def visit_block_quote(self, node): - self.body.append(self.starttag(node, 'blockquote')) - - def depart_block_quote(self, node): - self.body.append('</blockquote>\n') - - def check_simple_list(self, node): - """Check for a simple list that can be rendered compactly.""" - visitor = SimpleListChecker(self.document) - try: - node.walk(visitor) - except nodes.NodeFound: - return None - else: - return 1 - - def visit_bullet_list(self, node): - atts = {} - old_compact_simple = self.compact_simple - self.context.append((self.compact_simple, self.compact_p)) - self.compact_p = None - self.compact_simple = (self.settings.compact_lists and - (self.compact_simple - or self.topic_class == 'contents' - or self.check_simple_list(node))) - if self.compact_simple and not old_compact_simple: - atts['class'] = 'simple' - self.body.append(self.starttag(node, 'ul', **atts)) - - def depart_bullet_list(self, node): - self.compact_simple, self.compact_p = self.context.pop() - self.body.append('</ul>\n') - - def visit_caption(self, node): - self.body.append(self.starttag(node, 'p', '', CLASS='caption')) - - def depart_caption(self, node): - self.body.append('</p>\n') - - def visit_caution(self, node): - self.visit_admonition(node, 'caution') - - def depart_caution(self, node): - self.depart_admonition() - - def visit_citation(self, node): - self.body.append(self.starttag(node, 'table', CLASS='citation', - frame="void", rules="none")) - self.body.append('<colgroup><col class="label" /><col /></colgroup>\n' - '<col />\n' - '<tbody valign="top">\n' - '<tr>') - self.footnote_backrefs(node) - - def depart_citation(self, node): - self.body.append('</td></tr>\n' - '</tbody>\n</table>\n') - - def visit_citation_reference(self, node): - href = '' - if node.has_key('refid'): - href = '#' + node['refid'] - elif node.has_key('refname'): - href = '#' + self.document.nameids[node['refname']] - self.body.append(self.starttag(node, 'a', '[', href=href, - CLASS='citation-reference')) - - def depart_citation_reference(self, node): - self.body.append(']</a>') - - def visit_classifier(self, node): - self.body.append(' <span class="classifier-delimiter">:</span> ') - self.body.append(self.starttag(node, 'span', '', CLASS='classifier')) - - def depart_classifier(self, node): - self.body.append('</span>') - - def visit_colspec(self, node): - self.colspecs.append(node) - - def depart_colspec(self, node): - pass - - def write_colspecs(self): - width = 0 - for node in self.colspecs: - width += node['colwidth'] - for node in self.colspecs: - colwidth = int(node['colwidth'] * 100.0 / width + 0.5) - self.body.append(self.emptytag(node, 'col', - width='%i%%' % colwidth)) - self.colspecs = [] - - def visit_comment(self, node, - sub=re.compile('-(?=-)').sub): - """Escape double-dashes in comment text.""" - self.body.append('<!-- %s -->\n' % sub('- ', node.astext())) - # Content already processed: - raise nodes.SkipNode - - def visit_contact(self, node): - self.visit_docinfo_item(node, 'contact', meta=None) - - def depart_contact(self, node): - self.depart_docinfo_item() - - def visit_copyright(self, node): - self.visit_docinfo_item(node, 'copyright') - - def depart_copyright(self, node): - self.depart_docinfo_item() - - def visit_danger(self, node): - self.visit_admonition(node, 'danger') - - def depart_danger(self, node): - self.depart_admonition() - - def visit_date(self, node): - self.visit_docinfo_item(node, 'date') - - def depart_date(self, node): - self.depart_docinfo_item() - - def visit_decoration(self, node): - pass - - def depart_decoration(self, node): - pass - - def visit_definition(self, node): - self.body.append('</dt>\n') - self.body.append(self.starttag(node, 'dd', '')) - if len(node): - node[0].set_class('first') - node[-1].set_class('last') - - def depart_definition(self, node): - self.body.append('</dd>\n') - - def visit_definition_list(self, node): - self.body.append(self.starttag(node, 'dl')) - - def depart_definition_list(self, node): - self.body.append('</dl>\n') - - def visit_definition_list_item(self, node): - pass - - def depart_definition_list_item(self, node): - pass - - def visit_description(self, node): - self.body.append(self.starttag(node, 'td', '')) - if len(node): - node[0].set_class('first') - node[-1].set_class('last') - - def depart_description(self, node): - self.body.append('</td>') - - def visit_docinfo(self, node): - self.context.append(len(self.body)) - self.body.append(self.starttag(node, 'table', CLASS='docinfo', - frame="void", rules="none")) - self.body.append('<col class="docinfo-name" />\n' - '<col class="docinfo-content" />\n' - '<tbody valign="top">\n') - self.in_docinfo = 1 - - def depart_docinfo(self, node): - self.body.append('</tbody>\n</table>\n') - self.in_docinfo = None - start = self.context.pop() - self.body_pre_docinfo = self.body[:start] - self.docinfo = self.body[start:] - self.body = [] - - def visit_docinfo_item(self, node, name, meta=1): - if meta: - self.head.append('<meta name="%s" content="%s" />\n' - % (name, self.attval(node.astext()))) - self.body.append(self.starttag(node, 'tr', '')) - self.body.append('<th class="docinfo-name">%s:</th>\n<td>' - % self.language.labels[name]) - if len(node): - if isinstance(node[0], nodes.Element): - node[0].set_class('first') - if isinstance(node[-1], nodes.Element): - node[-1].set_class('last') - - def depart_docinfo_item(self): - self.body.append('</td></tr>\n') - - def visit_doctest_block(self, node): - self.body.append(self.starttag(node, 'pre', CLASS='doctest-block')) - - def depart_doctest_block(self, node): - self.body.append('\n</pre>\n') - - def visit_document(self, node): - self.body.append(self.starttag(node, 'div', CLASS='document')) - - def depart_document(self, node): - self.body.append('</div>\n') - - def visit_emphasis(self, node): - self.body.append('<em>') - - def depart_emphasis(self, node): - self.body.append('</em>') - - def visit_entry(self, node): - if isinstance(node.parent.parent, nodes.thead): - tagname = 'th' - else: - tagname = 'td' - atts = {} - if node.has_key('morerows'): - atts['rowspan'] = node['morerows'] + 1 - if node.has_key('morecols'): - atts['colspan'] = node['morecols'] + 1 - self.body.append(self.starttag(node, tagname, '', **atts)) - self.context.append('</%s>\n' % tagname.lower()) - if len(node) == 0: # empty cell - self.body.append(' ') - else: - node[0].set_class('first') - node[-1].set_class('last') - - def depart_entry(self, node): - self.body.append(self.context.pop()) - - def visit_enumerated_list(self, node): - """ - The 'start' attribute does not conform to HTML 4.01's strict.dtd, but - CSS1 doesn't help. CSS2 isn't widely enough supported yet to be - usable. - """ - atts = {} - if node.has_key('start'): - atts['start'] = node['start'] - if node.has_key('enumtype'): - atts['class'] = node['enumtype'] - # @@@ To do: prefix, suffix. How? Change prefix/suffix to a - # single "format" attribute? Use CSS2? - old_compact_simple = self.compact_simple - self.context.append((self.compact_simple, self.compact_p)) - self.compact_p = None - self.compact_simple = (self.settings.compact_lists and - (self.compact_simple - or self.topic_class == 'contents' - or self.check_simple_list(node))) - if self.compact_simple and not old_compact_simple: - atts['class'] = (atts.get('class', '') + ' simple').strip() - self.body.append(self.starttag(node, 'ol', **atts)) - - def depart_enumerated_list(self, node): - self.compact_simple, self.compact_p = self.context.pop() - self.body.append('</ol>\n') - - def visit_error(self, node): - self.visit_admonition(node, 'error') - - def depart_error(self, node): - self.depart_admonition() - - def visit_field(self, node): - self.body.append(self.starttag(node, 'tr', '', CLASS='field')) - - def depart_field(self, node): - self.body.append('</tr>\n') - - def visit_field_body(self, node): - self.body.append(self.starttag(node, 'td', '', CLASS='field-body')) - if len(node): - node[0].set_class('first') - node[-1].set_class('last') - - def depart_field_body(self, node): - self.body.append('</td>\n') - - def visit_field_list(self, node): - self.body.append(self.starttag(node, 'table', frame='void', - rules='none', CLASS='field-list')) - self.body.append('<col class="field-name" />\n' - '<col class="field-body" />\n' - '<tbody valign="top">\n') - - def depart_field_list(self, node): - self.body.append('</tbody>\n</table>\n') - - def visit_field_name(self, node): - atts = {} - if self.in_docinfo: - atts['class'] = 'docinfo-name' - else: - atts['class'] = 'field-name' - if len(node.astext()) > 14: - atts['colspan'] = 2 - self.context.append('</tr>\n<tr><td> </td>') - else: - self.context.append('') - self.body.append(self.starttag(node, 'th', '', **atts)) - - def depart_field_name(self, node): - self.body.append(':</th>') - self.body.append(self.context.pop()) - - def visit_figure(self, node): - atts = {'class': 'figure'} - if node.get('width'): - atts['style'] = 'width: %spx' % node['width'] - self.body.append(self.starttag(node, 'div', **atts)) - - def depart_figure(self, node): - self.body.append('</div>\n') - - def visit_footer(self, node): - self.context.append(len(self.body)) - - def depart_footer(self, node): - start = self.context.pop() - footer = (['<hr class="footer"/>\n', - self.starttag(node, 'div', CLASS='footer')] - + self.body[start:] + ['</div>\n']) - self.body_suffix[:0] = footer - del self.body[start:] - - def visit_footnote(self, node): - self.body.append(self.starttag(node, 'table', CLASS='footnote', - frame="void", rules="none")) - self.body.append('<colgroup><col class="label" /><col /></colgroup>\n' - '<tbody valign="top">\n' - '<tr>') - self.footnote_backrefs(node) - - def footnote_backrefs(self, node): - if self.settings.footnote_backlinks and node.hasattr('backrefs'): - backrefs = node['backrefs'] - if len(backrefs) == 1: - self.context.append('') - self.context.append('<a class="fn-backref" href="#%s" ' - 'name="%s">' % (backrefs[0], node['id'])) - else: - i = 1 - backlinks = [] - for backref in backrefs: - backlinks.append('<a class="fn-backref" href="#%s">%s</a>' - % (backref, i)) - i += 1 - self.context.append('<em>(%s)</em> ' % ', '.join(backlinks)) - self.context.append('<a name="%s">' % node['id']) - else: - self.context.append('') - self.context.append('<a name="%s">' % node['id']) - - def depart_footnote(self, node): - self.body.append('</td></tr>\n' - '</tbody>\n</table>\n') - - def visit_footnote_reference(self, node): - href = '' - if node.has_key('refid'): - href = '#' + node['refid'] - elif node.has_key('refname'): - href = '#' + self.document.nameids[node['refname']] - format = self.settings.footnote_references - if format == 'brackets': - suffix = '[' - self.context.append(']') - elif format == 'superscript': - suffix = '<sup>' - self.context.append('</sup>') - else: # shouldn't happen - suffix = '???' - self.content.append('???') - self.body.append(self.starttag(node, 'a', suffix, href=href, - CLASS='footnote-reference')) - - def depart_footnote_reference(self, node): - self.body.append(self.context.pop() + '</a>') - - def visit_generated(self, node): - pass - - def depart_generated(self, node): - pass - - def visit_header(self, node): - self.context.append(len(self.body)) - - def depart_header(self, node): - start = self.context.pop() - self.body_prefix.append(self.starttag(node, 'div', CLASS='header')) - self.body_prefix.extend(self.body[start:]) - self.body_prefix.append('<hr />\n</div>\n') - del self.body[start:] - - def visit_hint(self, node): - self.visit_admonition(node, 'hint') - - def depart_hint(self, node): - self.depart_admonition() - - def visit_image(self, node): - atts = node.attributes.copy() - atts['src'] = atts['uri'] - del atts['uri'] - if not atts.has_key('alt'): - atts['alt'] = atts['src'] - if isinstance(node.parent, nodes.TextElement): - self.context.append('') - else: - self.body.append('<p>') - self.context.append('</p>\n') - self.body.append(self.emptytag(node, 'img', '', **atts)) - - def depart_image(self, node): - self.body.append(self.context.pop()) - - def visit_important(self, node): - self.visit_admonition(node, 'important') - - def depart_important(self, node): - self.depart_admonition() - - def visit_inline(self, node): - self.body.append(self.starttag(node, 'span', '')) - - def depart_inline(self, node): - self.body.append('</span>') - - def visit_label(self, node): - self.body.append(self.starttag(node, 'td', '%s[' % self.context.pop(), - CLASS='label')) - - def depart_label(self, node): - self.body.append(']</a></td><td>%s' % self.context.pop()) - - def visit_legend(self, node): - self.body.append(self.starttag(node, 'div', CLASS='legend')) - - def depart_legend(self, node): - self.body.append('</div>\n') - - def visit_line_block(self, node): - self.body.append(self.starttag(node, 'pre', CLASS='line-block')) - - def depart_line_block(self, node): - self.body.append('\n</pre>\n') - - def visit_list_item(self, node): - self.body.append(self.starttag(node, 'li', '')) - if len(node): - node[0].set_class('first') - - def depart_list_item(self, node): - self.body.append('</li>\n') - - def visit_literal(self, node): - """Process text to prevent tokens from wrapping.""" - self.body.append(self.starttag(node, 'tt', '', CLASS='literal')) - text = node.astext() - for token in self.words_and_spaces.findall(text): - if token.strip(): - # Protect text like "--an-option" from bad line wrapping: - self.body.append('<span class="pre">%s</span>' - % self.encode(token)) - elif token in ('\n', ' '): - # Allow breaks at whitespace: - self.body.append(token) - else: - # Protect runs of multiple spaces; the last space can wrap: - self.body.append(' ' * (len(token) - 1) + ' ') - self.body.append('</tt>') - # Content already processed: - raise nodes.SkipNode - - def visit_literal_block(self, node): - self.body.append(self.starttag(node, 'pre', CLASS='literal-block')) - - def depart_literal_block(self, node): - self.body.append('\n</pre>\n') - - def visit_meta(self, node): - self.head.append(self.emptytag(node, 'meta', **node.attributes)) - - def depart_meta(self, node): - pass - - def visit_note(self, node): - self.visit_admonition(node, 'note') - - def depart_note(self, node): - self.depart_admonition() - - def visit_option(self, node): - if self.context[-1]: - self.body.append(', ') - - def depart_option(self, node): - self.context[-1] += 1 - - def visit_option_argument(self, node): - self.body.append(node.get('delimiter', ' ')) - self.body.append(self.starttag(node, 'var', '')) - - def depart_option_argument(self, node): - self.body.append('</var>') - - def visit_option_group(self, node): - atts = {} - if len(node.astext()) > 14: - atts['colspan'] = 2 - self.context.append('</tr>\n<tr><td> </td>') - else: - self.context.append('') - self.body.append(self.starttag(node, 'td', **atts)) - self.body.append('<kbd>') - self.context.append(0) # count number of options - - def depart_option_group(self, node): - self.context.pop() - self.body.append('</kbd></td>\n') - self.body.append(self.context.pop()) - - def visit_option_list(self, node): - self.body.append( - self.starttag(node, 'table', CLASS='option-list', - frame="void", rules="none")) - self.body.append('<col class="option" />\n' - '<col class="description" />\n' - '<tbody valign="top">\n') - - def depart_option_list(self, node): - self.body.append('</tbody>\n</table>\n') - - def visit_option_list_item(self, node): - self.body.append(self.starttag(node, 'tr', '')) - - def depart_option_list_item(self, node): - self.body.append('</tr>\n') - - def visit_option_string(self, node): - self.body.append(self.starttag(node, 'span', '', CLASS='option')) - - def depart_option_string(self, node): - self.body.append('</span>') - - def visit_organization(self, node): - self.visit_docinfo_item(node, 'organization') - - def depart_organization(self, node): - self.depart_docinfo_item() - - def visit_paragraph(self, node): - # Omit <p> tags if this is an only child and optimizable. - if (self.compact_simple or - self.compact_p and (len(node.parent) == 1 or - len(node.parent) == 2 and - isinstance(node.parent[0], nodes.label))): - self.context.append('') - else: - self.body.append(self.starttag(node, 'p', '')) - self.context.append('</p>\n') - - def depart_paragraph(self, node): - self.body.append(self.context.pop()) - - def visit_problematic(self, node): - if node.hasattr('refid'): - self.body.append('<a href="#%s" name="%s">' % (node['refid'], - node['id'])) - self.context.append('</a>') - else: - self.context.append('') - self.body.append(self.starttag(node, 'span', '', CLASS='problematic')) - - def depart_problematic(self, node): - self.body.append('</span>') - self.body.append(self.context.pop()) - - def visit_raw(self, node): - if node.get('format') == 'html': - self.body.append(node.astext()) - # Keep non-HTML raw text out of output: - raise nodes.SkipNode - - def visit_reference(self, node): - if node.has_key('refuri'): - href = node['refuri'] - elif node.has_key('refid'): - href = '#' + node['refid'] - elif node.has_key('refname'): - href = '#' + self.document.nameids[node['refname']] - self.body.append(self.starttag(node, 'a', '', href=href, - CLASS='reference')) - - def depart_reference(self, node): - self.body.append('</a>') - - def visit_revision(self, node): - self.visit_docinfo_item(node, 'revision', meta=None) - - def depart_revision(self, node): - self.depart_docinfo_item() - - def visit_row(self, node): - self.body.append(self.starttag(node, 'tr', '')) - - def depart_row(self, node): - self.body.append('</tr>\n') - - def visit_rubric(self, node): - self.body.append(self.starttag(node, 'p', '', CLASS='rubric')) - - def depart_rubric(self, node): - self.body.append('</p>\n') - - def visit_section(self, node): - self.section_level += 1 - self.body.append(self.starttag(node, 'div', CLASS='section')) - - def depart_section(self, node): - self.section_level -= 1 - self.body.append('</div>\n') - - def visit_sidebar(self, node): - self.body.append(self.starttag(node, 'div', CLASS='sidebar')) - self.in_sidebar = 1 - - def depart_sidebar(self, node): - self.body.append('</div>\n') - self.in_sidebar = None - - def visit_status(self, node): - self.visit_docinfo_item(node, 'status', meta=None) - - def depart_status(self, node): - self.depart_docinfo_item() - - def visit_strong(self, node): - self.body.append('<strong>') - - def depart_strong(self, node): - self.body.append('</strong>') - - def visit_subscript(self, node): - self.body.append(self.starttag(node, 'sub', '')) - - def depart_subscript(self, node): - self.body.append('</sub>') - - def visit_substitution_definition(self, node): - """Internal only.""" - raise nodes.SkipNode - - def visit_substitution_reference(self, node): - self.unimplemented_visit(node) - - def visit_subtitle(self, node): - if isinstance(node.parent, nodes.sidebar): - self.body.append(self.starttag(node, 'p', '', - CLASS='sidebar-subtitle')) - self.context.append('</p>\n') - else: - self.body.append(self.starttag(node, 'h2', '', CLASS='subtitle')) - self.context.append('</h2>\n') - - def depart_subtitle(self, node): - self.body.append(self.context.pop()) - - def visit_superscript(self, node): - self.body.append(self.starttag(node, 'sup', '')) - - def depart_superscript(self, node): - self.body.append('</sup>') - - def visit_system_message(self, node): - if node['level'] < self.document.reporter['writer'].report_level: - # Level is too low to display: - raise nodes.SkipNode - self.body.append(self.starttag(node, 'div', CLASS='system-message')) - self.body.append('<p class="system-message-title">') - attr = {} - backref_text = '' - if node.hasattr('id'): - attr['name'] = node['id'] - if node.hasattr('backrefs'): - backrefs = node['backrefs'] - if len(backrefs) == 1: - backref_text = ('; <em><a href="#%s">backlink</a></em>' - % backrefs[0]) - else: - i = 1 - backlinks = [] - for backref in backrefs: - backlinks.append('<a href="#%s">%s</a>' % (backref, i)) - i += 1 - backref_text = ('; <em>backlinks: %s</em>' - % ', '.join(backlinks)) - if node.hasattr('line'): - line = ', line %s' % node['line'] - else: - line = '' - if attr: - a_start = self.starttag({}, 'a', '', **attr) - a_end = '</a>' - else: - a_start = a_end = '' - self.body.append('System Message: %s%s/%s%s (<tt>%s</tt>%s)%s</p>\n' - % (a_start, node['type'], node['level'], a_end, - self.encode(node['source']), line, backref_text)) - - def depart_system_message(self, node): - self.body.append('</div>\n') - - def visit_table(self, node): - self.body.append( - self.starttag(node, 'table', CLASS="table", - frame='border', rules='all')) - - def depart_table(self, node): - self.body.append('</table>\n') - - def visit_target(self, node): - if not (node.has_key('refuri') or node.has_key('refid') - or node.has_key('refname')): - self.body.append(self.starttag(node, 'a', '', CLASS='target')) - self.context.append('</a>') - else: - self.context.append('') - - def depart_target(self, node): - self.body.append(self.context.pop()) - - def visit_tbody(self, node): - self.write_colspecs() - self.body.append(self.context.pop()) # '</colgroup>\n' or '' - self.body.append(self.starttag(node, 'tbody', valign='top')) - - def depart_tbody(self, node): - self.body.append('</tbody>\n') - - def visit_term(self, node): - self.body.append(self.starttag(node, 'dt', '')) - - def depart_term(self, node): - """ - Leave the end tag to `self.visit_definition()`, in case there's a - classifier. - """ - pass - - def visit_tgroup(self, node): - # Mozilla needs <colgroup>: - self.body.append(self.starttag(node, 'colgroup')) - # Appended by thead or tbody: - self.context.append('</colgroup>\n') - - def depart_tgroup(self, node): - pass - - def visit_thead(self, node): - self.write_colspecs() - self.body.append(self.context.pop()) # '</colgroup>\n' - # There may or may not be a <thead>; this is for <tbody> to use: - self.context.append('') - self.body.append(self.starttag(node, 'thead', valign='bottom')) - - def depart_thead(self, node): - self.body.append('</thead>\n') - - def visit_tip(self, node): - self.visit_admonition(node, 'tip') - - def depart_tip(self, node): - self.depart_admonition() - - def visit_title(self, node): - """Only 6 section levels are supported by HTML.""" - check_id = 0 - if isinstance(node.parent, nodes.topic): - self.body.append( - self.starttag(node, 'p', '', CLASS='topic-title')) - check_id = 1 - elif isinstance(node.parent, nodes.sidebar): - self.body.append( - self.starttag(node, 'p', '', CLASS='sidebar-title')) - check_id = 1 - elif isinstance(node.parent, nodes.admonition): - self.body.append( - self.starttag(node, 'p', '', CLASS='admonition-title')) - check_id = 1 - elif self.section_level == 0: - # document title - self.head.append('<title>%s</title>\n' - % self.encode(node.astext())) - self.body.append(self.starttag(node, 'h1', '', CLASS='title')) - self.context.append('</h1>\n') - else: - self.body.append( - self.starttag(node, 'h%s' % self.section_level, '')) - atts = {} - if node.parent.hasattr('id'): - atts['name'] = node.parent['id'] - if node.hasattr('refid'): - atts['class'] = 'toc-backref' - atts['href'] = '#' + node['refid'] - self.body.append(self.starttag({}, 'a', '', **atts)) - self.context.append('</a></h%s>\n' % (self.section_level)) - if check_id: - if node.parent.hasattr('id'): - self.body.append( - self.starttag({}, 'a', '', name=node.parent['id'])) - self.context.append('</a></p>\n') - else: - self.context.append('</p>\n') - - def depart_title(self, node): - self.body.append(self.context.pop()) - - def visit_title_reference(self, node): - self.body.append(self.starttag(node, 'cite', '')) - - def depart_title_reference(self, node): - self.body.append('</cite>') - - def visit_topic(self, node): - self.body.append(self.starttag(node, 'div', CLASS='topic')) - self.topic_class = node.get('class') - - def depart_topic(self, node): - self.body.append('</div>\n') - self.topic_class = '' - - def visit_transition(self, node): - self.body.append(self.emptytag(node, 'hr')) - - def depart_transition(self, node): - pass - - def visit_version(self, node): - self.visit_docinfo_item(node, 'version', meta=None) - - def depart_version(self, node): - self.depart_docinfo_item() - - def visit_warning(self, node): - self.visit_admonition(node, 'warning') - - def depart_warning(self, node): - self.depart_admonition() - - def unimplemented_visit(self, node): - raise NotImplementedError('visiting unimplemented node type: %s' - % node.__class__.__name__) - - -class SimpleListChecker(nodes.GenericNodeVisitor): - - """ - Raise `nodes.SkipNode` if non-simple list item is encountered. - - Here "simple" means a list item containing nothing other than a single - paragraph, a simple list, or a paragraph followed by a simple list. - """ - - def default_visit(self, node): - raise nodes.NodeFound - - def visit_bullet_list(self, node): - pass - - def visit_enumerated_list(self, node): - pass - - def visit_list_item(self, node): - children = [] - for child in node.get_children(): - if not isinstance(child, nodes.Invisible): - children.append(child) - if (children and isinstance(children[0], nodes.paragraph) - and (isinstance(children[-1], nodes.bullet_list) - or isinstance(children[-1], nodes.enumerated_list))): - children.pop() - if len(children) <= 1: - return - else: - raise nodes.NodeFound - - def visit_paragraph(self, node): - raise nodes.SkipNode - - def invisible_visit(self, node): - """Invisible nodes should be ignored.""" - pass - - visit_comment = invisible_visit - visit_substitution_definition = invisible_visit - visit_target = invisible_visit - visit_pending = invisible_visit diff --git a/docutils/docutils/writers/latex2e.py b/docutils/docutils/writers/latex2e.py deleted file mode 100644 index 619d168b7..000000000 --- a/docutils/docutils/writers/latex2e.py +++ /dev/null @@ -1,1472 +0,0 @@ -""" -:Author: Engelbert Gruber -:Contact: grubert@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. - -LaTeX2e document tree Writer. -""" - -__docformat__ = 'reStructuredText' - -# code contributions from several people included, thanks too all. -# some named: David Abrahams, Julien Letessier, who is missing. -# -# convention deactivate code by two # e.g. ##. - -import sys -import time -import re -import string -from types import ListType -from docutils import writers, nodes, languages - -class Writer(writers.Writer): - - supported = ('latex','latex2e') - """Formats this writer supports.""" - - settings_spec = ( - 'LaTeX-Specific Options', - 'The LaTeX "--output-encoding" default is "latin-1:strict".', - (('Specify documentclass. Default is "article".', - ['--documentclass'], - {'default': 'article', }), - ('Format for footnote references: one of "superscript" or ' - '"brackets". Default is "brackets".', - ['--footnote-references'], - {'choices': ['superscript', 'brackets'], 'default': 'brackets', - 'metavar': '<format>'}), - ('Format for block quote attributions: one of "dash" (em-dash ' - 'prefix), "parentheses"/"parens", or "none". Default is "dash".', - ['--attribution'], - {'choices': ['dash', 'parentheses', 'parens', 'none'], - 'default': 'dash', 'metavar': '<format>'}), - ('Specify a stylesheet file. The file will be "input" by latex ' - 'in the document header. Default is "style.tex". ' - 'If this is set to "" disables input.' - 'Overridden by --stylesheet-path.', - ['--stylesheet'], - {'default': 'style.tex', 'metavar': '<file>'}), - ('Specify a stylesheet file, relative to the current working ' - 'directory.' - 'Overrides --stylesheet.', - ['--stylesheet-path'], - {'metavar': '<file>'}), - ('Link to the stylesheet in the output LaTeX file. This is the ' - 'default.', - ['--link-stylesheet'], - {'dest': 'embed_stylesheet', 'action': 'store_false'}), - ('Embed the stylesheet in the output LaTeX file. The stylesheet ' - 'file must be accessible during processing (--stylesheet-path is ' - 'recommended).', - ['--embed-stylesheet'], - {'action': 'store_true'}), - ('Table of contents by docutils (default) or latex. Latex(writer) ' - 'supports only one ToC per document, but docutils does not write ' - 'pagenumbers.', - ['--use-latex-toc'], {'default': 0}), - ('Color of any hyperlinks embedded in text ' - '(default: "blue", "0" to disable).', - ['--hyperlink-color'], {'default': 'blue'}),)) - - settings_defaults = {'output_encoding': 'latin-1'} - - output = None - """Final translated form of `document`.""" - - def translate(self): - visitor = LaTeXTranslator(self.document) - self.document.walkabout(visitor) - self.output = visitor.astext() - self.head_prefix = visitor.head_prefix - self.head = visitor.head - self.body_prefix = visitor.body_prefix - self.body = visitor.body - self.body_suffix = visitor.body_suffix - -""" -Notes on LaTeX --------------- - -* latex does not support multiple tocs in one document. - (might be no limitation except for docutils documentation) - -* width - - * linewidth - width of a line in the local environment - * textwidth - the width of text on the page - - Maybe always use linewidth ? -""" - -class Babel: - """Language specifics for LaTeX.""" - # country code by a.schlock. - # partly manually converted from iso and babel stuff, dialects and some - _ISO639_TO_BABEL = { - 'no': 'norsk', #XXX added by hand ( forget about nynorsk?) - 'gd': 'scottish', #XXX added by hand - 'hu': 'magyar', #XXX added by hand - 'pt': 'portuguese',#XXX added by hand - 'sl': 'slovenian', - 'af': 'afrikaans', - 'bg': 'bulgarian', - 'br': 'breton', - 'ca': 'catalan', - 'cs': 'czech', - 'cy': 'welsh', - 'da': 'danish', - 'fr': 'french', - # french, francais, canadien, acadian - 'de': 'ngerman', #XXX rather than german - # ngerman, naustrian, german, germanb, austrian - 'el': 'greek', - 'en': 'english', - # english, USenglish, american, UKenglish, british, canadian - 'eo': 'esperanto', - 'es': 'spanish', - 'et': 'estonian', - 'eu': 'basque', - 'fi': 'finnish', - 'ga': 'irish', - 'gl': 'galician', - 'he': 'hebrew', - 'hr': 'croatian', - 'hu': 'hungarian', - 'is': 'icelandic', - 'it': 'italian', - 'la': 'latin', - 'nl': 'dutch', - 'pl': 'polish', - 'pt': 'portuguese', - 'ro': 'romanian', - 'ru': 'russian', - 'sk': 'slovak', - 'sr': 'serbian', - 'sv': 'swedish', - 'tr': 'turkish', - 'uk': 'ukrainian' - } - - def __init__(self,lang): - self.language = lang - # pdflatex does not produce double quotes for ngerman in tt. - self.double_quote_replacment = None - if re.search('^de',self.language): - # maybe use: {\glqq} {\grqq}. - self.quotes = ("\"`", "\"'") - self.double_quote_replacment = "{\\dq}" - else: - self.quotes = ("``", "''") - self.quote_index = 0 - - def next_quote(self): - q = self.quotes[self.quote_index] - self.quote_index = (self.quote_index+1)%2 - return q - - def quote_quotes(self,text): - t = None - for part in text.split('"'): - if t == None: - t = part - else: - t += self.next_quote() + part - return t - - def double_quotes_in_tt (self,text): - if not self.double_quote_replacment: - return text - return text.replace('"', self.double_quote_replacment) - - def get_language(self): - if self._ISO639_TO_BABEL.has_key(self.language): - return self._ISO639_TO_BABEL[self.language] - else: - # support dialects. - l = self.language.split("_")[0] - if self._ISO639_TO_BABEL.has_key(l): - return self._ISO639_TO_BABEL[l] - return None - - -latex_headings = { - 'optionlist_environment' : [ - '\\newcommand{\\optionlistlabel}[1]{\\bf #1 \\hfill}\n' - '\\newenvironment{optionlist}[1]\n' - '{\\begin{list}{}\n' - ' {\\setlength{\\labelwidth}{#1}\n' - ' \\setlength{\\rightmargin}{1cm}\n' - ' \\setlength{\\leftmargin}{\\rightmargin}\n' - ' \\addtolength{\\leftmargin}{\\labelwidth}\n' - ' \\addtolength{\\leftmargin}{\\labelsep}\n' - ' \\renewcommand{\\makelabel}{\\optionlistlabel}}\n' - '}{\\end{list}}\n', - ], - 'footnote_floats' : [ - '% begin: floats for footnotes tweaking.\n', - '\\setlength{\\floatsep}{0.5em}\n', - '\\setlength{\\textfloatsep}{\\fill}\n', - '\\addtolength{\\textfloatsep}{3em}\n', - '\\renewcommand{\\textfraction}{0.5}\n', - '\\renewcommand{\\topfraction}{0.5}\n', - '\\renewcommand{\\bottomfraction}{0.5}\n', - '\\setcounter{totalnumber}{50}\n', - '\\setcounter{topnumber}{50}\n', - '\\setcounter{bottomnumber}{50}\n', - '% end floats for footnotes\n', - ], - 'some_commands' : [ - '% some commands, that could be overwritten in the style file.\n' - '\\newcommand{\\rubric}[1]' - '{\\subsection*{~\\hfill {\\it #1} \\hfill ~}}\n' - '% end of "some commands"\n', - ] - } - - -class LaTeXTranslator(nodes.NodeVisitor): - # When options are given to the documentclass, latex will pass them - # to other packages, as done with babel. - # Dummy settings might be taken from document settings - - d_options = '10pt' # papersize, fontsize - d_paper = 'a4paper' - d_margins = '2cm' - - latex_head = '\\documentclass[%s]{%s}\n' - encoding = '\\usepackage[%s]{inputenc}\n' - linking = '\\usepackage[colorlinks=%s,linkcolor=%s,urlcolor=%s]{hyperref}\n' - geometry = '\\usepackage[%s,margin=%s,nohead]{geometry}\n' - stylesheet = '\\input{%s}\n' - # add a generated on day , machine by user using docutils version. - generator = '%% generator Docutils: http://docutils.sourceforge.net/\n' - - # use latex tableofcontents or let docutils do it. - use_latex_toc = 0 - # table kind: if 0 tabularx (single page), 1 longtable - # maybe should be decided on row count. - use_longtable = 1 - # TODO: use mixins for different implementations. - # list environment for option-list. else tabularx - use_optionlist_for_option_list = 1 - # list environment for docinfo. else tabularx - use_optionlist_for_docinfo = 0 # NOT YET IN USE - - # default link color - hyperlink_color = "blue" - - def __init__(self, document): - nodes.NodeVisitor.__init__(self, document) - self.settings = settings = document.settings - self.use_latex_toc = settings.use_latex_toc - self.hyperlink_color = settings.hyperlink_color - if self.hyperlink_color == '0': - self.hyperlink_color = 'black' - self.colorlinks = 'false' - else: - self.colorlinks = 'true' - - # language: labels, bibliographic_fields, and author_separators. - # to allow writing labes for specific languages. - self.language = languages.get_language(settings.language_code) - self.babel = Babel(settings.language_code) - self.author_separator = self.language.author_separators[0] - if self.babel.get_language(): - self.d_options += ',%s' % \ - self.babel.get_language() - self.head_prefix = [ - self.latex_head % (self.d_options,self.settings.documentclass), - '\\usepackage{babel}\n', # language is in documents settings. - '\\usepackage{shortvrb}\n', # allows verb in footnotes. - self.encoding % self.to_latex_encoding(settings.output_encoding), - # * tabularx: for docinfo, automatic width of columns, always on one page. - '\\usepackage{tabularx}\n', - '\\usepackage{longtable}\n', - # possible other packages. - # * fancyhdr - # * ltxtable is a combination of tabularx and longtable (pagebreaks). - # but ?? - # - # extra space between text in tables and the line above them - '\\setlength{\\extrarowheight}{2pt}\n', - '\\usepackage{amsmath}\n', # what fore amsmath. - '\\usepackage{graphicx}\n', - '\\usepackage{color}\n', - '\\usepackage{multirow}\n', - self.linking % (self.colorlinks, self.hyperlink_color, self.hyperlink_color), - # geometry and fonts might go into style.tex. - self.geometry % (self.d_paper, self.d_margins), - # - self.generator, - # latex lengths - '\\newlength{\\admonitionwidth}\n', - '\\setlength{\\admonitionwidth}{0.9\\textwidth}\n' - # width for docinfo tablewidth - '\\newlength{\\docinfowidth}\n', - '\\setlength{\\docinfowidth}{0.9\\textwidth}\n' - ] - self.head_prefix.extend( latex_headings['optionlist_environment'] ) - self.head_prefix.extend( latex_headings['footnote_floats'] ) - self.head_prefix.extend( latex_headings['some_commands'] ) - ## stylesheet is last: so it might be possible to overwrite defaults. - stylesheet = self.get_stylesheet_reference() - if stylesheet: - self.head_prefix.append(self.stylesheet % (stylesheet)) - - if self.linking: # and maybe check for pdf - self.pdfinfo = [ ] - self.pdfauthor = None - # pdftitle, pdfsubject, pdfauthor, pdfkeywords, pdfcreator, pdfproducer - else: - self.pdfinfo = None - # NOTE: Latex wants a date and an author, rst puts this into - # docinfo, so normally we donot want latex author/date handling. - # latex article has its own handling of date and author, deactivate. - self.latex_docinfo = 0 - self.head = [ ] - if not self.latex_docinfo: - self.head.extend( [ '\\author{}\n', '\\date{}\n' ] ) - self.body_prefix = ['\\raggedbottom\n'] - # separate title, so we can appen subtitle. - self.title = "" - self.body = [] - self.body_suffix = ['\n'] - self.section_level = 0 - self.context = [] - self.topic_class = '' - # column specification for tables - self.colspecs = [] - # Flags to encode - # --------------- - # verbatim: to tell encode not to encode. - self.verbatim = 0 - # insert_newline: to tell encode to replace blanks by "~". - self.insert_none_breaking_blanks = 0 - # insert_newline: to tell encode to add latex newline. - self.insert_newline = 0 - # mbox_newline: to tell encode to add mbox and newline. - self.mbox_newline = 0 - - # enumeration is done by list environment. - self._enum_cnt = 0 - # docinfo. - self.docinfo = None - # inside literal block: no quote mangling. - self.literal_block = 0 - self.literal = 0 - - def get_stylesheet_reference(self): - if self.settings.stylesheet_path: - return self.settings.stylesheet_path - else: - return self.settings.stylesheet - - def to_latex_encoding(self,docutils_encoding): - """ - Translate docutils encoding name into latex's. - - Default fallback method is remove "-" and "_" chars from docutils_encoding. - - """ - tr = { "iso-8859-1": "latin1", # west european - "iso-8859-2": "latin2", # east european - "iso-8859-3": "latin3", # esperanto, maltese - "iso-8859-4": "latin4", # north european,scandinavian, baltic - "iso-8859-5": "iso88595", # cyrillic (ISO) - "iso-8859-9": "latin5", # turkish - "iso-8859-15": "latin9", # latin9, update to latin1. - "mac_cyrillic": "maccyr", # cyrillic (on Mac) - "windows-1251": "cp1251", # cyrillic (on Windows) - "koi8-r": "koi8-r", # cyrillic (Russian) - "koi8-u": "koi8-u", # cyrillic (Ukrainian) - "windows-1250": "cp1250", # - "windows-1252": "cp1252", # - "us-ascii": "ascii", # ASCII (US) - # unmatched encodings - #"": "applemac", - #"": "ansinew", # windows 3.1 ansi - #"": "ascii", # ASCII encoding for the range 32--127. - #"": "cp437", # dos latine us - #"": "cp850", # dos latin 1 - #"": "cp852", # dos latin 2 - #"": "decmulti", - #"": "latin10", - #"iso-8859-6": "" # arabic - #"iso-8859-7": "" # greek - #"iso-8859-8": "" # hebrew - #"iso-8859-10": "" # latin6, more complete iso-8859-4 - } - if tr.has_key(docutils_encoding.lower()): - return tr[docutils_encoding.lower()] - return docutils_encoding.translate(string.maketrans("",""),"_-").lower() - - def language_label(self, docutil_label): - return self.language.labels[docutil_label] - - def encode(self, text): - """ - Encode special characters in `text` & return. - # $ % & ~ _ ^ \ { } - Escaping with a backslash does not help with backslashes, ~ and ^. - - < > are only available in math-mode (really ?) - $ starts math- mode. - AND quotes: - - """ - if self.verbatim: - return text - # compile the regexps once. do it here so one can see them. - # - # first the braces. - if not self.__dict__.has_key('encode_re_braces'): - self.encode_re_braces = re.compile(r'([{}])') - text = self.encode_re_braces.sub(r'{\\\1}',text) - if not self.__dict__.has_key('encode_re_bslash'): - # find backslash: except in the form '{\{}' or '{\}}'. - self.encode_re_bslash = re.compile(r'(?<!{)(\\)(?![{}]})') - # then the backslash: except in the form from line above: - # either '{\{}' or '{\}}'. - text = self.encode_re_bslash.sub(r'{\\textbackslash}', text) - - # then dollar - text = text.replace("$", '{\\$}') - # then all that needs math mode - text = text.replace("<", '{$<$}') - text = text.replace(">", '{$>$}') - # then - text = text.replace("&", '{\\&}') - text = text.replace("_", '{\\_}') - # the ^: - # * verb|^| does not work in mbox. - # * mathmode has wedge. hat{~} would also work. - text = text.replace("^", '{\\ensuremath{^\\wedge}}') - text = text.replace("%", '{\\%}') - text = text.replace("#", '{\\#}') - text = text.replace("~", '{\\~{ }}') - if self.literal_block or self.literal: - # pdflatex does not produce doublequotes for ngerman. - text = self.babel.double_quotes_in_tt(text) - else: - text = self.babel.quote_quotes(text) - if self.insert_newline: - # HACK: insert a blank before the newline, to avoid - # ! LaTeX Error: There's no line here to end. - text = text.replace("\n", '~\\\\\n') - elif self.mbox_newline: - text = text.replace("\n", '}\\\\\n\\mbox{') - if self.insert_none_breaking_blanks: - text = text.replace(' ', '~') - # unicode !!! - text = text.replace(u'\u2020', '{$\\dagger$}') - return text - - def attval(self, text, - whitespace=re.compile('[\n\r\t\v\f]')): - """Cleanse, encode, and return attribute value text.""" - return self.encode(whitespace.sub(' ', text)) - - def astext(self): - if self.pdfinfo: - if self.pdfauthor: - self.pdfinfo.append('pdfauthor={%s}' % self.pdfauthor) - pdfinfo = '\\hypersetup{\n' + ',\n'.join(self.pdfinfo) + '\n}\n' - else: - pdfinfo = '' - title = '\\title{%s}\n' % self.title - return ''.join(self.head_prefix + [title] - + self.head + [pdfinfo] - + self.body_prefix + self.body + self.body_suffix) - - def visit_Text(self, node): - self.body.append(self.encode(node.astext())) - - def depart_Text(self, node): - pass - - def visit_address(self, node): - self.visit_docinfo_item(node, 'address') - - def depart_address(self, node): - self.depart_docinfo_item(node) - - def visit_admonition(self, node, name): - self.body.append('\\begin{center}\\begin{sffamily}\n') - self.body.append('\\fbox{\\parbox{\\admonitionwidth}{\n') - self.body.append('\\textbf{\\large '+ self.language.labels[name] + '}\n'); - self.body.append('\\vspace{2mm}\n') - - - def depart_admonition(self): - self.body.append('}}\n') # end parbox fbox - self.body.append('\\end{sffamily}\n\\end{center}\n'); - - def visit_attention(self, node): - self.visit_admonition(node, 'attention') - - def depart_attention(self, node): - self.depart_admonition() - - def visit_author(self, node): - self.visit_docinfo_item(node, 'author') - - def depart_author(self, node): - self.depart_docinfo_item(node) - - def visit_authors(self, node): - # ignore. visit_author is called for each one - # self.visit_docinfo_item(node, 'author') - pass - - def depart_authors(self, node): - # self.depart_docinfo_item(node) - pass - - def visit_block_quote(self, node): - self.body.append( '\\begin{quote}\n') - - def depart_block_quote(self, node): - self.body.append( '\\end{quote}\n') - - def visit_bullet_list(self, node): - if not self.use_latex_toc and self.topic_class == 'contents': - self.body.append( '\\begin{list}{}{}\n' ) - else: - self.body.append( '\\begin{itemize}\n' ) - - def depart_bullet_list(self, node): - if not self.use_latex_toc and self.topic_class == 'contents': - self.body.append( '\\end{list}\n' ) - else: - self.body.append( '\\end{itemize}\n' ) - - def visit_caption(self, node): - self.body.append( '\\caption{' ) - - def depart_caption(self, node): - self.body.append('}') - - def visit_caution(self, node): - self.visit_admonition(node, 'caution') - - def depart_caution(self, node): - self.depart_admonition() - - def visit_citation(self, node): - self.visit_footnote(node) - - def depart_citation(self, node): - self.depart_footnote(node) - - def visit_title_reference(self, node): - # BUG title-references are what? - pass - - def depart_title_reference(self, node): - pass - - def visit_citation_reference(self, node): - href = '' - if node.has_key('refid'): - href = node['refid'] - elif node.has_key('refname'): - href = self.document.nameids[node['refname']] - self.body.append('[\\hyperlink{%s}{' % href) - - def depart_citation_reference(self, node): - self.body.append('}]') - - def visit_classifier(self, node): - self.body.append( '(\\textbf{' ) - - def depart_classifier(self, node): - self.body.append( '})\n' ) - - def visit_colspec(self, node): - if self.use_longtable: - self.colspecs.append(node) - else: - self.context[-1] += 1 - - def depart_colspec(self, node): - pass - - def visit_comment(self, node, - sub=re.compile('\n').sub): - """Escape end of line by a ne comment start in comment text.""" - self.body.append('%% %s \n' % sub('\n% ', node.astext())) - raise nodes.SkipNode - - def visit_contact(self, node): - self.visit_docinfo_item(node, 'contact') - - def depart_contact(self, node): - self.depart_docinfo_item(node) - - def visit_copyright(self, node): - self.visit_docinfo_item(node, 'copyright') - - def depart_copyright(self, node): - self.depart_docinfo_item(node) - - def visit_danger(self, node): - self.visit_admonition(node, 'danger') - - def depart_danger(self, node): - self.depart_admonition() - - def visit_date(self, node): - self.visit_docinfo_item(node, 'date') - - def depart_date(self, node): - self.depart_docinfo_item(node) - - def visit_decoration(self, node): - pass - - def depart_decoration(self, node): - pass - - def visit_definition(self, node): - self.body.append('%[visit_definition]\n') - - def depart_definition(self, node): - self.body.append('\n') - self.body.append('%[depart_definition]\n') - - def visit_definition_list(self, node): - self.body.append( '\\begin{description}\n' ) - - def depart_definition_list(self, node): - self.body.append( '\\end{description}\n' ) - - def visit_definition_list_item(self, node): - self.body.append('%[visit_definition_list_item]\n') - - def depart_definition_list_item(self, node): - self.body.append('%[depart_definition_list_item]\n') - - def visit_description(self, node): - if self.use_optionlist_for_option_list: - self.body.append( ' ' ) - else: - self.body.append( ' & ' ) - - def depart_description(self, node): - pass - - def visit_docinfo(self, node): - self.docinfo = [] - self.docinfo.append('%' + '_'*75 + '\n') - self.docinfo.append('\\begin{center}\n') - self.docinfo.append('\\begin{tabularx}{\\docinfowidth}{lX}\n') - - def depart_docinfo(self, node): - self.docinfo.append('\\end{tabularx}\n') - self.docinfo.append('\\end{center}\n') - self.body = self.docinfo + self.body - # clear docinfo, so field names are no longer appended. - self.docinfo = None - if self.use_latex_toc: - self.body.append('\\tableofcontents\n\n\\bigskip\n') - - def visit_docinfo_item(self, node, name): - if not self.latex_docinfo: - self.docinfo.append('\\textbf{%s}: &\n\t' % self.language_label(name)) - if name == 'author': - if not self.pdfinfo == None: - if not self.pdfauthor: - self.pdfauthor = self.attval(node.astext()) - else: - self.pdfauthor += self.author_separator + self.attval(node.astext()) - if self.latex_docinfo: - self.head.append('\\author{%s}\n' % self.attval(node.astext())) - raise nodes.SkipNode - elif name == 'date': - if self.latex_docinfo: - self.head.append('\\date{%s}\n' % self.attval(node.astext())) - raise nodes.SkipNode - if name == 'address': - # BUG will fail if latex_docinfo is set. - self.insert_newline = 1 - self.docinfo.append('{\\raggedright\n') - self.context.append(' } \\\\\n') - else: - self.context.append(' \\\\\n') - self.context.append(self.docinfo) - self.context.append(len(self.body)) - - def depart_docinfo_item(self, node): - size = self.context.pop() - dest = self.context.pop() - tail = self.context.pop() - tail = self.body[size:] + [tail] - del self.body[size:] - dest.extend(tail) - # for address we did set insert_newline - self.insert_newline = 0 - - def visit_doctest_block(self, node): - self.body.append( '\\begin{verbatim}' ) - self.verbatim = 1 - - def depart_doctest_block(self, node): - self.body.append( '\\end{verbatim}\n' ) - self.verbatim = 0 - - def visit_document(self, node): - self.body_prefix.append('\\begin{document}\n') - self.body_prefix.append('\\maketitle\n\n') - # alternative use titlepage environment. - # \begin{titlepage} - - def depart_document(self, node): - self.body_suffix.append('\\end{document}\n') - - def visit_emphasis(self, node): - self.body.append('\\emph{') - - def depart_emphasis(self, node): - self.body.append('}') - - def visit_entry(self, node): - # cell separation - column_one = 1 - if self.context[-1] > 0: - column_one = 0 - if not column_one: - self.body.append(' & ') - - # multi{row,column} - if node.has_key('morerows') and node.has_key('morecols'): - raise NotImplementedError('LaTeX can\'t handle cells that' - 'span multiple rows *and* columns, sorry.') - atts = {} - if node.has_key('morerows'): - count = node['morerows'] + 1 - self.body.append('\\multirow{%d}*{' % count) - self.context.append('}') - elif node.has_key('morecols'): - # the vertical bar before column is missing if it is the first column. - # the one after always. - if column_one: - bar = '|' - else: - bar = '' - count = node['morecols'] + 1 - self.body.append('\\multicolumn{%d}{%sl|}{' % (count, bar)) - self.context.append('}') - else: - self.context.append('') - - # header / not header - if isinstance(node.parent.parent, nodes.thead): - self.body.append('\\textbf{') - self.context.append('}') - else: - self.context.append('') - - def depart_entry(self, node): - self.body.append(self.context.pop()) # header / not header - self.body.append(self.context.pop()) # multirow/column - self.context[-1] += 1 - - def visit_enumerated_list(self, node): - # We create our own enumeration list environment. - # This allows to set the style and starting value - # and unlimited nesting. - self._enum_cnt += 1 - - enum_style = {'arabic':'arabic', - 'loweralpha':'alph', - 'upperalpha':'Alph', - 'lowerroman':'roman', - 'upperroman':'Roman' } - enum_suffix = "" - if node.has_key('suffix'): - enum_suffix = node['suffix'] - enum_prefix = "" - if node.has_key('prefix'): - enum_prefix = node['prefix'] - - enum_type = "arabic" - if node.has_key('enumtype'): - enum_type = node['enumtype'] - if enum_style.has_key(enum_type): - enum_type = enum_style[enum_type] - counter_name = "listcnt%d" % self._enum_cnt; - self.body.append('\\newcounter{%s}\n' % counter_name) - self.body.append('\\begin{list}{%s\\%s{%s}%s}\n' % \ - (enum_prefix,enum_type,counter_name,enum_suffix)) - self.body.append('{\n') - self.body.append('\\usecounter{%s}\n' % counter_name) - # set start after usecounter, because it initializes to zero. - if node.has_key('start'): - self.body.append('\\addtocounter{%s}{%d}\n' \ - % (counter_name,node['start']-1)) - ## set rightmargin equal to leftmargin - self.body.append('\\setlength{\\rightmargin}{\\leftmargin}\n') - self.body.append('}\n') - - def depart_enumerated_list(self, node): - self.body.append('\\end{list}\n') - - def visit_error(self, node): - self.visit_admonition(node, 'error') - - def depart_error(self, node): - self.depart_admonition() - - def visit_field(self, node): - # real output is done in siblings: _argument, _body, _name - pass - - def depart_field(self, node): - self.body.append('\n') - ##self.body.append('%[depart_field]\n') - - def visit_field_argument(self, node): - self.body.append('%[visit_field_argument]\n') - - def depart_field_argument(self, node): - self.body.append('%[depart_field_argument]\n') - - def visit_field_body(self, node): - # BUG by attach as text we loose references. - if self.docinfo: - self.docinfo.append('%s \\\\\n' % node.astext()) - raise nodes.SkipNode - # BUG: what happens if not docinfo - - def depart_field_body(self, node): - self.body.append( '\n' ) - - def visit_field_list(self, node): - if not self.docinfo: - self.body.append('\\begin{quote}\n') - self.body.append('\\begin{description}\n') - - def depart_field_list(self, node): - if not self.docinfo: - self.body.append('\\end{description}\n') - self.body.append('\\end{quote}\n') - - def visit_field_name(self, node): - # BUG this duplicates docinfo_item - if self.docinfo: - self.docinfo.append('\\textbf{%s}: &\n\t' % node.astext()) - raise nodes.SkipNode - else: - self.body.append('\\item [') - - def depart_field_name(self, node): - if not self.docinfo: - self.body.append(':]') - - def visit_figure(self, node): - self.body.append( '\\begin{figure}\n' ) - - def depart_figure(self, node): - self.body.append( '\\end{figure}\n' ) - - def visit_footer(self, node): - self.context.append(len(self.body)) - - def depart_footer(self, node): - start = self.context.pop() - footer = (['\n\\begin{center}\small\n'] - + self.body[start:] + ['\n\\end{center}\n']) - self.body_suffix[:0] = footer - del self.body[start:] - - def visit_footnote(self, node): - notename = node['id'] - self.body.append('\\begin{figure}[b]') - self.body.append('\\hypertarget{%s}' % notename) - - def depart_footnote(self, node): - self.body.append('\\end{figure}\n') - - def visit_footnote_reference(self, node): - href = '' - if node.has_key('refid'): - href = node['refid'] - elif node.has_key('refname'): - href = self.document.nameids[node['refname']] - format = self.settings.footnote_references - if format == 'brackets': - suffix = '[' - self.context.append(']') - elif format == 'superscript': - suffix = '\\raisebox{.5em}[0em]{\\scriptsize' - self.context.append('}') - else: # shouldn't happen - raise AssertionError('Illegal footnote reference format.') - self.body.append('%s\\hyperlink{%s}{' % (suffix,href)) - - def depart_footnote_reference(self, node): - self.body.append('}%s' % self.context.pop()) - - def visit_generated(self, node): - pass - - def depart_generated(self, node): - pass - - def visit_header(self, node): - self.context.append(len(self.body)) - - def depart_header(self, node): - start = self.context.pop() - self.body_prefix.append('\n\\verb|begin_header|\n') - self.body_prefix.extend(self.body[start:]) - self.body_prefix.append('\n\\verb|end_header|\n') - del self.body[start:] - - def visit_hint(self, node): - self.visit_admonition(node, 'hint') - - def depart_hint(self, node): - self.depart_admonition() - - def visit_image(self, node): - atts = node.attributes.copy() - href = atts['uri'] - ##self.body.append('\\begin{center}\n') - self.body.append('\n\\includegraphics{%s}\n' % href) - ##self.body.append('\\end{center}\n') - - def depart_image(self, node): - pass - - def visit_important(self, node): - self.visit_admonition(node, 'important') - - def depart_important(self, node): - self.depart_admonition() - - def visit_interpreted(self, node): - # @@@ Incomplete, pending a proper implementation on the - # Parser/Reader end. - self.visit_literal(node) - - def depart_interpreted(self, node): - self.depart_literal(node) - - def visit_label(self, node): - # footnote/citation label - self.body.append('[') - - def depart_label(self, node): - self.body.append(']') - - def visit_legend(self, node): - self.body.append('{\\small ') - - def depart_legend(self, node): - self.body.append('}') - - def visit_line_block(self, node): - """line-block: - * whitespace (including linebreaks) is significant - * inline markup is supported. - * serif typeface - """ - self.body.append('\\begin{flushleft}\n') - self.insert_none_breaking_blanks = 1 - self.line_block_without_mbox = 1 - if self.line_block_without_mbox: - self.insert_newline = 1 - else: - self.mbox_newline = 1 - self.body.append('\\mbox{') - - def depart_line_block(self, node): - if self.line_block_without_mbox: - self.insert_newline = 0 - else: - self.body.append('}') - self.mbox_newline = 0 - self.insert_none_breaking_blanks = 0 - self.body.append('\n\\end{flushleft}\n') - - def visit_list_item(self, node): - self.body.append('\\item ') - - def depart_list_item(self, node): - self.body.append('\n') - - def visit_literal(self, node): - self.literal = 1 - self.body.append('\\texttt{') - - def depart_literal(self, node): - self.body.append('}') - self.literal = 0 - - def visit_literal_block(self, node): - """ - .. parsed-literal:: - """ - # typically in a typewriter/monospaced typeface. - # care must be taken with the text, because inline markup is recognized. - # - # possibilities: - # * verbatim: is no possibility, as inline markup does not work. - # * obey..: is from julien and never worked for me (grubert). - self.use_for_literal_block = "mbox" - self.literal_block = 1 - if (self.use_for_literal_block == "mbox"): - self.mbox_newline = 1 - self.insert_none_breaking_blanks = 1 - self.body.append('\\begin{ttfamily}\\begin{flushleft}\n\\mbox{') - else: - self.body.append('{\\obeylines\\obeyspaces\\ttfamily\n') - - def depart_literal_block(self, node): - if (self.use_for_literal_block == "mbox"): - self.body.append('}\n\\end{flushleft}\\end{ttfamily}\n') - self.insert_none_breaking_blanks = 0 - self.mbox_newline = 0 - else: - self.body.append('}\n') - self.literal_block = 0 - - def visit_meta(self, node): - self.body.append('[visit_meta]\n') - # BUG maybe set keywords for pdf - ##self.head.append(self.starttag(node, 'meta', **node.attributes)) - - def depart_meta(self, node): - self.body.append('[depart_meta]\n') - - def visit_note(self, node): - self.visit_admonition(node, 'note') - - def depart_note(self, node): - self.depart_admonition() - - def visit_option(self, node): - if self.context[-1]: - # this is not the first option - self.body.append(', ') - - def depart_option(self, node): - # flag tha the first option is done. - self.context[-1] += 1 - - def visit_option_argument(self, node): - """The delimiter betweeen an option and its argument.""" - self.body.append(node.get('delimiter', ' ')) - - def depart_option_argument(self, node): - pass - - def visit_option_group(self, node): - if self.use_optionlist_for_option_list: - self.body.append('\\item [') - else: - atts = {} - if len(node.astext()) > 14: - self.body.append('\\multicolumn{2}{l}{') - self.context.append('} \\\\\n ') - else: - self.context.append('') - self.body.append('\\texttt{') - # flag for first option - self.context.append(0) - - def depart_option_group(self, node): - self.context.pop() # the flag - if self.use_optionlist_for_option_list: - self.body.append('] ') - else: - self.body.append('}') - self.body.append(self.context.pop()) - - def visit_option_list(self, node): - self.body.append('% [option list]\n') - if self.use_optionlist_for_option_list: - self.body.append('\\begin{optionlist}{3cm}\n') - else: - self.body.append('\\begin{center}\n') - # BUG: use admwidth or make it relative to textwidth ? - self.body.append('\\begin{tabularx}{.9\\linewidth}{lX}\n') - - def depart_option_list(self, node): - if self.use_optionlist_for_option_list: - self.body.append('\\end{optionlist}\n') - else: - self.body.append('\\end{tabularx}\n') - self.body.append('\\end{center}\n') - - def visit_option_list_item(self, node): - pass - - def depart_option_list_item(self, node): - if not self.use_optionlist_for_option_list: - self.body.append('\\\\\n') - - def visit_option_string(self, node): - ##self.body.append(self.starttag(node, 'span', '', CLASS='option')) - pass - - def depart_option_string(self, node): - ##self.body.append('</span>') - pass - - def visit_organization(self, node): - self.visit_docinfo_item(node, 'organization') - - def depart_organization(self, node): - self.depart_docinfo_item(node) - - def visit_paragraph(self, node): - if not self.topic_class == 'contents': - self.body.append('\n') - - def depart_paragraph(self, node): - if self.topic_class == 'contents': - self.body.append('\n') - else: - self.body.append('\n') - - def visit_problematic(self, node): - self.body.append('{\\color{red}\\bfseries{}') - - def depart_problematic(self, node): - self.body.append('}') - - def visit_raw(self, node): - if node.has_key('format') and node['format'].lower() == 'latex': - self.body.append(node.astext()) - raise nodes.SkipNode - - def visit_reference(self, node): - # for pdflatex hyperrefs might be supported - if node.has_key('refuri'): - href = node['refuri'] - elif node.has_key('refid'): - href = '#' + node['refid'] - elif node.has_key('refname'): - href = '#' + self.document.nameids[node['refname']] - ##self.body.append('[visit_reference]') - self.body.append('\\href{%s}{' % href) - - def depart_reference(self, node): - self.body.append('}') - ##self.body.append('[depart_reference]') - - def visit_revision(self, node): - self.visit_docinfo_item(node, 'revision') - - def depart_revision(self, node): - self.depart_docinfo_item(node) - - def visit_row(self, node): - self.context.append(0) - - def depart_row(self, node): - self.context.pop() # remove cell counter - self.body.append(' \\\\ \\hline\n') - - def visit_section(self, node): - self.section_level += 1 - - def depart_section(self, node): - self.section_level -= 1 - - def visit_sidebar(self, node): - # BUG: this is just a hack to make sidebars render something - self.body.append('\\begin{center}\\begin{sffamily}\n') - self.body.append('\\fbox{\\colorbox[gray]{0.80}{\\parbox{\\admonitionwidth}{\n') - - def depart_sidebar(self, node): - self.body.append('}}}\n') # end parbox colorbox fbox - self.body.append('\\end{sffamily}\n\\end{center}\n'); - - - attribution_formats = {'dash': ('---', ''), - 'parentheses': ('(', ')'), - 'parens': ('(', ')'), - 'none': ('', '')} - - def visit_attribution(self, node): - prefix, suffix = self.attribution_formats[self.settings.attribution] - self.body.append('\n\\begin{flushright}\n') - self.body.append(prefix) - self.context.append(suffix) - - def depart_attribution(self, node): - self.body.append(self.context.pop() + '\n') - self.body.append('\\end{flushright}\n') - - def visit_status(self, node): - self.visit_docinfo_item(node, 'status') - - def depart_status(self, node): - self.depart_docinfo_item(node) - - def visit_strong(self, node): - self.body.append('\\textbf{') - - def depart_strong(self, node): - self.body.append('}') - - def visit_substitution_definition(self, node): - raise nodes.SkipNode - - def visit_substitution_reference(self, node): - self.unimplemented_visit(node) - - def visit_subtitle(self, node): - if isinstance(node.parent, nodes.sidebar): - self.body.append('~\\\\\n\\textbf{') - self.context.append('}\n\\smallskip\n') - else: - self.title = self.title + \ - '\\\\\n\\large{%s}\n' % self.encode(node.astext()) - raise nodes.SkipNode - - def depart_subtitle(self, node): - if isinstance(node.parent, nodes.sidebar): - self.body.append(self.context.pop()) - - def visit_system_message(self, node): - if node['level'] < self.document.reporter['writer'].report_level: - raise nodes.SkipNode - - - def depart_system_message(self, node): - self.body.append('\n') - - def get_colspecs(self): - """ - Return column specification for longtable. - - Assumes reST line length being 80 characters. - """ - width = 80 - - total_width = 0.0 - # first see if we get too wide. - for node in self.colspecs: - colwidth = float(node['colwidth']) / width - total_width += colwidth - # donot make it full linewidth - factor = 0.93 - if total_width > 1.0: - factor /= total_width - - latex_table_spec = "" - for node in self.colspecs: - colwidth = factor * float(node['colwidth']) / width - latex_table_spec += "|p{%.2f\\linewidth}" % colwidth - self.colspecs = [] - return latex_table_spec+"|" - - def visit_table(self, node): - if self.use_longtable: - self.body.append('\n\\begin{longtable}[c]') - else: - self.body.append('\n\\begin{tabularx}{\\linewidth}') - self.context.append('table_sentinel') # sentinel - self.context.append(0) # column counter - - def depart_table(self, node): - if self.use_longtable: - self.body.append('\\end{longtable}\n') - else: - self.body.append('\\end{tabularx}\n') - sentinel = self.context.pop() - if sentinel != 'table_sentinel': - print 'context:', self.context + [sentinel] - raise AssertionError - - def table_preamble(self): - if self.use_longtable: - self.body.append('{%s}\n' % self.get_colspecs()) - else: - if self.context[-1] != 'table_sentinel': - self.body.append('{%s}' % ('|X' * self.context.pop() + '|')) - self.body.append('\n\\hline') - - def visit_target(self, node): - if not (node.has_key('refuri') or node.has_key('refid') - or node.has_key('refname')): - self.body.append('\\hypertarget{%s}{' % node['name']) - self.context.append('}') - else: - self.context.append('') - - def depart_target(self, node): - self.body.append(self.context.pop()) - - def visit_tbody(self, node): - # BUG write preamble if not yet done (colspecs not []) - # for tables without heads. - if self.colspecs: - self.visit_thead(None) - self.depart_thead(None) - self.body.append('%[visit_tbody]\n') - - def depart_tbody(self, node): - self.body.append('%[depart_tbody]\n') - - def visit_term(self, node): - self.body.append('\\item[') - - def depart_term(self, node): - # definition list term. - self.body.append(':]\n') - - def visit_tgroup(self, node): - #self.body.append(self.starttag(node, 'colgroup')) - #self.context.append('</colgroup>\n') - pass - - def depart_tgroup(self, node): - pass - - def visit_thead(self, node): - # number_of_columns will be zero after get_colspecs. - # BUG ! push onto context for depart to pop it. - number_of_columns = len(self.colspecs) - self.table_preamble() - #BUG longtable needs firstpage and lastfooter too. - self.body.append('\\hline\n') - - def depart_thead(self, node): - if self.use_longtable: - # the table header written should be on every page - # => \endhead - self.body.append('\\endhead\n') - # and the firsthead => \endfirsthead - # BUG i want a "continued from previous page" on every not - # firsthead, but then we need the header twice. - # - # there is a \endfoot and \endlastfoot too. - # but we need the number of columns to - # self.body.append('\\multicolumn{%d}{c}{"..."}\n' % number_of_columns) - # self.body.append('\\hline\n\\endfoot\n') - # self.body.append('\\hline\n') - # self.body.append('\\endlastfoot\n') - - - def visit_tip(self, node): - self.visit_admonition(node, 'tip') - - def depart_tip(self, node): - self.depart_admonition() - - def visit_title(self, node): - """Only 3 section levels are supported by LaTeX article (AFAIR).""" - if isinstance(node.parent, nodes.topic): - # section titles before the table of contents. - if node.parent.hasattr('id'): - self.body.append('\\hypertarget{%s}{}' % node.parent['id']) - # BUG: latex chokes on center environment with "perhaps a missing item". - # so we use hfill. - self.body.append('\\subsection*{~\\hfill ') - # the closing brace for subsection. - self.context.append('\\hfill ~}\n') - elif isinstance(node.parent, nodes.sidebar): - self.body.append('\\textbf{\\large ') - self.context.append('}\n\\smallskip\n') - elif self.section_level == 0: - # document title - self.title = self.encode(node.astext()) - if not self.pdfinfo == None: - self.pdfinfo.append( 'pdftitle={%s}' % self.encode(node.astext()) ) - raise nodes.SkipNode - else: - self.body.append('\n\n') - self.body.append('%' + '_' * 75) - self.body.append('\n\n') - if node.parent.hasattr('id'): - self.body.append('\\hypertarget{%s}{}\n' % node.parent['id']) - # section_level 0 is title and handled above. - # BUG: latex has no deeper sections (actually paragrah is no section either). - if self.use_latex_toc: - section_star = "" - else: - section_star = "*" - if (self.section_level<=3): # 1,2,3 - self.body.append('\\%ssection%s{' % ('sub'*(self.section_level-1),section_star)) - elif (self.section_level==4): - #self.body.append('\\paragraph*{') - self.body.append('\\subsubsection%s{' % (section_star)) - else: - #self.body.append('\\subparagraph*{') - self.body.append('\\subsubsection%s{' % (section_star)) - # BUG: self.body.append( '\\label{%s}\n' % name) - self.context.append('}\n') - - def depart_title(self, node): - self.body.append(self.context.pop()) - if isinstance(node.parent, nodes.sidebar): - return - # BUG level depends on style. - elif node.parent.hasattr('id') and not self.use_latex_toc: - # pdflatex allows level 0 to 3 - # ToC would be the only on level 0 so i choose to decrement the rest. - # "Table of contents" bookmark to see the ToC. To avoid this - # we set all zeroes to one. - l = self.section_level - if l>0: - l = l-1 - self.body.append('\\pdfbookmark[%d]{%s}{%s}\n' % \ - (l,node.astext(),node.parent['id'])) - - def visit_topic(self, node): - self.topic_class = node.get('class') - if self.use_latex_toc: - self.topic_class = '' - raise nodes.SkipNode - - def depart_topic(self, node): - self.topic_class = '' - self.body.append('\n') - - def visit_rubric(self, node): -# self.body.append('\\hfill {\\color{red}\\bfseries{}') -# self.context.append('} \\hfill ~\n') - self.body.append('\\rubric{') - self.context.append('}\n') - - def depart_rubric(self, node): - self.body.append(self.context.pop()) - - def visit_transition(self, node): - self.body.append('\n\n') - self.body.append('%' + '_' * 75) - self.body.append('\n\\hspace*{\\fill}\\hrulefill\\hspace*{\\fill}') - self.body.append('\n\n') - - def depart_transition(self, node): - #self.body.append('[depart_transition]') - pass - - def visit_version(self, node): - self.visit_docinfo_item(node, 'version') - - def depart_version(self, node): - self.depart_docinfo_item(node) - - def visit_warning(self, node): - self.visit_admonition(node, 'warning') - - def depart_warning(self, node): - self.depart_admonition() - - def unimplemented_visit(self, node): - raise NotImplementedError('visiting unimplemented node type: %s' - % node.__class__.__name__) - -# def unknown_visit(self, node): -# def default_visit(self, node): - -# vim: set ts=4 et ai : diff --git a/docutils/docutils/writers/pep_html.py b/docutils/docutils/writers/pep_html.py deleted file mode 100644 index 85c065c3d..000000000 --- a/docutils/docutils/writers/pep_html.py +++ /dev/null @@ -1,113 +0,0 @@ -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -PEP HTML Writer. -""" - -__docformat__ = 'reStructuredText' - - -import sys -import docutils -from docutils import nodes, frontend, utils -from docutils.writers import html4css1 - - -class Writer(html4css1.Writer): - - settings_spec = html4css1.Writer.settings_spec + ( - 'PEP/HTML-Specific Options', - 'The HTML --footnote-references option is set to "brackets" by ' - 'default.', - (('Specify a PEP stylesheet URL, used verbatim. Default is ' - '--stylesheet\'s value. If given, --pep-stylesheet overrides ' - '--stylesheet.', - ['--pep-stylesheet'], - {'metavar': '<URL>'}), - ('Specify a PEP stylesheet file, relative to the current working ' - 'directory. The path is adjusted relative to the output HTML ' - 'file. Overrides --pep-stylesheet and --stylesheet-path.', - ['--pep-stylesheet-path'], - {'metavar': '<path>'}), - ('Specify a template file. Default is "pep-html-template".', - ['--pep-template'], - {'default': 'pep-html-template', 'metavar': '<file>'}), - ('Python\'s home URL. Default is ".." (parent directory).', - ['--python-home'], - {'default': '..', 'metavar': '<URL>'}), - ('Home URL prefix for PEPs. Default is "." (current directory).', - ['--pep-home'], - {'default': '.', 'metavar': '<URL>'}), - # Workaround for SourceForge's broken Python - # (``import random`` causes a segfault). - (frontend.SUPPRESS_HELP, - ['--no-random'], {'action': 'store_true'}),)) - - settings_default_overrides = {'footnote_references': 'brackets'} - - relative_path_settings = ('pep_stylesheet_path', 'pep_template') - - def __init__(self): - html4css1.Writer.__init__(self) - self.translator_class = HTMLTranslator - - def translate(self): - html4css1.Writer.translate(self) - settings = self.document.settings - template = open(settings.pep_template).read() - # Substitutions dict for template: - subs = {} - subs['encoding'] = settings.output_encoding - subs['version'] = docutils.__version__ - subs['stylesheet'] = ''.join(self.stylesheet) - pyhome = settings.python_home - subs['pyhome'] = pyhome - subs['pephome'] = settings.pep_home - if pyhome == '..': - subs['pepindex'] = '.' - else: - subs['pepindex'] = pyhome + '/peps/' - index = self.document.first_child_matching_class(nodes.field_list) - header = self.document[index] - pepnum = header[0][1].astext() - subs['pep'] = pepnum - if settings.no_random: - subs['banner'] = 0 - else: - import random - subs['banner'] = random.randrange(64) - try: - subs['pepnum'] = '%04i' % int(pepnum) - except: - subs['pepnum'] = pepnum - subs['title'] = header[1][1].astext() - subs['body'] = ''.join( - self.body_pre_docinfo + self.docinfo + self.body) - subs['body_suffix'] = ''.join(self.body_suffix) - self.output = template % subs - - -class HTMLTranslator(html4css1.HTMLTranslator): - - def get_stylesheet_reference(self, relative_to=None): - settings = self.settings - if relative_to == None: - relative_to = settings._destination - if settings.pep_stylesheet_path: - return utils.relative_path(relative_to, - settings.pep_stylesheet_path) - elif settings.pep_stylesheet: - return settings.pep_stylesheet - elif settings._stylesheet_path: - return utils.relative_path(relative_to, settings.stylesheet_path) - else: - return settings.stylesheet - - def depart_field_list(self, node): - html4css1.HTMLTranslator.depart_field_list(self, node) - if node.get('class') == 'rfc2822': - self.body.append('<hr />\n') diff --git a/docutils/docutils/writers/pseudoxml.py b/docutils/docutils/writers/pseudoxml.py deleted file mode 100644 index 02dde58f3..000000000 --- a/docutils/docutils/writers/pseudoxml.py +++ /dev/null @@ -1,30 +0,0 @@ -# Authors: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Simple internal document tree Writer, writes indented pseudo-XML. -""" - -__docformat__ = 'reStructuredText' - - -from docutils import writers - - -class Writer(writers.Writer): - - supported = ('pprint', 'pformat', 'pseudoxml') - """Formats this writer supports.""" - - output = None - """Final translated form of `document`.""" - - def translate(self): - self.output = self.document.pformat() - - def supports(self, format): - """This writer supports all format-specific elements.""" - return 1 diff --git a/docutils/extras/optparse.py b/docutils/extras/optparse.py deleted file mode 100644 index 6e0381e4f..000000000 --- a/docutils/extras/optparse.py +++ /dev/null @@ -1,1401 +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', - 'STD_HELP_OPTION', - 'STD_VERSION_OPTION', - 'Values', - 'OptionContainer', - 'OptionGroup', - 'OptionParser', - 'HelpFormatter', - 'IndentedHelpFormatter', - 'TitledHelpFormatter', - 'OptParseError', - 'OptionError', - 'OptionConflictError', - 'OptionValueError', - 'BadOptionError'] - -__copyright__ = """ -Copyright (c) 2001-2003 Gregory P. Ward. 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 - -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) - - 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)) - - -_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" - -STD_HELP_OPTION = Option("-h", "--help", - action="help", - help="show this help message and exit") -STD_VERSION_OPTION = Option("--version", - action="version", - help="show program's version number and exit") - - -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): - if self.description: - desc = self.format_description(formatter) + "\n" - else: - desc = "" - return desc + self.format_option_help(formatter) - - -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 the STD_VERSION_OPTION (if 'version' supplied) - # and STD_HELP_OPTION globals. - 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 _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_option(STD_VERSION_OPTION) - if add_help: - self.add_option(STD_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.exit("%s: error: %s" % (self.get_prog_name(), msg)) - - 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 a4a549848..000000000 --- a/docutils/extras/textwrap.py +++ /dev/null @@ -1,355 +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 - -# 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, str): - text = text.translate(self.whitespace_trans) - elif isinstance(text, unicode): - 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/install.py b/docutils/install.py deleted file mode 100755 index ef3020b67..000000000 --- a/docutils/install.py +++ /dev/null @@ -1,21 +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! -""" - -from distutils import core -from setup import do_setup - -if __name__ == '__main__' : - core._setup_stop_after = 'config' - dist = do_setup() - dist.commands = ['install'] - dist.run_commands() 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/setup.py b/docutils/setup.py deleted file mode 100755 index 34c8680de..000000000 --- a/docutils/setup.py +++ /dev/null @@ -1,117 +0,0 @@ -#!/usr/bin/env python -# $Id$ -# Copyright: This file has been placed in the public domain. - -import sys -import os -from distutils.core import setup -from distutils.command.build_py import build_py - - -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 - -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 TeX. 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.3+', - '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',],} -"""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 :: 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/test/.cvsignore b/docutils/test/.cvsignore deleted file mode 100644 index b8af75aec..000000000 --- a/docutils/test/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -*.pyc -alltests.out diff --git a/docutils/test/DocutilsTestSupport.py b/docutils/test/DocutilsTestSupport.py deleted file mode 100644 index ebfc218f6..000000000 --- a/docutils/test/DocutilsTestSupport.py +++ /dev/null @@ -1,611 +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: - - `CustomTestSuite` - - `CustomTestCase` - - `TransformTestSuite` - - `TransformTestCase` - - `ParserTestSuite` - - `ParserTestCase` - - `PEPParserTestSuite` - - `PEPParserTestCase` - - `GridTableParserTestSuite` - - `GridTableParserTestCase` - - `SimpleTableParserTestSuite` - - `SimpleTableParserTestCase` - - 'LatexPublishTestSuite' - - 'LatexPublishTestCase' - - `DevNull` (output sink) -""" -__docformat__ = 'reStructuredText' - -import sys -import os -import unittest -import difflib -import inspect -from pprint import pformat -from types import UnicodeType -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, directives, languages -from docutils.readers import standalone, pep, python -from docutils.statemachine import string2lines - -try: - from docutils.readers.python import moduleparser -except: - moduleparser = None - -try: - import mypdb as pdb -except: - import pdb - - - -class DevNull: - - """Output sink.""" - - def write(self, string): - pass - - -class CustomTestSuite(unittest.TestSuite): - - """ - A collection of custom TestCases. - - """ - - 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): - """ - Initialize the CustomTestSuite. - - Arguments: - - id -- identifier for the suite, prepended to test cases. - """ - unittest.TestSuite.__init__(self, tests) - 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, short_description=None, - **kwargs): - """ - Create a custom TestCase in the CustomTestSuite. - Also return it, just in case. - - Arguments: - - test_case_class -- - method_name -- - 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. - short_description -- override to default test description. - """ - 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) - # generate and add test case - tc = test_case_class(method_name, input, expected, tcid, - run_in_debugger=run_in_debugger, - short_description=short_description, - **kwargs) - self.addTest(tc) - return tc - - -class CustomTestCase(unittest.TestCase): - - compare = difflib.Differ().compare - """Comparison method shared by all subclasses.""" - - def __init__(self, method_name, input, expected, id, - run_in_debugger=0, short_description=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. - short_description -- override to default test description. - """ - self.id = id - self.input = input - self.expected = expected - self.run_in_debugger = run_in_debugger - # 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 compare_output(self, input, output, expected): - """`input`, `output`, and `expected` should all be strings.""" - if type(input) == UnicodeType: - input = input.encode('raw_unicode_escape') - if type(output) == UnicodeType: - output = output.encode('raw_unicode_escape') - if type(expected) == UnicodeType: - expected = expected.encode('raw_unicode_escape') - try: - self.assertEquals('\n' + output, '\n' + expected) - except AssertionError: - print >>sys.stderr, '\n%s\ninput:' % (self,) - print >>sys.stderr, input - print >>sys.stderr, '-: expected\n+: output' - print >>sys.stderr, ''.join(self.compare(expected.splitlines(1), - output.splitlines(1))) - raise - - def skip_test(self): - print >>sys.stderr, '%s: Test skipped' % self - - -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): - self.parser = parser - """Parser shared by all test cases.""" - - CustomTestSuite.__init__(self) - - 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 list of transform - classes and 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: - 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 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() - - 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() - document = utils.new_document('test data', self.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 - document = utils.new_document('test data', self.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 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=(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() - document = utils.new_document('test data', self.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=pep.Inliner()) - """Parser shared by all PEPParserTestCases.""" - - option_parser = frontend.OptionParser(components=(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(string2lines(self.input)) - 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(string2lines(self.input)) - 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') - 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. - """ - - if moduleparser is None: - PythonModuleParserTestCase.test_parser = CustomTestCase.skip_test - PythonModuleParserTestCase.test_token_parser_rhs = \ - CustomTestCase.skip_test - - 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) - - -# @@@ These should be generalized to WriterPublishTestCase/Suite or -# just PublishTestCase/Suite, as per TransformTestCase/Suite. -class LatexPublishTestCase(CustomTestCase, docutils.SettingsSpec): - - """ - Test case for publish. - """ - - settings_default_overrides = {'_disable_config': 1} - - 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='latex', - settings_spec=self) - self.compare_output(self.input, output, self.expected) - - -class LatexPublishTestSuite(CustomTestSuite): - - def __init__(self): - CustomTestSuite.__init__(self) - - 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( - LatexPublishTestCase, 'test_publish', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -def exception_args(code): - try: - exec(code) - except Exception, detail: - return detail.args diff --git a/docutils/test/alltests.py b/docutils/test/alltests.py deleted file mode 100755 index 8cacec5f2..000000000 --- a/docutils/test/alltests.py +++ /dev/null @@ -1,70 +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. - -""" -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 - - -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) - - -# must redirect stderr *before* first import of unittest -sys.stdout = sys.stderr = Tee('alltests.out') - -import package_unittest - -path, script = os.path.split(sys.argv[0]) -suite = package_unittest.loadTestModules(path, 'test_', packages=1) -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/difflib.py b/docutils/test/difflib.py deleted file mode 100644 index a41d4d5ba..000000000 --- a/docutils/test/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/package_unittest.py b/docutils/test/package_unittest.py deleted file mode 100644 index 019d6fb38..000000000 --- a/docutils/test/package_unittest.py +++ /dev/null @@ -1,156 +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: - self.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 - module = import_module(mod) - # 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_language.py b/docutils/test/test_language.py deleted file mode 100644 index cf9d75804..000000000 --- a/docutils/test/test_language.py +++ /dev/null @@ -1,210 +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 docutils.languages -import docutils.parsers.rst.languages -from docutils.parsers.rst import states, directives -from DocutilsTestSupport import CustomTestSuite, CustomTestCase - -reference_language = 'en' - - -class LanguageTestSuite(CustomTestSuite): - - language_module_pattern = re.compile('^([a-z]{2,3}(_[a-z]{2,8})*)\.py$') - - def __init__(self, languages=None): - 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(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 - 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 = states.Inliner._interpreted_roles[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 = states.Inliner._interpreted_roles.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 4258d7817..000000000 --- a/docutils/test/test_nodes.py +++ /dev/null @@ -1,153 +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 -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"> - text - more -""") - - -class MiscTests(unittest.TestCase): - - def test_node_class_names(self): - node_class_names = [] - for x in dir(nodes): - c = getattr(nodes, x) - if type(c) is 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) - - -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)) - children1 = one.get_children() - children2 = two.get_children() - self.assertEquals(len(children1), len(children2)) - for i in range(len(children1)): - self.compare_trees(children1[i], children2[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) - - -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 2fe79c55c..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.curdir)) -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 2fe79c55c..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.curdir)) -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 100644 index 3bb669db1..000000000 --- a/docutils/test/test_parsers/test_rst/test_SimpleTableParser.py +++ /dev/null @@ -1,101 +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.'], -] - - -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 08b13fc8c..000000000 --- a/docutils/test/test_parsers/test_rst/test_TableParser.py +++ /dev/null @@ -1,198 +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.'], -] - - -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 276e0132c..000000000 --- a/docutils/test/test_parsers/test_rst/test_block_quotes.py +++ /dev/null @@ -1,252 +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 -"""], -["""\ -Paragraph. - - Block quote. - - -- Attribution line one - and line two - -Paragraph. - - Block quote. - - -- Attribution line one - and line two -""", -"""\ -<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. - - -- Not an attribution - -Paragraph. - - Block quote. - - \-- 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. - <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 a92e151a4..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 id="citation" name="citation"> - <label> - citation - <paragraph> - This is a citation. -"""], -["""\ -.. [citation1234] This is a citation with year. -""", -"""\ -<document source="test data"> - <citation id="citation1234" name="citation1234"> - <label> - citation1234 - <paragraph> - This is a citation with year. -"""], -["""\ -.. [citation] This is a citation - on multiple lines. -""", -"""\ -<document source="test data"> - <citation id="citation" name="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 id="citation1" name="citation1"> - <label> - citation1 - <paragraph> - This is a citation - on multiple lines with more space. - <citation id="citation2" name="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 id="citation" name="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 id="citation" name="citation"> - <label> - citation - <paragraph> - That was an empty citation. -"""], -["""\ -.. [citation] -No blank line. -""", -"""\ -<document source="test data"> - <citation id="citation" name="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 2cb0a6082..000000000 --- a/docutils/test/test_parsers/test_rst/test_definition_lists.py +++ /dev/null @@ -1,377 +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? 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 id="id2" refid="id1"> - ` - with \n\ - <problematic id="id4" refid="id3"> - * - inline \n\ - <problematic id="id6" refid="id5"> - `` - text \n\ - <problematic id="id8" refid="id7"> - ** - errors - <classifier> - classifier \n\ - <problematic id="id10" refid="id9"> - ` - with \n\ - <problematic id="id12" refid="id11"> - * - errors \n\ - <problematic id="id14" refid="id13"> - `` - too - <definition> - <system_message backrefs="id2" id="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" id="id3" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message backrefs="id6" id="id5" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. - <system_message backrefs="id8" id="id7" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. - <system_message backrefs="id10" id="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" id="id11" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message backrefs="id14" id="id13" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. - <paragraph> - Definition \n\ - <problematic id="id16" refid="id15"> - ` - with \n\ - <problematic id="id18" refid="id17"> - * - inline \n\ - <problematic id="id20" refid="id19"> - `` - text \n\ - <problematic id="id22" refid="id21"> - ** - markup errors. - <system_message backrefs="id16" id="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" id="id17" level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message backrefs="id20" id="id19" level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Inline literal start-string without end-string. - <system_message backrefs="id22" id="id21" level="2" line="2" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. -"""], -] - -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 2fe79c55c..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.curdir)) -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/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/include2.txt b/docutils/test/test_parsers/test_rst/test_directives/include2.txt deleted file mode 100644 index 5b76a7052..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/include9.txt b/docutils/test/test_parsers/test_rst/test_directives/include9.txt deleted file mode 100644 index 8eb5b1720..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/include9.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. |bad| unicode:: 0xFFFFFFFFF - -hi ------ - -hi ------ 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 af24935c1..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 class="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 class="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 class="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_contents.py b/docutils/test/test_parsers/test_rst/test_directives/test_contents.py deleted file mode 100755 index de5913708..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_contents.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 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"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - title: None -"""], -["""\ -.. contents:: Table of Contents -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - title: - <title> - Table of Contents -"""], -["""\ -.. contents:: - Table of Contents -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - title: - <title> - Table of Contents -"""], -["""\ -.. contents:: Table - of - Contents -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - title: - <title> - Table - of - Contents -"""], -["""\ -.. contents:: *Table* of ``Contents`` -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - title: - <title> - <emphasis> - Table - of \n\ - <literal> - Contents -"""], -["""\ -.. contents:: - :depth: 2 - :local: -""", -"""\ -<document source="test data"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - depth: 2 - local: None - title: 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"> - <pending> - .. internal attributes: - .transform: docutils.transforms.parts.Contents - .details: - backlinks: None - depth: 2 - local: None - title: - <title> - Table of Contents -"""], -["""\ -.. 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: -"""], -] - - -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 888744bad..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_figures.py +++ /dev/null @@ -1,287 +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:: not an image URI -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Image URI contains whitespace. - <literal_block xml:space="preserve"> - .. figure:: not an image URI -"""], -["""\ -.. 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:: not an image URI - - And a caption. -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Image URI contains whitespace. - <literal_block xml:space="preserve"> - .. figure:: not an image URI - \n\ - And a 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 - - A picture with image options on individual lines, and this caption. -""", -"""\ -<document source="test data"> - <figure 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. -"""], -["""\ -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 cde08dfe6..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_images.py +++ /dev/null @@ -1,249 +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 -""", -"""\ -<document source="test data"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Image URI contains whitespace. - <literal_block xml:space="preserve"> - .. image:: one two three -"""], -["""\ -.. 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 - :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_args('int(None)')[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"> - <system_message level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Image URI contains whitespace. - <literal_block xml:space="preserve"> - .. image:: picture.png - scale: 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 -"""], -] - - -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 892ec9816..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_include.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 misc.py "include" directive. -""" - -import os.path -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -mydir = os.path.dirname(suite.func_code.co_filename) -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') -include9 = os.path.join(mydir, 'include9.txt') -include9rel = DocutilsTestSupport.utils.relative_path(None, include9) - - -totest = {} - -totest['include'] = [ -["""\ -Include Test -============ - -.. include:: %s - -A paragraph. -""" % include1, -"""\ -<document source="test data"> - <section id="include-test" name="include test"> - <title> - Include Test - <section id="inclusion-1" name="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 id="include-test" name="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 \n\ - <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 id="include-test" name="include test"> - <title> - Include Test - <system_message level="4" line="4" source="test data" type="SEVERE"> - <paragraph> - Problems with "include" directive path: - [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 id="include-test" name="include test"> - <title> - Include Test - <section dupname="inclusion 1" id="inclusion-1"> - <title> - Inclusion 1 - <paragraph> - This file is used by - <literal> - test_include.py - . - <section dupname="inclusion 1" id="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 id="include-test" name="include test"> - <title> - Include Test - <section dupname="inclusion 1" id="inclusion-1"> - <title> - Inclusion 1 - <paragraph> - This file is used by - <literal> - test_include.py - . - <transition> - <system_message level="3" line="12" source="test data" type="ERROR"> - <paragraph> - Section may not end with a transition. - <section dupname="inclusion 1" id="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], -["""\ -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 id="section" name="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 - . -"""], -# @@@ BUG with errors reported with incorrect "source" & "line": -# ["""\ -# Testing bad charent includes: -# -# .. include:: %s -# """ % include9, -# """\ -# <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 -# """ % (include9rel, include9rel)], -] - - -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 ecfedd721..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.py 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 cbce2f50d..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_raw.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 misc.py "raw" directive. -""" - -import os.path -from __init__ import DocutilsTestSupport - - -def suite(): - s = DocutilsTestSupport.ParserTestSuite() - s.generateTests(totest) - return s - -mydir = os.path.dirname(suite.func_code.co_filename) -raw1 = os.path.join(mydir, 'raw1.txt') - -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> -"""], -] - - -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 6de59d3a4..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 name="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 name="Python"> - Python, - <emphasis> - the - best language around - <target id="python" name="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 id="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline emphasis start-string without end-string. - <system_message id="id3" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline strong start-string without end-string. - <system_message id="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_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_test_directives.py b/docutils/test/test_parsers/test_rst/test_directives/test_test_directives.py deleted file mode 100755 index 09313e32b..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_test_directives.py +++ /dev/null @@ -1,195 +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. -"""], -] - - -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 100644 index fa3d91100..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_topics.py +++ /dev/null @@ -1,242 +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, sidebars, 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, sidebars, 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, sidebars, 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 - <system_message level="3" line="4" source="test data" type="ERROR"> - <paragraph> - The "topic" directive may not be used within topics, sidebars, or body elements. - <literal_block xml:space="preserve"> - .. topic:: Nested - \n\ - 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 704c13fa5..000000000 --- a/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py +++ /dev/null @@ -1,131 +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 name="mdash"> - \u2014 - <substitution_definition name="copy"> - \u00A9 - <substitution_definition name="nbsp"> - \u00A0 - <substitution_definition name="bne"> - = - \u20e5 - <substitution_definition name="Omega"> - \u03a9 -"""], -[""" -Bad input: - -.. |empty| unicode:: -.. |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:: - <substitution_definition name="not hex"> - 0xHEX - <substitution_definition name="not all hex"> - UABCX - <system_message level="3" line="7" 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 name="copy"> - \u00A9 - <substitution_definition name="BogusMegaCorp (TM)"> - BogusMegaCorp - \u2122 -"""], -] - - -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_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_enumerated_lists.py b/docutils/test/test_parsers/test_rst/test_enumerated_lists.py deleted file mode 100755 index b89691516..000000000 --- a/docutils/test/test_parsers/test_rst/test_enumerated_lists.py +++ /dev/null @@ -1,727 +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: - <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="3" suffix="."> - <list_item> - <paragraph> - Item three. - <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="" start="2" suffix="."> - <list_item> - <paragraph> - Item two. - <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: - <system_message level="1" line="3" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "0" (ordinal 0) - <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. - <paragraph> - And again: - <system_message level="1" line="10" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "2" (ordinal 2) - <enumerated_list enumtype="arabic" prefix="" start="2" suffix="."> - <list_item> - <paragraph> - Item two. - <list_item> - <paragraph> - Item three. -"""], -["""\ -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. -"""], -["""\ -A. Einstein was a great influence on -B. Physicist, who was a colleague of -C. Chemist. They all worked in -Princeton, NJ. -""", -# @@@ I think this is the correct result, but I'm not certain: -"""\ -<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. -"""], -["""\ -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. - <system_message level="1" line="5" source="test data" type="INFO"> - <paragraph> - Enumerated list start value not ordinal-1: "3" (ordinal 3) - <enumerated_list enumtype="arabic" prefix="" start="3" suffix="."> - <list_item> - <paragraph> - Item three: paragraph 1, line 1, - <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. -"""], -] - - -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 4bdf07527..000000000 --- a/docutils/test/test_parsers/test_rst/test_field_lists.py +++ /dev/null @@ -1,469 +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 -"""], -["""\ -Some edge cases: - -:Empty: -:Author: Me -No blank line before this paragraph. - -:*Field* `with` **inline** ``markup``: inline markup shouldn't be recognized. - -: 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. -""", -"""\ -<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. - <field_list> - <field> - <field_name> - *Field* `with` **inline** ``markup`` - <field_body> - <paragraph> - inline markup shouldn't be recognized. - <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. -"""], -] - -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 00e5c1f5d..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 id="id1" name="1"> - <label> - 1 - <paragraph> - This is a footnote. -"""], -["""\ -.. [1] This is a footnote - on multiple lines. -""", -"""\ -<document source="test data"> - <footnote id="id1" name="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 id="id1" name="1"> - <label> - 1 - <paragraph> - This is a footnote - on multiple lines with more space. - <footnote id="id2" name="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 id="id1" name="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 id="id1" name="1"> - <label> - 1 - <paragraph> - That was an empty footnote. -"""], -["""\ -.. [1] -No blank line. -""", -"""\ -<document source="test data"> - <footnote id="id1" name="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" id="id1"> - is the first auto-numbered footnote reference. - <footnote_reference auto="1" id="id2"> - is the second auto-numbered footnote reference. - <footnote auto="1" id="id3"> - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" id="id4"> - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" id="id5"> - <paragraph> - Auto-numbered footnote 3. - <paragraph> - <footnote_reference auto="1" id="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" id="id1" refname="third"> - is a reference to the third auto-numbered footnote. - <footnote auto="1" id="first" name="first"> - <paragraph> - First auto-numbered footnote. - <footnote auto="1" id="second" name="second"> - <paragraph> - Second auto-numbered footnote. - <footnote auto="1" id="third" name="third"> - <paragraph> - Third auto-numbered footnote. - <paragraph> - <footnote_reference auto="1" id="id2" refname="second"> - is a reference to the second auto-numbered footnote. - <footnote_reference auto="1" id="id3" refname="first"> - is a reference to the first auto-numbered footnote. - <footnote_reference auto="1" id="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 refname="first"> - first - , \n\ - <reference refname="second"> - second - , \n\ - <reference 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" id="id1" refname="four"> - should be 4, \n\ - <footnote_reference auto="1" id="id2"> - should be 1, - <footnote_reference auto="1" id="id3"> - should be 3, \n\ - <footnote_reference auto="1" id="id4"> - is one too many, - <footnote_reference auto="1" id="id5" refname="two"> - should be 2, and \n\ - <footnote_reference auto="1" id="id6" refname="six"> - doesn't exist. - <footnote auto="1" id="id7"> - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" id="two" name="two"> - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" id="id8"> - <paragraph> - Auto-numbered footnote 3. - <footnote auto="1" id="four" name="four"> - <paragraph> - Auto-numbered footnote 4. - <footnote auto="1" dupname="five" id="five"> - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" dupname="five" id="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" id="id1" refname="four"> - should be 4, \n\ - <footnote_reference auto="1" id="id2"> - should be 2, - <footnote_reference id="id3" refname="1"> - 1 - is 1, \n\ - <footnote_reference id="id4" refname="3"> - 3 - is 3, - <footnote_reference auto="1" id="id5"> - should be 6, \n\ - <footnote_reference auto="1" id="id6"> - is one too many, - <footnote_reference auto="1" id="id7" refname="five"> - should be 5, and \n\ - <footnote_reference auto="1" id="id8" refname="six"> - doesn't exist. - <footnote id="id9" name="1"> - <label> - 1 - <paragraph> - Manually-numbered footnote 1. - <footnote auto="1" id="id10"> - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" id="four" name="four"> - <paragraph> - Auto-numbered footnote 4. - <footnote id="id11" name="3"> - <label> - 3 - <paragraph> - Manually-numbered footnote 3 - <footnote auto="1" dupname="five" id="five"> - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" dupname="five" id="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" id="id13"> - <paragraph> - Auto-numbered footnote 6. -"""], -] - -totest['auto_symbol_footnotes'] = [ -["""\ -.. [*] This is an auto-symbol footnote. -""", -"""\ -<document source="test data"> - <footnote auto="*" id="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 2cafdb09a..000000000 --- a/docutils/test/test_parsers/test_rst/test_inline_markup.py +++ /dev/null @@ -1,851 +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 id="id2" refid="id1"> - * - emphasis without closing asterisk - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - * - args' will trigger a warning and may be problematic) - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - ** - kwargs' will trigger a warning and may be problematic) - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - ** - strong without closing asterisks - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - `` - standalone TeX quotes'' will trigger a warning - and may be problematic) - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - `` - literal without closing backquotes - <system_message backrefs="id2" id="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 refname="ref"> - ref -"""], -["""\ -ref__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1"> - ref -"""], -["""\ -ref_, r_, r_e-f_, -ref_, and anonymousref__, -but not _ref_ or __attr__ or object.__attr__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference refname="ref"> - ref - , \n\ - <reference refname="r"> - r - , \n\ - <reference refname="r_e-f"> - r_e-f - , - - <reference refname="ref"> - ref - , and \n\ - <reference anonymous="1"> - anonymousref - , - but not _ref_ or __attr__ or object.__attr__ -"""], -] - -totest['phrase_references'] = [ -["""\ -`phrase reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference refname="phrase reference"> - phrase reference -"""], -["""\ -`anonymous reference`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1"> - anonymous reference -"""], -["""\ -`phrase reference -across lines`_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference refname="phrase reference across lines"> - phrase reference - across lines -"""], -["""\ -`phrase\`_ reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - <reference refname="phrase`_ reference"> - phrase`_ reference -"""], -["""\ -Invalid phrase reference: - -:role:`phrase reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - Invalid phrase reference: - <paragraph> - <problematic id="id2" refid="id1"> - :role:`phrase reference`_ - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - `phrase reference`:role:_ - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - ` - phrase \n\ - <reference refname="reference"> - reference - without closing backquote - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - ` - anonymous phrase \n\ - <reference anonymous="1"> - reference - without closing backquote - <system_message backrefs="id2" id="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 refuri="http://example.com"> - phrase reference - <target id="phrase-reference" name="phrase reference" refuri="http://example.com"> -"""], -["""\ -`anonymous reference <http://example.com>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference refuri="http://example.com"> - anonymous reference -"""], -["""\ -`embedded URI on next line -<http://example.com>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference refuri="http://example.com"> - embedded URI on next line -"""], -["""\ -`embedded URI across lines <http://example.com/ -long/path>`__ -""", -"""\ -<document source="test data"> - <paragraph> - <reference 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 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 refuri="mailto:jdoe@example.com"> - embedded email address - <paragraph> - <reference 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"> - embedded URI with too much whitespace < http://example.com/ - long/path /and /whitespace > - <paragraph> - <reference anonymous="1"> - embedded URI with too much whitespace at end <http://example.com/ - long/path /and /whitespace > - <paragraph> - <reference anonymous="1"> - embedded URI with no preceding whitespace<http://example.com> - <paragraph> - <reference anonymous="1"> - escaped URI <http://example.com> - <paragraph> - See \n\ - <reference refname="html anchors: <a>"> - HTML Anchors: <a> - . -"""], -] - -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 id="target" name="target"> - target - <paragraph> - Here is \n\ - <target id="another-target" name="another target"> - another target - in some text. And \n\ - <target id="yet-another-target" name="yet another target"> - yet - another target - , spanning lines. - <paragraph> - <target id="here-is-a-target" name="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 id="id2" refid="id1"> - _` - this`_ is just plain confusing. - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - _` - inline target without closing backquote - <system_message backrefs="id2" id="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 id="id1" refname="1"> - 1 -"""], -["""\ -[#]_ -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" id="id1"> -"""], -["""\ -[#label]_ -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="1" id="id1" refname="label"> -"""], -["""\ -[*]_ -""", -"""\ -<document source="test data"> - <paragraph> - <footnote_reference auto="*" id="id1"> -"""], -] - -totest['citation_reference'] = [ -["""\ -[citation]_ -""", -"""\ -<document source="test data"> - <paragraph> - <citation_reference id="id1" refname="citation"> - citation -"""], -["""\ -[citation]_ and [cit-ation]_ and [cit.ation]_ and [CIT1]_ but not [CIT 1]_ -""", -"""\ -<document source="test data"> - <paragraph> - <citation_reference id="id1" refname="citation"> - citation - and \n\ - <citation_reference id="id2" refname="cit-ation"> - cit-ation - and \n\ - <citation_reference id="id3" refname="cit.ation"> - cit.ation - and \n\ - <citation_reference id="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 id="id2" refid="id1"> - | - substitution reference without closing verbar - <system_message backrefs="id2" id="id1" level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Inline substitution_reference start-string without end-string. -"""], -["""\ -| and || and ||| -""", -"""\ -<document source="test data"> - <paragraph> - | and || and ||| -"""], -] - -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 - ?) -"""], -["""\ -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. -"""], -] - -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 100644 index 6c0d30ac0..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 id="id2" refid="id1"> - ` - interpreted without closing backquote - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - -1 - <system_message backrefs="id2" id="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 id="id2" refid="id1"> - 0 - <system_message backrefs="id2" id="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 id="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" id="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown interpreted text role "role". -"""], -["""\ -`interpreted`:role: -""", -"""\ -<document source="test data"> - <paragraph> - <problematic id="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" id="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 id="id2" refid="id1"> - :role:`interpreted`:role: - <system_message backrefs="id2" id="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 id="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" id="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 id="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" id="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_literal_blocks.py b/docutils/test/test_parsers/test_rst/test_literal_blocks.py deleted file mode 100755 index 2fe1c9b88..000000000 --- a/docutils/test/test_parsers/test_rst/test_literal_blocks.py +++ /dev/null @@ -1,234 +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['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 -"""], -["""\ -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="2" 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. -"""], -] - - -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 e7f17f615..000000000 --- a/docutils/test/test_parsers/test_rst/test_option_lists.py +++ /dev/null @@ -1,684 +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. -"""], -] - -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 98fdfcb8f..000000000 --- a/docutils/test/test_parsers/test_rst/test_section_headers.py +++ /dev/null @@ -1,912 +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 id="title" name="title"> - <title> - Title - <paragraph> - Paragraph. -"""], -["""\ -Title -===== -Paragraph (no blank line). -""", -"""\ -<document source="test data"> - <section id="title" name="title"> - <title> - Title - <paragraph> - Paragraph (no blank line). -"""], -["""\ -Paragraph. - -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <section id="title" name="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 id="title" name="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 id="title" name="title"> - <title> - Title - <paragraph> - Test overline title. -"""], -["""\ -======= - Title -======= - -Test overline title with inset. -""", -"""\ -<document source="test data"> - <section id="title" name="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 id="long-title" name="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"> - <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 not allowed. - <transition> - <paragraph> - Test missing titles; blank line in-between. - <transition> - <transition> - <system_message level="3" line="9" source="test data" type="ERROR"> - <paragraph> - Document or section may not end with a 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 id="title-1" name="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="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 id="title-1" name="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="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 id="title-1" name="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="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 id="title-1" name="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="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 id="title-1" name="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="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 id="title-containing-inline-markup" name="title containing inline markup"> - <title> - Title containing \n\ - <emphasis> - inline - \n\ - <literal> - markup - <paragraph> - Paragraph. -"""], -["""\ -1. Numbered Title -================= - -Paragraph. -""", -"""\ -<document source="test data"> - <section id="numbered-title" name="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 id="numbered-title" name="3. numbered title"> - <title> - 3. Numbered Title - <paragraph> - Paragraph. -"""], -["""\ -ABC -=== - -Short title. -""", -"""\ -<document source="test data"> - <section id="abc" name="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 dupname="..." id="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 dupname="..." id="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 dupname="..." id="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 id="hi" name="hi"> - <title> - Hi - <section id="yo" name="yo"> - <title> - Yo - <paragraph> - Ho -"""], -["""\ -Empty Section -============= -""", -"""\ -<document source="test data"> - <section id="empty-section" name="empty section"> - <title> - Empty Section - <system_message level="3" line="2" source="test data" type="ERROR"> - <paragraph> - Section empty; must have contents. -"""], -["""\ -=== -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 id="one" name="one"> - <title> - One - <paragraph> - The bubble-up parser strategy conflicts with short titles - (<= 3 char-long over- & underlines). - <section id="two" name="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"> - <system_message level="3" line="0" source="test data" type="ERROR"> - <paragraph> - Document empty; must have contents. -"""], -] - - -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 ecbe5eab1..000000000 --- a/docutils/test/test_parsers/test_rst/test_substitutions.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 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 name="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 name="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 name="symbol 1"> - <image alt="symbol 1" uri="symbol1.png"> - <substitution_definition name="SYMBOL 2"> - <image alt="SYMBOL 2" height="50" uri="symbol2.png" width="100"> - <substitution_definition name="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 name="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 name="symbol 1"> - <image alt="symbol 1" uri="symbol.png"> - <paragraph> - Followed by a paragraph. - <substitution_definition name="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 name="eacute"> - \u00E9 - <substitution_definition name="Eacute"> - \u00C9 -"""], -["""\ -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 dupname="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 name="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 name="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 -"""], -] - - -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 d0d1d1317..000000000 --- a/docutils/test/test_parsers/test_rst/test_tables.py +++ /dev/null @@ -1,1151 +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['full_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> -"""], -] - -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 2. - <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> -"""], -] - - -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 f246ccf6e..000000000 --- a/docutils/test/test_parsers/test_rst/test_targets.py +++ /dev/null @@ -1,448 +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 id="target" name="target"> - <paragraph> - (Internal hyperlink target.) -"""], -["""\ -.. _optional space before colon : -""", -"""\ -<document source="test data"> - <target id="optional-space-before-colon" name="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 id="one-liner" name="one-liner" refuri="http://structuredtext.sourceforge.net"> - <target id="starts-on-this-line" name="starts-on-this-line" refuri="http://structuredtext.sourceforge.net"> - <target id="entirely-below" name="entirely-below" refuri="http://structuredtext.sourceforge.net"> - <target id="not-indirect" name="not-indirect" refuri="uri_"> -"""], -["""\ -Indirect hyperlink targets: - -.. _target1: reference_ - -.. _target2: `phrase-link reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - Indirect hyperlink targets: - <target id="target1" name="target1" refname="reference"> - <target id="target2" name="target2" refname="phrase-link reference"> -"""], -["""\ -.. _target1: Not a proper hyperlink target - -.. _target2: Although it ends with an underscore, this is not a phrase-link_ - -.. _target3: A multi-line verson of something - ending with an underscore, but not a phrase-link_ -""", -"""\ -<document source="test data"> - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Hyperlink target contains whitespace. Perhaps a footnote was intended? - <literal_block xml:space="preserve"> - .. _target1: Not a proper hyperlink target - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Hyperlink target contains whitespace. Perhaps a footnote was intended? - <literal_block xml:space="preserve"> - .. _target2: Although it ends with an underscore, this is not a phrase-link_ - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Hyperlink target contains whitespace. Perhaps a footnote was intended? - <literal_block xml:space="preserve"> - .. _target3: A multi-line verson of something - ending with an underscore, but not a phrase-link_ -"""], -["""\ -.. __: Not a proper hyperlink target - -__ Although it ends with an underscore, this is not a phrase-link_ - -__ A multi-line verson of something - ending with an underscore, but not a phrase-link_ -""", -"""\ -<document source="test data"> - <system_message level="2" line="1" source="test data" type="WARNING"> - <paragraph> - Hyperlink target contains whitespace. Perhaps a footnote was intended? - <literal_block xml:space="preserve"> - .. __: Not a proper hyperlink target - <system_message level="2" line="3" source="test data" type="WARNING"> - <paragraph> - Anonymous hyperlink target contains whitespace. Perhaps a footnote was intended? - <literal_block xml:space="preserve"> - __ Although it ends with an underscore, this is not a phrase-link_ - <system_message level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Anonymous hyperlink target contains whitespace. Perhaps a footnote was intended? - <literal_block xml:space="preserve"> - __ A multi-line verson of something - ending with an underscore, but not a phrase-link_ -"""], -["""\ -.. _a long target name: - -.. _`a target name: including a colon (quoted)`: - -.. _a target name\: including a colon (escaped): -""", -"""\ -<document source="test data"> - <target id="a-long-target-name" name="a long target name"> - <target id="a-target-name-including-a-colon-quoted" name="a target name: including a colon (quoted)"> - <target id="a-target-name-including-a-colon-escaped" name="a target name: including a colon (escaped)"> -"""], -["""\ -.. _a very long target name, - split across lines: -.. _`and another, - with backquotes`: -""", -"""\ -<document source="test data"> - <target id="a-very-long-target-name-split-across-lines" name="a very long target name, split across lines"> - <target id="and-another-with-backquotes" name="and another, with backquotes"> -"""], -["""\ -External hyperlink: - -.. _target: http://www.python.org/ -""", -"""\ -<document source="test data"> - <paragraph> - External hyperlink: - <target id="target" name="target" refuri="http://www.python.org/"> -"""], -["""\ -.. _email: jdoe@example.com - -.. _multi-line email: jdoe - @example.com -""", -"""\ -<document source="test data"> - <target id="email" name="email" refuri="mailto:jdoe@example.com"> - <target id="multi-line-email" name="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 dupname="target" id="target" refuri="first"> - <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <target dupname="target" id="id1" refuri="second"> -"""], -["""\ -Duplicate external targets (same URIs): - -.. _target: first - -.. _target: first -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate external targets (same URIs): - <target id="target" name="target" refuri="first"> - <system_message backrefs="id1" level="1" line="5" source="test data" type="INFO"> - <paragraph> - Duplicate explicit target name: "target". - <target dupname="target" id="id1" refuri="first"> -"""], -["""\ -Duplicate implicit targets. - -Title -===== - -Paragraph. - -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate implicit targets. - <section dupname="title" id="title"> - <title> - Title - <paragraph> - Paragraph. - <section dupname="title" id="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 dupname="title" id="title"> - <title> - Title - <system_message backrefs="id1" level="1" line="6" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "title". - <target id="id1" name="title"> - <paragraph> - Paragraph. -"""], -["""\ -Duplicate explicit targets. - -.. _title: - -First. - -.. _title: - -Second. - -.. _title: - -Third. -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate explicit targets. - <target dupname="title" id="title"> - <paragraph> - First. - <system_message backrefs="id1" level="2" line="7" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "title". - <target dupname="title" id="id1"> - <paragraph> - Second. - <system_message backrefs="id2" level="2" line="11" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "title". - <target dupname="title" id="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 dupname="target" id="target"> - <title> - Target - <paragraph> - Implicit section header target. - <citation dupname="target" id="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" dupname="target" id="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 dupname="target" id="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 dupname="target" id="id4" refuri="Explicit_external_target"> -"""], -] - -totest['anonymous_targets'] = [ -["""\ -Anonymous external hyperlink target: - -.. __: http://w3c.org/ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous external hyperlink target: - <target anonymous="1" id="id1" refuri="http://w3c.org/"> -"""], -["""\ -Anonymous external hyperlink target: - -__ http://w3c.org/ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous external hyperlink target: - <target anonymous="1" id="id1" refuri="http://w3c.org/"> -"""], -["""\ -Anonymous indirect hyperlink target: - -.. __: reference_ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous indirect hyperlink target: - <target anonymous="1" id="id1" refname="reference"> -"""], -["""\ -Anonymous indirect hyperlink targets: - -__ reference_ -__ `a very long - reference`_ -""", -"""\ -<document source="test data"> - <paragraph> - Anonymous indirect hyperlink targets: - <target anonymous="1" id="id1" refname="reference"> - <target anonymous="1" id="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" id="id1" refname="reference"> - <target anonymous="1" id="id2" refname="reference"> - <target anonymous="1" id="id3" refname="reference"> - <target id="target1" name="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 id="target2" name="target2" refname="reference"> - <target anonymous="1" id="id4" refname="reference"> - <target anonymous="1" id="id5" refname="reference"> - <target anonymous="1" id="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 -"""], -] - - -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 3e8a63e91..000000000 --- a/docutils/test/test_parsers/test_rst/test_transitions.py +++ /dev/null @@ -1,220 +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 id="section-1" name="section 1"> - <title> - Section 1 - <paragraph> - First text division of section 1. - <transition> - <paragraph> - Second text division of section 1. - <section id="section-2" name="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"> - <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 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 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 or section may not end with a 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 -========= - ----------- - -Illegal transitions. - ----------- - -Section 2 -========= - ----------- -""", -"""\ -<document source="test data"> - <paragraph> - Sections with transitions at beginning and end. - <section id="section-1" name="section 1"> - <title> - Section 1 - <system_message level="3" line="6" source="test data" type="ERROR"> - <paragraph> - Section may not begin with a transition. - <transition> - <paragraph> - Illegal transitions. - <transition> - <system_message level="3" line="10" source="test data" type="ERROR"> - <paragraph> - Section may not end with a transition. - <section id="section-2" name="section 2"> - <title> - Section 2 - <system_message level="3" line="15" source="test data" type="ERROR"> - <paragraph> - Section may not begin with a transition. - <transition> - <system_message level="3" line="15" source="test data" type="ERROR"> - <paragraph> - Document or section 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. -"""], -] - - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') diff --git a/docutils/test/test_readers/__init__.py b/docutils/test/test_readers/__init__.py deleted file mode 100644 index 2fe79c55c..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.curdir)) -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 2fe79c55c..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.curdir)) -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 100644 index 7ae69e8ec..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="pep-0287.html"> - PEP 287 - ( - <reference refuri="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="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="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/spec/rst/reStructuredText.html. -""", -"""\ -<document source="test data"> - <paragraph> - For \n\ - <emphasis> - completeness - , \n\ - <target id="let-s" name="let's"> - let's - \n\ - <literal> - test - \n\ - <strong> - other - \n\ - <reference refname="forms"> - forms - \n\ - <substitution_reference refname="of"> - of - \n\ - <title_reference> - inline markup - \n\ - <footnote_reference auto="*" id="id1"> - . - <footnote auto="*" id="id2"> - <paragraph> - See \n\ - <reference refuri="http://docutils.sf.net/spec/rst/reStructuredText.html"> - http://docutils.sf.net/spec/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 100644 index f13de16d2..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 class="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 class="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 class="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 class="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 class="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 class="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 class="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 class="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 class="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 2fe79c55c..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.curdir)) -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 100644 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 100644 index ce70cc27c..000000000 --- a/docutils/test/test_readers/test_python/test_parser.py +++ /dev/null @@ -1,745 +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 filename="test data"> -'''], -['''\ -"""docstring""" -''', -'''\ -<Module filename="test data"> - <Docstring> - docstring -'''], -['''\ -u"""Unicode docstring""" -''', -'''\ -<Module filename="test data"> - <Docstring> - Unicode docstring -'''], -['''\ -"""docstring""" -"""additional docstring""" -''', -'''\ -<Module filename="test data"> - <Docstring> - docstring - <Docstring lineno="2"> - additional docstring -'''], -['''\ -"""docstring""" -# comment -"""additional docstring""" -''', -'''\ -<Module filename="test data"> - <Docstring> - docstring - <Docstring lineno="3"> - additional docstring -'''], -['''\ -"""docstring""" -1 -"""not an additional docstring""" -''', -'''\ -<Module filename="test data"> - <Docstring> - docstring -'''], -] - -totest['import'] = [ -['''\ -import module -''', -'''\ -<Module filename="test data"> - <Import lineno="1"> - module -'''], -['''\ -import module as local -''', -'''\ -<Module filename="test data"> - <Import lineno="1"> - module as local -'''], -['''\ -import module.name -''', -'''\ -<Module filename="test data"> - <Import lineno="1"> - module.name -'''], -['''\ -import module.name as local -''', -'''\ -<Module filename="test data"> - <Import lineno="1"> - module.name as local -'''], -['''\ -import module -"""not documentable""" -''', -'''\ -<Module filename="test data"> - <Import lineno="1"> - module -'''], -] - -totest['from'] = [ -['''\ -from module import name -''', -'''\ -<Module filename="test data"> - <Import from="module" lineno="1"> - name -'''], -['''\ -from module import name as local -''', -'''\ -<Module filename="test data"> - <Import from="module" lineno="1"> - name as local -'''], -['''\ -from module import name1, name2 as local2 -''', -'''\ -<Module filename="test data"> - <Import from="module" lineno="1"> - name1 - name2 as local2 -'''], -['''\ -from module.sub import name -''', -'''\ -<Module filename="test data"> - <Import from="module.sub" lineno="1"> - name -'''], -['''\ -from module.sub import name as local -''', -'''\ -<Module filename="test data"> - <Import from="module.sub" lineno="1"> - name as local -'''], -['''\ -from module import * -''', -'''\ -<Module filename="test data"> - <Import from="module" lineno="1"> - * -'''], -['''\ -from __future__ import division -''', -'''\ -<Module filename="test data"> - <Import from="__future__" lineno="1"> - division -'''], -] - -totest['assign'] = [ -['''\ -a = 1 -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - 1 -'''], -['''a = 1''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - 1 -'''], -['''\ -a = 1 -"""a's docstring""" -''', #" -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - 1 - <Docstring lineno="2"> - a's docstring -'''], #' -['''\ -a = 1 -"""a's docstring""" -"""additional docstring""" -''', #" -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - 1 - <Docstring lineno="2"> - a's docstring - <Docstring lineno="3"> - additional docstring -'''], #' -['''\ -a = 1 + 2 * 3 / 4 ** 5 -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - 1 + 2 * 3 / 4 ** 5 -'''], -['''\ -a = 1 \\ - + 2 -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - 1 + 2 -'''], -['''\ -a = not 1 and 2 or 3 -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - not 1 and 2 or 3 -'''], -['''\ -a = ~ 1 & 2 | 3 ^ 4 -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - ~ 1 & 2 | 3 ^ 4 -'''], -['''\ -a = `1 & 2` -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - `1 & 2` -'''], -['''\ -very_long_name = \\ - x -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="very_long_name"> - <Expression lineno="1"> - x -'''], -['''\ -very_long_name \\ - = x -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="very_long_name"> - <Expression lineno="2"> - x -'''], -['''\ -very_long_name = \\ - another_long_name = \\ - x -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="very_long_name"> - <Expression lineno="1"> - x - <Attribute lineno="2" name="another_long_name"> - <Expression lineno="1"> - x -'''], -['''\ -a = (1 - + 2) -b = a.b[1 + - fn(x, y, - z, {'key': (1 + 2 - + 3)})][4] -c = """first line -second line - third""" -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - (1 + 2) - <Attribute lineno="3" name="b"> - <Expression lineno="3"> - a.b[1 + fn(x, y, z, {'key': (1 + 2 + 3)})][4] - <Attribute lineno="7" name="c"> - <Expression lineno="7"> - """first line\\nsecond line\\n 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 filename="test data"> - <AttributeTuple lineno="1" names="a b c"> - <Expression lineno="1"> - range(3) - <AttributeTuple lineno="2" names="d e f"> - <Expression lineno="3"> - a, b, c - <AttributeTuple lineno="4" names="g h i"> - <Expression lineno="4"> - a, b, c - <Attribute lineno="4" name="j"> - <Expression lineno="4"> - a, b, c - <AttributeTuple lineno="5" names="k.a k.b.c k.d.e.f"> - <Expression lineno="5"> - a, b, c -'''], -['''\ -a = 1 ; b = 2 -print ; c = 3 -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - 1 - <Attribute lineno="1" name="b"> - <Expression lineno="1"> - 2 - <Attribute lineno="2" name="c"> - <Expression lineno="2"> - 3 -'''], -['''\ -a.b = 1 -"""This assignment is noted but ignored unless ``a`` is a function.""" -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a.b"> - <Expression lineno="1"> - 1 - <Docstring lineno="2"> - This assignment is noted but ignored unless ``a`` is a function. -'''], -['''\ -a[b] = 1 -"""Subscript assignments are ignored.""" -''', -'''\ -<Module filename="test data"> -'''], -['''\ -a = foo(b=1) -''', -'''\ -<Module filename="test data"> - <Attribute lineno="1" name="a"> - <Expression lineno="1"> - foo(b=1) -'''], -# ['''\ -# a = 1 -# -# """Because of the blank above, this is a module docstring.""" -# ''', -# '''\ -# <Module filename="test data"> -# <Attribute lineno="1" name="a"> -# <Expression lineno="1"> -# 1 -# <Docstring lineno="3"> -# Because of the blank above, this is a module docstring. -# '''], -] - -totest['def'] = [ -['''\ -def f(): - """Function f's docstring""" - """Additional docstring""" - local = 1 - """Not a docstring, since ``local`` is local.""" -''', # " -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <Docstring lineno="1"> - Function f's docstring - <Docstring lineno="3"> - Additional docstring -'''], # ' -['''\ -def f(a, b): - local = 1 -''', -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <ParameterList lineno="1"> - <Parameter lineno="1" name="a"> - <Parameter lineno="1" name="b"> -'''], -['''\ -def f(a=None, b=1): - local = 1 -''', -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <ParameterList lineno="1"> - <Parameter lineno="1" name="a"> - <Default lineno="1"> - None - <Parameter lineno="1" name="b"> - <Default lineno="1"> - 1 -'''], -['''\ -def f(a, (b, c, d)=range(3), - e=None): - local = 1 -''', -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <ParameterList lineno="1"> - <Parameter lineno="1" name="a"> - <ParameterTuple lineno="1" names="(b, c, d)"> - <Default lineno="1"> - range(3) - <Parameter lineno="1" name="e"> - <Default lineno="1"> - None -'''], -['''\ -def f(*args): - local = 1 -''', -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <ParameterList lineno="1"> - <ExcessPositionalArguments lineno="1" name="args"> -'''], -['''\ -def f(**kwargs): - local = 1 -''', -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <ParameterList lineno="1"> - <ExcessKeywordArguments lineno="1" name="kwargs"> -'''], -['''\ -def f(a, b=None, *args, **kwargs): - local = 1 -''', -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <ParameterList lineno="1"> - <Parameter lineno="1" name="a"> - <Parameter lineno="1" name="b"> - <Default lineno="1"> - None - <ExcessPositionalArguments lineno="1" name="args"> - <ExcessKeywordArguments lineno="1" name="kwargs"> -'''], -['''\ -def f(): - pass -f.attrib = 1 -"""f.attrib's docstring""" -''', # " -# @@@ When should the Attribute move inside the Function? -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> - <Attribute lineno="3" name="f.attrib"> - <Expression lineno="3"> - 1 - <Docstring lineno="4"> - f.attrib's docstring -'''], # ' -['''\ -def f(): - def g(): - pass - """Not a docstring""" - local = 1 -''', -'''\ -<Module filename="test data"> - <Function lineno="1" name="f"> -'''], -] - -totest['class'] = [ -['''\ -class C: - """class C's docstring""" -''', -'''\ -<Module filename="test data"> - <Class lineno="1" name="C"> - <Docstring lineno="1"> - class C's docstring -'''], -['''\ -class C(Super): - pass - -class D(SuperD, package.module.SuperD): - pass -''', -'''\ -<Module filename="test data"> - <Class bases="Super" lineno="1" name="C"> - <Class bases="SuperD package.module.SuperD" lineno="4" name="D"> -'''], -['''\ -class C: - class D: - pass - """Not a docstring""" -''', -'''\ -<Module filename="test data"> - <Class lineno="1" name="C"> -'''], -['''\ -class C: - def f(self): - self.local = 1 - local = 1 -''', -'''\ -<Module filename="test data"> - <Class lineno="1" name="C"> - <Method lineno="2" name="f"> - <ParameterList lineno="2"> - <Parameter lineno="2" name="self"> -'''], -['''\ -class C: - def __init__(self): - self.local = 1 - local = 1 -''', -'''\ -<Module filename="test data"> - <Class lineno="1" name="C"> - <Method lineno="2" name="__init__"> - <ParameterList lineno="2"> - <Parameter lineno="2" name="self"> - <Attribute lineno="3" name="self.local"> - <Expression lineno="3"> - 1 - <Attribute lineno="4" name="local"> - <Expression lineno="4"> - 1 -'''], -['''\ -class C: - def __init__(self): - local = foo(a=1) -''', -'''\ -<Module filename="test data"> - <Class lineno="1" name="C"> - <Method lineno="2" name="__init__"> - <ParameterList lineno="2"> - <Parameter lineno="2" name="self"> - <Attribute lineno="3" name="local"> - <Expression lineno="3"> - foo(a=1) -'''], -] - -totest['ignore'] = [ -['''\ -1 + 2 -''', -'''\ -<Module filename="test data"> -'''], -['''\ -del a -''', -'''\ -<Module filename="test data"> -'''], -] - -totest['comments'] = [ -# ['''\ -# # Comment -# ''', -# '''\ -# <Module filename="test data"> -# <Comment lineno="1"> -# # Comment -# '''], -] - -# @@@ no comments yet -totest['everything'] = [ -['''\ -# comment - -"""Docstring""" - -"""Additional docstring""" - -__docformat__ = 'reStructuredText' - -a = 1 -"""Attribute docstring""" - -class C(Super): - - """C's docstring""" - - class_attribute = 1 - """class_attribute's docstring""" - - def __init__(self, text=None): - """__init__'s docstring""" - - self.instance_attribute = (text * 7 - + ' whaddyaknow') - """instance_attribute's docstring""" - - -def f(x, # parameter x - y=a*5, # parameter y - *args): # parameter args - """f's docstring""" - return [x + item for item in args] - -f.function_attribute = 1 -"""f.function_attribute's docstring""" -''', -'''\ -<Module filename="test data"> - <Docstring> - Docstring - <Docstring lineno="5"> - Additional docstring - <Attribute lineno="7" name="__docformat__"> - <Expression lineno="7"> - 'reStructuredText' - <Attribute lineno="9" name="a"> - <Expression lineno="9"> - 1 - <Docstring lineno="10"> - Attribute docstring - <Class bases="Super" lineno="12" name="C"> - <Docstring lineno="12"> - C's docstring - <Attribute lineno="16" name="class_attribute"> - <Expression lineno="16"> - 1 - <Docstring lineno="17"> - class_attribute's docstring - <Method lineno="19" name="__init__"> - <Docstring lineno="19"> - __init__'s docstring - <ParameterList lineno="19"> - <Parameter lineno="19" name="self"> - <Parameter lineno="19" name="text"> - <Default lineno="19"> - None - <Attribute lineno="22" name="self.instance_attribute"> - <Expression lineno="22"> - (text * 7 + ' whaddyaknow') - <Docstring lineno="24"> - instance_attribute's docstring - <Function lineno="27" name="f"> - <Docstring lineno="27"> - f's docstring - <ParameterList lineno="27"> - <Parameter lineno="27" name="x"> - <Parameter lineno="27" name="y"> - <Default lineno="27"> - a * 5 - <ExcessPositionalArguments lineno="27" name="args"> - <Attribute lineno="33" name="f.function_attribute"> - <Expression lineno="33"> - 1 - <Docstring lineno="34"> - f.function_attribute's 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 100644 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_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 2fe79c55c..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.curdir)) -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_class.py b/docutils/test/test_transforms/test_class.py deleted file mode 100755 index db5a1cbdf..000000000 --- a/docutils/test/test_transforms/test_class.py +++ /dev/null @@ -1,104 +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['tables_of_contents'] = ((), [ -["""\ -.. class:: one - -paragraph -""", -"""\ -<document source="test data"> - <paragraph class="one"> - paragraph -"""], -["""\ -.. class:: two -.. - - Block quote -""", -"""\ -<document source="test data"> - <comment xml:space="preserve"> - <block_quote class="two"> - <paragraph> - Block quote -"""], -["""\ - Block quote - - .. class:: three - -Paragraph -""", -"""\ -<document source="test data"> - <block_quote> - <paragraph> - Block quote - <paragraph class="three"> - Paragraph -"""], -["""\ -.. class:: four - -Section Title -============= - -Paragraph -""", -"""\ -<document source="test data"> - <section class="four" id="section-title" name="section title"> - <title> - Section Title - <paragraph> - Paragraph -"""], -["""\ -.. 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 -"""], -]) - - -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 5f54e7a74..000000000 --- a/docutils/test/test_transforms/test_contents.py +++ /dev/null @@ -1,377 +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 class="contents" id="contents" name="contents"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference id="id1" refid="title-1"> - Title 1 - <bullet_list> - <list_item> - <paragraph> - <reference id="id2" refid="title-2"> - Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference id="id3" refid="title-3"> - Title 3 - <list_item> - <paragraph> - <reference id="id4" refid="title-4"> - Title 4 - <section id="title-1" name="title 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title refid="id2"> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title refid="id3"> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="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 class="contents" id="table-of-contents" name="table of contents"> - <title> - Table of Contents - <bullet_list> - <list_item> - <paragraph> - <reference id="id1" refid="title-1"> - Title 1 - <bullet_list> - <list_item> - <paragraph> - <reference id="id2" refid="title-2"> - Title 2 - <section id="title-1" name="title 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="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 class="contents" id="there-s-an-image-in-title-2" name="there's an image in title 2"> - <title> - There's an image in Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference id="id1" refid="title-1"> - Title 1 - <list_item> - <paragraph> - <reference id="id2" refid="title-2"> - Title 2 - <section id="title-1" name="title 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title refid="id2"> - <image alt="Title 2" uri="title2.png"> - <paragraph> - Paragraph 2. - <substitution_definition name="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 class="contents" id="contents" name="contents"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference id="id1" refid="title-1"> - Title 1 - <bullet_list> - <list_item> - <paragraph> - <reference id="id2" refid="title-2"> - Title 2 - <list_item> - <paragraph> - <reference id="id3" refid="title-4"> - Title 4 - <section id="title-1" name="title 1"> - <title refid="id1"> - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title refid="id2"> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="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 id="title-1" name="title 1"> - <title> - Title 1 - <topic class="contents" id="contents" name="contents"> - <bullet_list> - <list_item> - <paragraph> - <reference id="id1" refid="title-2"> - Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference id="id2" refid="title-3"> - Title 3 - <list_item> - <paragraph> - <reference id="id3" refid="title-4"> - Title 4 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title refid="id1"> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title refid="id2"> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="title 4"> - <title refid="id3"> - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. contents:: - :local: - -Test duplicate name "Contents". - -Contents --------- -Paragraph. -""", -"""\ -<document source="test data"> - <topic class="contents" id="id1"> - <bullet_list> - <list_item> - <paragraph> - <reference id="id2" refid="contents"> - Contents - <paragraph> - Test duplicate name "Contents". - <section id="contents" name="contents"> - <title refid="id2"> - Contents - <paragraph> - Paragraph. -"""], -["""\ -.. contents:: - :backlinks: top - -Contents --------- -Paragraph. -""", -"""\ -<document source="test data"> - <topic class="contents" id="id1"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference id="id2" refid="contents"> - Contents - <section id="contents" name="contents"> - <title refid="id1"> - Contents - <paragraph> - Paragraph. -"""], -["""\ -.. contents:: - :backlinks: none - -Contents --------- -Paragraph. -""", -"""\ -<document source="test data"> - <topic class="contents" id="id1"> - <title> - Contents - <bullet_list> - <list_item> - <paragraph> - <reference id="id2" refid="contents"> - Contents - <section id="contents" name="contents"> - <title> - Contents - <paragraph> - Paragraph. -"""], -["""\ -.. contents:: - -Degenerate case, no table of contents generated. -""", -"""\ -<document source="test data"> - <paragraph> - Degenerate case, no table of contents generated. -"""], -]) - - -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 9fafa4ccb..000000000 --- a/docutils/test/test_transforms/test_docinfo.py +++ /dev/null @@ -1,336 +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 class="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 class="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> - <author> - Only One - <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: $RCSfile$ -:Date: $Date$ - -RCS keyword 'RCSfile' doesn't change unless the file name changes, -so it's safe. The 'Date' keyword changes every time the file is -checked in to CVS, so the test's expected output text has to be -derived (hacked) in parallel in order to stay in sync. -""", -"""\ -<document source="test data"> - <docinfo> - <status> - test_docinfo.py - <date> - %s - <comment xml:space="preserve"> - RCS keyword extraction. - <paragraph> - RCS keyword 'RCSfile' doesn't change unless the file name changes, - so it's safe. The 'Date' keyword changes every time the file is - checked in to CVS, so the test's expected output text has to be - derived (hacked) in parallel in order to stay in sync. -""" % ('$Date$'[7:17].replace('/', '-'),)], -]) - - -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 3e08eb232..000000000 --- a/docutils/test/test_transforms/test_doctitle.py +++ /dev/null @@ -1,175 +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 -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['section_headers'] = ((DocTitle,), [ -["""\ -.. test title promotion - -Title -===== - -Paragraph. -""", -"""\ -<document id="title" name="title" source="test data"> - <title> - Title - <comment xml:space="preserve"> - test title promotion - <paragraph> - Paragraph. -"""], -["""\ -Title -===== -Paragraph (no blank line). -""", -"""\ -<document id="title" name="title" source="test data"> - <title> - Title - <paragraph> - Paragraph (no blank line). -"""], -["""\ -Paragraph. - -Title -===== - -Paragraph. -""", -"""\ -<document source="test data"> - <paragraph> - Paragraph. - <section id="title" name="title"> - <title> - Title - <paragraph> - Paragraph. -"""], -["""\ -Title -===== - -Subtitle --------- - -Test title & subtitle. -""", -"""\ -<document id="title" name="title" source="test data"> - <title> - Title - <subtitle id="subtitle" name="subtitle"> - Subtitle - <paragraph> - Test title & subtitle. -"""], -["""\ -Title -==== - -Test short underline. -""", -"""\ -<document id="title" name="title" source="test data"> - <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 id="long-title" name="long title" source="test data"> - <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 id="title-1" name="title 1" source="test data"> - <title> - Title 1 - <comment xml:space="preserve"> - Test multiple second-level titles. - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. -"""], -]) - - -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 100644 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_final_checks.py b/docutils/test/test_transforms/test_final_checks.py deleted file mode 100755 index 36c55efda..000000000 --- a/docutils/test/test_transforms/test_final_checks.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.transforms.universal.FinalChecks. -""" - -from __init__ import DocutilsTestSupport -from docutils.transforms.universal import FinalChecks -from docutils.parsers.rst import Parser - - -def suite(): - parser = Parser() - s = DocutilsTestSupport.TransformTestSuite(parser) - s.generateTests(totest) - return s - -totest = {} - -totest['final_checks'] = ((FinalChecks,), [ -["""\ -Unknown reference_. -""", -"""\ -<document source="test data"> - <paragraph> - Unknown \n\ - <problematic id="id2" refid="id1"> - reference_ - . - <system_message backrefs="id2" id="id1" level="3" line="1" source="test data" type="ERROR"> - <paragraph> - Unknown target name: "reference". -"""], -]) - - -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 4da43e055..000000000 --- a/docutils/test/test_transforms/test_footnotes.py +++ /dev/null @@ -1,520 +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" id="id1" refid="autolabel"> - 1 - <footnote auto="1" backrefs="id1" id="autolabel" name="autolabel"> - <label> - 1 - <paragraph> - text -"""], -["""\ -autonumber: [#]_ - -.. [#] text -""", -"""\ -<document source="test data"> - <paragraph> - autonumber: \n\ - <footnote_reference auto="1" id="id1" refid="id2"> - 1 - <footnote auto="1" backrefs="id1" id="id2" name="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" id="id1" refid="id3"> - 1 - is the first auto-numbered footnote reference. - <footnote_reference auto="1" id="id2" refid="id4"> - 2 - is the second auto-numbered footnote reference. - <footnote auto="1" backrefs="id1" id="id3" name="1"> - <label> - 1 - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" backrefs="id2" id="id4" name="2"> - <label> - 2 - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" backrefs="id6" id="id5" name="3"> - <label> - 3 - <paragraph> - Auto-numbered footnote 3. - <paragraph> - <footnote_reference auto="1" id="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" id="id1" refid="third"> - 3 - is a reference to the third auto-numbered footnote. - <footnote auto="1" backrefs="id3" id="first" name="first"> - <label> - 1 - <paragraph> - First auto-numbered footnote. - <footnote auto="1" backrefs="id2" id="second" name="second"> - <label> - 2 - <paragraph> - Second auto-numbered footnote. - <footnote auto="1" backrefs="id1 id4" id="third" name="third"> - <label> - 3 - <paragraph> - Third auto-numbered footnote. - <paragraph> - <footnote_reference auto="1" id="id2" refid="second"> - 2 - is a reference to the second auto-numbered footnote. - <footnote_reference auto="1" id="id3" refid="first"> - 1 - is a reference to the first auto-numbered footnote. - <footnote_reference auto="1" id="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 refname="first"> - first - , \n\ - <reference refname="second"> - second - , \n\ - <reference 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" id="id1" refid="four"> - 4 - should be 4, \n\ - <footnote_reference auto="1" id="id2" refid="id7"> - 1 - should be 1, - <footnote_reference auto="1" id="id3" refid="id8"> - 3 - should be 3, \n\ - <problematic id="id11" refid="id10"> - [#]_ - is one too many, - <footnote_reference auto="1" id="id5" refid="two"> - 2 - should be 2, and \n\ - <footnote_reference auto="1" id="id6" refname="six"> - doesn't exist. - <footnote auto="1" backrefs="id2" id="id7" name="1"> - <label> - 1 - <paragraph> - Auto-numbered footnote 1. - <footnote auto="1" backrefs="id5" id="two" name="two"> - <label> - 2 - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" backrefs="id3" id="id8" name="3"> - <label> - 3 - <paragraph> - Auto-numbered footnote 3. - <footnote auto="1" backrefs="id1" id="four" name="four"> - <label> - 4 - <paragraph> - Auto-numbered footnote 4. - <footnote auto="1" dupname="five" id="five"> - <label> - 5 - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" dupname="five" id="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" id="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 id="id1" name="1"> - <label> - 1 - <paragraph> - manually numbered - <footnote auto="1" id="id2" name="2"> - <label> - 2 - <paragraph> - auto-numbered - <footnote auto="1" id="label" name="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" id="id1" refid="footnote"> - 2 - . - <paragraph> - An unlabeled autonumbered footnote referece: \n\ - <footnote_reference auto="1" id="id2" refid="id3"> - 1 - . - <footnote auto="1" backrefs="id2" id="id3" name="1"> - <label> - 1 - <paragraph> - Unlabeled autonumbered footnote. - <footnote auto="1" backrefs="id1" id="footnote" name="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" id="id1" refid="four"> - 4 - should be 4, \n\ - <footnote_reference auto="1" id="id2" refid="id10"> - 2 - should be 2, - <footnote_reference id="id3" refid="id9"> - 1 - is 1, \n\ - <footnote_reference id="id4" refid="id11"> - 3 - is 3, - <footnote_reference auto="1" id="id5" refid="id12"> - 6 - should be 6, \n\ - <problematic id="id15" refid="id14"> - [#]_ - is one too many, - <footnote_reference auto="1" id="id7" refname="five"> - should be 5, and \n\ - <footnote_reference auto="1" id="id8" refname="eight"> - doesn't exist. - <footnote backrefs="id3" id="id9" name="1"> - <label> - 1 - <paragraph> - Manually-numbered footnote 1. - <footnote auto="1" backrefs="id2" id="id10" name="2"> - <label> - 2 - <paragraph> - Auto-numbered footnote 2. - <footnote auto="1" backrefs="id1" id="four" name="four"> - <label> - 4 - <paragraph> - Auto-numbered footnote 4. - <footnote backrefs="id4" id="id11" name="3"> - <label> - 3 - <paragraph> - Manually-numbered footnote 3 - <footnote auto="1" dupname="five" id="five"> - <label> - 5 - <paragraph> - Auto-numbered footnote 5. - <footnote auto="1" backrefs="id5" id="id12" name="6"> - <label> - 6 - <paragraph> - Auto-numbered footnote 6. - <footnote auto="1" dupname="five" id="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" id="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="*" id="id1" refid="id2"> - * - . - <footnote auto="*" backrefs="id1" id="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="*" id="id1" refid="id13"> - * - \n\ - <footnote_reference auto="*" id="id2" refid="id14"> - \u2020 - \n\ - <footnote_reference auto="*" id="id3" refid="id15"> - \u2021 - \n\ - <footnote_reference auto="*" id="id4" refid="id16"> - \u00A7 - \n\ - <footnote_reference auto="*" id="id5" refid="id17"> - \u00B6 - \n\ - <footnote_reference auto="*" id="id6" refid="id18"> - # - \n\ - <footnote_reference auto="*" id="id7" refid="id19"> - \u2660 - \n\ - <footnote_reference auto="*" id="id8" refid="id20"> - \u2665 - \n\ - <footnote_reference auto="*" id="id9" refid="id21"> - \u2666 - \n\ - <footnote_reference auto="*" id="id10" refid="id22"> - \u2663 - \n\ - <footnote_reference auto="*" id="id11" refid="id23"> - ** - \n\ - <footnote_reference auto="*" id="id12" refid="id24"> - \u2020\u2020 - . - <footnote auto="*" backrefs="id1" id="id13"> - <label> - * - <paragraph> - Auto-symbol footnote 1. - <footnote auto="*" backrefs="id2" id="id14"> - <label> - \u2020 - <paragraph> - Auto-symbol footnote 2. - <footnote auto="*" backrefs="id3" id="id15"> - <label> - \u2021 - <paragraph> - Auto-symbol footnote 3. - <footnote auto="*" backrefs="id4" id="id16"> - <label> - \u00A7 - <paragraph> - Auto-symbol footnote 4. - <footnote auto="*" backrefs="id5" id="id17"> - <label> - \u00B6 - <paragraph> - Auto-symbol footnote 5. - <footnote auto="*" backrefs="id6" id="id18"> - <label> - # - <paragraph> - Auto-symbol footnote 6. - <footnote auto="*" backrefs="id7" id="id19"> - <label> - \u2660 - <paragraph> - Auto-symbol footnote 7. - <footnote auto="*" backrefs="id8" id="id20"> - <label> - \u2665 - <paragraph> - Auto-symbol footnote 8. - <footnote auto="*" backrefs="id9" id="id21"> - <label> - \u2666 - <paragraph> - Auto-symbol footnote 9. - <footnote auto="*" backrefs="id10" id="id22"> - <label> - \u2663 - <paragraph> - Auto-symbol footnote 10. - <footnote auto="*" backrefs="id11" id="id23"> - <label> - ** - <paragraph> - Auto-symbol footnote 11. - <footnote auto="*" backrefs="id12" id="id24"> - <label> - \u2020\u2020 - <paragraph> - Auto-symbol footnote 12. -"""], -]) - - -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 43e18d3f2..000000000 --- a/docutils/test/test_transforms/test_hyperlinks.py +++ /dev/null @@ -1,520 +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 ChainedTargets, \ - AnonymousHyperlinks, IndirectHyperlinks, ExternalTargets, InternalTargets -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'] = ((ChainedTargets, AnonymousHyperlinks, - IndirectHyperlinks, ExternalTargets, - InternalTargets,), [ -["""\ -direct_ external - -.. _direct: http://direct -""", -"""\ -<document source="test data"> - <paragraph> - <reference refuri="http://direct"> - direct - external - <target id="direct" name="direct" refuri="http://direct"> -"""], -["""\ -indirect_ external - -.. _indirect: xtarget_ -.. _xtarget: http://indirect -""", -"""\ -<document source="test data"> - <paragraph> - <reference refuri="http://indirect"> - indirect - external - <target id="indirect" name="indirect" refuri="http://indirect"> - <target id="xtarget" name="xtarget" refuri="http://indirect"> -"""], -["""\ -.. _direct: - -direct_ internal -""", -"""\ -<document source="test data"> - <target id="direct" name="direct"> - <paragraph> - <reference refid="direct"> - direct - internal -"""], -["""\ -.. _ztarget: - -indirect_ internal - -.. _indirect2: ztarget_ -.. _indirect: indirect2_ -""", -"""\ -<document source="test data"> - <target id="ztarget" name="ztarget"> - <paragraph> - <reference refid="ztarget"> - indirect - internal - <target id="indirect2" name="indirect2" refid="ztarget"> - <target id="indirect" name="indirect" refid="ztarget"> -"""], -["""\ -Implicit --------- - -indirect_ internal - -.. _indirect: implicit_ -""", -"""\ -<document source="test data"> - <section id="implicit" name="implicit"> - <title> - Implicit - <paragraph> - <reference refid="implicit"> - indirect - internal - <target id="indirect" name="indirect" refid="implicit"> -"""], -["""\ -Implicit --------- - -`multiply-indirect`_ internal - -.. _multiply-indirect: indirect_ -.. _indirect: implicit_ -""", -"""\ -<document source="test data"> - <section id="implicit" name="implicit"> - <title> - Implicit - <paragraph> - <reference refid="implicit"> - multiply-indirect - internal - <target id="multiply-indirect" name="multiply-indirect" refid="implicit"> - <target id="indirect" name="indirect" refid="implicit"> -"""], -["""\ -circular_ indirect reference - -.. _circular: indirect_ -.. _indirect: circular_ -""", -"""\ -<document source="test data"> - <paragraph> - <problematic id="id2" refid="id1"> - circular_ - indirect reference - <target id="circular" name="circular" refid="circular"> - <problematic id="id3" refid="id1"> - .. _indirect: circular_ - <system_message backrefs="id2 id3" id="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_ -""", -"""\ -<document source="test data"> - <section dupname="implicit" id="implicit"> - <title> - Implicit - <paragraph> - Duplicate implicit targets. - <section dupname="implicit" id="id1"> - <title> - Implicit - <system_message backrefs="id1" level="1" line="7" source="test data" type="INFO"> - <paragraph> - Duplicate implicit target name: "implicit". - <paragraph> - <problematic id="id3" refid="id2"> - indirect_ - internal - <target id="indirect" name="indirect" refname="implicit"> - <system_message backrefs="id3" id="id2" level="3" line="11" source="test data" type="ERROR"> - <paragraph> - Indirect hyperlink target "indirect" (id="indirect") refers to target "implicit", which does not exist. -"""], -["""\ -`direct external`__ - -__ http://direct -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1" refuri="http://direct"> - direct external - <target anonymous="1" id="id1" refuri="http://direct"> -"""], -["""\ -`indirect external`__ - -__ xtarget_ -.. _xtarget: http://indirect -""", -"""\ -<document source="test data"> - <paragraph> - <reference anonymous="1" refuri="http://indirect"> - indirect external - <target anonymous="1" id="id1" refuri="http://indirect"> - <target id="xtarget" name="xtarget" refuri="http://indirect"> -"""], -["""\ -__ - -`direct internal`__ -""", -"""\ -<document source="test data"> - <target anonymous="1" id="id1"> - <paragraph> - <reference anonymous="1" refid="id1"> - direct internal -"""], -["""\ -.. _ztarget: - -`indirect internal`__ - -__ ztarget_ -""", -"""\ -<document source="test data"> - <target id="ztarget" name="ztarget"> - <paragraph> - <reference anonymous="1" refid="ztarget"> - indirect internal - <target anonymous="1" id="id1" refid="ztarget"> -"""], -["""\ -.. _ztarget: - -First - -.. _ztarget: - -Second - -`indirect internal`__ - -__ ztarget_ -""", -"""\ -<document source="test data"> - <target dupname="ztarget" id="ztarget"> - <paragraph> - First - <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "ztarget". - <target dupname="ztarget" id="id1"> - <paragraph> - Second - <paragraph> - <problematic id="id4" refid="id3"> - `indirect internal`__ - <target anonymous="1" id="id2" refname="ztarget"> - <system_message backrefs="id4" id="id3" level="3" line="11" source="test data" type="ERROR"> - <paragraph> - Indirect hyperlink target (id="id2") refers to target "ztarget", which does not exist. -"""], -["""\ -An `embedded uri <http://direct>`_. - -Another reference to the same `embedded URI`_. -""", -"""\ -<document source="test data"> - <paragraph> - An \n\ - <reference refuri="http://direct"> - embedded uri - <target id="embedded-uri" name="embedded uri" refuri="http://direct"> - . - <paragraph> - Another reference to the same \n\ - <reference refuri="http://direct"> - embedded URI - . -"""], -["""\ -An `anonymous embedded uri <http://direct>`__. -""", -"""\ -<document source="test data"> - <paragraph> - An \n\ - <reference refuri="http://direct"> - anonymous embedded uri - . -"""], -]) - -totest['hyperlinks'] = ((ChainedTargets, AnonymousHyperlinks, - IndirectHyperlinks, ExternalTargets, - InternalTargets,), [ -["""\ -.. _internal hyperlink: - -This paragraph referenced. - -By this `internal hyperlink`_ referemce. -""", -"""\ -<document source="test data"> - <target id="internal-hyperlink" name="internal hyperlink"> - <paragraph> - This paragraph referenced. - <paragraph> - By this \n\ - <reference refid="internal-hyperlink"> - internal hyperlink - referemce. -"""], -["""\ -.. _chained: -.. _internal hyperlink: - -This paragraph referenced. - -By this `internal hyperlink`_ referemce -as well as by this chained_ reference. - -The results of the transform are not visible at the XML level. -""", -"""\ -<document source="test data"> - <target id="chained" name="chained"> - <target id="internal-hyperlink" name="internal hyperlink"> - <paragraph> - This paragraph referenced. - <paragraph> - By this \n\ - <reference refid="internal-hyperlink"> - internal hyperlink - referemce - as well as by this \n\ - <reference refid="chained"> - chained - reference. - <paragraph> - The results of the transform are not visible at the XML level. -"""], -["""\ -.. _external hyperlink: http://uri - -`External hyperlink`_ reference. -""", -"""\ -<document source="test data"> - <target id="external-hyperlink" name="external hyperlink" refuri="http://uri"> - <paragraph> - <reference refuri="http://uri"> - External hyperlink - reference. -"""], -["""\ -.. _external hyperlink: http://uri -.. _indirect target: `external hyperlink`_ -""", -"""\ -<document source="test data"> - <target id="external-hyperlink" name="external hyperlink" refuri="http://uri"> - <target id="indirect-target" name="indirect target" refuri="http://uri"> - <system_message level="1" line="2" source="test data" type="INFO"> - <paragraph> - Indirect 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 id="chained" name="chained" refuri="http://uri"> - <target id="external-hyperlink" name="external hyperlink" refuri="http://uri"> - <paragraph> - <reference refuri="http://uri"> - External hyperlink - reference - and a \n\ - <reference refuri="http://uri"> - chained - reference too. -"""], -["""\ -.. _external hyperlink: http://uri -.. _indirect hyperlink: `external hyperlink`_ - -`Indirect hyperlink`_ reference. -""", -"""\ -<document source="test data"> - <target id="external-hyperlink" name="external hyperlink" refuri="http://uri"> - <target id="indirect-hyperlink" name="indirect hyperlink" refuri="http://uri"> - <paragraph> - <reference refuri="http://uri"> - Indirect hyperlink - reference. -"""], -["""\ -.. _external hyperlink: http://uri -.. _chained: -.. _indirect hyperlink: `external hyperlink`_ - -Chained_ `indirect hyperlink`_ reference. -""", -"""\ -<document source="test data"> - <target id="external-hyperlink" name="external hyperlink" refuri="http://uri"> - <target id="chained" name="chained" refuri="http://uri"> - <target id="indirect-hyperlink" name="indirect hyperlink" refuri="http://uri"> - <paragraph> - <reference refuri="http://uri"> - Chained - \n\ - <reference 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" id="id1" refuri="http://full"> - <target anonymous="1" id="id2" refuri="http://simplified"> - <target anonymous="1" id="id3" refuri="http://simplified"> - <target id="external" name="external" refuri="http://indirect.external"> - <target anonymous="1" id="id4" refuri="http://indirect.external"> - <target anonymous="1" id="id5"> - <paragraph> - <reference anonymous="1" refuri="http://full"> - Full syntax anonymous external hyperlink reference - , - <reference anonymous="1" refuri="http://simplified"> - chained anonymous external reference - , - <reference anonymous="1" refuri="http://simplified"> - simplified syntax anonymous external hyperlink reference - , - <reference anonymous="1" refuri="http://indirect.external"> - indirect anonymous hyperlink reference - , - <reference anonymous="1" refid="id5"> - internal anonymous hyperlink reference - . -"""], -["""\ -Duplicate external target_'s (different URIs): - -.. _target: first - -.. _target: second -""", -"""\ -<document source="test data"> - <paragraph> - Duplicate external \n\ - <reference refname="target"> - target - 's (different URIs): - <target dupname="target" id="target" refuri="first"> - <system_message backrefs="id1" level="2" line="5" source="test data" type="WARNING"> - <paragraph> - Duplicate explicit target name: "target". - <target dupname="target" id="id1" refuri="second"> -"""], -["""\ -Several__ anonymous__ hyperlinks__, but not enough targets. - -__ http://example.org -""", -"""\ -<document source="test data"> - <paragraph> - <problematic id="id3" refid="id2"> - Several__ - \n\ - <problematic id="id4" refid="id2"> - anonymous__ - \n\ - <problematic id="id5" refid="id2"> - hyperlinks__ - , but not enough targets. - <target anonymous="1" id="id1" refuri="http://example.org"> - <system_message backrefs="id3 id4 id5" id="id2" level="3" source="test data" type="ERROR"> - <paragraph> - Anonymous hyperlink mismatch: 3 references but 1 targets. - See "backrefs" attribute for IDs. -"""], -]) - - -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 75325bc96..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 id="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 class="system-messages"> - <title> - Docutils System Messages - <system_message backrefs="id2" id="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 100644 index 28fa68af2..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 refname="reference"> - reference - \n\ - <footnote_reference auto="1" id="id3" refname="target_note: id2"> - . - A "References" section should be generated. - <target id="reference" name="reference" refuri="http://www.example.org"> - <section id="id1"> - <title> - References - <footnote auto="1" id="id2" name="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 100644 index 543deac16..000000000 --- a/docutils/test/test_transforms/test_sectnum.py +++ /dev/null @@ -1,226 +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 id="title-1" name="title 1"> - <title auto="1"> - <generated class="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title auto="1"> - <generated class="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title auto="1"> - <generated class="sectnum"> - 1.1.1\u00a0\u00a0\u00a0 - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="title 4"> - <title auto="1"> - <generated class="sectnum"> - 1.2\u00a0\u00a0\u00a0 - Title 4 - <paragraph> - Paragraph 4. -"""], -["""\ -.. sectnum:: - -**Bold Title** -============== -Paragraph 1. -""", -u"""\ -<document source="test data"> - <section id="bold-title" name="bold title"> - <title auto="1"> - <generated class="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 id="title-1" name="title 1"> - <title auto="1"> - <generated class="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title auto="1"> - <generated class="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="title 4"> - <title auto="1"> - <generated class="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 class="contents" id="contents" name="contents"> - <title> - Contents - <bullet_list class="auto-toc"> - <list_item> - <paragraph> - <reference id="id1" refid="title-1"> - <generated class="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <bullet_list class="auto-toc"> - <list_item> - <paragraph> - <reference id="id2" refid="title-2"> - <generated class="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <bullet_list> - <list_item> - <paragraph> - <reference id="id3" refid="title-3"> - Title 3 - <list_item> - <paragraph> - <reference id="id4" refid="title-4"> - <generated class="sectnum"> - 1.2\u00a0\u00a0\u00a0 - Title 4 - <section id="title-1" name="title 1"> - <title auto="1" refid="id1"> - <generated class="sectnum"> - 1\u00a0\u00a0\u00a0 - Title 1 - <paragraph> - Paragraph 1. - <section id="title-2" name="title 2"> - <title auto="1" refid="id2"> - <generated class="sectnum"> - 1.1\u00a0\u00a0\u00a0 - Title 2 - <paragraph> - Paragraph 2. - <section id="title-3" name="title 3"> - <title refid="id3"> - Title 3 - <paragraph> - Paragraph 3. - <section id="title-4" name="title 4"> - <title auto="1" refid="id4"> - <generated class="sectnum"> - 1.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_substitutions.py b/docutils/test/test_transforms/test_substitutions.py deleted file mode 100755 index 503dfba40..000000000 --- a/docutils/test/test_transforms/test_substitutions.py +++ /dev/null @@ -1,151 +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 name="biohazard"> - <image alt="biohazard" uri="biohazard.png"> -"""], -["""\ -Here's an |unknown| substitution. -""", -"""\ -<document source="test data"> - <paragraph> - Here's an \n\ - <problematic id="id2" refid="id1"> - |unknown| - substitution. - <system_message backrefs="id2" id="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 name="eacute"> - \u00E9 - <substitution_definition name="Eacute"> - \u00C9 - <paragraph> - \u00C9 - t - \u00E9 - , and even \n\ - \u00C9 - . -"""], -]) - -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 name="mdash"> - \u2014 - <substitution_definition name="copy"> - \u00a9 - <substitution_definition name="nbsp"> - \u00a0 - <substitution_definition name="bne"> - = - \u20e5 - <substitution_definition name="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 name="copy"> - \u00a9 - <substitution_definition name="BogusMegaCorp (TM)"> - BogusMegaCorp - \u2122 -"""], -]) - - -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 dc4297113..000000000 --- a/docutils/test/test_utils.py +++ /dev/null @@ -1,297 +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') - self.assertEquals(sw.pformat(), """\ -<system_message level="0" source="test data" type="DEBUG"> - <paragraph> - a debug message -""") - 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 ReporterCategoryTests(unittest.TestCase): - - stream = StringIO.StringIO() - - def setUp(self): - self.stream.seek(0) - self.stream.truncate() - self.reporter = utils.Reporter('test data', 2, 4, self.stream, 1) - self.reporter.set_conditions('lemon', 1, 3, self.stream, 0) - - def test_getset(self): - self.reporter.set_conditions('test', 5, 5, None, 0) - self.assertEquals(self.reporter.get_conditions('other').astuple(), - (1, 2, 4, self.stream)) - self.assertEquals(self.reporter.get_conditions('test').astuple(), - (0, 5, 5, sys.stderr)) - self.assertEquals(self.reporter.get_conditions('test.dummy').astuple(), - (0, 5, 5, sys.stderr)) - self.reporter.set_conditions('test.dummy.spam', 1, 2, self.stream, 1) - self.assertEquals( - self.reporter.get_conditions('test.dummy.spam').astuple(), - (1, 1, 2, self.stream)) - self.assertEquals(self.reporter.get_conditions('test.dummy').astuple(), - (0, 5, 5, sys.stderr)) - self.assertEquals( - self.reporter.get_conditions('test.dummy.spam.eggs').astuple(), - (1, 1, 2, self.stream)) - self.reporter.unset_conditions('test.dummy.spam') - self.assertEquals( - self.reporter.get_conditions('test.dummy.spam.eggs').astuple(), - (0, 5, 5, sys.stderr)) - - def test_debug(self): - sw = self.reporter.debug('debug output', category='lemon.curry') - self.assertEquals(self.stream.getvalue(), '') - sw = self.reporter.debug('debug output') - self.assertEquals(self.stream.getvalue(), - 'test data:: (DEBUG/0) debug output\n') - - def test_info(self): - sw = self.reporter.info('some info') - self.assertEquals(self.stream.getvalue(), '') - sw = self.reporter.info('some info', category='lemon.curry') - self.assertEquals( - self.stream.getvalue(), - 'test data:: (INFO/1) some info [lemon.curry]\n') - - def test_warning(self): - sw = self.reporter.warning('a warning') - self.assertEquals(self.stream.getvalue(), - 'test data:: (WARNING/2) a warning\n') - sw = self.reporter.warning('a warning', category='lemon.curry') - self.assertEquals(self.stream.getvalue(), """\ -test data:: (WARNING/2) a warning -test data:: (WARNING/2) a warning [lemon.curry] -""") - - def test_error(self): - sw = self.reporter.error('an error') - self.assertEquals(self.stream.getvalue(), - 'test data:: (ERROR/3) an error\n') - self.assertRaises(utils.SystemMessage, self.reporter.error, - 'an error', category='lemon.curry') - self.assertEquals(self.stream.getvalue(), """\ -test data:: (ERROR/3) an error -test data:: (ERROR/3) an error [lemon.curry] -""") - - def test_severe(self): - self.assertRaises(utils.SystemMessage, self.reporter.severe, - 'a severe error') - self.assertEquals(self.stream.getvalue(), - 'test data:: (SEVERE/4) a severe error\n') - self.assertRaises(utils.SystemMessage, self.reporter.severe, - 'a severe error', category='lemon.curry') - self.assertEquals(self.stream.getvalue(), """\ -test data:: (SEVERE/4) a severe error -test data:: (SEVERE/4) a severe error [lemon.curry] -""") - - -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 100644 index 3ddf1fcf1..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_strip_indent(self): - s = self.a[3:5] - s.strip_indent(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 2fe79c55c..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.curdir)) -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_latex2e.py b/docutils/test/test_writers/test_latex2e.py deleted file mode 100644 index 75a013fe6..000000000 --- a/docutils/test/test_writers/test_latex2e.py +++ /dev/null @@ -1,255 +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.LatexPublishTestSuite() - s.generateTests(totest) - return s - - -latex_head = """\ -\\documentclass[10pt,english]{article} -\\usepackage{babel} -\\usepackage{shortvrb} -\\usepackage[latin1]{inputenc} -\\usepackage{tabularx} -\\usepackage{longtable} -\\setlength{\\extrarowheight}{2pt} -\\usepackage{amsmath} -\\usepackage{graphicx} -\\usepackage{color} -\\usepackage{multirow} -\\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} -\\usepackage[a4paper,margin=2cm,nohead]{geometry} -%% generator Docutils: http://docutils.sourceforge.net/ -\\newlength{\\admonitionwidth} -\\setlength{\\admonitionwidth}{0.9\\textwidth} -\\newlength{\\docinfowidth} -\\setlength{\\docinfowidth}{0.9\\textwidth} -\\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}} -% 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 ~}} -% end of "some commands" -\\input{style.tex} -""" - -totest = {} - -totest['table_of_contents'] = [ -# input -["""\ -.. contents:: Table of Contents - -Title 1 -======= -Paragraph 1. - -Title 2 -------- -Paragraph 2. -""", -# expected output -latex_head + """\ -\\title{Title 1} -\\author{} -\\date{} -\\hypersetup{\npdftitle={Title 1} -} -\\raggedbottom -\\begin{document} -\\maketitle - -\\hypertarget{table-of-contents}{}\\subsection*{~\\hfill Table of Contents\\hfill ~} -\\pdfbookmark[0]{Table of Contents}{table-of-contents} -\\begin{list}{}{} -\\item \\href{#title-2}{Title 2} - -\\end{list} - - -Paragraph 1. - - -%___________________________________________________________________________ - -\\hypertarget{title-2}{} -\\section*{Title 2} -\\pdfbookmark[0]{Title 2}{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} -\\maketitle - -\\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} -\\maketitle - - -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{ttfamily}\\begin{flushleft} -\\mbox{""}\\\\ -\\mbox{This~is~left~"untouched"~also~*this*.}\\\\ -\\mbox{""} -\\end{flushleft}\\end{ttfamily} -\\begin{ttfamily}\\begin{flushleft} -\\mbox{should~get~"quotes"~and~\\emph{italics}.} -\\end{flushleft}\\end{ttfamily} - -Inline \\texttt{literal "quotes"} should be kept. - -\\end{document} -"""], -] - -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 dfba99945..000000000 --- a/docutils/tools/buildhtml.py +++ /dev/null @@ -1,227 +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 PEPs (either old-style or -new reStructuredText PEPs). -""" -# Once PySource is here, build .html from .py as well. - -__docformat__ = 'reStructuredText' - - -import locale -try: - 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 .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}), - ('Do not scan subdirectories for files to process.', - ['--local'], {'dest': 'recurse', 'action': 'store_false'}), - ('Work silently (no progress messages). Independent of "--quiet".', - ['--silent'], {'action': 'store_true'}),)) - - -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=(SettingsSpec, pep.Reader, rst.Parser, - pep_html.Writer)), - '.txt': Struct(components=(rst.Parser, standalone.Reader, - html4css1.Writer)), - 'PEPs': Struct(components=(rst.Parser, pep.Reader, - pep_html.Writer))} - """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, - 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) - config_parser = frontend.ConfigParser() - config_parser.read_standard_files(option_parser) - self.config_settings = config_parser.get_section('options') - frontend.make_paths_absolute( - self.config_settings, - self.publishers[''].option_parser.relative_path_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 = copy.deepcopy(publisher.setting_defaults) - settings.__dict__.update(self.config_settings) - if directory: - config_parser = frontend.ConfigParser() - config_parser.read(os.path.join(directory, 'docutils.conf'), - publisher.option_parser) - local_config = config_parser.get_section('options') - frontend.make_paths_absolute( - local_config, publisher.option_parser.relative_path_settings, - directory) - settings.__dict__.update(local_config) - settings.__dict__.update(self.settings_spec.__dict__) - 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): - if not self.initial_settings.silent: - print >>sys.stderr, '/// Processing directory:', directory - sys.stderr.flush() - peps_found = 0 - for name in names: - if name.endswith('.txt'): - if name.startswith('pep-'): - peps_found = 1 - else: - self.process_txt(directory, name) - if peps_found: - self.process_peps(directory) - if not recurse: - del names[:] - - def process_txt(self, directory, name): - settings = self.get_settings('.txt', directory) - 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 .txt:', name - sys.stderr.flush() - try: - core.publish_file(source_path=settings._source, - destination_path=settings._destination, - reader_name='standalone', - parser_name='restructuredtext', - writer_name='html', - settings=settings) - except ApplicationError, error: - print >>sys.stderr, (' Error (%s): %s' - % (error.__class__.__name__, error)) - - def process_peps(self, directory): - # only import PEP module/script if we need it. - import pep2html - - settings = self.get_settings('PEPs', directory) - old_directory = os.getcwd() - os.chdir(directory) - if self.initial_settings.silent: - argv = ['-q'] - else: - print >>sys.stderr, ' ::: Processing PEPs:' - sys.stderr.flush() - argv = [] - pep2html.docutils_settings = settings - try: - pep2html.main(argv) - except Exception, error: - print >>sys.stderr, (' Error (%s): %s' - % (error.__class__.__name__, error)) - os.chdir(old_directory) - - -if __name__ == "__main__": - Builder().run() diff --git a/docutils/tools/docutils-xml.py b/docutils/tools/docutils-xml.py deleted file mode 100755 index 42c879cc8..000000000 --- a/docutils/tools/docutils-xml.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. -""" - -import locale -try: - 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/docutils.conf b/docutils/tools/docutils.conf deleted file mode 100644 index 63d8f4f5b..000000000 --- a/docutils/tools/docutils.conf +++ /dev/null @@ -1,15 +0,0 @@ -[options] - -# These entries affect all processing: -source-link: 1 -datestamp: %Y-%m-%d %H:%M UTC -generator: 1 - -# These entries affect HTML output: -stylesheet-path: stylesheets/default.css - -# These entries affect reStructuredText-style PEPs: -pep-template: pep-html-template -pep-stylesheet-path: stylesheets/pep.css -python-home: http://www.python.org -no-random: 1 diff --git a/docutils/tools/editors/README.txt b/docutils/tools/editors/README.txt deleted file mode 100644 index 8e489f447..000000000 --- a/docutils/tools/editors/README.txt +++ /dev/null @@ -1,12 +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>`__ - -.. _reStructuredText: http://docutils.sf.net/rst.html diff --git a/docutils/tools/editors/emacs/restructuredtext.el b/docutils/tools/editors/emacs/restructuredtext.el deleted file mode 100644 index 15cd4054e..000000000 --- a/docutils/tools/editors/emacs/restructuredtext.el +++ /dev/null @@ -1,149 +0,0 @@ -;; Authors: David Goodger <goodger@python.org>; -;; Martin Blais -;; Date: $Date$ -;; Copyright: This module has been placed in the public domain. -;; -;; Support code for editing reStructuredText with Emacs indented-text mode. -;; The goal is to create an integrated reStructuredText editing mode. -;; -;; Updates -;; ------- -;; -;; 2003-02-25 (blais): updated repeat-last-character function and added -;; a few routines for navigating between titles. - -(defun replace-lines (fromchar tochar) - ;; by David Goodger - "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))) - (kill-line) - (insert-char tochar l)) - (search-failed - (message (format "%d lines replaced." found))))))) - -(defun repeat-last-character () - ;; by Martin Blais - "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, -or if a prefix argument is provided, fill up to the fill-column. - -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 -behaviour is performed." - -;; TODO -;; ---- -;; It would be useful if only these characters were repeated: -;; =-`:.'"~^_*+#<>!$%&(),/;?@[\]{|} -;; Especially, empty lines shouldn't be repeated. - - (interactive) - (let* ((curcol (current-column)) - (curline (+ (count-lines (point-min) (point)) (if (eq curcol 0) 1 0))) - (lbp (line-beginning-position 0)) - (prevcol (if (= curline 1) - fill-column - (save-excursion - (forward-line -1) - (end-of-line) - (skip-chars-backward " \t" lbp) - (let ((cc (current-column))) - (if (= cc 0) fill-column cc))))) - (rightmost-column - (cond (current-prefix-arg 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)))) )) - -(defun reST-title-char-p (c) - ;; by Martin Blais - "Returns true if the given character is a valid title char." - (and (string-match "[-=`:\\.'\"~^_*+#<>!$%&(),/;?@\\\|]" - (char-to-string c)) t)) - -(defun reST-forward-title () - ;; by Martin Blais - "Skip to the next restructured text section title." - (interactive) - (let* ( (newpoint - (save-excursion - (forward-char) ;; in case we're right on a title - (while - (not - (and (re-search-forward "^[A-Za-z0-9].*[ \t]*$" nil t) - (reST-title-char-p (char-after (+ (point) 1))) - (looking-at (format "\n%c\\{%d,\\}[ \t]*$" - (char-after (+ (point) 1)) - (current-column)))))) - (beginning-of-line) - (point))) ) - (if newpoint (goto-char newpoint)) )) - -(defun reST-backward-title () - ;; by Martin Blais - "Skip to the previous restructured text section title." - (interactive) - (let* ( (newpoint - (save-excursion - ;;(forward-char) ;; in case we're right on a title - (while - (not - (and (or (backward-char) t) - (re-search-backward "^[A-Za-z0-9].*[ \t]*$" nil t) - (or (end-of-line) t) - (reST-title-char-p (char-after (+ (point) 1))) - (looking-at (format "\n%c\\{%d,\\}[ \t]*$" - (char-after (+ (point) 1)) - (current-column)))))) - (beginning-of-line) - (point))) ) - (if newpoint (goto-char newpoint)) )) - -(defun join-paragraph () - ;; by David Goodger - "Join lines in current paragraph into one line, removing end-of-lines." - (interactive) - (save-excursion - (backward-paragraph 1) - (forward-char 1) - (let ((start (point))) ; remember where we are - (forward-paragraph 1) ; go to the end of the paragraph - (beginning-of-line 0) ; go to the beginning of the previous line - (while (< start (point)) ; as long as we haven't passed where we started - (delete-indentation) ; join this line to the line before - (beginning-of-line))))) ; and go back to the beginning of the line - -(defun force-fill-paragraph () - ;; by David Goodger - "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)) diff --git a/docutils/tools/editors/emacs/rst-html.el b/docutils/tools/editors/emacs/rst-html.el deleted file mode 100644 index c9ebf33ef..000000000 --- a/docutils/tools/editors/emacs/rst-html.el +++ /dev/null @@ -1,129 +0,0 @@ -;;; rst-mode.el --- Goodies to automate converting reST documents to HTML. - -;; Copyright 2003 Martin Blais <blais@iro.umontreal.ca> -;; -;; 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 - -;;; Commentary: - -;; This package provides a few functions and variables that can help in -;; automating converting reST documents to HTML from within emacs. You could -;; use a makefile to do this, of use the compile command that this package -;; provides. - -;; You can also bind a command to automate converting to HTML: -;; (defun user-rst-mode-hook () -;; (local-set-key [(control c)(?9)] 'rst-html-compile)) -;; (add-hook 'rst-mode-hook 'user-rst-mode-hook) - -;;; Code: - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; Customization: - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -(defgroup rst-html nil - "Settings for conversion to HTML available by \\[rst-html-compile]. Use of -this functionality is discouraged. Get a proper `Makefile' instead." - :group 'rst - :version "21.1") - -(defcustom rst-html-command "docutils-html" - "Command to convert an reST file to HTML." - :group 'rst-html - :type '(string)) - -(defcustom rst-html-stylesheet "" - "Stylesheet for reST to HTML conversion. Empty for no special stylesheet." - :group 'rst-html - :type '(string)) - -(defcustom rst-html-options "" - "Local file options for reST to HTML conversion. -Stylesheets are set by an own option." - :group 'rst-html - :type '(string)) - -(defcustom rst-html-extension ".html" - "Extension for HTML output file." - :group 'rst-html - :type '(string)) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Conversion to HTML - -(defun rst-html-compile () - "Compile command to convert reST document into HTML." - (interactive) - (let* ((bufname (file-name-nondirectory buffer-file-name)) - (outname (file-name-sans-extension bufname)) - (ssheet - (or (and (not (zerop (length rst-html-stylesheet))) - (concat "--stylesheet=\"" rst-html-stylesheet "\"")) - ""))) - (set (make-local-variable 'compile-command) - (mapconcat 'identity - (list rst-html-command - ssheet rst-html-options - bufname (concat outname rst-html-extension)) - " ")) - (if (or compilation-read-command current-prefix-arg) - (call-interactively 'compile) - (compile compile-command)) - )) - -(defun rst-html-compile-with-conf () - "Compile command to convert reST document into HTML. Attempts to find -configuration file, if it can, overrides the options." - (interactive) - (let ((conffile (rst-html-find-conf))) - (if conffile - (let* ((bufname (file-name-nondirectory buffer-file-name)) - (outname (file-name-sans-extension bufname))) - (set (make-local-variable 'compile-command) - (mapconcat 'identity - (list rst-html-command - (concat "--config=\"" conffile "\"") - bufname (concat outname rst-html-extension)) - " ")) - (if (or compilation-read-command current-prefix-arg) - (call-interactively 'compile) - (compile compile-command))) - (call-interactively 'rst-html-compile) - ))) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;; Find the configuration file in the parents. - -(defun rst-html-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) - ))) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -;;; rst-mode.el ends here diff --git a/docutils/tools/editors/emacs/rst-mode.el b/docutils/tools/editors/emacs/rst-mode.el deleted file mode 100644 index 3f81da39c..000000000 --- a/docutils/tools/editors/emacs/rst-mode.el +++ /dev/null @@ -1,696 +0,0 @@ -;;; rst-mode.el --- Mode for viewing and editing reStructuredText-documents. - -;; Copyright 2003 Stefan Merten <smerten@oekonux.de> -;; -;; 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 - -;;; Commentary: - -;; This package provides support for documents marked up using the -;; reStructuredText format -;; [http://docutils.sourceforge.net/spec/rst/reStructuredText.html]. Support -;; includes font locking as well as some convenience functions for editing. - -;; The package 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: -;; -;; (autoload 'rst-mode "rst-mode" "mode for editing reStructuredText documents" t) -;; (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. - -;;; Code: - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; -;;; Customization: - -(defgroup rst nil "Support for reStructuredText documents" - :group 'wp - :version "21.1" - :link '(url-link "http://docutils.sourceforge.net/spec/rst/reStructuredText.html")) - -(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)) - -;; Faces for displaying items on several levels; these definitions define -;; different shades of grey where the lightest one is used for level 1 -(defconst rst-level-face-max 6 - "Maximum depth of level faces defined") -(defconst rst-level-face-base-color "grey" - "The base color to be used for creating level faces") -(defconst rst-level-face-base-light 85 - "The lightness factor for the base color") -(defconst rst-level-face-format-light "%2d" - "The format for the lightness factor for the base color") -(defconst rst-level-face-step-light -7 - "The step width to use for next color") - -;; Define the faces -(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))))) - -(defcustom rst-adornment-faces-alist - '((1 . rst-level-1-face) - (2 . rst-level-2-face) - (3 . rst-level-3-face) - (4 . rst-level-4-face) - (5 . rst-level-5-face) - (6 . rst-level-6-face) - (t . font-lock-keyword-face) - (nil . font-lock-keyword-face)) - "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)." - :group 'rst-faces - :type '(alist :key-type (choice (integer :tag "Section level") - (boolean :tag "transitions (on) / section title adornment (off)")) - :value-type (face))) - -;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; - -;; 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) - ) - -(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/spec/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 diff --git a/docutils/tools/html.py b/docutils/tools/html.py deleted file mode 100755 index 98293b3a1..000000000 --- a/docutils/tools/html.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 HTML. -""" - -import locale -try: - 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/pep-html-template b/docutils/tools/pep-html-template deleted file mode 100644 index 94ecafb70..000000000 --- a/docutils/tools/pep-html-template +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version="1.0" encoding="%(encoding)s" ?> -<!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=%(encoding)s" /> - <meta name="generator" content="Docutils %(version)s: http://docutils.sourceforge.net/" /> - <title>PEP %(pep)s -- %(title)s</title> - %(stylesheet)s</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="%(pyhome)s/" title="Python Home Page"> -<img src="%(pyhome)s/pics/PyBanner%(banner)03d.gif" alt="[Python]" - border="0" width="150" height="35" /></a></td> -<td class="textlinks" align="left"> -[<b><a href="%(pyhome)s/">Python Home</a></b>] -[<b><a href="%(pepindex)s">PEP Index</a></b>] -[<b><a href="%(pephome)s/pep-%(pepnum)s.txt">PEP Source</a></b>] -</td></tr></table> -%(body)s -%(body_suffix)s diff --git a/docutils/tools/pep.py b/docutils/tools/pep.py deleted file mode 100755 index 4c38980b6..000000000 --- a/docutils/tools/pep.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. -""" - -import locale -try: - 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/tools/pep2html.py b/docutils/tools/pep2html.py deleted file mode 100755 index fb82a4718..000000000 --- a/docutils/tools/pep2html.py +++ /dev/null @@ -1,531 +0,0 @@ -#!/usr/bin/env python -"""Convert PEPs to (X)HTML - courtesy of /F - -Usage: %(PROGRAM)s [options] [peps] - -Options: - - -u/--user - python.org username - - -b/--browse - After generating the HTML, direct your web browser to view it - (using the Python webbrowser module). If both -i and -b are - given, this will browse the on-line HTML; otherwise it will - browse the local HTML. If no pep arguments are given, this - will browse PEP 0. - - -i/--install - After generating the HTML, install it and the plaintext source file - (.txt) on python.org. In that case the user's name is used in the scp - and ssh commands, unless "-u username" is given (in which case, it is - used instead). Without -i, -u is ignored. - - -l/--local - Same as -i/--install, except install on the local machine. Use this - when logged in to the python.org machine (creosote). - - -q/--quiet - Turn off verbose messages. - - -h/--help - Print this help message and exit. - -The optional argument `peps' is a list of either pep numbers or .txt files. -""" - -import sys -import os -import re -import cgi -import glob -import getopt -import errno -import random -import time - -REQUIRES = {'python': '2.2', - 'docutils': '0.2.7'} -PROGRAM = sys.argv[0] -RFCURL = 'http://www.faqs.org/rfcs/rfc%d.html' -PEPURL = 'pep-%04d.html' -PEPCVSURL = ('http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python' - '/nondist/peps/pep-%04d.txt') -PEPDIRRUL = 'http://www.python.org/peps/' - - -HOST = "www.python.org" # host for update -HDIR = "/ftp/ftp.python.org/pub/www.python.org/peps" # target host directory -LOCALVARS = "Local Variables:" - -COMMENT = """<!-- -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! --->""" - -# The generated HTML doesn't validate -- you cannot use <hr> and <h3> inside -# <pre> tags. But if I change that, the result doesn't look very nice... -DTD = ('<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"\n' - ' "http://www.w3.org/TR/REC-html40/loose.dtd">') - -fixpat = re.compile("((http|ftp):[-_a-zA-Z0-9/.+~:?#$=&,]+)|(pep-\d+(.txt)?)|" - "(RFC[- ]?(?P<rfcnum>\d+))|" - "(PEP\s+(?P<pepnum>\d+))|" - ".") - -EMPTYSTRING = '' -SPACE = ' ' -COMMASPACE = ', ' - - - -def usage(code, msg=''): - print >> sys.stderr, __doc__ % globals() - if msg: - print >> sys.stderr, msg - sys.exit(code) - - - -def fixanchor(current, match): - text = match.group(0) - link = None - if text.startswith('http:') or text.startswith('ftp:'): - # Strip off trailing punctuation. Pattern taken from faqwiz. - ltext = list(text) - while ltext: - c = ltext.pop() - if c not in '();:,.?\'"<>': - ltext.append(c) - break - link = EMPTYSTRING.join(ltext) - elif text.startswith('pep-') and text <> current: - link = os.path.splitext(text)[0] + ".html" - elif text.startswith('PEP'): - pepnum = int(match.group('pepnum')) - link = PEPURL % pepnum - elif text.startswith('RFC'): - rfcnum = int(match.group('rfcnum')) - link = RFCURL % rfcnum - if link: - return '<a href="%s">%s</a>' % (cgi.escape(link), cgi.escape(text)) - return cgi.escape(match.group(0)) # really slow, but it works... - - - -NON_MASKED_EMAILS = [ - 'peps@python.org', - 'python-list@python.org', - 'python-dev@python.org', - ] - -def fixemail(address, pepno): - if address.lower() in NON_MASKED_EMAILS: - # return hyperlinked version of email address - return linkemail(address, pepno) - else: - # return masked version of email address - parts = address.split('@', 1) - return '%s at %s' % (parts[0], parts[1]) - - -def linkemail(address, pepno): - parts = address.split('@', 1) - return ('<a href="mailto:%s@%s?subject=PEP%%20%s">' - '%s at %s</a>' - % (parts[0], parts[1], pepno, parts[0], parts[1])) - - -def fixfile(inpath, input_lines, outfile): - from email.Utils import parseaddr - basename = os.path.basename(inpath) - infile = iter(input_lines) - # convert plaintext pep to minimal XHTML markup - print >> outfile, DTD - print >> outfile, '<html>' - print >> outfile, COMMENT - print >> outfile, '<head>' - # head - header = [] - pep = "" - title = "" - for line in infile: - if not line.strip(): - break - if line[0].strip(): - if ":" not in line: - break - key, value = line.split(":", 1) - value = value.strip() - header.append((key, value)) - else: - # continuation line - key, value = header[-1] - value = value + line - header[-1] = key, value - if key.lower() == "title": - title = value - elif key.lower() == "pep": - pep = value - if pep: - title = "PEP " + pep + " -- " + title - if title: - print >> outfile, ' <title>%s</title>' % cgi.escape(title) - r = random.choice(range(64)) - print >> outfile, ( - ' <link rel="STYLESHEET" href="style.css" type="text/css" />\n' - '</head>\n' - '<body bgcolor="white">\n' - '<table class="navigation" cellpadding="0" cellspacing="0"\n' - ' width="100%%" border="0">\n' - '<tr><td class="navicon" width="150" height="35">\n' - '<a href="../" title="Python Home Page">\n' - '<img src="../pics/PyBanner%03d.gif" alt="[Python]"\n' - ' border="0" width="150" height="35" /></a></td>\n' - '<td class="textlinks" align="left">\n' - '[<b><a href="../">Python Home</a></b>]' % r) - if basename <> 'pep-0000.txt': - print >> outfile, '[<b><a href=".">PEP Index</a></b>]' - if pep: - try: - print >> outfile, ('[<b><a href="pep-%04d.txt">PEP Source</a>' - '</b>]' % int(pep)) - except ValueError, error: - print >> sys.stderr, ('ValueError (invalid PEP number): %s' - % error) - print >> outfile, '</td></tr></table>' - print >> outfile, '<div class="header">\n<table border="0">' - for k, v in header: - if k.lower() in ('author', 'discussions-to'): - mailtos = [] - for part in re.split(',\s*', v): - if '@' in part: - realname, addr = parseaddr(part) - if k.lower() == 'discussions-to': - m = linkemail(addr, pep) - else: - m = fixemail(addr, pep) - mailtos.append('%s <%s>' % (realname, m)) - elif part.startswith('http:'): - mailtos.append( - '<a href="%s">%s</a>' % (part, part)) - else: - mailtos.append(part) - v = COMMASPACE.join(mailtos) - elif k.lower() in ('replaces', 'replaced-by', 'requires'): - otherpeps = '' - for otherpep in re.split(',?\s+', v): - otherpep = int(otherpep) - otherpeps += '<a href="pep-%04d.html">%i</a> ' % (otherpep, - otherpep) - v = otherpeps - elif k.lower() in ('last-modified',): - date = v or time.strftime('%d-%b-%Y', - time.localtime(os.stat(inpath)[8])) - try: - url = PEPCVSURL % int(pep) - v = '<a href="%s">%s</a> ' % (url, cgi.escape(date)) - except ValueError, error: - v = date - elif k.lower() in ('content-type',): - url = PEPURL % 9 - pep_type = v or 'text/plain' - v = '<a href="%s">%s</a> ' % (url, cgi.escape(pep_type)) - else: - v = cgi.escape(v) - print >> outfile, ' <tr><th>%s: </th><td>%s</td></tr>' \ - % (cgi.escape(k), v) - print >> outfile, '</table>' - print >> outfile, '</div>' - print >> outfile, '<hr />' - print >> outfile, '<div class="content">' - need_pre = 1 - for line in infile: - if line[0] == '\f': - continue - if line.strip() == LOCALVARS: - break - if line[0].strip(): - if not need_pre: - print >> outfile, '</pre>' - print >> outfile, '<h3>%s</h3>' % line.strip() - need_pre = 1 - elif not line.strip() and need_pre: - continue - else: - # PEP 0 has some special treatment - if basename == 'pep-0000.txt': - parts = line.split() - if len(parts) > 1 and re.match(r'\s*\d{1,4}', parts[1]): - # This is a PEP summary line, which we need to hyperlink - url = PEPURL % int(parts[1]) - if need_pre: - print >> outfile, '<pre>' - need_pre = 0 - print >> outfile, re.sub( - parts[1], - '<a href="%s">%s</a>' % (url, parts[1]), - line, 1), - continue - elif parts and '@' in parts[-1]: - # This is a pep email address line, so filter it. - url = fixemail(parts[-1], pep) - if need_pre: - print >> outfile, '<pre>' - need_pre = 0 - print >> outfile, re.sub( - parts[-1], url, line, 1), - continue - line = fixpat.sub(lambda x, c=inpath: fixanchor(c, x), line) - if need_pre: - print >> outfile, '<pre>' - need_pre = 0 - outfile.write(line) - if not need_pre: - print >> outfile, '</pre>' - print >> outfile, '</div>' - print >> outfile, '</body>' - print >> outfile, '</html>' - - -docutils_settings = None -"""Runtime settings object used by Docutils. Can be set by the client -application when this module is imported.""" - -def fix_rst_pep(inpath, input_lines, outfile): - from docutils import core - output = core.publish_string( - source=''.join(input_lines), - source_path=inpath, - destination_path=outfile.name, - reader_name='pep', - parser_name='restructuredtext', - writer_name='pep_html', - settings=docutils_settings) - outfile.write(output) - - -def get_pep_type(input_lines): - """ - Return the Content-Type of the input. "text/plain" is the default. - Return ``None`` if the input is not a PEP. - """ - pep_type = None - for line in input_lines: - line = line.rstrip().lower() - if not line: - # End of the RFC 2822 header (first blank line). - break - elif line.startswith('content-type: '): - pep_type = line.split()[1] or 'text/plain' - break - elif line.startswith('pep: '): - # Default PEP type, used if no explicit content-type specified: - pep_type = 'text/plain' - return pep_type - - -def get_input_lines(inpath): - try: - infile = open(inpath) - except IOError, e: - if e.errno <> errno.ENOENT: raise - print >> sys.stderr, 'Error: Skipping missing PEP file:', e.filename - sys.stderr.flush() - return None, None - lines = infile.read().splitlines(1) # handles x-platform line endings - infile.close() - return lines - - -def find_pep(pep_str): - """Find the .txt file indicated by a cmd line argument""" - if os.path.exists(pep_str): - return pep_str - num = int(pep_str) - return "pep-%04d.txt" % num - -def make_html(inpath, verbose=0): - input_lines = get_input_lines(inpath) - pep_type = get_pep_type(input_lines) - if pep_type is None: - print >> sys.stderr, 'Error: Input file %s is not a PEP.' % inpath - sys.stdout.flush() - return None - elif not PEP_TYPE_DISPATCH.has_key(pep_type): - print >> sys.stderr, ('Error: Unknown PEP type for input file %s: %s' - % (inpath, pep_type)) - sys.stdout.flush() - return None - elif PEP_TYPE_DISPATCH[pep_type] == None: - pep_type_error(inpath, pep_type) - return None - outpath = os.path.splitext(inpath)[0] + ".html" - if verbose: - print inpath, "(%s)" % pep_type, "->", outpath - sys.stdout.flush() - outfile = open(outpath, "w") - PEP_TYPE_DISPATCH[pep_type](inpath, input_lines, outfile) - outfile.close() - os.chmod(outfile.name, 0664) - return outpath - -def push_pep(htmlfiles, txtfiles, username, verbose, local=0): - quiet = "" - if local: - if verbose: - quiet = "-v" - target = HDIR - copy_cmd = "cp" - chmod_cmd = "chmod" - else: - if not verbose: - quiet = "-q" - if username: - username = username + "@" - target = username + HOST + ":" + HDIR - copy_cmd = "scp" - chmod_cmd = "ssh %s%s chmod" % (username, HOST) - files = htmlfiles[:] - files.extend(txtfiles) - files.append("style.css") - files.append("pep.css") - filelist = SPACE.join(files) - rc = os.system("%s %s %s %s" % (copy_cmd, quiet, filelist, target)) - if rc: - sys.exit(rc) - rc = os.system("%s 664 %s/*" % (chmod_cmd, HDIR)) - if rc: - sys.exit(rc) - - -PEP_TYPE_DISPATCH = {'text/plain': fixfile, - 'text/x-rst': fix_rst_pep} -PEP_TYPE_MESSAGES = {} - -def check_requirements(): - # Check Python: - try: - from email.Utils import parseaddr - except ImportError: - PEP_TYPE_DISPATCH['text/plain'] = None - PEP_TYPE_MESSAGES['text/plain'] = ( - 'Python %s or better required for "%%(pep_type)s" PEP ' - 'processing; %s present (%%(inpath)s).' - % (REQUIRES['python'], sys.version.split()[0])) - # Check Docutils: - try: - import docutils - except ImportError: - PEP_TYPE_DISPATCH['text/x-rst'] = None - PEP_TYPE_MESSAGES['text/x-rst'] = ( - 'Docutils not present for "%(pep_type)s" PEP file %(inpath)s. ' - 'See README.txt for installation.') - else: - installed = [int(part) for part in docutils.__version__.split('.')] - required = [int(part) for part in REQUIRES['docutils'].split('.')] - if installed < required: - PEP_TYPE_DISPATCH['text/x-rst'] = None - PEP_TYPE_MESSAGES['text/x-rst'] = ( - 'Docutils must be reinstalled for "%%(pep_type)s" PEP ' - 'processing (%%(inpath)s). Version %s or better required; ' - '%s present. See README.txt for installation.' - % (REQUIRES['docutils'], docutils.__version__)) - -def pep_type_error(inpath, pep_type): - print >> sys.stderr, 'Error: ' + PEP_TYPE_MESSAGES[pep_type] % locals() - sys.stdout.flush() - - -def browse_file(pep): - import webbrowser - file = find_pep(pep) - if file.endswith(".txt"): - file = file[:-3] + "html" - file = os.path.abspath(file) - url = "file:" + file - webbrowser.open(url) - -def browse_remote(pep): - import webbrowser - file = find_pep(pep) - if file.endswith(".txt"): - file = file[:-3] + "html" - url = PEPDIRRUL + file - webbrowser.open(url) - - -def main(argv=None): - # defaults - update = 0 - local = 0 - username = '' - verbose = 1 - browse = 0 - - check_requirements() - - if argv is None: - argv = sys.argv[1:] - - try: - opts, args = getopt.getopt( - argv, 'bilhqu:', - ['browse', 'install', 'local', 'help', 'quiet', 'user=']) - except getopt.error, msg: - usage(1, msg) - - for opt, arg in opts: - if opt in ('-h', '--help'): - usage(0) - elif opt in ('-i', '--install'): - update = 1 - elif opt in ('-l', '--local'): - update = 1 - local = 1 - elif opt in ('-u', '--user'): - username = arg - elif opt in ('-q', '--quiet'): - verbose = 0 - elif opt in ('-b', '--browse'): - browse = 1 - - if args: - peptxt = [] - html = [] - for pep in args: - file = find_pep(pep) - peptxt.append(file) - newfile = make_html(file, verbose=verbose) - if newfile: - html.append(newfile) - if browse and not update: - browse_file(pep) - else: - # do them all - peptxt = [] - html = [] - files = glob.glob("pep-*.txt") - files.sort() - for file in files: - peptxt.append(file) - newfile = make_html(file, verbose=verbose) - if newfile: - html.append(newfile) - if browse and not update: - browse_file("0") - - if update: - push_pep(html, peptxt, username, verbose, local=local) - if browse: - if args: - for pep in args: - browse_remote(pep) - else: - browse_remote("0") - - - -if __name__ == "__main__": - main() diff --git a/docutils/tools/publish.py b/docutils/tools/publish.py deleted file mode 100755 index d360cd124..000000000 --- a/docutils/tools/publish.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. -""" - -import locale -try: - 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/quicktest.py b/docutils/tools/quicktest.py deleted file mode 100755 index 04e3209fa..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. - -import locale -try: - 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 == '--attributes': - 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/rst2latex.py b/docutils/tools/rst2latex.py deleted file mode 100755 index 3b7fdae82..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. -""" - -import locale -try: - 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/stylesheets/default.css b/docutils/tools/stylesheets/default.css deleted file mode 100644 index 5b2e1be96..000000000 --- a/docutils/tools/stylesheets/default.css +++ /dev/null @@ -1,224 +0,0 @@ -/* -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:date: $Date$ -:version: $Revision$ -:copyright: This stylesheet has been placed in the public domain. - -Default cascading style sheet for the HTML output of Docutils. -*/ - -.first { - margin-top: 0 } - -.last { - margin-bottom: 0 } - -a.toc-backref { - text-decoration: none ; - color: black } - -dd { - margin-bottom: 0.5em } - -div.abstract { - margin: 2em 5em } - -div.abstract p.topic-title { - font-weight: bold ; - text-align: center } - -div.attention, div.caution, div.danger, div.error, div.hint, -div.important, div.note, div.tip, div.warning, div.admonition { - margin: 2em ; - border: medium outset ; - padding: 1em } - -div.attention p.admonition-title, div.caution p.admonition-title, -div.danger p.admonition-title, div.error p.admonition-title, -div.warning p.admonition-title { - color: red ; - font-weight: bold ; - font-family: sans-serif } - -div.hint p.admonition-title, div.important p.admonition-title, -div.note p.admonition-title, div.tip p.admonition-title, -div.admonition p.admonition-title { - font-weight: bold ; - font-family: sans-serif } - -div.dedication { - margin: 2em 5em ; - text-align: center ; - font-style: italic } - -div.dedication p.topic-title { - font-weight: bold ; - font-style: normal } - -div.figure { - margin-left: 2em } - -div.footer, div.header { - font-size: smaller } - -div.sidebar { - margin-left: 1em ; - border: medium outset ; - padding: 0em 1em ; - background-color: #ffffee ; - width: 40% ; - float: right ; - clear: right } - -div.sidebar p.rubric { - font-family: sans-serif ; - font-size: medium } - -div.system-messages { - margin: 5em } - -div.system-messages h1 { - color: red } - -div.system-message { - border: medium outset ; - padding: 1em } - -div.system-message p.system-message-title { - color: red ; - font-weight: bold } - -div.topic { - margin: 2em } - -h1.title { - text-align: center } - -h2.subtitle { - text-align: center } - -hr { - width: 75% } - -ol.simple, ul.simple { - margin-bottom: 1em } - -ol.arabic { - list-style: decimal } - -ol.loweralpha { - list-style: lower-alpha } - -ol.upperalpha { - list-style: upper-alpha } - -ol.lowerroman { - list-style: lower-roman } - -ol.upperroman { - list-style: upper-roman } - -p.attribution { - text-align: right ; - margin-left: 50% } - -p.caption { - font-style: italic } - -p.credits { - font-style: italic ; - font-size: smaller } - -p.label { - white-space: nowrap } - -p.rubric { - font-weight: bold ; - font-size: larger ; - color: darkred ; - text-align: center } - -p.sidebar-title { - font-family: sans-serif ; - font-weight: bold ; - font-size: larger } - -p.sidebar-subtitle { - font-family: sans-serif ; - font-weight: bold } - -p.topic-title { - font-weight: bold } - -pre.address { - margin-bottom: 0 ; - margin-top: 0 ; - font-family: serif ; - font-size: 100% } - -pre.line-block { - font-family: serif ; - font-size: 100% } - -pre.literal-block, pre.doctest-block { - margin-left: 2em ; - margin-right: 2em ; - background-color: #eeeeee } - -span.classifier { - font-family: sans-serif ; - font-style: oblique } - -span.classifier-delimiter { - font-family: sans-serif ; - font-weight: bold } - -span.interpreted { - font-family: sans-serif } - -span.option { - white-space: nowrap } - -span.option-argument { - font-style: italic } - -span.pre { - white-space: pre } - -span.problematic { - color: red } - -table { - margin-top: 0.5em ; - margin-bottom: 0.5em } - -table.citation { - border-left: solid thin gray ; - padding-left: 0.5ex } - -table.docinfo { - margin: 2em 4em } - -table.footnote { - border-left: solid thin black ; - padding-left: 0.5ex } - -td, th { - padding-left: 0.5em ; - padding-right: 0.5em ; - vertical-align: top } - -th.docinfo-name, th.field-name { - font-weight: bold ; - text-align: left ; - white-space: nowrap } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - font-size: 100% } - -tt { - background-color: #eeeeee } - -ul.auto-toc { - list-style-type: none } diff --git a/docutils/tools/stylesheets/pep.css b/docutils/tools/stylesheets/pep.css deleted file mode 100644 index a82045bc9..000000000 --- a/docutils/tools/stylesheets/pep.css +++ /dev/null @@ -1,240 +0,0 @@ -/* -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:date: $Date$ -:version: $Revision$ -:copyright: This stylesheet has been placed in the public domain. - -Default cascading style sheet for the PEP HTML output of Docutils. -*/ - -.first { - margin-top: 0 } - -.last { - margin-bottom: 0 } - -.navigation { - width: 100% ; - background: #99ccff ; - margin-top: 0px ; - margin-bottom: 0px } - -.navigation .navicon { - width: 150px ; - height: 35px } - -.navigation .textlinks { - padding-left: 1em ; - text-align: left } - -.navigation td, .navigation th { - padding-left: 0em ; - padding-right: 0em ; - vertical-align: middle } - -.rfc2822 { - margin-top: 0.5em ; - margin-left: 0.5em ; - margin-right: 0.5em ; - margin-bottom: 0em } - -.rfc2822 td { - text-align: left } - -.rfc2822 th.field-name { - text-align: right ; - font-family: sans-serif ; - padding-right: 0.5em ; - font-weight: bold ; - margin-bottom: 0em } - -a.toc-backref { - text-decoration: none ; - color: black } - -body { - margin: 0px ; - margin-bottom: 1em ; - padding: 0px } - -dd { - margin-bottom: 0.5em } - -div.section { - margin-left: 1em ; - margin-right: 1em ; - margin-bottom: 1.5em } - -div.section div.section { - margin-left: 0em ; - margin-right: 0em ; - margin-top: 1.5em } - -div.abstract { - margin: 2em 5em } - -div.abstract p.topic-title { - font-weight: bold ; - text-align: center } - -div.attention, div.caution, div.danger, div.error, div.hint, -div.important, div.note, div.tip, div.warning { - margin: 2em ; - border: medium outset ; - padding: 1em } - -div.attention p.admonition-title, div.caution p.admonition-title, -div.danger p.admonition-title, div.error p.admonition-title, -div.warning p.admonition-title { - color: red ; - font-weight: bold ; - font-family: sans-serif } - -div.hint p.admonition-title, div.important p.admonition-title, -div.note p.admonition-title, div.tip p.admonition-title { - font-weight: bold ; - font-family: sans-serif } - -div.figure { - margin-left: 2em } - -div.footer, div.header { - font-size: smaller } - -div.footer { - margin-left: 1em ; - margin-right: 1em } - -div.system-messages { - margin: 5em } - -div.system-messages h1 { - color: red } - -div.system-message { - border: medium outset ; - padding: 1em } - -div.system-message p.system-message-title { - color: red ; - font-weight: bold } - -div.topic { - margin: 2em } - -h1 { - font-family: sans-serif ; - font-size: large } - -h2 { - font-family: sans-serif ; - font-size: medium } - -h3 { - font-family: sans-serif ; - font-size: small } - -h4 { - font-family: sans-serif ; - font-style: italic ; - font-size: small } - -h5 { - font-family: sans-serif; - font-size: x-small } - -h6 { - font-family: sans-serif; - font-style: italic ; - font-size: x-small } - -.section hr { - width: 75% } - -ol.simple, ul.simple { - margin-bottom: 1em } - -ol.arabic { - list-style: decimal } - -ol.loweralpha { - list-style: lower-alpha } - -ol.upperalpha { - list-style: upper-alpha } - -ol.lowerroman { - list-style: lower-roman } - -ol.upperroman { - list-style: upper-roman } - -p.caption { - font-style: italic } - -p.credits { - font-style: italic ; - font-size: smaller } - -p.label { - white-space: nowrap } - -p.topic-title { - font-family: sans-serif ; - font-weight: bold } - -pre.line-block { - font-family: serif ; - font-size: 100% } - -pre.literal-block, pre.doctest-block { - margin-left: 2em ; - margin-right: 2em ; - background-color: #eeeeee } - -span.classifier { - font-family: sans-serif ; - font-style: oblique } - -span.classifier-delimiter { - font-family: sans-serif ; - font-weight: bold } - -span.interpreted { - font-family: sans-serif } - -span.option-argument { - font-style: italic } - -span.pre { - white-space: pre } - -span.problematic { - color: red } - -table { - margin-top: 0.5em ; - margin-bottom: 0.5em } - -td, th { - padding-left: 0.5em ; - padding-right: 0.5em ; - vertical-align: top } - -td.num { - text-align: right } - -th.field-name { - font-weight: bold ; - text-align: left ; - white-space: nowrap } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - font-size: 100% } - -tt { - background-color: #eeeeee } - -ul.auto-toc { - list-style-type: none } diff --git a/docutils/tools/unicode2rstsubs.py b/docutils/tools/unicode2rstsubs.py deleted file mode 100755 index d5e259863..000000000 --- a/docutils/tools/unicode2rstsubs.py +++ /dev/null @@ -1,195 +0,0 @@ -#! /usr/bin/env python - -# Author: David Goodger -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This program has been placed in the public domain. - -""" -unicode2subfiles.py -- produce character entity files (reSructuredText -substitutions) from the MathML 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 at -<http://www.w3.org/Math/characters/unicode.xml> (as of 2003-06-22). -""" - -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'] - - 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 - 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()) |
