Author: jpages Date: 2012-06-13 17:51:18 +0200 (Wed, 13 Jun 2012) New Revision: 717 Url: http://nuiton.org/repositories/revision/jrst/717 Log: Suppression des fichiers inutiles de DocUtils Correction du pom de jrst (supression de la version de guana) Removed: trunk/docutils/src/main/resources/docutils/BUGS.txt trunk/docutils/src/main/resources/docutils/COPYING.txt trunk/docutils/src/main/resources/docutils/FAQ.txt trunk/docutils/src/main/resources/docutils/HISTORY.txt trunk/docutils/src/main/resources/docutils/MANIFEST.in trunk/docutils/src/main/resources/docutils/PKG-INFO trunk/docutils/src/main/resources/docutils/README.txt trunk/docutils/src/main/resources/docutils/RELEASE-NOTES.txt trunk/docutils/src/main/resources/docutils/THANKS.txt trunk/docutils/src/main/resources/docutils/build/ trunk/docutils/src/main/resources/docutils/docs/ trunk/docutils/src/main/resources/docutils/extras/ trunk/docutils/src/main/resources/docutils/install.py trunk/docutils/src/main/resources/docutils/licenses/ trunk/docutils/src/main/resources/docutils/roman.py trunk/docutils/src/main/resources/docutils/setup.cfg trunk/docutils/src/main/resources/docutils/setup.py trunk/docutils/src/main/resources/docutils/test/ trunk/docutils/src/main/resources/docutils/tools/ Modified: trunk/docutils/src/main/resources/docutils/__run__.py trunk/docutils/src/main/resources/docutils/docutils/__init__$py.class trunk/docutils/src/main/resources/docutils/docutils/core$py.class trunk/jrst/pom.xml trunk/jrst/src/main/java/org/nuiton/jrst/JRST.java trunk/jrst/src/test/java/org/nuiton/jrst/JRSTTest.java Deleted: trunk/docutils/src/main/resources/docutils/BUGS.txt =================================================================== --- trunk/docutils/src/main/resources/docutils/BUGS.txt 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/BUGS.txt 2012-06-13 15:51:18 UTC (rev 717) @@ -1,286 +0,0 @@ -================ - Docutils_ Bugs -================ - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date: 2012-01-04 15:20:52 +0100 (Mit, 04 Jän 2012) $ -:Revision: $Revision: 7304 $ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - - -Bugs in Docutils?!? Yes, we do have a few. Some are old-timers that -tend to stay in the shadows and don't bother anybody. Once in a while -new bugs are born. From time to time some bugs (new and old) crawl -out into the light and must be dealt with. Icky. - -This document describes how to report a bug, and lists known bugs. - -.. contents:: - - -How To Report A Bug -=================== - -If you think you've discovered a bug, please read through these -guidelines before reporting it. - -First, make sure it's a new bug: - -* Please check the list of `known bugs`_ below and the `SourceForge - Bug Tracker`_ to see if it has already been reported. - -* Are you using the very latest version of Docutils? The bug may have - already been fixed. Please get the latest version of Docutils from - the repository_ or from the current snapshot_ and check again. Even - if your bug has not been fixed, others probably have, and you're - better off with the most up-to-date code. - - If you don't have time to check the latest snapshot, please report - the bug anyway. We'd rather tell you that it's already fixed than - miss reports of unfixed bugs. - -* If Docutils does not behave the way you expect, look in the - documentation_ (don't forget the FAQ_!) and `mailing list archives`_ - for evidence that it should behave the way you expect. - -If you're not sure, please ask on the Docutils-users_ mailing list -first. - ---------------------------------------------------------------------- - -If it's a new bug, the most important thing you can do is to write a -simple description and a recipe that reproduces the bug. Try to -create a `minimal example`_ that demonstrates the bug. The easier you -make it to understand and track down the bug, the more likely a fix -will be. - -.. sidebar:: minimal example - - .. _minimal example: - - A minimal example is an example which is as small as possible. These - examples are much easier to understand than long examples. - - To construct an example which is as small as possible, the rule is - quite simple: *remove anything which is not necessary*. - - See also: `LaTeX FAQ`__, `Lilypond Documentation`__, minimalbeispiel.de__ - - __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl - __ http://lilypond.org/doc/v2.9/Documentation/user/lilypond/Minimal-examples - __ http://www.minimalbeispiel.de/mini-en.html - -Now you're ready to write the bug report. Please include: - -* A clear description of the bug. Describe how you expected Docutils - to behave, and contrast that with how it actually behaved. While - the bug may seem obvious to you, it may not be so obvious to someone - else, so it's best to avoid a guessing game. - -* A complete description of the environment in which you reproduced - the bug: - - - Your operating system & version. - - The version of Python (``python -V``). - - The version of Docutils (use the "-V" option to most Docutils - front-end tools). - - Any private modifications you made to Docutils. - - Anything else that could possibly be relevant. Err on the side - of too much information, rather than too little. - -* A literal transcript of the *exact* command you ran, and the *exact* - output. Use the "--traceback" option to get a complete picture. - -* The exact input and output files. Create a `minimal example`_ - of the failing behaviour — it is better to attach complete files - to your bug report than to include just a summary or excerpt. - -* If you also want to include speculation as to the cause, and even a - patch to fix the bug, that would be great! - -The best place to send your bug report is to the `SourceForge Bug -Tracker`_. That way, it won't be misplaced or forgotten. In fact, an -open bug report on SourceForge is a constant irritant that begs to be -squashed. - -Thank you! - -(This section was inspired by the `Subversion project's`__ BUGS__ -file.) - -__ http://subversion.tigris.org/ -__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup - -.. _repository: docs/dev/repository.html -.. _snapshot: http://docutils.sourceforge.net/#download -.. _documentation: docs/ -.. _FAQ: FAQ.html -.. _mailing list archives: http://docutils.sf.net/#mailing-lists -.. _Docutils-users: docs/user/mailing-lists.html#docutils-users -.. _SourceForge Bug Tracker: - http://sourceforge.net/tracker/?group_id=38414&atid=422030 - - -Known Bugs -========== - -Also see the `SourceForge Bug Tracker`_. - -* .. _error reporting: - - Calling rst2s5.py with a non-existent theme (``--theme - does_not_exist``) - causes exceptions. Such errors should be handled more gracefully. - -* The "stylesheet" setting (a URL, to be used verbatim) should be - allowed to be combined with "embed_stylesheet". The stylesheet data - should be read in using urllib. There was an assumption that a - stylesheet to be embedded should exist as a file on the local - system, and only the "stylesheet_path" setting should be used. - -* ``utils.relative_path()`` sometimes returns absolute _`paths on - Windows` (like ``C:/test/foo.css``) where it could have chosen a - relative path. - - Furthermore, absolute pathnames are inserted verbatim, like - ``href="C:/test/foo.css"`` instead of - ``href="file:///C:/test/foo.css"``. - - For details, see `this posting by Alan G. Isaac - <http://article.gmane.org/gmane.text.docutils.user/1569>`_. - -* Footnote label "5" should be "4" when processing the following - input:: - - ref [#abc]_ [#]_ [1]_ [#4]_ - - .. [#abc] footnote - .. [#] two - .. [1] one - .. [#4] four - - Output:: - - <document source="<stdin>"> - <paragraph> - ref - <footnote_reference auto="1" ids="id1" refid="abc"> - 2 - - <footnote_reference auto="1" ids="id2" refid="id5"> - 3 - - <footnote_reference ids="id3" refid="id6"> - 1 - - <footnote_reference auto="1" ids="id4" refid="id7"> - 5 - <footnote auto="1" backrefs="id1" ids="abc" names="abc"> - <label> - 2 - <paragraph> - footnote - <footnote auto="1" backrefs="id2" ids="id5" names="3"> - <label> - 3 - <paragraph> - two - <footnote backrefs="id3" ids="id6" names="1"> - <label> - 1 - <paragraph> - one - <footnote auto="1" backrefs="id4" ids="id7" names="4"> - <label> - 5 - <paragraph> - four - -* IDs are based on names. Explicit hyperlink targets have priority - over implicit targets. But if an explicit target comes after an - implicit target with the same name, the ID of the first (implicit) - target remains based on the implicit name. Since HTML fragment - identifiers based on the IDs, the first target keeps the name. For - example:: - - .. contents:: - - Section - ======= - - .. _contents: - - Subsection - ---------- - - text with a reference to contents_ and section_ - - .. _section: - - This paragraph is explicitly targeted with the name "section". - - When processed to HTML, the 2 internal hyperlinks (to "contents" & - "section") will work fine, but hyperlinks from outside the document - using ``href="...#contents"`` and ``href="...#section"`` won't work. - Such external links will connect to the implicit targets (table of - contents and "Section" title) instead of the explicit targets - ("Subsection" title and last paragraph). - - Hyperlink targets with duplicate names should be assigned new IDs - unrelated to the target names (i.e., "id"-prefix serial IDs). - -* The "contents" ID of the local table of contents in - ``test/functional/expected/standalone_rst_pseudoxml.txt`` is lost in - the HTML output at - ``test/functional/expected/standalone_rst_html4css1.html``. - -* _`Blank first columns` in simple tables with explicit row separators - silently swallow their input. They should at least produce system - error messages. But, with explicit row separators, the meaning is - unambiguous and ought to be supported:: - - ============== ========== - Table with row separators - ============== ========== - and blank - -------------- ---------- - entries - -------------- ---------- - in first - -------------- ---------- - columns. - ============== ========== - - Added a commented-out test case to - test/test_parsers/test_rst/test_SimpleTableParser.py. - -* _`Footnote references with hyperlink targets` cause a possibly - invalid node tree and make the HTML writer crash:: - - $ rst2pseudoxml.py - [1]_ - - .. _1: URI - <document source="<stdin>"> - <paragraph> - <footnote_reference ids="id1" refuri="URI"> - 1 - <target ids="id2" names="1" refuri="URI"> - -* Anonymous references have "name" attributes. Should they? Are they - used? See ``test/test_parsers/test_rst/test_inline_markup.py``. - -* <reference> elements have a "name" attribute, not "names". The - attribute should be "names"; this is an inconsistency. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: Deleted: trunk/docutils/src/main/resources/docutils/COPYING.txt =================================================================== --- trunk/docutils/src/main/resources/docutils/COPYING.txt 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/COPYING.txt 2012-06-13 15:51:18 UTC (rev 717) @@ -1,125 +0,0 @@ -================== - Copying Docutils -================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date: 2011-12-31 15:22:16 +0100 (Sam, 31 Dez 2011) $ -: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. -Files in the Sandbox_ are not distributed with Docutils releases and -may have different license terms. - - -Public Domain Dedication -======================== - -The persons who have associated their work with this project (the -"Dedicator": David Goodger and the many contributors to the Docutils -project) hereby dedicate the entire copyright, less the exceptions_ -listed below, in the work of authorship known as "Docutils" identified -below (the "Work") to the public domain. - -The primary repository for the Work is the Internet World Wide Web -site <http://docutils.sourceforge.net/>. The Work consists of the -files within the "docutils" module of the Docutils project Subversion -repository (Internet host docutils.svn.sourceforge.net, filesystem path -/svnroot/docutils), whose Internet web interface is located at -<http://docutils.svn.sourceforge.net/viewvc/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>`_. [#]_) - -.. [#] Creative Commons has `retired this legal tool`__ and does not - recommend that it be applied to works: This tool is based on United - States law and may not be applicable outside the US. For dedicating - new works to the public domain, Creative Commons recommend CC0_. So - does the Free Software Foundation in its license-list_. - - __ http://creativecommons.org/retiredlicenses - .. _CC0: http://creativecommons.org/publicdomain/zero/1.0/legalcode - -Exceptions -========== - -The exceptions to the `Public Domain Dedication`_ above are: - -* docutils/writers/s5_html/themes/default/iepngfix.htc: - - IE5.5+ PNG Alpha Fix v1.0 by Angus Turnbull - <http://www.twinhelix.com>. Free usage permitted as long as - this notice remains intact. - -* docutils/math/__init__.py, - docutils/math/latex2mathml.py, - docutils/writers/xetex/__init__.py, - docutils/writers/latex2e/docutils-05-compat.sty, - docs/user/docutils-05-compat.sty.txt, - docutils/error_reporting.py: - - Copyright © Günter Milde. - Released under the terms of the `2-Clause BSD license`_ - (`local copy <licenses/BSD-2-Clause.txt>`__). - -* docutils/math/math2html.py, - docutils/writers/html4css1/math.css - - Copyright © Alex Fernández - These files are part of eLyXer_, released under the `GNU - General Public License`_ version 3 or later. The author relicensed - them for Docutils under the terms of the `2-Clause BSD license`_ - (`local copy <licenses/BSD-2-Clause.txt>`__). - - .. _eLyXer: http://www.nongnu.org/elyxer/ - -* extras/roman.py, copyright by Mark Pilgrim, released under the - `Python 2.1.1 license`_ (`local copy`__). - - __ licenses/python-2-1-1.txt - -* tools/editors/emacs/rst.el, copyright by Free Software Foundation, - Inc., released under the `GNU General Public License`_ version 3 or - later (`local copy`__). - - __ licenses/gpl-3-0.txt - -The `2-Clause BSD license`_ and the Python licenses are OSI-approved_ -and GPL-compatible_. - -Plaintext versions of all the linked-to licenses are provided in the -licenses_ directory. - -.. _sandbox: http://docutils.sourceforge.net/sandbox/README.html -.. _licenses: licenses/ -.. _Python 2.1.1 license: http://www.python.org/2.1.1/license.html -.. _GNU General Public License: http://www.gnu.org/copyleft/gpl.html -.. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause -.. _OSI-approved: http://opensource.org/licenses/ -.. _license-list: -.. _GPL-compatible: http://www.gnu.org/licenses/license-list.html Deleted: trunk/docutils/src/main/resources/docutils/FAQ.txt =================================================================== --- trunk/docutils/src/main/resources/docutils/FAQ.txt 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/FAQ.txt 2012-06-13 15:51:18 UTC (rev 717) @@ -1,1296 +0,0 @@ -.. -*- coding: utf-8 -*- - - -.. NOTE TO MAINTAINERS: Please add new questions to the end of their - sections, so section/question numbers remain stable. - - -=========================================== - Docutils FAQ (Frequently Asked Questions) -=========================================== - -:Date: $Date: 2012-02-16 18:15:55 +0100 (Don, 16 Feb 2012) $ -:Revision: $Revision: 7361 $ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. contents:: -.. sectnum:: - - -This is a work in progress. If you are reading a local copy, the -`master copy`_ might be newer. This document uses are relative links; -if they don't work, please use the `master copy`_. - -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. - -.. _master copy: http://docutils.sourceforge.net/FAQ.html -.. _let us know: -.. _Docutils-users: docs/user/mailing-lists.html#docutils-users - - - -Docutils -======== - -What is Docutils? ------------------ - -Docutils_ is a system for processing plaintext documentation into -useful formats, such as HTML, XML, and LaTeX. It supports multiple -types of input, such as standalone files (implemented), inline -documentation from Python modules and packages (under development), -`PEPs (Python Enhancement Proposals)`_ (implemented), and others as -discovered. - -The Docutils distribution consists of: - -* a library (the "docutils" package), which `can be used by client - code`_; -* several `front-end tools`_ (such as ``rst2html.py``, which converts - reStructuredText input into HTML output); -* a `test suite`_; and -* extensive documentation_. - -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 -.. _can be used by client code: docs/api/publisher.html -.. _front-end tools: docs/user/tools.html -.. _test suite: docs/dev/testing.html -.. _documentation: docs/index.html -.. _PEP 258: http://www.python.org/peps/pep-0258.html -.. _Python: http://www.python.org/ - - -Why is it called "Docutils"? ----------------------------- - -Docutils is short for "Python Documentation Utilities". The name -"Docutils" was inspired by "Distutils", the Python Distribution -Utilities architected by Greg Ward, a component of Python's standard -library. - -The earliest known use of the term "docutils" in a Python context was -a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in -the Python Doc-SIG mailing list. It was suggested `as a project -name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to -a question from Tony "Tibs" Ibbs: "What do we want to *call* this -thing?". This was shortly after David Goodger first `announced -reStructuredText`__ on Doc-SIG. - -Tibs used the name "Docutils" for `his effort`__ "to document what the -Python docutils package should support, with a particular emphasis on -documentation strings". Tibs joined the current project (and its -predecessors) and graciously donated the name. - -For more history of reStructuredText and the Docutils project, see `An -Introduction to reStructuredText`_. - -Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils" -or any other variation. It is pronounced as in "DOCumentation -UTILitieS", with emphasis on the first syllable. - -.. _An Introduction to reStructuredText: docs/ref/rst/introduction.html -__ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html -__ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html - - -Is there a GUI authoring environment for Docutils? --------------------------------------------------- - -DocFactory_ is under development. It uses wxPython and looks very -promising. - -.. _DocFactory: - http://docutils.sf.net/sandbox/gschwant/docfactory/doc/ - - -What is the status of the Docutils project? -------------------------------------------- - -Although useful and relatively stable, Docutils is experimental code, -with APIs and architecture subject to change. - -Our highest priority is to fix bugs as they are reported. So the -latest code from the repository_ (or the snapshots_) is almost always -the most stable (bug-free) as well as the most featureful. - - -What is the Docutils project release policy? --------------------------------------------- - -It's "release early & often". We also have automatically-generated -snapshots_ which always contain the latest code from the repository_. -As the project matures, we may formalize on a -stable/development-branch scheme, but we're not using anything like -that yet. - -.. _repository: docs/dev/repository.html -.. _snapshots: http://docutils.sourceforge.net/#download - - -reStructuredText -================ - -What is reStructuredText? -------------------------- - -reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get -plaintext markup syntax and parser system. The reStructuredText -parser is a component of Docutils_. reStructuredText is a revision -and reinterpretation of the StructuredText_ and Setext_ lightweight -markup systems. - -If you are reading this on the web, you can see for yourself. `The -source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open -it in another window and compare them side by side. - -`A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user -reference are a good place to start. The `reStructuredText Markup -Specification`_ is a detailed technical specification. - -.. _A ReStructuredText Primer: docs/user/rst/quickstart.html -.. _Quick reStructuredText: docs/user/rst/quickref.html -.. _reStructuredText Markup Specification: - docs/ref/rst/restructuredtext.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/ -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html - - -Why is it called "reStructuredText"? ------------------------------------- - -The name came from a combination of "StructuredText", one of -reStructuredText's predecessors, with "re": "revised", "reworked", and -"reinterpreted", and as in the ``re.py`` regular expression module. -For a detailed history of reStructuredText and the Docutils project, -see `An Introduction to reStructuredText`_. - - -What's the standard abbreviation for "reStructuredText"? --------------------------------------------------------- - -"RST" and "ReST" (or "reST") are both acceptable. Care should be -taken with capitalization, to avoid confusion with "REST__", an -acronym for "Representational State Transfer". - -The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used; -they overemphasize reStructuredText's precedessor, Zope's -StructuredText. - -__ http://en.wikipedia.org/wiki/Representational_State_Transfer - - -What's the standard filename extension for a reStructuredText file? -------------------------------------------------------------------- - -It's ".txt". Some people would like to use ".rest" or ".rst" or -".restx", but why bother? ReStructuredText source files are meant to -be readable as plaintext, and most operating systems already associate -".txt" with text files. Using a specialized filename extension would -require that users alter their OS settings, which is something that -many users will not be willing or able to do. - -Also see `What's the official MIME type for reStructuredText data?`_ - - -Are there any reStructuredText editor extensions? -------------------------------------------------- - -See `Editor Support for reStructuredText`__. - -__ tools/editors/README.html - - -How can I indicate the document title? Subtitle? -------------------------------------------------- - -A uniquely-adorned section title at the beginning of a document is -treated specially, as the document title. Similarly, a -uniquely-adorned section title immediately after the document title -becomes the document subtitle. For example:: - - This is the Document Title - ========================== - - This is the Document Subtitle - ----------------------------- - - Here's an ordinary paragraph. - -Counterexample:: - - Here's an ordinary paragraph. - - This is *not* a Document Title - ============================== - - The "ordinary paragraph" above the section title - prevents it from becoming the document title. - -Another counterexample:: - - This is not the Document Title, because... - =========================================== - - Here's an ordinary paragraph. - - ... the title adornment is not unique - ===================================== - - Another ordinary paragraph. - - -How can I represent esoteric characters (e.g. character entities) in a document? --------------------------------------------------------------------------------- - -For example, say you want an em-dash (XML character entity —, -Unicode character U+2014) in your document: use a real em-dash. -Insert concrete characters (e.g. type a *real* em-dash) into your -input file, using whatever encoding suits your application, and tell -Docutils the input encoding. Docutils uses Unicode internally, so the -em-dash character is a real em-dash internally. - -Emacs users should refer to the `Emacs Support for reStructuredText`__ -document. Tips for other editors are welcome. - -__ tools/editors/emacs/README.html - -ReStructuredText has no character entity subsystem; it doesn't know -anything about XML charents. To Docutils, "—" in input text is -7 discrete characters; no interpretation happens. When writing HTML, -the "&" is converted to "&", so in the raw output you'd see -"—". There's no difference in interpretation for text -inside or outside inline literals or literal blocks -- there's no -character entity interpretation in either case. - -If you can't use a Unicode-compatible encoding and must rely on 7-bit -ASCII, there is a workaround. New in Docutils 0.3.10 is a set of -`Standard Substitution Definition Sets`_, which provide equivalents of -XML & HTML character entity sets as substitution definitions. For -example, the Japanese yen currency symbol can be used as follows:: - - .. include:: <xhtml1-lat1.txt> - - |yen| 600 for a complete meal? That's cheap! - -For earlier versions of Docutils, equivalent files containing -character entity set substitution definitions using the "unicode_" -directive `are available`_. Please read the `description and -instructions`_ for use. Thanks to David Priest for the original idea. - -If you insist on using XML-style charents, you'll have to implement a -pre-processing system to convert to UTF-8 or something. That -introduces complications though; you can no longer *write* about -charents naturally; instead of writing "—" you'd have to write -"—". - -For the common case of long dashes, you might also want to insert the -following substitution definitons into your document (both of them are -using the "unicode_" directive):: - - .. |--| unicode:: U+2013 .. en dash - .. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace - :trim: - -.. |--| unicode:: U+2013 .. en dash -.. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace - :trim: - -Now you can write dashes using pure ASCII: "``foo |--| bar; foo |---| -bar``", rendered as "foo |--| bar; foo |---| bar". (Note that Mozilla -and Firefox may render this incorrectly.) The ``:trim:`` option for -the em dash is necessary because you cannot write "``foo|---|bar``"; -thus you need to add spaces ("``foo |---| bar``") and advise the -reStructuredText parser to trim the spaces. - -.. _Standard Substitution Definition Sets: docs/ref/rst/substitutions.html -.. _unicode: docs/ref/rst/directives.html#unicode-character-codes -.. _are available: http://docutils.sourceforge.net/tmp/charents/ -.. _tarball: http://docutils.sourceforge.net/tmp/charents.tgz -.. _description and instructions: - http://docutils.sourceforge.net/tmp/charents/README.html -.. _to-do list: docs/dev/todo.html - - -How can I generate backticks using a Scandinavian keyboard? ------------------------------------------------------------ - -The use of backticks in reStructuredText is a bit awkward with -Scandinavian keyboards, where the backtick is a "dead" key. To get -one ` character one must press SHIFT-` + SPACE. - -Unfortunately, with all the variations out there, there's no way to -please everyone. For Scandinavian programmers and technical writers, -this is not limited to reStructuredText but affects many languages and -environments. - -Possible solutions include - -* If you have to input a lot of backticks, simply type one in the - normal/awkward way, select it, copy and then paste the rest (CTRL-V - is a lot faster than SHIFT-` + SPACE). - -* Use keyboard macros. - -* Remap the keyboard. The Scandinavian keyboard layout is awkward for - other programming/technical characters too; for example, []{} - etc. are a bit awkward compared to US keyboards. - - According to Axel Kollmorgen, - - Under Windows, you can use the `Microsoft Keyboard Layout Creator - <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily - map the backtick key to a real backtick (no dead key). took me - five minutes to load my default (german) keyboard layout, untick - "Dead Key?" from the backtick key properties ("in all shift - states"), "build dll and setup package", install the generated - .msi, and add my custom keyboard layout via Control Panel > - Regional and Language Options > Languages > Details > Add - Keyboard layout (and setting it as default "when you start your - computer"). - -* Use a virtual/screen keyboard or character palette, such as: - - - `Web-based keyboards <http://keyboard.lab.co.il/>`__ (IE only - unfortunately). - - Windows: `Click-N-Type <http://www.lakefolks.org/cnt/>`__. - - Mac OS X: the Character Palette can store a set of favorite - characters for easy input. Open System Preferences, - International, Input Menu tab, enable "Show input menu in menu - bar", and be sure that Character Palette is enabled in the list. - -If anyone knows of other/better solutions, please `let us know`_. - - -Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping) ------------------------------------------------------------------------ - -People have tossed the idea around, and some implementations of -reStructuredText-generating tools can be found in the `Docutils Link -List`_. - -There's no reason why reStructuredText should not be round-trippable -to/from XML; any technicalities which prevent round-tripping would be -considered bugs. Whitespace would not be identical, but paragraphs -shouldn't suffer. The tricky parts would be the smaller details, like -links and IDs and other bookkeeping. - -For HTML, true round-tripping may not be possible. Even adding lots -of extra "class" attributes may not be enough. A "simple HTML" to RST -filter is possible -- for some definition of "simple HTML" -- but HTML -is used as dumb formatting so much that such a filter may not be -particularly useful. An 80/20 approach should work though: build a -tool that does 80% of the work automatically, leaving the other 20% -for manual tweaks. - -.. _Docutils Link List: docs/user/links.html - - -Are there any Wikis that use reStructuredText syntax? ------------------------------------------------------ - -There are several, with various degrees of completeness. With no -implied endorsement or recommendation, and in no particular order: - -* `Webware for Python wiki - <http://wiki.webwareforpython.org/thiswiki.html>`__ - -* `Ian Bicking's experimental code - <http://docutils.sf.net/sandbox/ianb/wiki/Wiki.py>`__ - -* `MoinMoin <http://moinmoin.wikiwikiweb.de/>`__ has some support; - `here's a sample <http://moinmoin.wikiwikiweb.de/RestSample>`__ - -* Zope-based `Zwiki <http://zwiki.org/>`__ - -* Zope3-based Zwiki (in the Zope 3 source tree as - ``zope.products.zwiki``) - -* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__ - -* `Trac <http://projects.edgewall.com/trac/>`__ `supports using - reStructuredText - <http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as - an alternative to wiki markup. This includes support for `TracLinks - <http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within - RST text via a custom RST reference-directive or, even easier, an - interpreted text role 'trac' - -Please `let us know`_ of any other reStructuredText Wikis. - -The example application for the `Web Framework Shootout -<http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using -reStructuredText. - - -Are there any Weblog (Blog) projects that use reStructuredText syntax? ----------------------------------------------------------------------- - -With no implied endorsement or recommendation, and in no particular -order: - -* `Firedrop <http://www.voidspace.org.uk/python/firedrop2/>`__ -* `PyBloxsom <http://pyblosxom.sourceforge.net/>`__ -* `Lino WebMan <http://lino.sourceforge.net/webman.html>`__ - -Please `let us know`_ of any other reStructuredText Blogs. - - -.. _Can lists be indented without generating block quotes?: - -How should I mark up lists? ---------------------------- - -Bullet_ & enumerated_ list markup is very intuitive but there are 2 -points that must be noted: - -.. _bullet: docs/ref/rst/restructuredtext.html#bullet-lists -.. _enumerated: docs/ref/rst/restructuredtext.html#enumerated-lists - -1. Lists should **not** be indented. This is correct:: - - paragraph - - * list item 1 - - * nested item 1.1 - * nested item 1.2 - - * list item 2 - - while this is probably incorrect:: - - paragraph - - * list item 1 - - * nested item 1.1 - * nested item 1.2 - - * list item 2 - - The extra indentation (of the list containing items 1.1 and 1.2) is - recognized as a block quote. This is usually not what you mean and - it causes the list in the output to be indented too much. - -2. There **must** be blank lines around list items, except between - items of the same level, where blank lines are optional. The - example above shows this. - -Note that formatting of the *output* is independent of the input, and -is decided by the writer and the stylesheet. For instance, lists -*are* indented in HTML output by default. See `How are lists -formatted in HTML?`_ for details. - - -Could lists be indented without generating block quotes? --------------------------------------------------------- - -Some people like to write lists with indentation but don't intend a -blockquote context. There has been a lot of discussion about allowing -this in reStructuredText, but there are some issues that would need to -be resolved before it could be implemented. There is a summary of the -issues and pointers to the discussions in `the to-do list`__. - -__ docs/dev/todo.html#indented-lists - - -Could the requirement for blank lines around lists be relaxed? --------------------------------------------------------------- - -Short answer: no. - -In reStructuredText, it would be impossible to unambigously mark up -and parse lists without blank lines before and after. Deeply nested -lists may look ugly with so many blank lines, but it's a price we pay -for unambiguous markup. Some other plaintext markup systems do not -require blank lines in nested lists, but they have to compromise -somehow, either accepting ambiguity or requiring extra complexity. -For example, `Epytext <http://epydoc.sf.net/epytext.html#list>`__ does -not require blank lines around lists, but it does require that lists -be indented and that ambiguous cases be escaped. - - -How can I include mathematical equations in documents? ------------------------------------------------------- - -There is no elegant built-in way, yet. There are several ideas, but -no obvious winner. This issue requires a champion to solve the -technical and aesthetic issues and implement a generic solution. -Here's the `to-do list entry`__. - -__ docs/dev/todo.html#math-markup - -There are several quick & dirty ways to include equations in documents. -They all presently use LaTeX syntax or dialects of it. - -* For LaTeX output, nothing beats raw LaTeX math. A simple way is to - use the `raw directive`_:: - - .. raw:: latex - - \[ x^3 + 3x^2a + 3xa^2 + a^3, \] - - For inline math you could use substitutions of the raw directive but - the recently added `raw role`_ is more convenient. You must define a - custom role based on it once in your document:: - - .. role:: raw-latex(raw) - :format: latex - - and then you can just use the new role in your text:: - - the binomial expansion of :raw-latex:`$(x+a)^3$` is - - .. _raw directive: docs/ref/rst/directives.html#raw-data-pass-through - .. _raw role: docs/ref/rst/roles.html#raw - -* Jens Jørgen Mortensen has implemented a "latex-math" role and - directive, available from `his sandbox`__. - - __ http://docutils.sourceforge.net/sandbox/jensj/latex_math/ - -* For HTML the "Right" w3c-standard way to include math is MathML_. - Unfortunately its rendering is still quite broken (or absent) on many - browsers but it's getting better. Another bad problem is that typing - or reading raw MathML by humans is *really* painful, so embedding it - in a reST document with the raw directive would defy the goals of - readability and editability of reST (see an `example of raw MathML - <http://sf.net/mailarchive/message.php?msg_id=2177102>`__). - - A much less painful way to generate HTML+MathML is to use itex2mml_ to - convert a dialect of LaTeX syntax to presentation MathML. Here is an - example of potential `itex math markup - <http://article.gmane.org/gmane.text.docutils.user/118>`__. The - simplest way to use it is to add ``html`` to the format lists for the - raw directive/role and postprocess the resulting document with - itex2mml. This way you can *generate LaTeX and HTML+MathML from the - same source*, but you must limit yourself to the intersection of LaTeX - and itex markups for this to work. Alan G. Isaac wrote a detailed - HOWTO_ for this approach. - - .. _MathML: http://www.w3.org/Math/ - .. _itex2mml: http://pear.math.pitt.edu/mathzilla/itex2mml.html - .. _HOWTO: http://www.american.edu/econ/itex2mml/mathhack.rst - -* The other way to add math to HTML is to use images of the equations, - typically generated by TeX. This is inferior to MathML in the long - term but is perhaps more accessible nowdays. - - Of course, doing it by hand is too much work. Beni Cherniavsky has - written some `preprocessing scripts`__ for converting the - ``texmath`` role/directive into images for HTML output and raw - directives/subsitution for LaTeX output. This way you can *generate - LaTeX and HTML+images from the same source*. `Instructions here`__. - - __ http://docutils.sourceforge.net/sandbox/cben/rolehack/ - __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html - - -Is nested inline markup possible? ---------------------------------- - -Not currently, no. It's on the `to-do list`__ (`details here`__), and -hopefully will be part of the reStructuredText parser soon. At that -time, markup like this will become possible:: - - Here is some *emphasized text containing a `hyperlink`_ and - ``inline literals``*. - -__ docs/dev/todo.html#nested-inline-markup -__ docs/dev/rst/alternatives.html#nested-inline-markup - -There are workarounds, but they are either convoluted or ugly or both. -They are not recommended. - -* Inline markup can be combined with hyperlinks using `substitution - definitions`__ and references__ with the `"replace" directive`__. - For example:: - - Here is an |emphasized hyperlink|_. - - .. |emphasized hyperlink| replace:: *emphasized hyperlink* - .. _emphasized hyperlink: http://example.org - - It is not possible for just a portion of the replacement text to be - a hyperlink; it's the entire replacement text or nothing. - - __ docs/ref/rst/restructuredtext.html#substitution-definitions - __ docs/ref/rst/restructuredtext.html#substitution-references - __ docs/ref/rst/directives.html#replace - -* The `"raw" directive`__ can be used to insert raw HTML into HTML - output:: - - Here is some |stuff|. - - .. |stuff| raw:: html - - <em>emphasized text containing a - <a href="http://example.org">hyperlink</a> and - <tt>inline literals</tt></em> - - Raw LaTeX is supported for LaTeX output, etc. - - __ docs/ref/rst/directives.html#raw - - -How to indicate a line break or a significant newline? ------------------------------------------------------- - -`Line blocks`__ are designed for address blocks, verse, and other -cases where line breaks are significant and must be preserved. Unlike -literal blocks, the typeface is not changed, and inline markup is -recognized. For example:: - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -__ docs/ref/rst/restructuredtext.html#line-blocks - -Here's a workaround for manually inserting explicit line breaks in -HTML output:: - - .. |br| raw:: html - - <br /> - - I want to break this line here: |br| this is after the break. - - If the extra whitespace bothers you, |br|\ backslash-escape it. - - -A URL containing asterisks doesn't work. What to do? ------------------------------------------------------ - -Asterisks are valid URL characters (see :RFC:`2396`), sometimes used -in URLs. For example:: - - http://cvs.example.org/viewcvs.py/*checkout*/module/file - -Unfortunately, the parser thinks the asterisks are indicating -emphasis. The slashes serve as delineating punctuation, allowing the -asterisks to be recognized as markup. The example above is separated -by the parser into a truncated URL, an emphasized word, and some -regular text:: - - http://cvs.example.org/viewcvs.py/ - *checkout* - /module/file - -To turn off markup recognition, use a backslash to escape at least the -first asterisk, like this:: - - http://cvs.example.org/viewcvs.py/\*checkout*/module/file - -Escaping the second asterisk doesn't hurt, but it isn't necessary. - - -How can I make a literal block with *some* formatting? ------------------------------------------------------- - -Use the `parsed-literal`_ directive. - -.. _parsed-literal: docs/ref/rst/directives.html#parsed-literal - -Scenario: a document contains some source code, which calls for a -literal block to preserve linebreaks and whitespace. But part of the -source code should be formatted, for example as emphasis or as a -hyperlink. This calls for a *parsed* literal block:: - - .. parsed-literal:: - - print "Hello world!" # *tricky* code [1]_ - -The emphasis (``*tricky*``) and footnote reference (``[1]_``) will be -parsed. - - -Can reStructuredText be used for web or generic templating? ------------------------------------------------------------ - -Docutils and reStructuredText can be used with or as a component of a -templating system, but they do not themselves include templating -functionality. Templating should simply be left to dedicated -templating systems. Users can choose a templating system to apply to -their reStructuredText documents as best serves their interests. - -There are many good templating systems for Python (ht2html_, YAPTU_, -Quixote_'s PTL, Cheetah_, etc.; see this non-exhaustive list of `some -other templating systems`_), and many more for other languages, each -with different approaches. We invite you to try several and find one -you like. If you adapt it to use Docutils/reStructuredText, please -consider contributing the code to Docutils or `let us know`_ and we'll -keep a list here. - -One reST-specific web templating system is `rest2web -<http://www.voidspace.org.uk/python/rest2web>`_, a tool for -automatically building websites, or parts of websites. - -.. _ht2html: http://ht2html.sourceforge.net/ -.. _YAPTU: - http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305 -.. _Quixote: http://www.mems-exchange.org/software/quixote/ -.. _Cheetah: http://www.cheetahtemplate.org/ -.. _some other templating systems: - http://webware.sourceforge.net/Papers/Templates/ - - -How can I mark up a FAQ or other list of questions & answers? -------------------------------------------------------------- - -There is no specific syntax for FAQs and Q&A lists. Here are two -options: - -1. For a FAQ (Frequently Asked Questions, usually with answers), a - convenient way to mark up the questions is as section titles, with - the answer(s) as section content. This document is marked up in - this way. - - The advantages of using section titles for questions are: sections - can be numbered automatically, and a table of contents can be - generated automatically. One limitation of this format is that - questions must fit on one line (section titles may not wrap, in the - source text). For very long questions, the title may be a summary - of the question, with the full question in the section body. - -2. Field lists work well as Q&A lists:: - - :Q: What kind of questions can we - put here? - - :A: Any kind we like! - - In order to separate questions, lists can be used: - - 1. :Q: What kind of question can we - put here? - :A: Any kind we like! - - 2. :Q: How many answers can a question have? - :A: It can have one, - :A: or more. - :A3: Answers can be numbered like this. - :A: 1. Or like this. - 2. We're flexible! - - If you don't want to number or otherwise mark questions, you can - use an empty comment between individual field lists to separate - them:: - - :Q: First question? - :A: Answer. - - .. - - :Q: Second question? - :A: Answer. - - -.. _bidi: - -Can I produce documents in right-to-left languages? ---------------------------------------------------- - -Languages written from right to left, such as Arabic and Hebrew, must -be reordered according to the `Unicode Bidi Algorithm`_. This -requires support from the editor and special markup in the output -format. - -The source format of reStructuredText is relatively bidi-friendly: -most constructs are denoted by punctuation without intrusion of -English and when you must write in English, it's usually on a separate -line. So any editor that auto-detects direction per-line (like gedit -or geresh_) will suffice. - -Moreover, it's possible to translate_ all reStructuredText keywords. -This was not yet done for any RTL language, but when it is, it will be -possible to write an RTL document with vitually no English. This will -allow reasonable use of editors limited to a single base direction for -the whole document (like Notepad, Vim and text boxes in Firefox). - -.. _Unicode Bidi Algorithm: http://www.unicode.org/reports/tr9/ -.. _geresh: http://www.typo.co.il/~mooffie/geresh/ -.. _translate: docs/howto/i18n.html - -The second problem is bidi markup of the output. There is an almost -transparent implicit solution for HTML: - -* Grab http://cben-hacks.sourceforge.net/bidi/hibidi.py and - http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py. - Put them both in the same directory and make them executable. - -* Use ``rst2html_hibidi.py`` instead of ``rst2html.py``. - -* It infers dir attributes in the HTML from the text. It does it - hierachically, giving much better results than usual. You can still - use LRM/RLM and LRE/RLE/PDF control codes to help it. - - * If you want the gory details: See the full theory_, and note the - incomplete practice_ (this is still a partial implementation - but - sufficient for most needs). - - .. _theory: http://cben-hacks.sf.net/bidi/hibidi.html - .. _practice: http://cben-hacks.sf.net/bidi/hibidi.html#practice - -There is also an explicit way to set directions through CSS and -classes in the HTML: - -* Copy ``default.css`` to a new file and add relevant parts of the - following:: - - /* Use these two if the main document direction is RTL */ - body { direction: rtl; } - div.sidebar { float: left !important; } - - /* The next 3 rules are very useful in documents containing pieces - of code in english */ - /* Use this if you all your literal blocks (::) are LTR */ - pre {direction: ltr; unicode-bidi: embed; } - /* Use this if you all your inline literals (``) are LTR */ - tt {direction: ltr; unicode-bidi: embed; } - /* Use this if you all your interpretted text (`) is LTR */ - cite {direction: ltr; unicode-bidi: embed; } - - /* Allow manual direction override by class directive and roles */ - .rtl { direction: rtl; } - .ltr { direction: ltr; } - -* Select this new stylesheet with ``--stylesheet=<file>`` or the - stylesheet_ setting. - -* Now if you need to override the direction of some element (from a - paragraph to a whole section), write:: - - .. class:: rtl - - or:: - - .. class:: ltr - - before it (see the class_ directive for details). - -* To change the direction of some inline text fragment, you can use - RLE/LRE/PDF control characters, or write ``:rtl:`RTL text``` / - ``:ltr:`RTL text```. To use the latter syntax, you must write this - once at the beginning of your document:: - - .. role:: ltr - .. role:: rtl - -.. _stylesheet: docs/user/config.html#stylesheet -.. _class: docs/ref/rst/directives.txt#class - -LaTeX is quite hard to implement (it doesn't support the bidi -algorithm, so all direction changes - even numbers in RTL text - must -be explicitly marked). Other formats are more-or-less easy. - -If you have any questions/problems/bugs related to bidi with docutils, -ask `Beni Cherniavsky`__ directly or the `Docutils-users`_ mailing -list. - -__ mailto:cben@users.sf.net - - -What's the official MIME type for reStructuredText data? --------------------------------------------------------- - -While there is no registered MIME type for reStructuredText, the -"official unofficial" standard MIME type is "text/x-rst". This was -invented for the build system for PEPs (Python Enhancement Proposals), -and it's used by the python.org web site build system. - -(The "x-" prefix means it's an unregistered MIME type.) - -Also see `What's the standard filename extension for a -reStructuredText file?`_ - - -HTML Writer -=========== - -What is the status of the HTML Writer? --------------------------------------- - -The HTML Writer module, ``docutils/writers/html4css1.py``, is a -proof-of-concept reference implementation. While it is a complete -implementation, some aspects of the HTML it produces may be -incompatible with older browsers or specialized applications (such as -web templating). Alternate implementations are welcome. - - -What kind of HTML does it produce? ----------------------------------- - -It produces XHTML compatible with the `XHTML 1.0`_ specification. A -cascading stylesheet is required for proper viewing with a modern -graphical browser. Correct rendering of the HTML produced depends on -the CSS support of the browser. A general-purpose stylesheet, -``html4css1.css`` is provided with the code, and is embedded by -default. It is installed in the "writers/html4css1/" subdirectory -within the Docutils package. Use the ``--help`` command-line option -to see the specific location on your machine. - -.. _XHTML 1.0: http://www.w3.org/TR/xhtml1/ - - -What browsers are supported? ----------------------------- - -No specific browser is targeted; all modern graphical browsers should -work. Some older browsers, text-only browsers, and browsers without -full CSS support are known to produce inferior results. Firefox, -Safari, Mozilla (version 1.0 and up), and MS Internet Explorer -(version 5.0 and up) are known to give good results. Reports of -experiences with other browsers are welcome. - - -Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why? --------------------------------------------------------------------------- - -Here's the question in full: - - I have this text:: - - Heading 1 - ========= - - All my life, I wanted to be H1. - - Heading 1.1 - ----------- - - But along came H1, and so shouldn't I be H2? - No! I'm H1! - - Heading 1.1.1 - ************* - - Yeah, imagine me, I'm stuck at H3! No?!? - - When I run it through tools/rst2html.py, I get unexpected results - (below). I was expecting H1, H2, then H3; instead, I get H1, H1, - H2:: - - ... - <html lang="en"> - <head> - ... - <title>Heading 1</title> - </head> - <body> - <div class="document" id="heading-1"> - <h1 class="title">Heading 1</h1> <-- first H1 - <p>All my life, I wanted to be H1.</p> - <div class="section" id="heading-1-1"> - <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1 - <p>But along came H1, and so now I must be H2.</p> - <div class="section" id="heading-1-1-1"> - <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2> - <p>Yeah, imagine me, I'm stuck at H3!</p> - ... - - What gives? - -Check the "class" attribute on the H1 tags, and you will see a -difference. The first H1 is actually ``<h1 class="title">``; this is -the document title, and the default stylesheet renders it centered. -There can also be an ``<h2 class="subtitle">`` for the document -subtitle. - -If there's only one highest-level section title at the beginning of a -document, it is treated specially, as the document title. (Similarly, a -lone second-highest-level section title may become the document -subtitle.) See `How can I indicate the document title? Subtitle?`_ for -details. Rather than use a plain H1 for the document title, we use ``<h1 -class="title">`` so that we can use H1 again within the document. Why -do we do this? HTML only has H1-H6, so by making H1 do double duty, we -effectively reserve these tags to provide 6 levels of heading beyond the -single document title. - -HTML is being used for dumb formatting for nothing but final display. -A stylesheet *is required*, and one is provided; see `What kind of -HTML does it produce?`_ above. Of course, you're welcome to roll your -own. The default stylesheet provides rules to format ``<h1 -class="title">`` and ``<h2 class="subtitle">`` differently from -ordinary ``<h1>`` and ``<h2>``:: - - h1.title { - text-align: center } - - h2.subtitle { - text-align: center } - -If you don't want the top section heading to be interpreted as a -title at all, disable the `doctitle_xform`_ setting -(``--no-doc-title`` option). This will interpret your document -differently from the standard settings, which might not be a good -idea. If you don't like the reuse of the H1 in the HTML output, you -can tweak the `initial_header_level`_ setting -(``--initial-header-level`` option) -- but unless you match its value -to your specific document, you might end up with bad HTML (e.g. H3 -without H2). - -.. _doctitle_xform: docs/user/config.html#doctitle-xform -.. _initial_header_level: docs/user/config.html#initial-header-level - -(Thanks to Mark McEahern for the question and much of the answer.) - - -How are lists formatted in HTML? --------------------------------- - -If list formatting looks strange, first check that you understand -`list markup`__. - -__ `How should I mark up lists?`_ - -* By default, HTML browsers indent lists relative to their context. - This follows a long tradition in browsers (but isn't so established - in print). If you don't like it, you should change the stylesheet. - - This is different from how lists look in reStructuredText source. - Extra indentation in the source indicates a blockquote, resulting in - too much indentation in the browser. - -* A list item can contain multiple paragraphs etc. In complex cases - list items are separated by vertical space. By default this spacing - is omitted in "simple" lists. A list is simple if every item - contains a simple paragraph and/or a "simple" nested list. For - example: - - * text - - * simple - - * simple - * simple - - * simple - - text after a nested list - - * multiple - - paragraphs - - In this example the nested lists are simple (and should appear - compacted) but the outer list is not. - - If you want all lists to have equal spacing, disable the - `compact_lists`_ setting (``--no-compact-lists`` option). The - precise spacing can be controlled in the stylesheet. - - Note again that this is not exactly WYSIWYG: it partially resembles - the rules about blank lines being optional between list items in - reStructuredText -- but adding/removing optional blank lines does - not affect spacing in the output! It's a feature, not a bug: you - write it as you like but the output is styled consistently. - - .. _compact_lists: docs/user/config.html#compact-lists - - -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 enabling the -`embed_stylesheet`_ setting [``--embed-stylesheet`` option]), or the -browser can't understand it (try a recent Firefox, Mozilla, Konqueror, -Opera, Safari, or even MSIE). - -.. _embed_stylesheet: docs/user/config.html#embed-stylesheet - - -There appear to be garbage characters in the HTML. What's up? --------------------------------------------------------------- - -What you're seeing is most probably not garbage, but the result of a -mismatch between the actual encoding of the HTML output and the -encoding your browser is expecting. Your browser is misinterpreting -the HTML data, which is encoded text. A discussion of text encodings -is beyond the scope of this FAQ; see one or more of these documents -for more info: - -* `UTF-8 and Unicode FAQ for Unix/Linux - <http://www.cl.cam.ac.uk/~mgk25/unicode.html>`_ - -* Chapters 3 and 4 of `Introduction to i18n [Internationalization] - <http://www.debian.org/doc/manuals/intro-i18n/>`_ - -* `Python Unicode Tutorial - <http://www.reportlab.com/i18n/python_unicode_tutorial.html>`_ - -* `Python Unicode Objects: Some Observations on Working With Non-ASCII - Character Sets <http://effbot.org/zone/unicode-objects.htm>`_ - -The common case is with the default output encoding (UTF-8), when -either numbered sections are used (via the "sectnum_" directive) or -symbol-footnotes. 3 non-breaking spaces are inserted in each numbered -section title, between the generated number and the title text. Most -footnote symbols are not available in ASCII, nor are non-breaking -spaces. When encoded with UTF-8 and viewed with ordinary ASCII tools, -these characters will appear to be multi-character garbage. - -You may have an decoding problem in your browser (or editor, etc.). -The encoding of the output is set to "utf-8", but your browswer isn't -recognizing that. You can either try to fix your browser (enable -"UTF-8 character set", sometimes called "Unicode"), or choose a -different encoding for the HTML output. You can also try -``--output-encoding=ascii:xmlcharrefreplace`` for HTML or XML, but not -applicable to non-XMLish outputs (if using runtime -settings/configuration files, use ``output_encoding=ascii`` and -``output_encoding_error_handler=xmlcharrefreplace``). - -If you're generating document fragments, the "Content-Type" metadata -(between the HTML ``<head>`` and ``</head>`` tags) must agree with the -encoding of the rest of the document. For UTF-8, it should be:: - - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - -Also, Docutils normally generates an XML declaration as the first line -of the output. It must also match the document encoding. For UTF-8:: - - <?xml version="1.0" encoding="utf-8" ?> - -.. _sectnum: docs/ref/rst/directives.html#sectnum - - -How can I retrieve the body of the HTML document? -------------------------------------------------- - -(This is usually needed when using Docutils in conjunction with a -templating system.) - -You can use the `docutils.core.publish_parts()`_ function, which -returns a dictionary containing an 'html_body_' entry. - -.. _docutils.core.publish_parts(): docs/api/publisher.html#publish-parts -.. _html_body: docs/api/publisher.html#html-body - - -Why is the Docutils XHTML served as "Content-type: text/html"? --------------------------------------------------------------- - -Full question: - - Docutils' HTML output looks like XHTML and is advertised as such:: - - <?xml version="1.0" encoding="utf-8" ?> - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" - "http://www.w3.org/TR/xht ml1/DTD/xhtml1-transitional.dtd"> - - But this is followed by:: - - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - - Shouldn't this be "application/xhtml+xml" instead of "text/html"? - -In a perfect web, the Docutils XHTML output would be 100% strict -XHTML. But it's not a perfect web, and a major source of imperfection -is Internet Explorer. Despite it's drawbacks, IE still represents the -majority of web browsers, and cannot be ignored. - -Short answer: if we didn't serve XHTML as "text/html" (which is a -perfectly valid thing to do), it couldn't be viewed in Internet -Explorer. - -Long answer: see the `"Criticisms of Internet Explorer" Wikipedia -entry <http://en.wikipedia.org/wiki/Criticisms_of_Internet_Explorer#XHTML>`__. - -However, there's also `Sending XHTML as text/html Considered -Harmful`__. What to do, what to do? We're damned no matter what we -do. So we'll continue to do the practical instead of the pure: -support the browsers that are actually out there, and not fight for -strict standards compliance. - -__ http://hixie.ch/advocacy/xhtml - -(Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan -G. Isaac.) - - -Python Source Reader -==================== - -Can I use Docutils for Python auto-documentation? -------------------------------------------------- - -Yes, in conjunction with other projects. - -Docstring extraction functionality from within Docutils is still under -development. There is most of a source code parsing module in -docutils/readers/python/moduleparser.py. We do plan to finish it -eventually. Ian Bicking wrote an initial front end for the -moduleparser.py module, in sandbox/ianb/extractor/extractor.py. Ian -also did some work on the Python Source Reader -(docutils.readers.python) component at PyCon DC 2004. - -Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_ -supports reStructuredText-format docstrings for HTML output. Docutils -0.3 or newer is required. Development of a Docutils-specific -auto-documentation tool will continue. Epydoc works by importing -Python modules to be documented, whereas the Docutils-specific tool, -described above, will parse modules without importing them (as with -`HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support -reStructuredText). - -The advantages of parsing over importing are security and flexibility; -the disadvantage is complexity/difficulty. - -* Security: untrusted code that shouldn't be executed can be parsed; - importing a module executes its top-level code. -* Flexibility: comments and unofficial docstrings (those not supported - by Python syntax) can only be processed by parsing. -* Complexity/difficulty: it's a lot harder to parse and analyze a - module than it is to ``import`` and analyze one. - -For more details, please see "Docstring Extraction Rules" in `PEP -258`_, item 3 ("How"). - - -Miscellaneous -============= - -Is the Docutils document model based on any existing XML models? ----------------------------------------------------------------- - -Not directly, no. It borrows bits from DocBook, HTML, and others. I -(David Goodger) have designed several document models over the years, -and have my own biases. The Docutils document model is designed for -simplicity and extensibility, and has been influenced by the needs of -the reStructuredText markup. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: Deleted: trunk/docutils/src/main/resources/docutils/HISTORY.txt =================================================================== --- trunk/docutils/src/main/resources/docutils/HISTORY.txt 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/HISTORY.txt 2012-06-13 15:51:18 UTC (rev 717) @@ -1,2790 +0,0 @@ -.. -*- coding: utf-8 -*- - -================== - Docutils History -================== - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date: 2012-05-02 19:13:41 +0200 (Mit, 02 Mai 2012) $ -:Revision: $Revision: 7410 $ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -Release 0.9 (2012-05-02) -======================== - -* General: - - - New reStructuredText "code" role and directive and "code" option - of the "include" directive with syntax highlighting by Pygments_. - - Fix parse_option_marker for option arguments containing ``=``. - -.. _Pygments: http://pygments.org/ - -* setup.py - - - Fix [ 2971827 ] and [ 3442827 ] - extras/roman.py moved to docutils/utils/roman.py - -* docutils/frontend.py - - - Fix [ 3481980 ] Use os.getcwdu() in make_paths_absolute(). - -* docutils/io.py - - - Fix [ 3395948 ] (Work around encoding problems in Py3k). - - `mode` argument for FileOutput avoids code replication in - BinaryFileOutput. - - New exceptions InputError and OutputError for IO errors in - FileInput/FileOutput. - -* docutils/core.py: - - - No "hard" system exit on file IO errors: catch and report them in - `Publisher.reportException` instead. Allows handling by a calling - application if the configuration setting `traceback` is True. - -* docutils/utils.py -> docutils/utils/__init__.py - - - docutils.utils is now a package (providing a place for sub-modules) - - .. note:: docutils/math, docutils/error_reporting.py, and - docutils/urischemes.py will move to the utils package in the next - release, too. See RELEASE-NOTES__ - - __ RELEASE-NOTES.html - - - DependencyList uses io.FileOutput and 'utf8' encoding to prevent - errors recording non-ASCII filenames (fixes [ 3434355 ]). - - - Fix relative_path() with source=None and `unicode` target. - -* docutils/parsers/rst/states.py - - - Fix [ 3402314 ] allow non-ASCII whitespace, punctuation - characters and "international" quotes around inline markup. - - Use `field_marker` pattern to look for start of a - directive option block (fixes [ 3484857 ]). - -* docutils/parsers/rst/tableparser.py - - - Fix [ 2926161 ] for simple tables. - (Combining chars in grid tables still contribute to cell width.) - -* docutils/writers/latex2e/__init__.py - - - Support the `abbreviation` and `acronym` standard roles. - - Record only files required to generate the LaTeX source as dependencies. - - Fix handling of missing stylesheets. - - Use ``\setcounter{secnumdepth}{0}`` instead of ``*``-versions - when suppressing LaTeX section numbering. - - Use ``\DUtitle`` for unsupported section levels - - Apply [ 3512791 ] do not compare string literals with "is" - -* docutils/writers/xetex/__init__.py - - - Avoid code duplication with latex2e writer (solves [ 3512728 ]). - -* docutils/writers/html4css1/__init__.py - - - Change default for `math-output` setting to MathJax. - - Fix handling of missing stylesheets. - -* docutils/writers/docutils_xml.py - - - Use the visitor pattern with default_visit()/default_depart() methods - instead of minidom to facilitate special handling of selected nodes. - - Support raw XML (inserted as-is inside a <raw></raw> node). - -* docutils/writers/manpage.py - - - Do not emit comment line with trailing blank. Problematic for VCS. - -Release 0.8.1 (2011-08-30) -========================== - -* General: - - - Fix [ 3364658 ] (Change last file with Apache license to BSD-2-Clause) - and [ 3395920 ] (correct copyright info for rst.el). - -* docutils/test/ - - - Apply [ 3303733 ] and [ 3365041 ] to fix tests under py3k. - -* docutils/writers/latex2e/__init__.py - - - Clean up Babel language setting. Restores Sphinx compatibility. - -Release 0.8 (2011-07-07) -======================== - -* General: - - - Handle language codes according to `BCP 47`_. - - If the specified language is not supported by Docutils, - warn and fall back to English. - - Math support: reStructuredText "math" role and directive, - ``math`` and ``math_block`` doctree elements. - - Decode command line arguments with the locale's preferred encoding - (to allow, e.g., ``--title=Dornröschen``). - - Orphaned "python" reader and "newlatex2e" writer moved to the sandbox. - - New sub-module `error_reporting`: handle encoding/decoding errors - when reporting exceptions. - - Some additions to the Docutils core are released under the 2-Clause BSD - license, see COPYING_ for details. - - .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt - .. _COPYING: COPYING.html - -* reStructuredText: - - - Most directives now support a "name" option that attaches a - reference name. - - - Directive content may start on the first line also when the directive - type accepts options. - -* docs/dev/policies.txt: - - - Recommend the 2-Clause BSD license - (http://www.spdx.org/licenses/BSD-2-Clause) - for code that is kept under the author's copyright. - -* tools/buildhtml.py: - - - Fix ``--local`` switch. - -* Fix [ 3018371 ] Added Lithuanian mappings by Dalius Dobravolskas. - -* docutils/writers/html4css1/__init__.py - - - Set "lang" argument for objects with class argument - "language-<language tag>". - - New setting "math-output" with support for HTML, MathML, and LaTeX. - -* docutils/writers/latex2e/__init__.py - - - Fix [ 3043986 ] AttributeError using :local: with table of content. - - Place title data in the document preamble. - - Load `babel` package only if required. - - Update list of supported languages. - - New config setting "hyperref-options". - No hard-coded "unicode" hyperref option (clash with xetex). - - Set language for custom roles, paragraphs, block-quotes, and - line-quotes with class argument "language-<language tag>". - - Fix [ 3095603 ] wrong quotes output for russian and other languages. - - Convert image URI to a local file path. - - Apply [ 3148141 ] fix multicolumn support when a colspanning cell - has more than one paragraph (Wolfgang Scherer). - - \leavevmode before longtable only when needed (prevents spurious vspace) - - do not advance table counter for tables without caption - -* docutils/writers/xetex/__init__.py - - - New writer generating LaTeX code for compiling with ``xelatex``. - - A separate writer (inheriting from latex2e) instead of a ``--xetex`` - option allows separate config options for XeTeX vs. LaTeX2e. - -* docutils/writers/manpage.py - - - Fix: BUG#3219183 - vertical space in definition lists containing markup. - - Fix: vertical space cleaning for option group ``.``. - -* tools/editors/emacs/rst.el: - - - Fix [ 3001100 ] does not handle spaces in filenames - (thanks to Jakub Wilk) - -* docutils/utils.py: - - - strip whitespace from stylesheet arguments - - exclude combining chars from column_width() - (partial fix for [ 2926161 ]) - -* docutils/parsers/rst/directives/misc.py: - - - Fix [ 1830389 ] Replace not breaking on getting system_messages from - nested_parse - -* docutils/io.py: - - - Do not close() sys.stdin, sys.stdout, or sys.stderr. Prevents - ``Exception ValueError: 'I/O operation on closed file.'`` with Python 3. - -Release 0.7 (2010-07-07) -======================== - -* General: - - - Fix [ 2881769 ] setup configuration. - - Fix [ 2788716 ] reporting problems in included files. - -* docutils/io.py - - - FileInput opens files as text files with universal newline support - (mode "rU", configurable with the new optional argument "mode"). - -* docutils/nodes.py - - - Fix [ 2975987 ] repr(Text) failed with long string (Jeffrey C. Jacobs). - -* docutils/utils.py - - - Fix [ 2923723 ] let decode_path() tolerate path == None - -* docutils/writers/html4css1/__init__.py - - - Support SVG and SWF images (thanks to Stefan Rank). - - Generate valid XHTML for centered images with targets. - Use CSS classes instead of "align" tags for image alignment. - -* docutils/writers/latex2e/__init__.py - - - Use `transforms.writer_aux.Admonitions` to "normalize" special - admonitions. - - Use the ``\url`` command for URLs (breaks long URLs instead of - writing into the margin). - - Preserve runs of spaces in `inline literals`__. - - Deprecate ``figure_footnotes`` setting. - - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__. - - New ``latex_preamble`` setting. - - Use PDF standard fonts (Times/Helvetica/Courier) as default. - - Fix hyperlink targets (labels) for images, figures, and tables. - - Apply [ 2961988 ] Load babel after inputenc and fontenc. - - Apply [ 2961991 ] Call hyperref with unicode option. - - Drop the special `output_encoding`__ default ("latin-1"). - The Docutils wide default (usually "UTF-8") is used instead. - - Render inline markup in document title and subtitle. - - Fix numbering depth with LaTeX section numbering. - - Update Unicode -> LaTeX translations. - - Fix bug with topic directive (thanks to Alan G Isaac for reporting). - -__ docs/ref/restructuredtext.html#inline-literals -__ docs/user/config.html#docutils-footnotes -__ docs/user/config.html#output_encoding - -* docutils/writers/manpage.py - - - Fix: supported attribute (thanks to peter2108). - - Remove trailing blanks in code (keep in sync with mercurial version). - - Titles level 1, that is ``.SH``, always uppercase. - - Apply patch from mg: literal text should be bold in man-pages. - -* docutils/nodes.py - - - Fix: encoding ``'ascii'`` must be lowercase to prevent problems for - turkish locale. - -* setup.py: - - - Python 3 support: copy test/ and tools/ to the build-dir - and convert Python sources with 2to3. - - -Release 0.6 (2009-10-11) -======================== - -* General: - - - Docutils is now compatible with Python versions from 2.3 up to 2.6 - and convertible to 3.1 code. - - + Node.__nonzero__ returns True instead of 1. - + use os.walk instead os.path.walk. - + minimize "types" module where possible. - + Backwards-compatible changes to remove python2.6 -3 deprecation warnings - + Text nodes now subclass unicode rather than UserString - (which is gone in python 3.0). - + 3.0 compatibility module docutils._compat - - + Drop 2.2 compatibility workarounds. - + Drop extras/optparse.py and extras/textwrap.py - (stdlib modules since 2.3). - - - OpenOffice export: ODT writer moved from sandbox to Doctutils core. - - Unix man page export: manpage writer moved from sandbox to Doctutils - core. - - - Apply [ 1719345 ] Galician translation - - Apply [ 1905741 ] Polish translation - - Apply [ 1878977 ] make_id(): deaccent characters. - - Apply [ 2029251 ] return nonzero when tests fail. - - Fix [ 1692788 ] allow UTF-8 in style sheets. - - Fix [ 2781629 ] support non-ASCII chars in file names. - - Apply [ 2845002 ] let ``--no-raw`` disable raw *roles* too. - - Fix [ 2831643 ] by renaming DirectiveError.message to DirectiveError.msg - - Fix [ 2821266 ] --strict option works now like --halt=info. - - Fix [ 2788716 ] DirectiveError now correctly reports source and line. - - Fix [ 1627229 ] hyperlink references in substitutions. - - - The "newlatex" writer is orphaned. - -* reStructuredText: - - - Documented Unicode characters allowed as inline markup openers, - closers, and delimiters. - - Allow units for all length specifications. - - Allow percent sign in "scale" argument of "figure" and "image" directives. - - Bugfix: The "figalign" argument of a figure now works as intended - (aligning the figure, not its contents). - - Align images with class "align-[right|center|left]" - (allows setting the alignment of an image in a figure). - -* docutils/nodes.py: - - - Added ``Element.__contains__`` method, for the in-operator. - -* docutils/parsers/rst/states.py: - - - Apply [ 1994493 ] Patch to support all kinds of quotes in inline markup. - - Added support for Unicode inline markup delimiters "‐ ‑ ‒ – —" and - " " (non-breaking space), and "¡ ¿" openers. - -* docutils/parsers/directives/misc.py: - - - Added ``start-line`` and ``end-line`` options to "include" - directive to select a range of lines. - - Hard tabs in literal inclusions are replaced by spaces. This is - configurable via the new ``tab-width`` option of the "include" directive - (a negative tab-width prevents tab expansion). - -* docutils/utils.py: - - - Add ``get_stylesheet_list`` function. - - Apply [ 2834836 ] print info at halt - -* docutils/transforms/universal.py: - - - Raise default priority of StripClasses to exclude stripped classes from - the ToC. - -* docutils/writers/html4css1/__init__.py: - - - ``--stylesheet`` and ``--stylesheet-path`` options support a comma - separated list of stylesheets. - - Address [ 1938891 ] Inline literal text creates "pre" span only when - needed to prevent inter-word line wraps. - - Use `translate` method instead of repeated `replace` calls. - - Fix [ 1757105 ] New ``table-style`` option. Added to standard table - classes to allow CSS styling that does not interfere with other - table-using constructs (field lists, citations, ...). - -* docutils/writers/newlatex2e/__init__.py: - - - Apply [ 1612821 ] Double quotes in literal text in Italian/German - -* docutils/writers/latex2e/__init__.py (see also - `<docs/user/docutils-05-compat.sty.html>`__) : - - - Add ``--embed-stylesheet`` option. - - Apply [ 1474017 ] image vertical alignment is reversed. - - Apply [ 2051599 ] multi-page tables in latex writer (from pabigot). - - Change: has_key for dictionaries (not Nodes) to in-operator. - - Merge adjacent citations into one latex cite command. - - Failsave implementation of custom roles. LaTeX compilation now ignores - unknown classes instead of aborting with an error. - - Support custom roles based on standard roles. - - LaTeX packages can be used as ``--stylesheet`` arguments without - restriction. (A style sheet is now referenced with the ``\usepackage`` - command, if it ends with ``.sty`` or has no extension.) - - Add ``bp`` to lenghts without unit (prevents LaTex errors). - - Correctly write length unit ``pt`` as ``bp`` in LaTeX. - - Do not convert ``px`` to ``pt`` (``px`` is supported by pdfTeX since - 2005-02-04 as a configurable length unit). - - Do not use fontenc, nor the obsolete 'ae' and 'aeguill' packages - if font-encoding is set to ''. LaTeX defaults to OT1 then. - - Set sub- and superscript role argument in text mode not as math. - Use a custom role based on sub-/superscript if you want italic shape. - - Shorter preamble and less dependencies: Load packages and define macros - only if required in the document. - - Use the name prefix ``DU`` for all Docutils specific LaTeX macros. - - New custom environments and commands with optional "classes" argument. - - Simpler LaTeX encoding, e.g. "\%" instead of "{\%}". - - Better conformance to Docutils specifications with ``--use-latex-toc``. - Support for LaTeX generated ToC also with unnumbered sections. - - If 'sectnum_xform' is False, the 'sectnum' directive triggers - section numbering by LaTeX. - - Use default font in admonitions and sidebar. - - Align of image in a figure defaults to 'center'. - - Bugfix: Newlines around targets and references prevent run-together - paragraphs. - - Fix internal hyperlinks. - - Use class defaults for page margins ('typearea' now optional). - - Float placement made configurable, default changed to "here definitely". - - Typeset generic topic as "quote block with title". - - Use template (file and configuration option). - - In the default template, load cmap.sty (fix text extraction in PDF) and - fixltx2e.sty (LaTeX patches, \textsubscript). - - Render doctest blocks as literal blocks (fixes [ 1586058 ]). - - Use `translate` instead of repeated `replace` calls for text encoding. - - Hyperlinked footnotes and support for symbol footnotes and - ``--footnote-references=brackets`` with ``--use-latex-footnotes``. - - Complete pairs of binary options - (``--figure-footnotes, --figure-citations, --link-stylesheet``, - ``--use-docutils-toc, --use-docutils-docinfo, --topic-abstract``) - - New defaults: - - font-encoding: "T1" (formerly implicitely set by 'ae'). - - use-latex-toc: true (ToC with page numbers). - - use-latex-footnotes: true (no mixup with figures). - -* docutils/writers/manpage.py - - - Do not print version at document end, this is done by the viewer. - - Do not print date at document end, this is done by the viewer. - - Fix storage of docinfo fields for none standard fields. - -* docutils/tools/rst2man.py - -Release 0.5 (2008-06-25) -======================== - -* docutils/languages/he.py: Added to project: Hebrew mappings by - Meir Kriheli. - -* docutils/parsers/rst/languages/he.py: Added to project: Hebrew - mappings by Meir Kriheli. - -* docutils/frontend.py: - - - Configuration files are now assumed and required to be - UTF-8-encoded. - - Paths of applied configuration files are now recorded in the - runtime setting ``_config_files`` (accessible via - ``--dump-settings``). - - Added ``--strip-elements-with-class`` and ``--strip-class`` - options (``strip_elements_with_classes`` and ``strip_classes`` - settings). - -* docutils/io.py: - - - Added code to determine the input encoding from data: encoding - declarations or the presence of byte order marks (UTF-8 & UTF-16). - - Added support for IronPython 1.0. - -* docutils/nodes.py: - - - Added ``document.__getstate__`` method, for pickling. - -* docutils/parsers/rst/states.py: - - - Allow ``+`` and ``:`` in reference names. - - Unquoted targets beginning with an underscore (``.. __target: - URI``) are no longer accepted. - - Added support for multiple attributions in a physical block quote - (indented text block), dividing it into multiple logical block - quotes. - - Added support for unicode bullets in bullet lists: "•", "‣", and - "⁃". - - Added support for new object-oriented directive interface, - retaining compatibility to the old functional interface. - - Added support for throwing ``DirectiveError``'s from within - directive code. - -* docutils/parsers/rst/__init__.py: - - - Added ``Directive`` base class. - - Added ``DirectiveError`` base class. - - Fixed ``file_insertion_enabled`` & ``raw_enabled`` setting - definitions. - -* docutils/parsers/directives/: - - - Refactored all reStructuredText directives to use the new - object-oriented directive interface. Errors are now (mostly) - thrown using the new ``DirectiveError`` class. - -* docutils/parsers/directives/misc.py: - - - Added ``start-after`` and ``end-before`` options to ``include`` - directive; thanks to Stefan Rank. - -* docutils/transforms/universal.py: - - - Added ``StripClassesAndElements`` transform to remove from the - document tree all elements with classes in - ``settings.strip_elements_with_classes`` and all "classes" - attribute values in ``self.document.settings.strip_classes``. - -* docutils/transforms/writer_aux.py: - - - Added ``Admonitions`` transform to transform specific admonitions - (like ``note``, ``warning``, etc.) into generic admonitions with a - localized title. - -* docutils/writers/html4css1/__init__.py: - - - Moved template functionality from the PEP/HTML writer here. - - Expanded the fragments available in the ``parts`` attribute. - - Moved ``id`` attributes from titles to surrounding ``div`` - elements. - - Dropped all ``name`` attributes of ``a`` elements (``id`` is - universally supported now). - - ``template.txt`` is now opened in text mode instead of binary mode - (to ensure Windows compatibility). - - ``a`` elements now have an "internal" or "external" class, - depending on reference type. - -* docutils/writers/html4css1/template.txt: Added to project. - -* docutils/writers/pep_html/: - - - Moved template functionality to the HTML writer. - -* docutils/writers/s5_html/__init__.py: - - - Added ``view_mode`` & ``hidden_controls`` settings - (``--view-mode`` & ``--hidden-controls/--visible-controls`` - options). - -* docutils/writers/latex2e/__init__.py: - - - Add ``--literal-block-env`` - - Fix: escaping ``%`` in href urls. - - Move usepackage hyperref after stylesheet inclusion. - - Fix: scrartcl does not have chapter but scrreprt. - - Add newline after ``\end{verbatim}``. - - Merge smaller differences from latex2e_adaptive_preamble. - - Add ``use-part-section``. - - Put leavevmode before longtable to avoid having it moved before sub/pargraph. - - Using leavemode option_list no longer needs to check if parent - is a definition list. - - Append ``\leavemode`` to definition list terms. - - No longer write visit\_/depart_definition_list_item comments to - output. - - Table column width with 3 decimal places. - - Add table stubs support (boldfont). - - Add assemble_parts to writer. - - Add simply support for nested tables. - - Fix verbatim in tables if use-verbatim-when-possible. - - Use section commands down to subparagraph. - - Put ensuremath around some latin1 chars. - - Set ``usepackage[utf8x]{inputenc}`` for utf-8. - - New option ``--use-bibtex=style,db1,db2``. - - New option ``--reference-label`` to allow usage of LaTeX ref for - labels in section references. - - Add a label after every section to support sectionnumbers as reference - labels. - - Fix: bug# 1605376 rst2latex: bad options group list - - Remove inactive code for use_optionlist_for_option_list. - - Remove latex comments from option_list output. - - Fix: bug# 1612270 double qoutes in italian literal. - - Fix: output ``hypertarget{ node.get(refid) }{}`` from visit_target. - - Add option --use-latex-abstract. - - Image width unit ``px`` is translated to ``pt``. - - Add image height support. - - Fix: image width ``70%`` is converted ``0.700\linewidth``. - bug #1457388 - - Fix: Do not escape underscores in citation reference labels if - use-latex-citations is set. - - Use centering instead of center for figure contents, to avoid vertical - space. - - Recognize table class: borderless, nolines, booktabs, standard. - - Fix: Renaming contents section does not work with latex writer; SF - bug #1487405. - - Applied patch for custom roles with classes from Edward Loper. - - Fixed bug that caused crashes with more than 256 lists. - -* docutils/writers/pep_html/__init__.py: - - - Changed to support new python.org website structure and - pep2pyramid.py. - -* docs/howto/security.txt: "Deploying Docutils Securely", added to - project. - -* tools/buildhtml.py: - - -- Added ``ignore`` setting to exclude a list of shell patterns - (default: ``.svn:CVS``). - -* tools/editors/emacs/rst.el: - - - Changed license to "GPL". - - Added ``rst-straighten-decorations`` function. - - The ``compile`` module is now always loaded. - - Added ``rst-toggle-line-block`` function. - - Headings consisting only of non-ASCII characters are now - recognized by ``rst-toc`` and ``rst-adjust``. - - Added font-lock support for multi-line comments where the first - comment line is empty. - - Added ``(require 'font-lock)``. - -* setup.py: - - - Provide descriptive error message if distutils is missing. - - -Release 0.4 (2006-01-09) -======================== - -* General: - - - Updated the project policies for trunk/branch development & - version numbering. - -* docutils/__init__.py: - - - Added ``__version_details__`` attribute to describe code source - (repository/snapshot/release). - - Replaced ``default_transforms`` attribute of TransformSpec with - ``get_transforms()`` method. - -* docutils/core.py: - - - Added ``publish_doctree`` and ``publish_from_doctree`` convenience - functions, for document tree extraction and reprocessing. - -* docutils/io.py: - - - Added ``DocTreeInput`` class, for reprocessing existing documents. - - Added support for non-Unicode (e.g. binary) writer output. - -* docutils/nodes.py: - - - Re-introduced ``Targetable.indirect_reference_name``, for - MoinMoin/reST compatibility (removed in r3124/r3129). - - Added ``serial_escape`` function; escapes string values that are - elements of a list, for serialization. Modified Docutils-XML - writing (``Element._dom_node``) and pseudo-XML writing - (``Element.starttag``) to use ``serial_escape``. - - Added ``Node.deepcopy()`` method. - - Removed the internal lists ``document.substitution_refs``, - ``document.anonymous_refs``, and ``document.anonymous_targets``. - - Added a "container" element. - - Fixed bug where values of list-valued attributes of elements - originating from custom interpreted text roles (i.e., with custom - classes) were being shared between element instances. Reported by - Shmuel Zeigerman. - -* docutils/statemachine.py: - - - Added trailing whitespace stripping to ``string2lines()``. - - Added ``StringList.pad_double_width()`` & ``.replace()`` for East - Asian double-width character support. - -* docutils/utils.py: - - - Added ``east_asian_column_width()`` for double-width character - support. - -* docutils/languages/ja.py: Added to project: Japanese mappings by - Hisashi Morita. - -* docutils/languages/zh_cn.py: Added to project: Simplified Chinese - mappings by Panjunyong. - -* docutils/parsers/null.py: Added to project; a do-nothing parser. - -* docutils/parsers/rst/__init__.py: - - - Added validator to tab_width setting, with test. Closes SF bug - #1212515, report from Wu Wei. - -* docutils/parsers/rst/states.py: - - - Fixed bug with escaped colons indicating a literal block. - - Fixed bug with enumerated lists (SF#1254145). - - Backslash-escaped colons inside of field names are now allowed. - - Targets (implicit and explicit), anonymous hyperlink references - and auto-numbered footnote references inside of substitution - definitions are now disallowed. - - Fixed bug: list items with blank first lines. - - Fixed bug: block quote attributions with indented second lines. - - Added East Asian double-width character support (Python 2.4 only). - -* docutils/parsers/rst/tableparser.py: - - - Added East Asian double-width character support (Python 2.4 only). - -* docutils/parsers/rst/directives/body.py: - - - Added the "container" directive. - -* docutils/parsers/rst/directives/misc.py: - - - Added the "default-role", "title", and "date" directives. - - Added standard data file syntax to the "include" directive. - - Added support for "class" directive content. - -* docutils/parsers/rst/directives/images.py: - - - Added ``indirect_reference_name`` support for images with a target - option. - - Added support for image width and height units. - - Fixed bug with image "target" options. - -* docutils/parsers/rst/directives/references.py: - - - Added "class" attribute to "target-notes" directive, for - footnote_reference classes. - -* docutils/parsers/rst/include/: Directory added to project; contains - standard data files for the "include" directive. Initial contents: - character entity substitution definition sets, and a set of - definitions for S5/HTML presentations. - -* docutils/parsers/rst/languages/ja.py: Added to project: Japanese - mappings by David Goodger. - -* docutils/parsers/rst/languages/zh_cn.py: Added to project: - Simplified Chinese mappings by Panjunyong. - -* docutils/readers/__init__.py: - - - Added universal.Decorations and universal.ExposeInternals - transforms as default transforms for all readers. - - Added ``ReReader`` base class for readers that reread an existing - document tree. - -* docutils/readers/doctree.py: Added to project; a reader for existing - document trees. - -* docutils/transforms/frontmatter.py: - - - Fixed the DocInfo transform to handle SVN-style expansion of the - "Date" keyword. - - In ``DocInfo.extract_authors``, treat the contents of "authors" - fields uniformly. - -* docutils/transforms/misc.py: - - - Added misc.Transitions transform, extracted from - universal.FinalChecks. - -* docutils/transforms/references.py: - - - Added references.DanglingReferences transform, extracted from - universal.FinalChecks. - - Fixed bug with doubly-indirect substitutions. - - Added footnote_reference classes attribute to "TargetNotes". - - Fixed bug with circular substitution definitions that put Docutils - into an infinite loop. - -* docutils/transforms/universal.py: - - - Added universal.ExposeInternals transform, extracted from - universal.FinalChecks. - - Removed universal.FinalChecks transform (logic has been moved to - several new transforms). - - Fixed bug with the "expose_internals" setting and Text nodes - (exposed by the "rawsource" internal attribute). - - Added the universal.StripComments transform, implementation of the - "strip_comments" setting. - -* docutils/transforms/writer_aux.py: Added to project; auxiliary - transforms for writers. - - - Added ``Compound`` transform, which flattens compound paragraphs. - -* docutils/writers/: Several writer modules (html4css1.py) were - converted into packages. Support modules and data files have been - moved into the packages. The stylesheets for the HTML writers are - now installed along with the code, the code knows where to find - them, and the default is to use them (actually, to embed them). - Some adjustments to configuration files may be necessary. The - easiest way to obtain the new default behavior is to remove all - settings whose name includes "stylesheet". - -* docutils/writers/__init__.py: - - - Added universal.Messages and universal.FilterMessages transforms - as default transforms for all writers. - - Added ``UnfilteredWriter`` base class for writers that pass the - document tree on unchanged. - -* docutils/writers/docutils_xml.py: - - - Made ``xmlcharrefreplace`` the default output encoding error - handler. - -* docutils/writers/html4css1/: - - - Added support for image width and height units. - - Made ``xmlcharrefreplace`` the default output encoding error - handler. - - Made ``--embed-stylesheet`` the default rather than - ``--link-stylesheet``. - - Moved "id" attribute from container (section etc.) to title's <a> - tag, to be on the same tag as "name". - (!!! To be reverted in Docutils 0.5.) - - Added vertical space between fields of field lists. - - Added ``--compact-field-lists`` option to remove vertical space in - simple field lists. - - Made cloaking of email addresses with ``--cloak-email-addresses`` - less obtrusive. - - Fixed support for centered images. - - Added support for class="compact" & class="open" lists. - -* docutils/writers/latex2e/: - - - Underscores in citekeys are no longer escaped. - -* docutils/writers/newlatex2e/unicode_map.py: Added to project; - mapping of Unicode characters to LaTeX equivalents. - -* docutils/writers/s5_html/: Package added to project; writer for - S5/HTML slide shows. - -* docs/dev/distributing.txt: Added to project; guide for distributors - (package maintainers). - -* docs/dev/hacking.txt: Added to project; guide for developers. - -* docs/ref/doctree.txt: - - - Updated for plural attributes "classes", "ids", "names", - "dupnames". - - Added the "container" element. - -* docs/ref/docutils.dtd: - - - Updated for plural attributes "classes", "ids", "names", - "dupnames". - -* docs/user/emacs.txt: Added to project; a document about Emacs - support for reStructuredText and Docutils. - -* docs/user/links.txt: Added to project; lists of Docutils-related - links. - -* docs/user/mailing-lists.txt: Added to project; information about - Docutils-related mailing lists and how to access them. - -* docs/user/slide-shows.txt: Added to project; example of and docs for - the S5/HTML writer (``rst2s5.py`` front end). - -* docs/ref/rst/definitions.txt: "reStructuredText Standard Definition - Files", added to project. - -* test/coverage.sh: Added to project; test coverage script. - -* test/DocutilsTestSupport.py: - - - Added support for specifying runtime settings at the suite level. - -* test/test_functional.py: - - - Added the ``clear_output_directory`` function. - - Added support for ``_test_more`` functions in functional test - config files. - -* tools/rst2s5.py: Added to project; front end for the S5/HTML writer. - -* tools/rstpep2html.py: Renamed from pep.py. - -* tools/dev/create_unimap.py: Added to project; script to create the - docutils/writers/unimap_latex.py mapping file. - -* tools/dev/profile_docutils.py: Added to project; profiler script. - -* tools/dev/unicode2rstsubs.py: Moved from tools/unicode2rstsubs.py. - -* tools/editors/emacs/restructuredtext.el, - tools/editors/emacs/rst-html.el, tools/editors/emacs/rst-mode.el: - Removed from project; the functionality is now contained in rst.el. - -* tools/editors/emacs/rst.el: Added to project. Added many features - and fixed many bugs. See docs/user/emacs.txt for details. - -* tools/stylesheets: Removed from project. Stylesheets have been - renamed and moved into writer packages. - - -Release 0.3.9 (2005-05-26) -========================== - -* General: - - - Eliminated and replaced all uses of the old string attributes - ``id``, ``name``, ``dupname`` and ``class`` with references to the - new list attributes ``ids``, ``names``, ``dupnames`` and - ``classes`` throughout the whole source tree. - -* docutils/core.py: - - - Enabled ``--dump-*`` options when ``--traceback`` specified, - allowing for easier debugging. - - In ``Publisher.publish()``, expanded the generic top-level - exception catching. - -* docutils/examples.py: - - - Added ``internals`` function for exploration. - -* docutils/io.py: - - - Fixed ``Input.decode`` method to apply heuristics only if no - encoding is explicitly given, and to provide better reporting of - decoding errors. - - The ``Input.decode`` method now removes byte order marks (BOMs) - from input streams. - -* docutils/nodes.py: - - - ``image`` element class changed to subclass of Element, not - TextElement (it's an empty element, and cannot contain text). - - Added ``attr_defaults`` dictionary for default attribute values. - - Added empty list as default value for the following attributes: - ``ids``, ``names``, ``dupnames``, ``classes``, and ``backrefs``. - - Added ``document.decoration`` attribute, - ``document.get_decoration`` method, and ``decoration.get_header`` - & ``.get_footer`` methods. - - Added ``Element.update_basic_atts()`` and ``Element.substitute()`` - methods. - -* docutils/utils.py: - - - Removed ``docutils.utils.Reporter.categories``, - ``docutils.utils.ConditionSet``, and all references to them, to - simplify error reporting. - -* docutils/languages/nl.py: Added to project; Dutch mappings by - Martijn Pieters. - -* docutils/parsers/rst/__init__.py: - - - Added settings: ``file_insertion_enabled`` & ``raw_enabled``. - -* docutils/parsers/rst/states.py: - - - Added check for escaped at-mark to prevent email address recognition. - - Fixed option lists to allow spaces inside ``<angle-bracketed option - arguments>``. - - Allowed whitespace in paths and URLs. - - Added auto-enumerated list items. - - Fixed bug that assumed ``.. _`` and ``.. |`` were invariably - followed by text. - - Added support for table stub columns. - -* docutils/parsers/rst/directives/__init__.py: - - - Allowed whitespace in paths (``path`` function). - - Added ``uri`` directive option conversion function. - -* docutils/parsers/rst/directives/body.py: - - - Fixed illegal context bug with "topic" directive (allowed within - sidebars; not within body elements). - -* docutils/parsers/rst/directives/images.py: - - - Allowed whitespace (stripped) in "image" & "figure" directive URLs. - - Added support for the ``file_insertion_enabled`` setting in the - "figure" directive (disables "figwidth" option). - - "image" directive: added checks for valid values of "align" option, - depending on context. "figure" directive: added specialized - "align" option and attribute on "figure" element. - - Made ":figwidth: image" option of "figure" directive work again. - - Fixed bug with reference names containing uppercase letters - (e.g. ``Name_``) in "target" option of "image" directive. - -* docutils/parsers/rst/directives/misc.py: - - - Fixed "include" and "raw" directives to catch text decoding - errors. - - Allowed whitespace in "include" & "raw" directive paths. - - Added support for ``file_insertion_enabled`` & ``raw_enabled`` - settings in "include" & "raw" directives. - -* docutils/parsers/rst/directives/parts.py: - - - Added "header" & "footer" directives. - - Fixed illegal context bug with "contents" directive (topics - allowed within sidebars; not within body elements). - -* docutils/parsers/rst/directives/tables.py: - - - Added "list-table" directive. - - Caught empty CSV table bug. - - Added support for the ``file_insertion_enabled`` setting in the - "csv-table" directive. - - Added ``stub-columns`` option to "csv-table" and "list-table" - directives. - -* docutils/parsers/rst/languages/nl.py: Added to project; Dutch - mappings by Martijn Pieters. - -* docutils/readers/standalone.py: - - - Added ``--section-subtitles`` and ``--no-section-subtitles`` - options to activate or deactivate the SectSubTitle transform. - -* docutils/transforms/frontmatter.py: - - - Added SectSubTitle transform to promote titles of lone - subsections to subtitles. - -* docutils/transforms/references.py: - - - Fixed mislocated internal targets bug, by propagating internal - targets to the next node, making use of the newly added support - for multiple names and IDs. - - Fixed duplicate footnote label bug. - - Replaced ``ChainedTargets`` with more generic ``PropagateTargets`` - transform. - -* docutils/writers/html4css1.py: - - - Fixed unencoded stylesheet reference bug (characters like "&" in - stylesheet references). - - ``target`` nodes now appear as ``span`` tags (instead of ``a`` - tags). - - Added support for multiple IDs per node by creating empty ``span`` - tags. - - Added the ``field_name_limit`` & ``option_limit`` settings & - support. - - Added support for table stub columns. - - Added support for the ``align`` attribute on ``figure`` elements. - - Added the ``cloak_email_addresses`` setting & support. - - Added ``html_prolog``, ``html_head``, ``html_body``, - ``html_title``, & ``html_subtitle`` to parts dictionary exposed by - ``docutils.core.publish_parts``. - - Added support for section subtitles. - -* docutils/writers/latex2e.py: - - - Fixed tables starting with more than one multirow cell. - - Improved --use-latex-docinfo so that organization/contact/address - fields are lumped with the last author field and appear on the - titlepage. - - Made sure the titlepage is always shown with --use-latex-docinfo, - even if the document has no title. - - Made sure that latex doesn't fill in today's date if no date field - was given. - - Added support for section subtitles. - -* docutils/writers/newlatex2e.py: Added to project; a new LaTeX writer - (under development). - -* docutils/writers/null.py: Added to project; a do-nothing Writer. - -* docs/api/publisher.txt: - - - Added "``publish_parts`` Details" section. - -* docutils/dev/repository.txt: Added to project; information about the - Docutils Subversion repository. - -* docs/ref/docutils.dtd: - - - Added a ``stub`` attribute to the ``colspec`` element via the - ``tbl.colspec.att`` parameter entity. - - Allowed topic elements within sidebars - - Added an ``align`` attribute to the ``figure`` element. - -* tools/rst2newlatex.py: Added to project; front end for the new LaTeX - writer. - - -Release 0.3.7 (2004-12-24) -========================== - -* docutils/frontend.py: - - - Added options: --input-encoding-error-handler, - --record-dependencies, --leave-footnote-reference-space, - --strict-visitor. - - Added command-line and config file support for "overrides" setting - parameter. - -* docutils/io.py: - - - Added support for input encoding error handler. - -* docutils/nodes.py: - - - Added dispatch_visit and dispatch_departure methods to - NodeVisitor; useful as a hook for Visitors. - - Changed structure of ``line_block``; added ``line``. - - Added ``compound`` node class. - - Added a mechanism for Visitors to transitionally ignore new node - classes. - -* docutils/utils.py: - - - Moved ``escape2null`` and ``unescape`` functions from - docutils/parsers/rst/states.py. - -* docutils/parsers/rst/roles.py: - - - Added "raw" role. - - Changed role function API: the "text" parameter now takes - null-escaped interpreted text content. - -* docutils/parsers/rst/states.py: - - - Fixed bug where a "role" directive in a nested parse would crash - the parser; the state machine's "language" attribute was not being - copied over. - - Added support for line block syntax. - - Fixed directive parsing bug: argument-less directives didn't - notice that arguments were present. - - Removed error checking for transitions. - - Added support for multiple classifiers in definition list items. - - Moved ``escape2null`` and ``unescape`` functions to docutils/utils.py. - - Changed role function API: the "text" parameter now takes - null-escaped interpreted text content. - - Empty sections and documents are allowed now. - -* docutils/parsers/rst/directives/__init__.py: - - - Added ``encoding`` directive option conversion function. - - Allow multiple class names in class_option conversion function. - -* docutils/parsers/rst/directives/body.py: - - - Converted the line-block directive to use the new structure. - - Extracted the old line-block functionality to the ``block`` - function (still used). - - Added ``compound`` directive (thanks to Lea Wiemann). - -* docutils/parsers/rst/directives/misc.py: - - - Added "encoding" option to "include" and "raw" directives. - - Added "trim", "ltrim", and "rtrim" options to "unicode" directive. - - Allow multiple class names in the "class" directive. - -* docutils/parsers/rst/directives/parts.py: - - - Directive "sectnum" now accepts "prefix", "suffix", and "start" - options. Thanks to Lele Gaifax. - -* docutils/parsers/rst/directives/tables.py: - - - Added "encoding" directive to "csv-table" directive. - - Added workaround for lack of Unicode support in csv.py, for - non-ASCII CSV input. - -* docutils/transforms/misc.py: - - - Fixed bug when multiple "class" directives are applied to a single - element. - - Enabled multiple format names for "raw" directive. - -* docutils/transforms/references.py: - - - Added support for trimming whitespace from beside substitution - references. - -* docutils/transforms/universal.py: - - - FinalChecks now checks for illegal transitions and moves - transitions between sections. - -* docutils/writers/html4css1.py: - - - HTMLTranslator.encode now converts U+00A0 to " ". - - "stylesheet" and "stylesheet_path" settings are now mutually - exclusive. - - Added support for the new line_block/line structure. - - --footnote-references now overrides - --trim-footnote-reference-space, if applicable. - - Added support for ``compound`` elements. - - Enabled multiple format names for "raw" directive. - - ``<p>`` tags of a paragraph which is the only visible child of the - document node are no longer stripped. - - Moved paragraph-compacting logic (for stripping ``<p>`` tags) to - new method ``should_be_compact_paragraph()``. - - Added class="docutils" to ``dl``, ``hr``, ``table`` and ``tt`` - elements. - - "raw" elements are now surrounded by ``span`` or ``div`` tags in - the output if they have their ``class`` attribute set. - - The whole document is now surrounded by a ``<div - class="document">`` element. - - Body-level images are now wrapped by their own ``<div>`` elements, - with image classes copied to the wrapper, and for images which - have the ``:align:`` option set, the surrounding ``<div>`` now - receives a class attribute (like ``class="align-left"``). - -* docutils/writers/latex2e.py: - - - no newline after depart_term. - - Added translations for some Unicode quotes. - - Added option "font-encoding", made package AE the default. - - "stylesheet" and "stylesheet_path" settings are now mutually - exclusive. - - --footnote-references now overrides - --trim-footnote-reference-space, if applicable. - - The footnote label style now matches the footnote reference style - ("brackets" or "superscript"). - - Added support for ``compound`` elements. - - Enabled multiple format names for "raw" directive. - -* docs/ref/docutils.dtd: - - - Changed structure of the ``line_block`` element; added ``line``. - - Added ``compound`` element. - - Added "ltrim" and "rtrim" attributes to - ``substitution_definition`` element. - - Enabled multiple format names for ``raw`` element. - - Enabled multiple classifiers in ``definition_list_item`` elements. - -* docs/ref/rst/directives.txt - - - Marked "line-block" as deprecated. - - "Class" directive now allows multiple class names. - - Added "Rationale for Class Attribute Value Conversion". - - Added warning about "raw" overuse/abuse. - -* docs/ref/rst/restructuredtext.txt: - - - Added syntax for line blocks. - - Definition list items may have multiple classifiers. - -* docs/ref/rst/roles.txt: - - - Added "raw" role. - -* tools/stylesheets/default.css: - - - Added support for the new line_block structure. - - Added "docutils" class to ``dl``, ``hr``, ``table`` and ``tt``. - - -Release 0.3.5 (2004-07-29) -========================== - -General: - -* _`Documentation cleanup/reorganization`. - - - Created new subdirectories of docs/: - - * ``docs/user/``: introductory/tutorial material for end-users - * ``docs/dev/``: for core-developers (development notes, plans, etc.) - * ``docs/api/``: API reference material for client-developers - * ``docs/ref/``: reference material for all groups - * ``docs/howto/``: for component-developers and core-developers - * ``docs/peps/``: Python Enhancement Proposals - - - Moved ``docs/*`` to ``docs/user/``. - - Moved ``pysource.dtd``, ``pysource.txt``, ``semantics.txt`` from - ``spec/`` to ``docs/dev``. - - Moved ``doctree.txt``, ``docutils.dtd``, ``soextblx.dtd``, - ``transforms.txt`` from ``spec/`` to ``docs/ref/``. - - Moved ``alternatives.txt``, and ``problems.txt`` from - ``spec/rst/`` to ``docs/dev/rst/``. - - Moved ``reStructuredText.txt``, ``directives.txt``, - ``interpreted.txt``, and ``introduction.txt`` from ``spec/rst/`` - to ``docs/ref/rst/``. Renamed ``interpreted.txt`` to - ``roles.txt``, ``reStructuredText.txt`` to - ``restructuredtext.txt``. - - Moved ``spec/howto/`` to ``docs/howto``. - - In order to keep the CVS history of moved files, we supplied - SourceForge with a `script for modifying the Docutils CVS - repository`__. - - __ http://cvs.sourceforge.net/viewcvs.py/*checkout*/docutils/sandbox/davidg/infrastructure/cvs-reorg.sh?content-type=text/plain&rev=1.5 - - After running the cleanup script: - - - Added ``docs/index.txt``. - - Added a ``.htaccess`` file to the ``web`` module, containing - redirects for all old paths to new paths. They'll preserve - fragments (the "#name" part of a URL), and won't clutter up the - file system, and will correct the URL in the user's browser. - - Added ``BUGS.txt``, ``docs/dev/policies.txt``, - ``docs/dev/website.txt``, ``docs/dev/release.txt`` from all but - the "To Do" list itself in ``docs/dev/todo.txt``. - - Moved "Future Plans" from ``HISTORY.txt`` to new "Priorities" - section of ``docs/dev/todo.txt``. - - Added ``THANKS.txt`` from "Acknowledgements" in ``HISTORY.txt``. - - Added "How To Report Bugs" to ``BUGS.txt``. - - Went through all the sources and docs (including under web/) and - updated links. Mostly done by Lea Wiemann; thanks Lea! - (Still need to update links in the sandboxes.) - -Specific: - -* BUGS.txt: Added to project. - -* THANKS.txt: Added to project. - -* docutils/__init__.py: - - - 0.3.4: Post-release. - -* docutils/core.py: - - - Added special error handling & advice for UnicodeEncodeError. - - Refactored Publisher.publish (simplified exception handling & - extracted debug dumps). - - Renamed "enable_exit" parameter of convenience functions to - "enable_exit_status". - - Enabled traceback (exception propagation) by default in - programmatic convenience functions. - - Now publish_file and publish_cmdline convenience functions return - the encoded string results in addition to their regular I/O. - - Extracted common code from publish_file, publish_string, and - publish_parts, into new publish_programmatically. Extracted - settings code to ``Publisher.process_programmatic_settings``. - - In Publisher.publish, disabled ``settings_overrides`` when - ``settings`` is supplied; redundant. - -* docutils/frontend.py: - - - Added help text for "--output-encoding-error-handler" and - "--error-encoding-error-handler". - - Renamed "--exit" to "--exit-status". - - Simplified default-setting code. - -* docutils/parsers/rst/__init__.py: - - - Added "--pep-base-url" and "--rfc-base-url" options. - -* docutils/parsers/rst/states.py: - - - Made URI recognition more aggressive and intelligent. - -* docutils/parsers/rst/directives/__init__.py: - - - Added several directive option conversion functions. - -* docutils/parsers/rst/directives/body.py: - - - Moved "table" directive to tables.py. - -* docutils/parsers/rst/directives/tables.py: Table-related directives, - added to project. - -* docutils/writers/latex2e.py: - - - Added "--table-style=(standard|booktabs|nolines)" - - figures get "here" option (LaTeX per default puts them at bottom), - and figure content is centered. - - Rowspan support for tables. - - Fix: admonition titles before first section. - - Replace ``--`` in literal by ``-{}-`` because fontencoding T1 has endash. - - Replave ``_`` in literal by an underlined blank, because it has the correct - width. - - Fix: encode pdfbookmark titles, ``#`` broke pdflatex. - - A few unicode replacements, if output_encoding != utf - - Add "--graphicx-option". - - Indent literal-blocks. - - Fix: omit ``\maketitle`` when there is no document title. - -* docs/index.txt: "Docutils Project Documentation Overview", added to - project. - -* docs/api/cmdline-tool.txt: "Inside A Docutils Command-Line Front-End - Tool", added to project. - -* docs/api/publisher.txt: "The Docutils Publisher", added to project. - -* docs/api/runtime-settings.txt: "Docutils Runtime Settings", added to project. - -* docs/dev/policies.txt: Added to project (extracted from - ``docs/dev/todo.txt``, formerly ``spec/notes.txt``). - -* docs/dev/release.txt: Added to project (extracted from - ``docs/dev/todo.txt``, formerly ``spec/notes.txt``). - -* docs/dev/testing.txt: Added to project. - -* docs/dev/website.txt: Added to project (extracted from - ``docs/dev/todo.txt``, formerly ``spec/notes.txt``). - -* docs/ref/rst/directives.txt: - - - Added directives: "table", "csv-table". - -* docs/user/rst/cheatsheet.txt: "The reStructuredText Cheat Sheet" - added to project. 1 page for syntax, and a 1 page reference for - directives and roles. Source text to be used as-is; not meant to be - converted to HTML. - -* docs/user/rst/demo.txt: Added to project; moved from tools/test.txt - with a change of title. - -* test/functional/, contents, and test/test_functional.py: Added to - project. - -* tools/buildhtml.py: Fixed bug with config file handling. - -* tools/html.py: Removed from project (duplicate of rst2html.py). - -* tools/pep2html.py: Removed from project (duplicate of Python's - nondist/peps/pep2html.py; Docutils' tools/pep.py can be used for - Docutils-related PEPs in docs/peps/). - -* tools/rst2pseudoxml.py: Renamed from publish.py. - -* tools/rst2xml.py: Renamed from docutils-xml.py. - -* tools/test.txt: Removed from project; moved to - docs/user/rst/demo.txt. - -* setup.py: Now also installs ``rst2latex.py``. - - -Release 0.3.3 (2004-05-09) -========================== - -* docutils/__init__.py: - - - 0.3.1: Reorganized config file format (multiple sections); see - docs/config.txt. - - Added unknown_reference_resolvers attribute to TransformSpec. - - 0.3.2: Interpreted text reorganization. - - 0.3.3: Released. - -* docutils/core.py: - - - Catch system messages to stop tracebacks from parsing errors. - - Catch exceptions during processing report & exit without - tracebacks, except when "--traceback" used. - - Reordered components for OptionParser; application comes last. - - Added "config_section" parameter to several methods and functions, - allowing front ends to easily specify their config file sections. - - Added publish_parts convenience function to allow access to individual - parts of a document. - -* docutils/examples.py: Added to project; practical examples of - Docutils client code, to be used as-is or as models for variations. - -* docutils/frontend.py: - - - Added "--traceback" & "--no-traceback" options ("traceback" - setting). - - Implemented support for config file reorganization: - ``standard_config_files`` moved from ``ConfigParser`` to - ``OptionParser``; added - ``OptionParser.get_config_file_settings()`` and - ``.get_standard_config_settings()``; support for old "[options]" - section (with deprecation warning) and mapping from old to new - settings. - - Reimplemented setting validation. - - Enabled flexible boolean values: yes/no, true/false, on/off. - - Added ``Values``, a subclass of ``optparse.Values``, with support - for list setting attributes. - - Added support for new ``DOCUTILSCONFIG`` environment variable; - thanks to Beni Cherniavsky. - - Added "--no-section-numbering" option. - -* docutils/io.py: - - - Catch IOErrors when opening source & destination files, report & - exit without tracebacks. Added ``handle_io_errors`` parameter to - ``FileInput`` & ``FileOutput`` to enable caller error handling. - -* docutils/nodes.py: - - - Changed ``SparseNodeVisitor`` and ``GenericNodeVisitor`` dynamic - method definitions (via ``exec``) to dynamic assignments (via - ``setattr``); thanks to Roman Suzi. - - Encapsulated visitor dynamic assignments in a function; thanks to - Ian Bicking. - - Added indirect_reference_name attribute to the Targetable - class. This attribute holds the whitespace_normalized_name - (contains mixed case) of a target. - -* docutils/statemachine.py: - - - Renamed ``StringList.strip_indent`` to ``.trim_left``. - - Added ``StringList.get_2D_block``. - -* docutils/utils.py: - - - Added "level" attribute to SystemMessage exceptions. - -* docutils/languages/af.py: Added to project; Afrikaans mappings by - Jannie Hofmeyr. - -* docutils/languages/cs.py: Added to project; Czech mappings by Marek - Blaha. - -* docutils/languages/eo.py: Added to project; Esperanto mappings by - Marcelo Huerta San Martin. - -* docutils/languages/pt_br.py: Added to project; Brazilian Portuguese - mappings by Lalo Martins. - -* docutils/languages/ru.py: Added to project; Russian mappings by - Roman Suzi. - -* docutils/parsers/rst/roles.py: Added to project. Contains - interpreted text role functions, a registry for interpreted text - roles, and an API for adding to and retrieving from the registry. - Contributed by Edward Loper. - -* docutils/parsers/rst/states.py: - - - Updated ``RSTState.nested_parse`` for "include" in table cells. - - Allowed true em-dash character and "---" as block quote - attribution marker. - - Added support for <angle-bracketed> complex option arguments - (option lists). - - Fixed handling of backslashes in substitution definitions. - - Fixed off-by-1 error with extra whitespace after substitution - definition directive. - - Added inline markup parsing to field lists' field names. - - Added support for quoted (and unindented) literal blocks. - Driven in part by a bribe from Frank Siebenlist (thanks!). - - Parser now handles escapes in URIs correctly. - - Made embedded-URIs' reference text omittable. Idea from Beni - Cherniavsky. - - Refactored explicit target processing code. - - Added name attribute to references containing the reference name only - through whitespace_normalize_name (no case changes). - - parse_target no longer returns the refname after going through - normalize_name. This is now handled in make_target. - - Fixed bug relating to role-less interpreted text in non-English - contexts. - - Reorganized interpreted text processing; moved code into the new - roles.py module. Contributed by Edward Loper. - - Refactored ``Body.parse_directive`` into ``run_directive`` and - ``parse_directive_block``. - -* docutils/parsers/rst/tableparser.py: - - - Reworked for ``StringList``, to support "include" directives in - table cells. - -* docutils/parsers/rst/directives/__init__.py: - - - Renamed ``unchanged()`` directive option conversion function to - ``unchanged_required``, and added a new ``unchanged``. - - Catch unicode value too high error; fixes bug 781766. - - Beefed up directive error reporting. - -* docutils/parsers/rst/directives/body.py: - - - Added basic "table" directive. - -* docutils/parsers/rst/directives/images.py: - - - Added "target" option to "image" directive. - - Added name attribute to references containing the reference name only - through whitespace_normalize_name (no case changes). - -* docutils/parsers/rst/directives/misc.py: - - - Isolated the import of the ``urllib2`` module; was causing - problems on SourceForge (``libssl.so.2`` unavailable?). - - Added the "role" directive for declaring custom interpreted text - roles. - -* docutils/parsers/rst/directives/parts.py: - - - The "contents" directive does more work up-front, creating the - "topic" and "title", and leaving the "pending" node for the - transform. Allows earlier reference resolution; fixes subtle bug. - -* docutils/parsers/rst/languages/af.py: Added to project; Afrikaans - mappings by Jannie Hofmeyr. - -* docutils/parsers/rst/languages/cs.py: Added to project; Czech - mappings by Marek Blaha. - -* docutils/parsers/rst/languages/eo.py: Added to project; Esperanto - mappings by Marcelo Huerta San Martin. - -* docutils/parsers/rst/languages/pt_br.py: Added to project; Brazilian - Portuguese mappings by Lalo Martins. - -* docutils/parsers/rst/languages/ru.py: Added to project; Russian - mappings by Roman Suzi. - -* docutils/transforms/parts.py: - - - The "contents" directive does more work up-front, creating the - "topic" and "title", and leaving the "pending" node for the - transform. Allows earlier reference resolution; fixes subtle bug. - - Added support for disabling of section numbering. - -* docutils/transforms/references.py: - - - Verifying that external targets are truly targets and not indirect - references. This is because we are now adding a "name" attribute to - references in addition to targets. Note sure if this is correct! - - Added code to hook into the unknown_reference_resolvers list for a - transformer in resolve_indirect_target. This allows the - unknown_reference_resolvers to keep around indirect targets which - docutils doesn't know about. - - Added specific error message for duplicate targets. - -* docutils/transforms/universal.py: - - - Added FilterMessages transform (removes system messages below the - verbosity threshold). - - Added hook (via docutils.TransformSpec.unknown_reference_resolvers) - to FinalCheckVisitor for application-specific handling of - unresolvable references. - - Added specific error message for duplicate targets. - -* docutils/writers/__init__.py: - - - Added assemble_parts method to the Writer class to allow for - access to a documents individual parts. - - Documented & set default for ``Writer.output`` attribute. - -* docutils/writers/html4css1.py: - - - Fixed unicode handling of attribute values (bug 760673). - - Prevent duplication of "class" attribute values (bug report from - Kirill Lapshin). - - Improved table grid/border handling (prompted by report from Bob - Marshall). - - Added support for table titles. - - Added "<title />" for untitled docs, for XHTML conformance; thanks - to Darek Suchojad. - - Added functionality to keep track of individual parts of a document - and store them in a dictionary as the "parts" attribute of the writer. - Contributed by Reggie Dugard at the Docutils sprint at PyCon DC 2004. - - Added proper support for the "scale" attribute of the "image" - element. Contributed by Brent Cook. - - Added ``--initial-header-level`` option. - - Fixed bug: the body_pre_docinfo segment depended on there being a - docinfo; if no docinfo, the document title was incorporated into - the body segment. Adversely affected the publish_parts interface. - -* docutils/writers/latex2e.py: - - - Changed default stylesheet to "no stylesheet" to avoid latex complaining - about a missing file. - - Added options and support: ``--compound-enumerators``, - ``--section-prefix-for-enumerators``, and - ``--section-enumerator-separator``. By John F Meinel Jr (SF patch - 934322). - - Added option ``--use-verbatim-when-possible``, to avoid - problematic characters (eg, '~' in italian) in literal blocks. - - It's now possible to use four section levels in the `book` and - `report` LaTeX classes. The default `article` class still has - three levels limit. - -* docs/config.txt: "Docutils Configuration Files", added to project. - Moved config file entry descriptions from tools.txt. - -* docs/tools.txt: - - - Moved config file entry descriptions to config.txt. - -* spec/notes.txt: Continual updates. Added "Setting Up For Docutils - Development". - -* spec/howto/rst-roles.txt: "Creating reStructuredText Interpreted - Text Roles", added to project. - -* spec/rst/reStructuredText.txt: - - - Added description of support for <angle-bracketed> complex option - arguments to option lists. - - Added subsections for indented and quoted literal blocks. - -* test: Continually adding & updating tests. - - - Added test/test_settings.py & test/data/config_*.txt support - files. - - Added test/test_writers/test_htmlfragment.py. - -* test/DocutilsTestSupport.py: - - - Refactored LaTeX publisher test suite/case class names to make - testing other writers easier. - - Added HtmlWriterPublishTestCase and HtmlFragmentTestSuite classes - to test the processing of HTML fragments which use the new - publish_parts convenience function. - -* tools/buildhtml.py: - - - Added support for the "--prune" option. - - Removed dependency on pep2html.py; plaintext PEPs no longer - supported. - -* tools/docutils.conf: - - - Updated for configuration file reorganization. - -* tools/rst2html.py: - - - copied from tools/html.py - -* setup.py: - - - added a 'scripts' section to configuration - - added 'tools/rst2html.py' to the scripts section - - -Release 0.3 (2003-06-24) -======================== - -General: - -* Renamed "attribute" to "option" for directives/extensions. - -* Renamed transform method "transform" to "apply". - -* Renamed "options" to "settings" for runtime settings (as set by - command-line options). Sometimes "option" (singular) became - "settings" (plural). Some variations below: - - - document.options -> document.settings (stored in other objects as - well) - - option_spec -> settings_spec (not directives though) - - OptionSpec -> SettingsSpec - - cmdline_options -> settings_spec - - relative_path_options -> relative_path_settings - - option_default_overrides -> settings_default_overrides - - Publisher.set_options -> Publisher.get_settings - -Specific: - -* COPYING.txt: Added "Public Domain Dedication". - -* FAQ.txt: Frequently asked questions, added to project. - -* setup.py: - - - Updated with PyPI Trove classifiers. - - Conditional installation of third-party modules. - -* docutils/__init__.py: - - - Bumped version to 0.2.1 to reflect changes to I/O classes. - - Bumped version to 0.2.2 to reflect changes to stylesheet options. - - Factored ``SettingsSpec`` out of ``Component``; separately useful. - - Bumped version to 0.2.3 because of the new "--embed-stylesheet" - option and its effect on the PEP template & writer. - - Bumped version to 0.2.4 due to changes to the PEP template & - stylesheet. - - Bumped version to 0.2.5 to reflect changes to Reporter output. - - Added ``TransformSpec`` class for new transform system. - - Bumped version to 0.2.6 for API changes (renaming). - - Bumped version to 0.2.7 for new ``docutils.core.publish_*`` - convenience functions. - - Added ``Component.component_type`` attribute. - - Bumped version to 0.2.8 because of the internal parser switch from - plain lists to the docutils.statemachine.StringList objects. - - Bumped version to 0.2.9 because of the frontend.py API changes. - - Bumped version to 0.2.10 due to changes to the project layout - (third-party modules removed from the "docutils" package), and - signature changes in ``io.Input``/``io.Output``. - - Changed version to 0.3.0 for release. - -* docutils/core.py: - - - Made ``publish()`` a bit more convenient. - - Generalized ``Publisher.set_io``. - - Renamed ``publish()`` to ``publish_cmdline()``; rearranged its - parameters; improved its docstring. - - Added ``publish_file()`` and ``publish_string()``. - - Factored ``Publisher.set_source()`` and ``.set_destination()`` - out of ``.set_io``. - - Added support for "--dump-pseudo-xml", "--dump-settings", and - "--dump-transforms" hidden options. - - Added ``Publisher.apply_transforms()`` method. - - Added ``Publisher.set_components()`` method; support for - ``publish_*()`` conveninece functions. - - Moved config file processing to docutils/frontend.py. - - Added support for exit status ("exit_level" setting & - ``enable_exit`` parameter for Publisher.publish() and convenience - functions). - -* docutils/frontend.py: - - - Check for & exit on identical source & destination paths. - - Fixed bug with absolute paths & "--config". - - Set non-command-line defaults in ``OptionParser.__init__()``: - ``_source`` & ``_destination``. - - Distributed ``relative_path_settings`` to components; updated - ``OptionParser.populate_from_components()`` to combine it all. - - Require list of keys in ``make_paths_absolute`` (was implicit in - global ``relative_path_settings``). - - Added "--expose-internal-attribute", "--dump-pseudo-xml", - "--dump-settings", and "--dump-transforms" hidden options. - - Removed nasty internals-fiddling ``ConfigParser.get_section`` - code, replaced with correct code. - - Added validation functionality for config files. - - Added "--error-encoding" option/setting, "_disable_config" - internal setting. - - Added encoding validation; updated "--input-encoding" and - "--output-encoding"; added "--error-encoding-error-handler" and - "--output-encoding-error-handler". - - Moved config file processing from docutils/core.py. - - Updated ``OptionParser.populate_from_components`` to handle new - ``SettingsSpec.settings_defaults`` dict. - - Added support for "-" => stdin/stdout. - - Added "exit_level" setting ("--exit" option). - -* docutils/io.py: - - - Split ``IO`` classes into subclasses of ``Input`` and ``Output``. - - Added automatic closing to ``FileInput`` and ``FileOutput``. - - Delayed opening of ``FileOutput`` file until ``write()`` called. - - ``FileOutput.write()`` now returns the encoded output string. - - Try to get path/stream name automatically in ``FileInput`` & - ``FileOutput``. - - Added defaults for source & destination paths. - - Allow for Unicode I/O with an explicit "unicode" encoding. - - Added ``Output.encode()``. - - Removed dependency on runtime settings; pass encoding directly. - - Recognize Unicode strings in ``Input.decode()``. - - Added support for output encoding error handlers. - -* docutils/nodes.py: - - - Added "Invisible" element category class. - - Changed ``Node.walk()`` & ``.walkabout()`` to permit more tree - modification during a traversal. - - Added element classes: ``line_block``, ``generated``, ``address``, - ``sidebar``, ``rubric``, ``attribution``, ``admonition``, - ``superscript``, ``subscript``, ``inline`` - - Added support for lists of nodes to ``Element.insert()``. - - Fixed parent linking in ``Element.replace()``. - - Added new abstract superclass ``FixedTextElement``; adds - "xml:space" attribute. - - Added support for "line" attribute of ``system_message`` nodes. - - Added support for the observer pattern from ``utils.Reporter``. - Added ``parse_messages`` and ``transform_messages`` attributes to - ``document``, removed ``messages``. Added ``note_parse_message`` - and ``note_transform_message`` methods. - - Added support for improved diagnostics: - - - Added "document", "source", and "line" internal attributes to - ``Node``, set by ``Node.setup_child()``. - - Converted variations on ``node.parent = self`` to - ``self.setup_child(node)``. - - Added ``document.current_source`` & ``.current_line`` - attributes, and ``.note_source`` observer method. - - Changed "system_message" output to GNU-Tools format. - - - Added a "rawsource" attribute to the ``Text`` class, for text - before backslash-escape resolution. - - Support for new transform system. - - Reworked ``pending`` element. - - Fixed XML DOM bug (SF #660611). - - Removed the ``interpeted`` element class and added - ``title_reference``, ``abbreviation``, ``acronym``. - - Made substitutions case-sensitive-but-forgiving; moved some code - from the parser. - - Fixed Unicode bug on element attributes (report: William Dode). - -* docutils/optik.py: Removed from project; replaced with - extras/optparse.py and extras/textwrap.py. These will be installed - only if they're not already present in the Python installation. - -* docutils/roman.py: Moved to extras/roman.py; this will be installed - only if it's not already present in the Python installation. - -* docutils/statemachine.py: - - - Factored out ``State.add_initial_transitions()`` so it can be - extended. - - Converted whitespace-specific "blank" and "indent" transitions - from special-case code to ordinary transitions: removed - ``StateMachineWS.check_line()`` & ``.check_whitespace()``, added - ``StateWS.add_initial_transitions()`` method, ``ws_patterns`` & - ``ws_initial_transitions`` attributes. - - Removed ``State.match_transition()`` after merging it into - ``.check_line()``. - - Added ``StateCorrection`` exception. - - Added support for ``StateCorrection`` in ``StateMachine.run()`` - (moved ``TransitionCorrection`` support there too.) - - Changed ``StateMachine.next_line()`` and ``.goto_line()`` to raise - ``EOFError`` instead of ``IndexError``. - - Added ``State.no_match`` method. - - Added support for the Observer pattern, triggered by input line - changes. - - Added ``strip_top`` parameter to - ``StateMachineWS.get_first_known_indented``. - - Made ``context`` a parameter to ``StateMachine.run()``. - - Added ``ViewList`` & ``StringList`` classes; - ``extract_indented()`` becomes ``StringList.get_indented()``. - - Added ``StateMachine.insert_input()``. - - Fixed ViewList slice handling for Python 2.3. Patch from (and - thanks to) Fred Drake. - -* docutils/utils.py: - - - Added a ``source`` attribute to Reporter instances and - ``system_message`` elements. - - Added an observer pattern to ``utils.Reporter`` to keep track of - system messages. - - Fixed bugs in ``relative_path()``. - - Added support for improved diagnostics. - - Moved ``normalize_name()`` to nodes.py (``fully_normalize_name``). - - Added support for encoding Reporter stderr output, and encoding - error handlers. - - Reporter keeps track of the highest level system message yet - generated. - -* docutils/languages: Fixed bibliographic field language lookups. - -* docutils/languages/es.py: Added to project; Spanish mappings by - Marcelo Huerta San Martin. - -* docutils/languages/fr.py: Added to project; French mappings by - Stefane Fermigier. - -* docutils/languages/it.py: Added to project; Italian mappings by - Nicola Larosa. - -* docutils/languages/sk.py: Added to project; Slovak mappings by - Miroslav Vasko. - -* docutils/parser/__init__.py: - - - Added ``Parser.finish_parse()`` method. - -* docutils/parser/rst/__init__.py: - - - Added options: "--pep-references", "--rfc-references", - "--tab-width", "--trim-footnote-reference-space". - -* docutils/parsers/rst/states.py: - - - Changed "title under/overline too short" system messages from INFO - to WARNING, and fixed its insertion location. - - Fixed enumerated list item parsing to allow paragraphs & section - titles to begin with enumerators. - - Converted system messages to use the new "line" attribute. - - Fixed a substitution reference edge case. - - Added support for "--pep-references" and "--rfc-references" - options; reworked ``Inliner`` code to make customization easier. - - Removed field argument parsing. - - Added support for short section title over/underlines. - - Fixed "simple reference name" regexp to ignore text like - "object.__method__"; not an anonymous reference. - - Added support for improved diagnostics. - - Reworked directive API, based on Dethe Elza's contribution. Added - ``Body.parse_directive()``, ``.parse_directive_options()``, - ``.parse_directive_arguments()`` methods. - - Added ``ExtensionOptions`` class, to parse directive options - without parsing field bodies. Factored - ``Body.parse_field_body()`` out of ``Body.field()``, overridden in - ``ExtensionOptions``. - - Improved definition list term/classifier parsing. - - Added warnings for unknown directives. - - Renamed ``Stuff`` to ``Struct``. - - Now flagged as errors: transitions at the beginning or end of - sections, empty sections (except title), and empty documents. - - Updated for ``statemachine.StringList``. - - Enabled recognition of schemeless email addresses in targets. - - Added support for embedded URIs in hyperlink references. - - Added backslash-escapes to inline markup end-string suffix. - - Added support for correct interpreted text processing. - - Fixed nested title parsing (topic, sidebar directives). - - Added special processing of backslash-escaped whitespace (idea - from David Abrahams). - - Made substitutions case-sensitive-but-forgiving; moved some code - to ``docutils.nodes``. - - Added support for block quote attributions. - - Added a kludge to work-around a conflict between the bubble-up - parser strategy and short titles (<= 3 char-long over- & - underlines). Fixes SF bug #738803 "infinite loop with multiple - titles" submitted by Jason Diamond. - - Added explicit interpreted text roles for standard inline markup: - "emphasis", "strong", "literal". - - Implemented "superscript" and "subscript" interpreted text roles. - - Added initial support for "abbreviation" and "acronym" roles; - incomplete. - - Added support for "--trim-footnote-reference-space" option. - - Optional space before colons in directives & hyperlink targets. - -* docutils/parsers/rst/tableparser.py: - - - Fixed a bug that was producing unwanted empty rows in "simple" - tables. - - Detect bad column spans in "simple" tables. - -* docutils/parsers/rst/directives: Updated all directive functions to - new API. - -* docutils/parsers/rst/directives/__init__.py: - - - Added ``flag()``, ``unchanged()``, ``path()``, - ``nonnegative_int()``, ``choice()``, and ``class_option()`` - directive option helper functions. - - Added warnings for unknown directives. - - Return ``None`` for missing directives. - - Added ``register_directive()``, thanks to William Dode and Paul - Moore. - -* docutils/parsers/rst/directives/admonitions.py: - - - Added "admonition" directive. - -* docutils/parsers/rst/directives/body.py: Added to project. Contains - the "topic", "sidebar" (from Patrick O'Brien), "line-block", - "parsed-literal", "rubric", "epigraph", "highlights" and - "pull-quote" directives. - -* docutils/parsers/rst/directives/images.py: - - - Added an "align" attribute to the "image" & "figure" directives - (by Adam Chodorowski). - - Added "class" option to "image", and "figclass" to "figure". - -* docutils/parsers/rst/directives/misc.py: - - - Added "include", "raw", and "replace" directives, courtesy of - Dethe Elza. - - Added "unicode" and "class" directives. - -* docutils/parsers/rst/directives/parts.py: - - - Added the "sectnum" directive; by Dmitry Jemerov. - - Added "class" option to "contents" directive. - -* docutils/parsers/rst/directives/references.py: Added to project. - Contains the "target-notes" directive. - -* docutils/parsers/rst/languages/__init__.py: - - - Return ``None`` from get_language() for missing language modules. - -* docutils/parsers/rst/languages/de.py: Added to project; German - mappings by Engelbert Gruber. - -* docutils/parsers/rst/languages/en.py: - - - Added interpreted text roles mapping. - -* docutils/parsers/rst/languages/es.py: Added to project; Spanish - mappings by Marcelo Huerta San Martin. - -* docutils/parsers/rst/languages/fr.py: Added to project; French - mappings by William Dode. - -* docutils/parsers/rst/languages/it.py: Added to project; Italian - mappings by Nicola Larosa. - -* docutils/parsers/rst/languages/sk.py: Added to project; Slovak - mappings by Miroslav Vasko. - -* docutils/readers/__init__.py: - - - Added support for the observer pattern from ``utils.Reporter``, in - ``Reader.parse`` and ``Reader.transform``. - - Removed ``Reader.transform()`` method. - - Added default parameter values to ``Reader.__init__()`` to make - instantiation easier. - - Removed bogus aliases: "restructuredtext" is *not* a Reader. - -* docutils/readers/pep.py: - - - Added the ``peps.TargetNotes`` transform to the Reader. - - Removed PEP & RFC reference detection code; moved to - parsers/rst/states.py as options (enabled here by default). - - Added support for pre-acceptance PEPs (no PEP number yet). - - Moved ``Inliner`` & made it a class attribute of ``Reader`` for - easy subclassing. - -* docutils/readers/python: Python Source Reader subpackage added to - project, including preliminary versions of: - - - __init__.py - - moduleparser.py: Parser for Python modules. - -* docutils/transforms/__init__.py: - - - Added ``Transformer`` class and completed transform reform. - - Added unknown_reference_resolvers list for each transformer. This list holds - the list of functions provided by each component of the transformer that - help resolve references. - -* docutils/transforms/frontmatter.py: - - - Improved support for generic fields. - - Fixed bibliographic field language lookups. - -* docutils/transforms/misc.py: Added to project. Miscellaneous - transforms. - -* docutils/transforms/parts.py: - - - Moved the "id" attribute from TOC list items to the references - (``Contents.build_contents()``). - - Added the ``SectNum`` transform; by Dmitry Jemerov. - - Added "class" attribute support to ``Contents``. - -* docutils/transforms/peps.py: - - - Added ``mask_email()`` function, updating to pep2html.py's - functionality. - - Linked "Content-Type: text/x-rst" to PEP 12. - - Added the ``TargetNotes`` PEP-specific transform. - - Added ``TargetNotes.cleanup_callback``. - - Added title check to ``Headers``. - -* docutils/transforms/references.py: - - - Added the ``TargetNotes`` generic transform. - - Split ``Hyperlinks`` into multiple transforms. - - Fixed bug with multiply-indirect references (report: Bruce Smith). - - Added check for circular indirect references. - - Made substitutions case-sensitive-but-forgiving. - -* docutils/transforms/universal.py: - - - Added support for the "--expose-internal-attributes" option. - - Removed ``Pending`` transform classes & data. - -* docutils/writers/__init__.py: - - - Removed ``Writer.transform()`` method. - -* docutils/writers/docutils-xml.py: - - - Added XML and doctype declarations. - - Added "--no-doctype" and "--no-xml-declaration" options. - -* docutils/writers/html4css1.py: - - - "name" attributes only on these tags: a, applet, form, frame, - iframe, img, map. - - Added "name" attribute to <a> in section titles for Netscape 4 - support (bug report: Pearu Peterson). - - Fixed targets (names) on footnote, citation, topic title, - problematic, and system_message nodes (for Netscape 4). - - Changed field names from "<td>" to "<th>". - - Added "@" to "@" encoding to thwart address harvesters. - - Improved the vertical whitespace optimization; ignore "invisible" - nodes (targets, comments, etc.). - - Improved inline literals with ``<span class="pre">`` around chunks - of text and `` `` for runs of spaces. - - Improved modularity of output; added ``self.body_pre_docinfo`` and - ``self.docinfo`` segments. - - Added support for "line_block", "address" elements. - - Improved backlinks (footnotes & system_messages). - - Improved system_message output. - - Redefined "--stylesheet" as containing an invariant URL, used - verbatim. Added "--stylesheet-path", interpreted w.r.t. the - working directory. - - Added "--footnote-references" option (superscript or brackets). - - Added "--compact-lists" and "--no-compact-lists" options. - - Added "--embed-stylesheet" and "--link-stylesheet" options; - factored out ``HTMLTranslator.get_stylesheet_reference()``. - - Improved field list rendering. - - Added Docutils version to "generator" meta tag. - - Fixed a bug with images; they must be inline, so wrapped in <p>. - - Improved layout of <pre> HTML source. - - Fixed attribute typo on <colspec>. - - Refined XML prologue. - - Support for no stylesheet. - - Removed "interpreted" element support. - - Added support for "title_reference", "sidebar", "attribution", - "rubric", and generic "admonition" elements. - - Added "--attribution" option. - - Added support for "inline", "subscript", "superscript" elements. - - Added initial support for "abbreviation" and "acronym"; - incomplete. - -* docutils/writers/latex2e.py: LaTeX Writer, added by Engelbert Gruber - (from the sandbox). - - - Added french. - - Double quotes in literal blocks (special treatment for de/ngerman). - - Added '--hyperlink-color' option ('0' turns off coloring of links). - - Added "--attribution" option. - - Right align attributions. - -* docutils/writers/pep_html.py: - - - Parameterized output encoding in PEP template. - - Reworked substitutions from ``locals()`` into ``subs`` dict. - - Redefined "--pep-stylesheet" as containing an invariant URL, used - verbatim. Added "--pep-stylesheet-path", interpreted w.r.t. the - working directory. - - Added an override on the "--footnote-references" option. - - Factored out ``HTMLTranslator.get_stylesheet_reference()``. - - Added Docutils version to "generator" meta tag. - - Added a "DO NOT EDIT THIS FILE" comment to generated HTML. - -* docs/tools.txt: - - - Added a "silent" setting for ``buildhtml.py``. - - Added a "Getting Help" section. - - Rearranged the structure. - - Kept up to date, with new settings, command-line options etc. - - Added section for ``rst2latex.py`` (Engelbert Gruber). - - Converted settings table into a definition list. - -* docs/rst/quickstart.txt: - - - Added a table of contents. - - Added feedback information. - - Added mention of minimum section title underline lengths. - - Removed the 4-character minimum for section title underlines. - -* docs/rst/quickref.html: - - - Added a "Getting Help" section. - - Added a style to make section title backlinks more subtle. - - Added mention of minimum section title underline lengths. - - Removed the 4-character minimum for section title underlines. - -* extras: Directory added to project; contains third-party modules - that Docutils depends on (optparse, textwrap, roman). These are - only installed if they're not already present. - -* licenses: Directory added to project; contains copies of license - files for non-public-domain files. - -* spec/doctree.txt: - - - Changed the focus. It's about DTD elements: structural - relationships, semantics, and external (public) attributes. Not - about the element class library. - - Moved some implementation-specific stuff into ``docutils.nodes`` - docstrings. - - Wrote descriptions of all common attributes and parameter - entities. Filled in introductory material. - - Working through the element descriptions: 55 down, 37 to go. - - Removed "Representation of Horizontal Rules" to - spec/rst/alternatives.txt. - -* spec/docutils.dtd: - - - Added "generated" inline element. - - Added "line_block" body element. - - Added "auto" attribute to "title". - - Changed content models of "literal_block" and "doctest_block" to - ``%text.model``. - - Added ``%number;`` attribute type parameter entity. - - Changed ``%structural.elements;`` to ``%section.elements``. - - Updated attribute types; made more specific. - - Added "address" bibliographic element. - - Added "line" attribute to ``system_message`` element. - - Removed "field_argument" element; "field_name" may contain - multiple words and whitespace. - - Changed public identifier to docutils.sf.net. - - Removed "interpreted" element; added "title_reference", - "abbreviation", "acronym". - - Removed "refuri" attribute from "footnote_reference" and - "citation_reference". - - Added "sidebar", "rubric", "attribution", "admonition", - "superscript", "subscript", and "inline" elements. - -* spec/pep-0256.txt: Converted to reStructuredText & updated. - -* spec/pep-0257.txt: Converted to reStructuredText & updated. - -* spec/pep-0258.txt: Converted to reStructuredText & updated. - -* spec/semantics.txt: Updated with text from a Doc-SIG response to - Dallas Mahrt. - -* spec/transforms.txt: Added to project. - -* spec/howto: Added subdirectory, for developer how-to docs. - -* spec/howto/rst-directives.txt: Added to project. Original by Dethe - Elza, edited & extended by David Goodger. - -* spec/howto/i18n.txt: Docutils Internationalization. Added to - project. - -* spec/rst/alternatives.txt: - - - Added "Doctree Representation of Transitions" from - spec/doctree.txt. - - Updated "Inline External Targets" & closed the debate. - - Added ideas for interpreted text syntax extensions. - - Added "Nested Inline Markup" section. - -* spec/rst/directives.txt: - - - Added directives: "topic", "sectnum", "target-notes", - "line-block", "parsed-literal", "include", "replace", "sidebar", - "admonition", "rubric", "epigraph", "highlights", "unicode" and - "class". - - Formalized descriptions of directive details. - - Added an "align" attribute to the "image" & "figure" directives - (by Adam Chodorowski). - - Added "class" options to "topic", "sidebar", "line-block", - "parsed-literal", "contents", and "image"; and "figclass" to - "figure". - -* spec/rst/interpreted.txt: Added to project. Descriptions of - interpreted text roles. - -* spec/rst/introduction.txt: - - - Added pointers to material for new users. - -* spec/rst/reStructuredText.txt: - - - Disambiguated comments (just add a newline after the "::"). - - Updated enumerated list description; added a discussion of the - second-line validity checking. - - Updated directive description. - - Added a note redirecting newbies to the user docs. - - Expanded description of inline markup start-strings in non-markup - contexts. - - Removed field arguments and made field lists a generic construct. - - Removed the 4-character minimum for section title underlines. - - Clarified term/classifier delimiter & inline markup ambiguity - (definition lists). - - Added "Embedded URIs". - - Updated "Interpreted Text" section. - - Added "Character-Level Inline Markup" section. - -* test: Continually adding & updating tests. - - - Moved test/test_rst/ to test/test_parsers/test_rst/. - - Moved test/test_pep/ to test/test_readers/test_pep/. - - Added test/test_readers/test_python/. - - Added test/test_writers/ (Engelbert Gruber). - -* tools: - - - Made the ``locale.setlocale()`` calls in front ends - fault-tolerant. - -* tools/buildhtml.py: - - - Added "--silent" option. - - Fixed bug with absolute paths & "--config". - - Updated for new I/O classes. - - Added some exception handling. - - Separated publishers' setting defaults; prevents interference. - - Updated for new ``publish_file()`` convenience function. - -* tools/pep-html-template: - - - Allow for "--embed-stylesheet". - - Added Docutils version to "generator" meta tag. - - Added a "DO NOT EDIT THIS FILE" comment to generated HTML. - - Conform to XHTML spec. - -* tools/pep2html.py: - - - Made ``argv`` a parameter to ``main()``. - - Added support for "Content-Type:" header & arbitrary PEP formats. - - Linked "Content-Type: text/plain" to PEP 9. - - Files skipped (due to an error) are not pushed onto the server. - - Updated for new I/O classes. - - Added ``check_requirements()`` & ``pep_type_error()``. - - Added some exception handling. - - Updated for new ``publish_string()`` convenience function. - - Added a "DO NOT EDIT THIS FILE" comment to generated HTML. - -* tools/quicktest.py: - - - Added "-V"/"--version" option. - -* tools/rst2latex.py: LaTeX front end, added by Engelbert Gruber. - -* tools/unicode2rstsubs.py: Added to project. Produces character - entity files (reSructuredText substitutions) from the MathML master - unicode.xml file. - -* tools/editors: Support code for editors, added to project. Contains - ``emacs/restructuredtext.el``. - -* tools/stylesheets/default.css: Moved into the stylesheets directory. - - - Added style for chunks of inline literals. - - Removed margin for first child of table cells. - - Right-aligned field list names. - - Support for auto-numbered section titles in TOCs. - - Increased the size of inline literals (<tt>) in titles. - - Restored the light gray background for inline literals. - - Added support for "line_block" elements. - - Added style for "address" elements. - - Removed "a.footnote-reference" style; doing it with ``<sup>`` now. - - Improved field list rendering. - - Vertical whitespace improvements. - - Removed "a.target" style. - -* tools/stylesheets/pep.css: - - - Fixed nested section margins. - - Other changes parallel those of ``../default.css``. - - -Release 0.2 (2002-07-31) -======================== - -General: - -- The word "component" was being used ambiguously. From now on, - "component" will be used to mean "Docutils component", as in Reader, - Writer, Parser, or Transform. Portions of documents (Table of - Contents, sections, etc.) will be called "document parts". -- Did a grand renaming: a lot of ``verylongnames`` became - ``very_long_names``. -- Cleaned up imports: no more relative package imports or - comma-separated lists of top-level modules. -- Added support for an option values object which carries default - settings and overrides (from command-line options and library use). -- Added internal Unicode support, and support for both input and - output encodings. -- Added support for the ``docutils.io.IO`` class & subclasses. - -Specific: - -* docutils/__init__.py: - - - Added ``ApplicationError`` and ``DataError``, for use throughout - the package. - - Added ``Component`` base class for Docutils components; implements - the ``supports`` method. - - Added ``__version__`` (thus, ``docutils.__version__``). - -* docutils/core.py: - - - Removed many keyword parameters to ``Publisher.__init__()`` and - ``publish()``; bundled into an option values object. Added - "argv", "usage", "description", and "option_spec" parameters for - command-line support. - - Added ``Publisher.process_command_line()`` and ``.set_options()`` - methods. - - Reworked I/O model for ``docutils.io`` wrappers. - - Updated ``Publisher.set_options()``; now returns option values - object. - - Added support for configuration files (/etc/docutils.conf, - ./docutils.conf, ~/.docutils). - - Added ``Publisher.setup_option_parser()``. - - Added default usage message and description. - -* docutils/frontend.py: Added to project; support for front-end - (command-line) scripts. Option specifications may be augmented by - components. Requires Optik (http://optik.sf.net/) for option - processing (installed locally as docutils/optik.py). - -* docutils/io.py: Added to project; uniform API for a variety of input - output mechanisms. - -* docutils/nodes.py: - - - Added ``TreeCopyVisitor`` class. - - Added a ``copy`` method to ``Node`` and subclasses. - - Added a ``SkipDeparture`` exception for visitors. - - Renamed ``TreePruningException`` from ``VisitorException``. - - Added docstrings to ``TreePruningException``, subclasses, and - ``Nodes.walk()``. - - Improved docstrings. - - Added ``SparseNodeVisitor``, refined ``NodeVisitor``. - - Moved ``utils.id()`` to ``nodes.make_id()`` to avoid circular - imports. - - Added ``decoration``, ``header``, and ``footer`` node classes, and - ``PreDecorative`` mixin. - - Reworked the name/id bookkeeping; to ``document``, removed - ``explicit_targets`` and ``implicit_targets`` attributes, added - ``nametypes`` attribute and ``set_name_id_map`` method. - - Added ``NodeFound`` exception, for use with ``NodeVisitor`` - traversals. - - Added ``document.has_name()`` method. - - Fixed DOM generation for list-attributes. - - Added category class ``Labeled`` (used by footnotes & citations). - - Added ``Element.set_class()`` method (sets "class" attribute). - -* docutils/optik.py: Added to project. Combined from the Optik - package, with added option groups and other modifications. The use - of this module is probably only temporary. - -* docutils/statemachine.py: - - - Added ``runtime_init`` method to ``StateMachine`` and ``State``. - - Added underscores to improve many awkward names. - - In ``string2lines()``, changed whitespace normalizing translation - table to regexp; restores Python 2.0 compatibility with Unicode. - -* docutils/urischemes.py: - - - Filled in some descriptions. - - Added "shttp" scheme. - -* docutils/utils.py: - - - Added ``clean_rcs_keywords`` function (moved from - docutils/transforms/frontmatter.py - ``DocInfo.filter_rcs_keywords``). - - Added underscores to improve many awkward names. - - Changed names of Reporter's thresholds: - warning_level -> report_level; error_level -> halt_level. - - Moved ``utils.id()`` to ``nodes.make_id()``. - - Added ``relative_path(source, target)``. - -* docutils/languages/de.py: German mappings; added to project. Thanks - to Gunnar Schwant for the translations. - -* docutils/languages/en.py: Added "Dedication" bibliographic field - mappings. - -* docutils/languages/sv.py: Swedish mappings; added to project by Adam - Chodorowski. - -* docutils/parsers/rst/states.py: - - - Added underscores to improve many awkward names. - - Added RFC-2822 header support. - - Extracted the inline parsing code from ``RSTState`` to a separate - class, ``Inliner``, which will allow easy subclassing. - - Made local bindings for ``memo`` container & often-used contents - (reduces code complexity a lot). See ``RSTState.runtime_init()``. - - ``RSTState.parent`` replaces ``RSTState.statemachine.node``. - - Added ``MarkupMismatch`` exception; for late corrections. - - Added ``-/:`` characters to inline markup's start string prefix, - ``/`` to end string suffix. - - Fixed a footnote bug. - - Fixed a bug with literal blocks. - - Applied patch from Simon Budig: simplified regexps with symbolic - names, removed ``Inliner.groups`` and ``Body.explicit.groups``. - - Converted regexps from ``'%s' % var`` to ``'%(var)s' % locals()``. - - Fixed a bug in ``Inliner.interpreted_or_phrase_ref()``. - - Allowed non-ASCII in "simple names" (directive names, field names, - references, etc.). - - Converted ``Inliner.patterns.initial`` to be dynamically built - from parts with ``build_regexp()`` function. - - Changed ``Inliner.inline_target`` to ``.inline_internal_target``. - - Updated docstrings. - - Changed "table" to "grid_table"; added "simple_table" support. - -* docutils/parsers/rst/tableparser.py: - - - Changed ``TableParser`` to ``GridTableParser``. - - Added ``SimpleTableParser``. - - Refactored naming. - -* docutils/parsers/rst/directives/__init__.py: Added "en" (English) as - a fallback language for directive names. - -* docutils/parsers/rst/directives/html.py: Changed the ``meta`` - directive to use a ``pending`` element, used only by HTML writers. - -* docutils/parsers/rst/directives/parts.py: Renamed from - components.py. - - - Added "backlinks" attribute to "contents" directive. - -* docutils/parsers/rst/languages/sv.py: Swedish mappings; added to - project by Adam Chodorowski. - -* docutils/readers/__init__.py: Gave Readers more control over - choosing and instantiating Parsers. - -* docutils/readers/pep.py: Added to project; for PEP processing. - -* docutils/transforms/__init__.py: ``Transform.__init__()`` now - requires a ``component`` parameter. - -* docutils/transforms/components.py: Added to project; transforms - related to Docutils components. - -* docutils/transforms/frontmatter.py: - - - In ``DocInfo.extract_authors``, check for a single "author" in an - "authors" group, and convert it to a single "author" element. - - Added support for "Dedication" and generic bibliographic fields. - -* docutils/transforms/peps.py: Added to project; PEP-specific. - -* docutils/transforms/parts.py: Renamed from old components.py. - - - Added filter for `Contents`, to use alt-text for inline images, - and to remove inline markup that doesn't make sense in the ToC. - - Added "name" attribute to TOC topic depending on its title. - - Added support for optional TOC backlinks. - -* docutils/transforms/references.py: Fixed indirect target resolution - in ``Hyperlinks`` transform. - -* docutils/transforms/universal.py: - - - Changed ``Messages`` transform to properly filter out system - messages below the warning threshold. - - Added ``Decorations`` transform (support for ``--generator``, - ``--date``, ``--time``, ``--source-link`` options). - -* docutils/writers/__init__.py: Added "pdf" alias in anticipation of - Engelbert Gruber's PDF writer. - -* docutils/writers/html4css1.py: - - - Made XHTML-compatible (switched to lowercase element & attribute - names; empty tag format). - - Escape double-dashes in comment text. - - Improved boilerplate & modularity of output. - - Exposed modular output in Writer class. - - Added a "generator" meta tag to <head>. - - Added support for the ``--stylesheet`` option. - - Added support for ``decoration``, ``header``, and ``footer`` - elements. - - In ``HTMLTranslator.attval()``, changed whitespace normalizing - translation table to regexp; restores Python 2.0 compatibility - with Unicode. - - Added the translator class as instance variable to the Writer, to - make it easily subclassable. - - Improved option list spacing (thanks to Richard Jones). - - Modified field list output. - - Added backlinks to footnotes & citations. - - Added percentage widths to "<col>" tags (from colspec). - - Option lists: "<code>" changed to "<kbd>", ``option_argument`` - "<span>" changed to "<var>". - - Inline literals: "<code>" changed to "<tt>". - - Many changes to optimize vertical space: compact simple lists etc. - - Add a command-line options & directive attributes to control TOC - and footnote/citation backlinks. - - Added support for optional footnote/citation backlinks. - - Added support for generic bibliographic fields. - - Identify backrefs. - - Relative URLs for stylesheet links. - -* docutils/writers/pep_html.py: Added to project; HTML Writer for - PEPs (subclass of ``html4css1.Writer``). - -* docutils/writers/pseudoxml.py: Renamed from pprint.py. - -* docutils/writers/docutils_xml.py: Added to project; trivial writer - of the Docutils internal doctree in XML. - -* docs/tools.txt: "Docutils Front-End Tools", added to project. - -* spec/doctree.txt: - - - Changed the title to "The Docutils Document Tree". - - Added "Hyperlink Bookkeeping" section. - -* spec/docutils.dtd: - - - Added ``decoration``, ``header``, and ``footer`` elements. - - Brought ``interpreted`` element in line with the parser: changed - attribute "type" to "role", added "position". - - Added support for generic bibliographic fields. - -* spec/notes.txt: Continual updates. Added "Project Policies". - -* spec/pep-0256.txt: Updated. Added "Roadmap to the Doctring PEPs" - section. - -* spec/pep-0257.txt: Clarified prohibition of signature repetition. - -* spec/pep-0258.txt: Updated. Added text from pysource.txt and - mailing list discussions. - -* spec/pep-0287.txt: - - - Renamed to "reStructuredText Docstring Format". - - Minor edits. - - Reworked Q&A as an enumerated list. - - Converted to reStructuredText format. - -* spec/pysource.dtd: - - - Reworked structural elements, incorporating ideas from Tony Ibbs. - -* spec/pysource.txt: Removed from project. Moved much of its contents - to pep-0258.txt. - -* spec/rst/alternatives.txt: - - - Expanded auto-enumerated list idea; thanks to Fred Bremmer. - - Added "Inline External Targets" section. - -* spec/rst/directives.txt: - - - Added "backlinks" attribute to "contents" directive. - -* spec/rst/problems.txt: - - - Updated the Enumerated List Markup discussion. - - Added new alternative table markup syntaxes. - -* spec/rst/reStructuredText.txt: - - - Clarified field list usage. - - Updated enumerated list description. - - Clarified purpose of directives. - - Added ``-/:`` characters to inline markup's start string prefix, - ``/`` to end string suffix. - - Updated "Authors" bibliographic field behavior. - - Changed "inline hyperlink targets" to "inline internal targets". - - Added "simple table" syntax to supplement the existing but - newly-renamed "grid tables". - - Added cautions for anonymous hyperlink use. - - Added "Dedication" and generic bibliographic fields. - -* test: Made test modules standalone (subdirectories became packages). - -* test/DocutilsTestSupport.py: - - - Added support for PEP extensions to reStructuredText. - - Added support for simple tables. - - Refactored naming. - -* test/package_unittest.py: Renamed from UnitTestFolder.py. - - - Now supports true packages containing test modules - (``__init__.py`` files required); fixes duplicate module name bug. - -* test/test_pep/: Subpackage added to project; PEP testing. - -* test/test_rst/test_SimpleTableParser.py: Added to project. - -* tools: - - - Updated html.py and publish.py front-end tools to use the new - command-line processing facilities of ``docutils.frontend`` - (exposed in ``docutils.core.Publisher``), reducing each to just a - few lines of code. - - Added ``locale.setlocale()`` calls to front-end tools. - -* tools/buildhtml.py: Added to project; batch-generates .html from all - the .txt files in directories and subdirectories. - -* tools/default.css: - - - Added support for ``header`` and ``footer`` elements. - - Added styles for "Dedication" topics (biblio fields). - -* tools/docutils.conf: A configuration file; added to project. - -* tools/docutils-xml.py: Added to project. - -* tools/pep.py: Added to project; PEP to HTML front-end tool. - -* tools/pep-html-template: Added to project. - -* tools/pep2html.py: Added to project from Python (nondist/peps). - Added support for Docutils (reStructuredText PEPs). - -* tools/quicktest.py: - - - Added the ``--attributes`` option, hacked a bit. - - Added a second command-line argument (output file); cleaned up. - -* tools/stylesheets/: Subdirectory added to project. - -* tools/stylesheets/pep.css: Added to project; stylesheet for PEPs. - - -Release 0.1 (2002-04-20) -======================== - -This is the first release of Docutils, merged from the now inactive -reStructuredText__ and `Docstring Processing System`__ projects. For -the pre-Docutils history, see the `reStructuredText HISTORY`__ and the -`DPS HISTORY`__ files. - -__ http://structuredtext.sourceforge.net/ -__ http://docstring.sourceforge.net/ -__ http://structuredtext.sourceforge.net/HISTORY.html -__ http://docstring.sourceforge.net/HISTORY.html - -General changes: renamed 'dps' package to 'docutils'; renamed -'restructuredtext' subpackage to 'rst'; merged the codebases; merged -the test suites (reStructuredText's test/test_states renamed to -test/test_rst); and all modifications required to make it all work. - -* docutils/parsers/rst/states.py: - - - Improved diagnostic system messages for missing blank lines. - - Fixed substitution_reference bug. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: Deleted: trunk/docutils/src/main/resources/docutils/MANIFEST.in =================================================================== --- trunk/docutils/src/main/resources/docutils/MANIFEST.in 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/MANIFEST.in 2012-06-13 15:51:18 UTC (rev 717) @@ -1,12 +0,0 @@ -include *.txt -include *.py -include setup.cfg -include MANIFEST -include MANIFEST.in -recursive-include docutils * -recursive-include docs * -recursive-include extras * -recursive-include licenses * -recursive-include test * -recursive-include tools * -recursive-exclude * .cvsignore *.pyc *~ .DS_Store Deleted: trunk/docutils/src/main/resources/docutils/PKG-INFO =================================================================== --- trunk/docutils/src/main/resources/docutils/PKG-INFO 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/PKG-INFO 2012-06-13 15:51:18 UTC (rev 717) @@ -1,49 +0,0 @@ -Metadata-Version: 1.0 -Name: docutils -Version: 0.9 -Summary: Docutils -- Python Documentation Utilities -Home-page: http://docutils.sourceforge.net/ -Author: David Goodger -Author-email: goodger@python.org -License: public domain, Python, 2-Clause BSD, GPL 3 (see COPYING.txt) -Description: Docutils is a modular system for processing documentation - into useful formats, such as HTML, XML, and LaTeX. For - input Docutils supports reStructuredText, an easy-to-read, - what-you-see-is-what-you-get plaintext markup syntax. -Platform: OS-independent -Classifier: Development Status :: 4 - Beta -Classifier: Environment :: Console -Classifier: Intended Audience :: End Users/Desktop -Classifier: Intended Audience :: Other Audience -Classifier: Intended Audience :: Developers -Classifier: Intended Audience :: System Administrators -Classifier: License :: Public Domain -Classifier: License :: OSI Approved :: Python Software Foundation License -Classifier: License :: OSI Approved :: BSD License -Classifier: License :: OSI Approved :: GNU General Public License (GPL) -Classifier: Operating System :: OS Independent -Classifier: Programming Language :: Python -Classifier: Topic :: Documentation -Classifier: Topic :: Software Development :: Documentation -Classifier: Topic :: Text Processing -Classifier: Natural Language :: English -Classifier: Natural Language :: Afrikaans -Classifier: Natural Language :: Brazilian Portuguese -Classifier: Natural Language :: Catalan -Classifier: Natural Language :: Czech -Classifier: Natural Language :: Dutch -Classifier: Natural Language :: Esperanto -Classifier: Natural Language :: Finnish -Classifier: Natural Language :: French -Classifier: Natural Language :: Galician -Classifier: Natural Language :: German -Classifier: Natural Language :: Italian -Classifier: Natural Language :: Japanese -Classifier: Natural Language :: Lithuanian -Classifier: Natural Language :: Polish -Classifier: Natural Language :: Russian -Classifier: Natural Language :: Simplified Chinese -Classifier: Natural Language :: Slovak -Classifier: Natural Language :: Spanish -Classifier: Natural Language :: Swedish -Classifier: Natural Language :: Traditional Chinese Deleted: trunk/docutils/src/main/resources/docutils/README.txt =================================================================== --- trunk/docutils/src/main/resources/docutils/README.txt 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/README.txt 2012-06-13 15:51:18 UTC (rev 717) @@ -1,372 +0,0 @@ -====================== - README: Docutils 0.9 -====================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date: 2012-02-28 17:39:05 +0100 (Die, 28 Feb 2012) $ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Quick-Start -=========== - -This is for those who want to get up & running quickly. Read on for -complete details. - -1. Get and install the latest release of Python, available from - - http://www.python.org/ - - Docutils is compatible with Python versions from 2.3 up to 2.6 and - version 3.1. (Support for Python 3 is new and might still have some - issues.) - -2. Use the latest Docutils code. Get the code from Subversion or from - the snapshot: - - http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar - - See `Releases & Snapshots`_ below for details. - -3. Unpack the tarball in a temporary directory (**not** directly in - Python's ``site-packages``) and run ``setup.py install`` or - ``install.py`` with admin rights. On Windows systems it may be - sufficient to double-click ``install.py``. On Unix or Mac OS X, - type:: - - su - (enter admin password) - ./setup.py install - - Docutils will only work with Python 3, if installed with a Python - version >= 3. If your default Python version is 2.x, also call - ``python3 setup.py install`` from the temporary directory. - See Installation_ below for details. - -4. Use a front-end tool from the "tools" subdirectory of the same - directory as in step 3. For example:: - - cd tools - ./rst2html.py ../FAQ.txt ../FAQ.html (Unix) - python rst2html.py ..\FAQ.txt ..\FAQ.html (Windows) - - See Usage_ below for details. - - -Purpose -======= - -The purpose of the Docutils project is to create a set of tools for -processing plaintext documentation into useful formats, such as HTML, -XML, and LaTeX. Support for the following sources has been -implemented: - -* Standalone files. - -* `PEPs (Python Enhancement Proposals)`_. - -Support for the following sources is planned: - -* Inline documentation from Python modules and packages, extracted - with namespace context. - -* Email (RFC-822 headers, quoted excerpts, signatures, MIME parts). - -* Wikis, with global reference lookups of "wiki links". - -* Compound documents, such as multiple chapter files merged into a - book. - -* And others as discovered. - -.. _PEPs (Python Enhancement Proposals): - http://www.python.org/peps/pep-0012.html - - -Releases & Snapshots -==================== - -While we are trying to follow a "release early & often" policy, -features are added very frequently. Since the code in the Subversion -repository is usually in a bug-free state, we recommend that you use -the current snapshot (which is usually updated within an hour of -changes being committed to the repository): - -* Snapshot of Docutils code, documentation, front-end tools, and - tests: - http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar - -* Snapshot of the Sandbox (experimental, contributed code): - http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/sandbox/?view=tar - -To keep up to date on the latest developments, download fresh copies -of the snapshots regularly. New functionality is being added weekly, -sometimes daily. (There's also the `Subversion repository`_.) - -.. _Subversion repository: docs/dev/repository.html - - -Requirements -============ - -To run the code, Python 2.3 or later must already be installed. -Python is available from -http://www.python.org/. - -The `Python Imaging Library`, or PIL, is used for some image -manipulation operations if it is installed. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ -.. _Optik: http://optik.sourceforge.net/ - - -Project Files & Directories -=========================== - -* README.txt: You're reading it. - -* COPYING.txt: Public Domain Dedication and copyright details for - non-public-domain files (most are PD). - -* FAQ.txt: Frequently Asked Questions (with answers!). - -* RELEASE-NOTES.txt: Summary of the major changes in recent releases. - -* HISTORY.txt: A detailed change log, for the current and all previous - project releases. - -* BUGS.txt: Known bugs, and how to report a bug. - -* THANKS.txt: List of contributors. - -* setup.py: Installation script. See "Installation" below. - -* install.py: Quick & dirty installation script. Just run it. For - any kind of customization or help though, setup.py must be used. - -* docutils: The project source directory, installed as a Python - package. - -* extras: Directory for third-party modules that Docutils depends on - (roman.py). These are only installed if - they're not already present. - -* docs: The project documentation directory. Read ``docs/index.txt`` - for an overview. - -* docs/user: The project user documentation directory. Contains the - following documents, among others: - - - docs/user/tools.txt: Docutils Front-End Tools - - docs/user/latex.txt: Docutils LaTeX Writer - - docs/user/rst/quickstart.txt: A ReStructuredText Primer - - docs/user/rst/quickref.html: Quick reStructuredText (HTML only) - -* docs/ref: The project reference directory. - ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText - reference. - -* licenses: Directory containing copies of license files for - non-public-domain files. - -* tools: Directory for Docutils front-end tools. See - ``docs/user/tools.txt`` for documentation. - -* test: Unit tests. Not required to use the software, but very useful - if you're planning to modify it. See `Running the Test Suite`_ - below. - - -Installation -============ - -The first step is to expand the ``.tgz`` archive in a temporary -directory (**not** directly in Python's ``site-packages``). It -contains a distutils setup file "setup.py". OS-specific installation -instructions follow. - - -GNU/Linux, BSDs, Unix, Mac OS X, etc. -------------------------------------- - -1. Open a shell. - -2. Go to the directory created by expanding the archive:: - - cd <archive_directory_path> - -3. Install the package:: - - python setup.py install - - If the python executable isn't on your path, you'll have to specify - the complete path, such as /usr/local/bin/python. You may need - root permissions to complete this step. - - To install for a specific python version, use this version in the - setup call, e.g. :: - - python3.1 setup.py install - - -Windows -------- - -Just double-click ``install.py``. If this doesn't work, try the -following: - -1. Open a DOS Box (Command Shell, MS-DOS Prompt, or whatever they're - calling it these days). - -2. Go to the directory created by expanding the archive:: - - cd <archive_directory_path> - -3. Install the package:: - - <path_to_python.exe>\python setup.py install - - To install for a specific python version, specify the Python - executable for this version. - - -Python 3 peculiarities ----------------------- - -If called from Python 3, setup.py, in addition to copying the sources -to the right place, will also convert them using 2to3 to Python 3 -compatible code. - -* If you want to test or develop Docutils, also run ``python3 setup.py - build``. This will generate Python 3 compatible sources, tests and - developer tools in the build directory. Do changes on the Python 2 - versions of the sources and re-run the build command. This works - incrementally, so if you change one file it will only reconvert that - file the next time you run setup.py build. - - -Usage -===== - -After unpacking and installing the Docutils package, the following -shell commands will generate HTML for all included documentation:: - - cd <archive_directory_path>/tools - ./buildhtml.py ../ - -On Windows systems, type:: - - cd <archive_directory_path>\tools - python buildhtml.py .. - -The final directory name of the ``<archive_directory_path>`` is -"docutils" for snapshots. For official releases, the directory may be -called "docutils-X.Y.Z", where "X.Y.Z" is the release version. -Alternatively:: - - cd <archive_directory_path> - tools/buildhtml.py --config=tools/docutils.conf (Unix) - python tools\buildhtml.py --config=tools\docutils.conf (Windows) - -With Python 3, call:: - - build/<Python-3-subdir>/tools/buildhtml.py --config=tools/docutils.conf - -Some files may generate system messages (warnings and errors). The -``docs/user/rst/demo.txt`` file (under the archive directory) contains -five intentional errors. (They test the error reporting mechanism!) - -There are many front-end tools in the unpacked "tools" subdirectory. -You may want to begin with the "rst2html.py" front-end tool. Most -tools take up to two arguments, the source path and destination path, -with STDIN and STDOUT being the defaults. Use the "--help" option to -the front-end tools for details on options and arguments. See -Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation. - -The package modules are continually growing and evolving. The -``docutils.statemachine`` module is usable independently. It contains -extensive inline documentation (in reStructuredText format of course). - -Contributions are welcome! - - -Running the Test Suite -====================== - -To run the entire test suite, after installation_ open a shell and use -the following commands:: - - cd <archive_directory_path>/test - ./alltests.py - -Under Windows, type:: - - cd <archive_directory_path>\test - python alltests.py - -For testing with Python 3 use the converted test suite:: - - cd <archive_directory_path>/build/<Python-3-subdir>/test - python alltests.py - - -You should see a long line of periods, one for each test, and then a -summary like this:: - - Ran 1111 tests in 24.653s - - OK - Elapsed time: 26.189 seconds - -The number of tests will grow over time, and the times reported will -depend on the computer running the tests. The difference between the -two times represents the time required to set up the tests (import -modules, create data structures, etc.). - -If any of the tests fail, please `open a bug report`_, `send email`_, -or post a message via the `web interface`_ (see `Bugs <BUGS.html>`_). -Please include all relevant output, information about your operating -system, Python version, and Docutils version. To see the Docutils -version, use one of the ``rst2*`` front ends or ``tools/quicktest.py`` -with the ``--version`` option, e.g.:: - - cd ../tools - ./quicktest.py --version - -Windows users type these commands:: - - cd ..\tools - python quicktest.py --version - -Python 3 users must use ``build/<Python-3-subdir>/tools/quicktest.py``. - - -.. _open a bug report: - http://sourceforge.net/tracker/?group_id=38414&atid=422030 -.. _send email: mailto:docutils-users@lists.sourceforge.net - ?subject=Test%20suite%20failure -.. _web interface: http://post.gmane.org/post.php - ?group=gmane.text.docutils.user&subject=Test+suite+failure - - -Getting Help -============ - -If you have questions or need assistance with Docutils or -reStructuredText, please post a message to the Docutils-users_ mailing -list. - -.. _Docutils-users: docs/user/mailing-lists.html#docutils-users - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: Deleted: trunk/docutils/src/main/resources/docutils/RELEASE-NOTES.txt =================================================================== --- trunk/docutils/src/main/resources/docutils/RELEASE-NOTES.txt 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/RELEASE-NOTES.txt 2012-06-13 15:51:18 UTC (rev 717) @@ -1,470 +0,0 @@ -======================== - Docutils Release Notes -======================== - -:Contact: grubert@users.sourceforge.net -:Date: $Date: 2012-05-02 19:13:41 +0200 (Mit, 02 Mai 2012) $ -:Revision: $Revision: 7410 $ -:Web site: http://docutils.sourceforge.net/ -:Copyright: This document has been placed in the public domain. - - -This document summarizes the major changes in recent releases. For a -more detailed list of changes, please see the `Docutils History`_. - -.. _Docutils History: HISTORY.html - -.. contents:: - -Future changes -============== - -* docutils/math, docutils/error_reporting.py, and - docutils/urischemes.py will move to the utils package - Code importing these modules needs to adapt, e.g.:: - - try: - import docutils.math as math - except ImportError: - import docutils.utils.math as math - -* docutils.io.FileInput/FileOutput will no longer do a - system-exit on IOError by default. - - Roadmap: - - :0.10: change of default behaviour to the equivalent of - ``handle_io_errors=False`` and deprecation of the - `handle_io_errors` option, - :0.11: deprecation warning to stderr if FileInput/FileOutput - is called with `handle_io_errors`, - :0.12: ignore ``handle_io_errors=True``, - :0.13: remove the `handle_io_errors` option. - - -Release 0.9 (2012-05-02) -========================= - -* General: - - - reStructuredText "code" role and directive with syntax highlighting - by Pygments_. - - "code" option of the "include" directive. - - .. _Pygments: http://pygments.org/ - - - Fix [ 3402314 ] allow non-ASCII whitespace, punctuation - characters and "international" quotes around inline markup. - - - Fix handling of missing stylesheets. - -* setup.py - - - Fix [ 2971827 ] and [ 3442827 ] - extras/roman.py moved to docutils/utils/roman.py - -* docutils/utils.py -> docutils/utils/__init__.py - - - docutils.utils is now a package (providing a place for sub-modules) - -* docutils/writers/html4css1/__init__.py - - - change default for `math-output` setting to MathJax - -* docutils/writers/latex2e/__init__.py - - - Support the `abbreviation` and `acronym` standard roles. - - Record only files required to generate the LaTeX source as dependencies. - - Use ``\setcounter{secnumdepth}{0}`` instead of ``*``-versions - when suppressing LaTeX section numbering. - - -Release 0.8.1 (2011-08-30) -========================== - -* General: - - - Fix [ 3364658 ] (Change last file with Apache license to BSD-2-Clause) - and [ 3395920 ] (correct copyright info for rst.el). - -* docutils/test/ - - - Apply [ 3303733 ] and [ 3365041 ] to fix tests under py3k. - -* docutils/writers/latex2e/__init__.py - - - Clean up Babel language setting. Restores Sphinx compatibility. - -Release 0.8 (2011-07-07) -======================== - -* COPYING: - - - Some additions to the Docutils core are released under the 2-Clause BSD - license. - -* General: - - - Handle language codes according to `BCP 47`_. - - If the specified langauage is not supported by Docutils, - warn and fall back to English. - - Math support: reStructuredText "math" role and directive, - ``math`` and ``math_block`` doctree elements. - - Orphaned "python" reader and "newlatex2e" writer moved to the sandbox. - - .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt - -* reStructuredText: - - - most directives now support a "name" option that attaches a - reference name. So you can write :: - - .. figure:: image.png - :name: figure name - - as a short form of :: - - .. _figure name: - - .. figure:: image.png - -Internationalization: - -* Added lithuanian mappings. - -Components: - -* HTML writer: - - - New setting "math-output" with support for HTML, MathML, and LaTeX. - -* LaTeX2e writer: - - - Convert image URI to a local file path. - - Apply [ 3148141 ] fix multicolumn support when a colspanning cell - has more than one paragraph (Wolfgang Scherer). - -* XeTeX writer: - - - New writer generating LaTeX code for compiling with ``xelatex``. - - XeTeX uses unicode and modern font technologies. - -* and fixes and enhancements here and there. - -Release 0.7 (2010-07-07) -======================== - -Components: - -* HTML writer: - - - Support SVG and SWF images (thanks to Stefan Rank). - - Generate valid XHTML for centered images with targets. - Use CSS classes instead of "align" tags for image alignment. - -* LaTeX2e writer: - - - Use the ``\url`` command for URLs (breaks long URLs instead of writing - into the margin). - - Preserve runs of spaces in 'inline literals'. - - Deprecate ``figure_footnotes`` setting. - - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__. - - New ``latex_preamble`` setting. - - Use PDF standard fonts (Times/Helvetica/Courier) as default. - - `hyperref` package called with ``unicode`` option (see the - `hyperref config tips`__ for how to override). - - Drop the special `output_encoding`__ default ("latin-1"). - The Docutils wide default (usually "UTF-8") is used instead. - -__ docs/user/config.html#docutils-footnotes -__ docs/user/latex.html#hyperlinks -__ docs/user/latex.html#output-encoding - -* manpage writer: - - - Titles level 1, that is ``.SH``, always uppercase. - - Apply patch from mg: literal text should be bold in man-pages. - -General: - -* io.FileInput opens files as text files with universal newline support - (mode "rU", configurable with the new optional argument "mode"). - -* setup.py: - - - Python 3 support: copy test/ and tools/ to the build-dir - and convert Python sources with 2to3. - -Release 0.6 (2009-10-11) -======================== - -.. Note:: - - Docutils 0.5 is the last version supporting Python 2.2. - - Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6 - and convertible to 3.1 code. - -.. note:: - - The "newlatex" writer is orphaned. - - The recommended way to generate PDF output is to use either the - LaTeX2e writer or one of the alternatives listed at - http://docutils.sourceforge.net/docs/user/links.html#pdf. - -* reStructuredText: - - - Allow length units for all length specifications. - - Allow percent sign in "scale" argument of "figure" and "image" directives. - - Bugfix: The "figalign" argument of a figure now works as intended - (aligning the figure not its contents). - - Align images with class "align-[right|center|left]" - (allows setting the alignment of an image in a figure). - - Hard tabs in literal inclusions are replaced by spaces. This is - configurable via the new "tab-width" option of the "include" directive - (a negative tab-width prevents tab expansion). - -* HTML writer: - - - ``--stylesheet`` and ``--stylesheet-path`` options now support a comma - separated list of stylesheets. - -* LaTeX2e writer: - - - New defaults: - - font-encoding: "T1" (formerly implicitely set by 'ae'). - - use-latex-toc: true (ToC with page numbers). - - use-latex-footnotes: true (no mixup with figures). - - Float placement defaults to "here definitely" (configurable). - - Align of image in a figure defaults to 'center'. - - Use class defaults for page margins ('typearea' now optional). - - Support LaTeX packages as ``--stylesheet`` arguments. - - Use ``bp`` for lengths without unit or unit ``pt``, - do not convert ``px`` to ``pt``. - - Do not use 'ae' and 'aeguill' packages if font-encoding is set to ''. - - Set sub- and superscript role argument as text not math. - - Support custom roles based on standard roles. - - Load packages and define macros only if required in the document. - - All Docutils specific LaTeX macros are prefixed with ``DU``. - - Better conformance to Docutils specifications with "use_latex_toc". - - If 'sectnum_xform' is False, the 'sectnum' directive triggers - section numbering by LaTeX. - - Use default font in admonitions and sidebar. - - Typeset generic topic as "quote with title". - - Use template (file and configuration option). - - Render doctest blocks as literal blocks (indented). - -* ODT writer: - - - moved from sandbox to Doctutils core. - -* manpage writer: - - - moved from sandbox to Doctutils core. - - -Release 0.5 (2008-06-25) -======================== - -Components: - -* HTML writer. - - - Dropped all ``name`` attributes of ``a`` elements (``id`` is - universally supported now). - -* LaTeX2e writer: - - - Better bibTeX citation support. - - Add ``--literal-block-env`` - -* PEP writer: - - - Changed to support new python.org website structure and - pep2pyramid.py. - -reStructuredText: - -* Changed the directive API to a new object-oriented system. - (Compatibility for the old, functional-style directive interface is - retained.) See the updated `Creating reStructuredText Directives`__ - how-to. - - __ docs/howto/rst-directives.html - -* Allow ``+`` and ``:`` in reference names requested for citations. - -Documentation: - -* Added `Deploying Docutils Securely`__ - - __ docs/howto/security.txt - -Internationalization: - -* Added hebrew mappings. - -General: - -* Configuration files are now assumed and required to be - UTF-8-encoded. - -* Added docutils/writers/html4css1/template.txt. - -* Enhance emacs support. - -Release 0.4 (2006-01-09) -======================== - -.. Note:: - - Docutils 0.4.x is the last version that will support Python 2.1. - Docutils 0.5 will *not* be compatible with Python 2.1; Python 2.2 - or later will be required. - - Docutils 0.4.x is the last version that will make compromises in - its HTML output for Netscape Navigator 4. Docutils 0.5 will - require more up-to-date browsers (the exact definition is to be - determined). - -Components: - -* Added an `S5/HTML writer`__ and the rst2s5.py__ front end: - multi-platform, multi-browser HTML slide shows. - - __ docs/user/slide-shows.html - __ docs/user/tools.html#rst2s5-py - -* The newlatex2e writer is nearing completion. - -* Added a DocTree reader, ``publish_doctree`` and - ``publish_from_doctree`` convenience functions, for document tree - extraction and reprocessing. - -reStructuredText: - -* Added directives: "container__" (generic block-level container), - "default-role__" (role used for \`backtick\` syntax), "title__" - (document title metadata), and "date__" (generate the current local - date, for substitution definitions). - - __ docs/ref/rst/directives.html#container - __ docs/ref/rst/directives.html#default-role - __ docs/ref/rst/directives.html#title - __ docs/ref/rst/directives.html#date - -* Length units are now supported for image__ sizes. - - __ docs/ref/rst/directives.html#image - -* Added `standard definition files`__ for special characters etc. - - __ docs/ref/rst/definitions.html - -Internationalization: - -* Added Japanese and Simplified Chinese language mappings, and support - for double-width CJK-characters in tables and section titles. - -Documentation: - -* Added a `guide for distributors`__ (package maintainers) and a - `guide for developers`__. - - __ docs/dev/distributing.html - __ docs/dev/hacking.html - -General: - -* Added significant `Emacs support for reST`__. - - __ docs/user/emacs.html - -* Added a `--strip-comments`__ option. - - __ docs/user/config.html#strip-comments - -* `--embed-stylesheet`__ is now the default for the HTML writer - (rather than --link-stylesheet). - - __ docs/user/config.html#embed-stylesheet - - -Release 0.3.9 (2005-05-26) -========================== - -* Added "file_insertion_enabled__" and "raw_enabled__" settings. - - __ docs/user/config.html#file-insertion-enabled - __ docs/user/config.html#raw-enabled - -* Added `auto-enumerated lists`__. - - __ docs/ref/rst/restructuredtext.html#enumerated-lists - -* Added `"header" and "footer"`__ directives. - - __ docs/ref/rst/directives.html#document-header-footer - -* Added "list-table__" directive. - - __ docs/ref/rst/directives.html#list-table - -* Added support for `section subtitles`__. - - __ docs/user/config.html#sectsubtitle-xform - -* Added "field_name_limit__" and "option_limit__" settings to HTML writer. - - __ docs/user/config.html#field-name-limit - __ docs/user/config.html#option-limit - -* Added "cloak_email_addresses__" setting to HTML writer. - - __ docs/user/config.html#cloak-email-addresses - -* UTF-8 BOMs are now removed from the input stream. - - -Release 0.3.7 (2004-12-24) -========================== - -* A special "`line block`__" syntax has been added. (Also see the - `quick reference`__.) - - __ docs/ref/rst/restructuredtext.html#line-blocks - __ docs/user/rst/quickref.html#line-blocks - -* Empty sections are now allowed. - -* A "raw__" role has been added. - - __ docs/ref/rst/roles.html#raw - -* The LaTeX writer now escapes consecutive dashes (like "--" or "---") - so that they are no longer transformed by LaTeX to en or em dashes. - (Please see the FAQ__ for how to represent such dashes.) - - __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document - -* A `dependency recorder`__ has been added. - - __ docs/user/config.html#record-dependencies - -* A directive has been added for `compound paragraphs`__. - - __ docs/ref/rst/directives.html#compound-paragraph - - -Release 0.3.5 (2004-07-29) -========================== - -* Improved, extended and reorganized the documentation__. - - __ docs/index.html - -* Added "csv-table__" directive. - - __ docs/ref/rst/directives.html#csv-table Deleted: trunk/docutils/src/main/resources/docutils/THANKS.txt =================================================================== --- trunk/docutils/src/main/resources/docutils/THANKS.txt 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/THANKS.txt 2012-06-13 15:51:18 UTC (rev 717) @@ -1,167 +0,0 @@ -.. -*- coding: utf-8 -*- - -Acknowledgements -================ - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date: 2008-08-25 15:07:53 +0200 (Mon, 25 Aug 2008) $ -:Revision: $Revision: 5637 $ -:Copyright: This document has been placed in the public domain. - -I would like to acknowledge the people who have made a direct impact -on the Docutils project, knowingly or not, in terms of encouragement, -suggestions, criticism, bug reports, code contributions, cash -donations, tasty treats, and related projects: - -* Aahz -* David Abrahams -* Guy D. Alcos -* David Ascher -* Ned Batchelder -* Heiko Baumann -* Anthony Baxter -* Eric Bellot -* Frank Bennett -* Ian Bicking -* Marek Blaha -* Martin Blais -* Stephen Boulet -* Fred Bremmer -* Simon Budig -* Bill Bumgarner -* Brett Cannon -* Greg Chapman -* Nicolas Chauveau -* Beni Cherniavsky -* Adam Chodorowski -* Brent Cook -* Laura Creighton -* Artur de Sousa Rocha -* Stephan Deibel & `Wing IDE <http://wingide.com/>`__ -* Jason Diamond -* William Dode -* Fred Drake -* Reggie Dugard -* Dethe Elza -* Marcus Ertl -* Benja Fallenstein -* fantasai -* Stefane Fermigier -* Michael Foord -* Jim Fulton -* Peter Funk -* Lele Gaifax -* Dinu C. Gherman -* Matt Gilbert -* Jorge Gonzalez -* Engelbert Gruber -* Jacob Hallen -* Simon Hefti -* Doug Hellmann -* Marc Herbert -* Juergen Hermann -* Jannie Hofmeyr -* Steve Holden -* Michael Hudson -* Marcelo Huerta San Martin -* Ludger Humbert -* Jeremy Hylton -* Tony Ibbs -* Alan G. Isaac -* Alan Jaffray -* Joe YS Jaw -* Dmitry Jemerov -* Richard Jones -* Andreas Jung -* Robert Kern -* Garth Kidd -* Philipp Knüsel -* Axel Kollmorgen -* Jeff Kowalczyk -* Martin F. Krafft -* Meir Kriheli -* Dave Kuhlman -* Lloyd Kvam -* Kirill Lapshin -* Nicola Larosa -* Daniel Larsson -* Marc-Andre Lemburg -* Julien Letessier -* Chris Liechti -* Wolfgang Lipp -* Edward Loper -* Dallas Mahrt -* Mikolaj Machowski -* Ken Manheimer -* Bob Marshall -* Mark McEahern -* Vincent McIntyre -* John F Meinel Jr -* Ivan Mendez for Free Software Office of the University of A Coruña -* Eric Meyer -* Günter Milde -* Skip Montanaro -* Paul Moore -* Nigel W. Moriarty -* Hisashi Morita -* Mark Nodine -* Omidyar Network (Pierre Omidyar & Doug Solomon) -* Panjunyong -* Patrick K. O'Brien -* Michel Pelletier -* Sam Penrose -* Tim Peters -* Pearu Peterson -* Martijn Pieters -* Mark Pilgrim -* Brett g Porter -* David Priest -* Jens Quade -* Stefan Rank -* Edward K. Ream -* Andy Robinson -* Tavis Rudd -* Tracy Ruggles -* Oliver Rutherfurd -* Luc Saffre -* Seo Sanghyeon -* Kenichi Sato -* Ueli Schlaepfer -* Gunnar Schwant -* Bill Sconce -* Frank Siebenlist -* Bruce Smith -* Nir Soffer -* Asko Soukka -* Darek Suchojad -* Roman Suzi -* Janet Swisher -* tav -* Kent Tenney -* Bob Tolbert -* Paul Tremblay -* Laurence Tratt -* Adrian van den Dries -* Guido van Rossum -* Miroslav Vasko -* Paul Viren -* Martin von Loewis -* Greg Ward -* Barry Warsaw -* Wu Wei -* Edward Welbourne -* Lea Wiemann -* Anthony Williams -* Robert Wojciechowicz -* Ka-Ping Yee -* Moshe Zadka -* Shmuel Zeigerman - -Thank you! - -Special thanks to `SourceForge <http://sourceforge.net>`__ and the -`Python Software Foundation <http://www.python.org/psf/>`__. - -Hopefully I haven't forgotten anyone or misspelled any names; -apologies (and please let me know!) if I have. Modified: trunk/docutils/src/main/resources/docutils/__run__.py =================================================================== --- trunk/docutils/src/main/resources/docutils/__run__.py 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/__run__.py 2012-06-13 15:51:18 UTC (rev 717) @@ -36,7 +36,7 @@ __builtin__.__dict__["openlegacy"] = __builtin__.__dict__["open"] __builtin__.__dict__["open"] = jaropen -def exec_docutils (docutilsPath, typeOutput, filein): +def exec_docutils (docutilsPath, typeOutput, fileList): # Initalization before using Docutils init_docutils(docutilsPath) @@ -55,6 +55,7 @@ listType = ["xml", "html", "odt", "latex", "man", "s5", "xetex"] if typeOutput in listType: from docutils.core import publish_file - publish_file( source_path=filein, writer_name=typeOutput ) + for fileIn in fileList: + publish_file( source_path=fileIn, writer_name=typeOutput ) else: - print "Wrong output format" \ No newline at end of file + print "Wrong output format" Modified: trunk/docutils/src/main/resources/docutils/docutils/__init__$py.class =================================================================== (Binary files differ) Modified: trunk/docutils/src/main/resources/docutils/docutils/core$py.class =================================================================== (Binary files differ) Deleted: trunk/docutils/src/main/resources/docutils/install.py =================================================================== --- trunk/docutils/src/main/resources/docutils/install.py 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/install.py 2012-06-13 15:51:18 UTC (rev 717) @@ -1,27 +0,0 @@ -#!/usr/bin/env python -# $Id: install.py 2428 2004-07-13 15:57:13Z goodger $ -# Copyright: This file has been placed in the public domain. - -""" -This is a quick & dirty installation shortcut. It is equivalent to the -command:: - - python setup.py install - -However, the shortcut lacks error checking and command-line option -processing. If you need any kind of customization or help, please use -one of:: - - python setup.py install --help - python setup.py --help -""" - -from distutils import core -from setup import do_setup - -if __name__ == '__main__' : - print __doc__ - core._setup_stop_after = 'config' - dist = do_setup() - dist.commands = ['install'] - dist.run_commands() Deleted: trunk/docutils/src/main/resources/docutils/roman.py =================================================================== --- trunk/docutils/src/main/resources/docutils/roman.py 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/roman.py 2012-06-13 15:51:18 UTC (rev 717) @@ -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 - Deleted: trunk/docutils/src/main/resources/docutils/setup.cfg =================================================================== --- trunk/docutils/src/main/resources/docutils/setup.cfg 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/setup.cfg 2012-06-13 15:51:18 UTC (rev 717) @@ -1,10 +0,0 @@ -[bdist_rpm] -doc_files = BUGS.txt - COPYING.txt - FAQ.txt - HISTORY.txt - README.txt - RELEASE-NOTES.txt - THANKS.txt - docs/ - licenses/ Deleted: trunk/docutils/src/main/resources/docutils/setup.py =================================================================== --- trunk/docutils/src/main/resources/docutils/setup.py 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/docutils/src/main/resources/docutils/setup.py 2012-06-13 15:51:18 UTC (rev 717) @@ -1,219 +0,0 @@ -#!/usr/bin/env python -# $Id: setup.py 7268 2011-12-20 16:39:10Z milde $ -# Copyright: This file has been placed in the public domain. - -import sys -import os -import glob -try: - from distutils.core import setup, Command - from distutils.command.build import build - from distutils.command.build_py import build_py - if sys.version_info >= (3,): - from distutils.command.build_py import build_py_2to3 - from distutils.util import copydir_run_2to3 - from distutils.command.install_data import install_data - from distutils.util import convert_path - from distutils import log -except ImportError: - print ('Error: The "distutils" standard module, which is required for the ') - print ('installation of Docutils, could not be found. You may need to ') - print ('install a package called "python-devel" (or similar) on your ') - print ('system using your package manager.') - sys.exit(1) - - -if sys.version_info >= (3,): - # copy-convert auxiliary python sources - class copy_build_py_2to3(build_py_2to3): - """Copy/convert Python source files in given directories recursively. - - Build py3k versions of the modules and packages. Also copy - 'tools/' and 'test/' dirs and run 2to3 on *.py files. - """ - manifest_in = """\ - exclude *.pyc *~ .DS_Store - recursive-exclude * *.pyc *~ .DS_Store - recursive-exclude functional/output * - include functional/output/README.txt - prune .svn - prune */.svn - prune */*/.svn - prune */*/*/.svn - prune */*/*/*/.svn - prune */*/*/*/*/.svn - """ - def run(self): - build_py_2to3.run(self) - print("copying aux dirs") - loglevel = log.set_threshold(log.ERROR) - for source in ['tools', 'test']: - dest = os.path.join(self.build_lib, source) - copydir_run_2to3(source, dest, template=self.manifest_in) - log.set_threshold(loglevel) - - -class smart_install_data(install_data): - # From <http://wiki.python.org/moin/DistutilsInstallDataScattered>, - # by Pete Shinners. - - def run(self): - #need to change self.install_dir to the library dir - install_cmd = self.get_finalized_command('install') - self.install_dir = getattr(install_cmd, 'install_lib') - return install_data.run(self) - -class build_data(Command): - - def initialize_options(self): - pass - - def finalize_options(self): - pass - - def run(self): - build_py = self.get_finalized_command('build_py') - data_files = self.distribution.data_files - for f in data_files: - dir = convert_path(f[0]) - dir = os.path.join(build_py.build_lib, dir) - self.mkpath(dir) - for data in f[1]: - data = convert_path(data) - self.copy_file(data, dir) - -# let our build_data run -build.sub_commands.append(('build_data', lambda *a: True)) - - -def do_setup(): - kwargs = package_data.copy() - kwargs['classifiers'] = classifiers - # Install data files properly. - kwargs['cmdclass'] = {'build_data': build_data, - 'install_data': smart_install_data} - # Auto-convert source code for Python 3 - if sys.version_info >= (3,): - kwargs['cmdclass']['build_py'] = copy_build_py_2to3 - else: - kwargs['cmdclass']['build_py'] = build_py - dist = setup(**kwargs) - return dist - -s5_theme_files = [] -for dir in glob.glob('docutils/writers/s5_html/themes/*'): - if os.path.isdir(dir): - theme_files = glob.glob('%s/*' % dir) - s5_theme_files.append((dir, theme_files)) - -package_data = { - 'name': 'docutils', - 'description': 'Docutils -- Python Documentation Utilities', - 'long_description': """\ -Docutils is a modular system for processing documentation -into useful formats, such as HTML, XML, and LaTeX. For -input Docutils supports reStructuredText, an easy-to-read, -what-you-see-is-what-you-get plaintext markup syntax.""", # wrap at col 60 - 'url': 'http://docutils.sourceforge.net/', - 'version': '0.9', - 'author': 'David Goodger', - 'author_email': 'goodger@python.org', - 'license': 'public domain, Python, 2-Clause BSD, GPL 3 (see COPYING.txt)', - 'platforms': 'OS-independent', - 'package_dir': {'docutils': 'docutils', - 'docutils.tools': 'tools'}, - 'packages': ['docutils', - 'docutils.languages', - 'docutils.parsers', - 'docutils.parsers.rst', - 'docutils.parsers.rst.directives', - 'docutils.parsers.rst.languages', - 'docutils.readers', - # 'docutils.readers.python', # in the sandbox since 0.8 - 'docutils.transforms', - 'docutils.utils', - 'docutils.math', - 'docutils.writers', - 'docutils.writers.html4css1', - # 'docutils.writers.html4strict', # in the sandbox! - 'docutils.writers.pep_html', - 'docutils.writers.s5_html', - 'docutils.writers.latex2e', - # 'docutils.writers.newlatex2e', # in the sandbox since 0.8 - 'docutils.writers.xetex', - 'docutils.writers.odf_odt', - ], - 'data_files': ([('docutils/parsers/rst/include', - glob.glob('docutils/parsers/rst/include/*.txt')), - ('docutils/writers/html4css1', - ['docutils/writers/html4css1/html4css1.css', - 'docutils/writers/html4css1/template.txt']), - ('docutils/writers/latex2e', - ['docutils/writers/latex2e/default.tex', - 'docutils/writers/latex2e/titlepage.tex', - 'docutils/writers/latex2e/xelatex.tex',]), - ('docutils/writers/pep_html', - ['docutils/writers/pep_html/pep.css', - 'docutils/writers/pep_html/template.txt']), - ('docutils/writers/s5_html/themes', - ['docutils/writers/s5_html/themes/README.txt']), - ('docutils/writers/odf_odt', - ['docutils/writers/odf_odt/styles.odt']), - ] - + s5_theme_files), - 'scripts' : ['tools/rst2html.py', - 'tools/rst2s5.py', - 'tools/rst2latex.py', - 'tools/rst2xetex.py', - 'tools/rst2man.py', - 'tools/rst2xml.py', - 'tools/rst2pseudoxml.py', - 'tools/rstpep2html.py', - 'tools/rst2odt.py', - 'tools/rst2odt_prepstyles.py', - ],} -"""Distutils setup parameters.""" - -classifiers = [ - 'Development Status :: 4 - Beta', - '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 :: Brazilian Portuguese', - 'Natural Language :: Catalan', - 'Natural Language :: Czech', - 'Natural Language :: Dutch', - 'Natural Language :: Esperanto', - 'Natural Language :: Finnish', - 'Natural Language :: French', - 'Natural Language :: Galician', - 'Natural Language :: German', - 'Natural Language :: Italian', - 'Natural Language :: Japanese', - 'Natural Language :: Lithuanian', - 'Natural Language :: Polish', - 'Natural Language :: Russian', - 'Natural Language :: Simplified Chinese ', - 'Natural Language :: Slovak', - 'Natural Language :: Spanish', - 'Natural Language :: Swedish', - 'Natural Language :: Traditional Chinese ', - ] -"""Trove classifiers for the Distutils "register" command; -Python 2.3 and up.""" - -if __name__ == '__main__' : - do_setup() Modified: trunk/jrst/pom.xml =================================================================== --- trunk/jrst/pom.xml 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/jrst/pom.xml 2012-06-13 15:51:18 UTC (rev 717) @@ -166,7 +166,6 @@ <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> - <version>12.0</version> </dependency> <!-- itext --> Modified: trunk/jrst/src/main/java/org/nuiton/jrst/JRST.java =================================================================== --- trunk/jrst/src/main/java/org/nuiton/jrst/JRST.java 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/jrst/src/main/java/org/nuiton/jrst/JRST.java 2012-06-13 15:51:18 UTC (rev 717) @@ -37,6 +37,7 @@ import java.io.Reader; import java.net.URL; import java.util.HashMap; +import java.util.Iterator; import java.util.List; import java.util.Locale; import java.util.Map; @@ -365,7 +366,7 @@ interp.setOut(out); // Execution of the docutils script to transform rst to xml - String commandExec = String.format("__run__.exec_docutils('%s', '%s', '%s')", + String commandExec = String.format("__run__.exec_docutils('%s', '%s', ['%s'])", docutilsPath, TYPE_XML, filePath); interp.exec(commandExec); @@ -390,6 +391,69 @@ } } + public static void generateDocutilsList(List<File> listIn) throws Exception { + + ByteArrayOutputStream out = null; + + try { + // Transformation to XML + out = new ByteArrayOutputStream(); + + // Transformation of the __run__ URL into a path that python will use + // For example the URL is : + // jar:file:/home/user/.m2/repository/org/nuiton/jrst/docutils/1.6-SNAPSHOT/docutils-1.6-SNAPSHOT.jar!/__run__.py + // and it becomes : + // /home/user/.m2/repository/org/nuiton/jrst/docutils/1.6-SNAPSHOT/docutils-1.6-SNAPSHOT.jar/ + URL resource = JRST.class.getResource("/" + DOCUTILS_LAUNCHER); + String docutilsPath = resource.getPath() + .replaceAll(DOCUTILS_LAUNCHER, ""); + + docutilsPath = docutilsPath.replaceAll(BANG, ""); + docutilsPath = docutilsPath.replaceAll(FILE_URI_PREFIX, ""); + + // Import of the main script to use docutils ( __run__ ) + PythonInterpreter interp = new PythonInterpreter(); + String commandImport = IMPORT_SCRIPT; + interp.exec(commandImport); + + /* + // If the OS is windows, escapes the backslashs in the filepath + String filePath = in.getAbsolutePath(); + String property = System.getProperty(OS_NAME).toLowerCase(); + if (property.contains(WINDOWS_NAME)) { + filePath = filePath.replaceAll("\\\\", "\\\\\\\\"); + } + */ + + // Sets an output stream in the python interpreter and executes the code + interp.setOut(out); + + // Execution of the docutils script to transform rst to xml + String commandExec = String.format("__run__.exec_docutils('%s', '%s', [",docutilsPath, TYPE_XML); + + Iterator<File> iterator = listIn.iterator(); + while (iterator.hasNext()) { + commandExec += "'" + iterator.next().getAbsolutePath() + "',"; + } + + commandExec = commandExec.substring(0,commandExec.lastIndexOf(",")); + commandExec += "])"; + log.info(commandExec); + interp.exec(commandExec); + + // Cleans the python interpreter to avoid problems if they are multiple execution of this method + interp.cleanup(); + + // Transforms the output stream to a document + String xmlString = new String(out.toByteArray(), UTF_8); + log.info(xmlString); + } finally { + if (out != null) { + out.close(); + } + } + } + /** * Applies XSL stylesheet(s) to a XML document * Modified: trunk/jrst/src/test/java/org/nuiton/jrst/JRSTTest.java =================================================================== --- trunk/jrst/src/test/java/org/nuiton/jrst/JRSTTest.java 2012-06-13 14:11:20 UTC (rev 716) +++ trunk/jrst/src/test/java/org/nuiton/jrst/JRSTTest.java 2012-06-13 15:51:18 UTC (rev 717) @@ -26,11 +26,14 @@ package org.nuiton.jrst; import java.io.File; +import java.util.LinkedList; +import java.util.List; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.junit.Assert; import org.junit.Test; import org.nuiton.util.Resource; +import org.nuiton.util.TimeLog; /** * @@ -67,6 +70,35 @@ } @Test + public void generateMultipleXml() throws Exception { + + File in = getTestFile("test.rst"); + File out = getOutputTestFile("jrst-RstToXml.xml"); + + List<File> liste = new LinkedList<File>(); + for (int i = 0; i < 1 ; i++) { + liste.add(in) ; + } + + TimeLog docutilsTimeLog = new TimeLog("Generation"); + + long start = TimeLog.getTime(); + JRST.generateDocutilsList(liste); + + start = docutilsTimeLog.log(start, "generation avec boucle Python"); + + for (int i = 0; i < 1 ; i++) { + JRST.generateDocutils(in); + } + start = docutilsTimeLog.log(start, "multiple generation normale"); + + for (int i = 0; i < 1 ; i++) { + JRST.generateSimpleDoc(in, "UTF-8"); + } + docutilsTimeLog.log(start, "multiple generation simple"); + } + + @Test public void generateSimpleXml() throws Exception { File in = getTestFile("test.rst");