diff options
Diffstat (limited to 'docutils/docs')
68 files changed, 0 insertions, 31456 deletions
diff --git a/docutils/docs/api/cmdline-tool.txt b/docutils/docs/api/cmdline-tool.txt deleted file mode 100644 index 3d3d4a635..000000000 --- a/docutils/docs/api/cmdline-tool.txt +++ /dev/null @@ -1,68 +0,0 @@ -=============================================== - Inside A Docutils Command-Line Front-End Tool -=============================================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -`The Docutils Publisher`_ class was set up to make building -command-line tools easy. All that's required is to choose components -and supply settings for variations. Let's take a look at a typical -command-line front-end tool, ``tools/rst2html.py``, from top to -bottom. - -On Unixish systems, it's best to make the file executable (``chmod +x -file``), and supply an interpreter on the first line, the "shebang" or -"hash-bang" line:: - - #!/usr/bin/env python - -Windows systems can be set up to associate the Python interpreter with -the ``.py`` extension. - -Next are some comments providing metadata:: - - # Author: David Goodger - # Contact: goodger@python.org - # Revision: $Revision: ... - # Date: $Date: ... - # Copyright: This module has been placed in the public domain. - -The module docstring describes the purpose of the tool:: - - """ - A minimal front end to the Docutils Publisher, producing HTML. - """ - -This next block attempts to invoke locale support for -internationalization services, specifically text encoding. It's not -supported on all platforms though, so it's forgiving:: - - try: - import locale - locale.setlocale(locale.LC_ALL, '') - except: - pass - -The real work will be done by the code that's imported here:: - - from docutils.core import publish_cmdline, default_description - -We construct a description of the tool, for command-line help:: - - description = ('Generates (X)HTML documents from standalone ' - 'reStructuredText sources. ' + default_description) - -Now we call the Publisher convenience function, which takes over. -Most of it's defaults are used ("standalone" Reader, -"reStructuredText" Parser, etc.). The HTML Writer is chosen by name, -and a description for command-line help is passed in:: - - publish_cmdline(writer_name='html', description=description) - -That's it! `The Docutils Publisher`_ takes care of the rest. - -.. _The Docutils Publisher: ./publisher.html diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt deleted file mode 100644 index 73cfc0ef2..000000000 --- a/docutils/docs/api/publisher.txt +++ /dev/null @@ -1,176 +0,0 @@ -======================== - The Docutils Publisher -======================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Publisher Convenience Functions -=============================== - -Each of these functions set up a ``docutils.core.Publisher`` object, -then call its ``publish`` method. ``docutils.core.Publisher.publish`` -handles everything else. There are five convenience functions in the -``docutils.core`` module: - -:_`publish_cmdline`: for command-line front-end tools, like - ``rst2html.py``. There are several examples in the ``tools/`` - directory. A detailed analysis of one such tool is in `Inside A - Docutils Command-Line Front-End Tool`_ - -:_`publish_file`: for programmatic use with file-like I/O. In - addition to writing the encoded output to a file, also returns the - encoded output as a string. - -:_`publish_string`: for programmatic use with string I/O. Returns - the encoded output as a string. - -:_`publish_parts`: for programmatic use with string input; returns a - dictionary of document parts. Dictionary keys are the names of - parts, and values are Unicode strings; encoding is up to the client. - Useful when only portions of the processed document are desired. - See `publish_parts Details`_ below. - - There are usage examples in the `docutils/examples.py`_ module. - -:_`publish_programmatically`: for custom programmatic use. This - function implements common code and is used by ``publish_file``, - ``publish_string``, and ``publish_parts``. It returns a 2-tuple: - the encoded string output and the Publisher object. - -.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html -.. _docutils/examples.py: ../../docutils/examples.py - - -Configuration -------------- - -To pass application-specific setting defaults to the Publisher -convenience functions, use the ``settings_overrides`` parameter. Pass -a dictionary of setting names & values, like this:: - - overrides = {'input_encoding': 'ascii', - 'output_encoding': 'latin-1'} - output = publish_string(..., settings_overrides=overrides) - -Settings from command-line options override configuration file -settings, and they override application defaults. For details, see -`Docutils Runtime Settings`_. See `Docutils Configuration Files`_ for -details about individual settings. - -.. _Docutils Runtime Settings: ./runtime-settings.html -.. _Docutils Configuration Files: ../user/tools.html - - -Encodings ---------- - -The default output encoding of Docutils is UTF-8. If you have any -non-ASCII in your input text, you may have to do a bit more setup. -Docutils may introduce some non-ASCII text if you use -`auto-symbol footnotes`_ or the `"contents" directive`_. - -.. _auto-symbol footnotes: - ../ref/rst/restructuredtext.html#auto-symbol-footnotes -.. _"contents" directive: - ../ref/rst/directives.html#table-of-contents - - -``publish_parts`` Details -========================= - -The ``docutils.core.publish_parts`` convenience function returns a -dictionary of document parts. Dictionary keys are the names of parts, -and values are Unicode strings. - -Each Writer component may publish a different set of document parts, -described below. Currently only the HTML Writer implements more than -the "whole" part. - - -Parts Provided By All Writers ------------------------------ - -_`whole` - ``parts['whole']`` contains the entire formatted document. - - -Parts Provided By the HTML Writer ---------------------------------- - -_`body` - ``parts['body']`` is equivalent to parts['fragment_']. It is - *not* equivalent to parts['html_body_']. - -_`docinfo` - ``parts['docinfo']`` contains the document bibliographic data. - -_`footer` - ``parts['footer']`` contains the document footer content, meant to - appear at the bottom of a web page, or repeated at the bottom of - every printed page. - -_`fragment` - ``parts['fragment']`` contains the document body (*not* the HTML - ``<body>``). In other words, it contains the entire document, - less the document title, subtitle, docinfo, header, and footer. - -_`header` - ``parts['header']`` contains the document header content, meant to - appear at the top of a web page, or repeated at the top of every - printed page. - -_`html_body` - ``parts['html_body']`` contains the HTML ``<body>`` content, less - the ``<body>`` and ``</body>`` tags themselves. - -_`html_head` - ``parts['html_head']`` contains the HTML ``<head>`` content, less - the stylesheet link and the ``<head>`` and ``</head>`` tags - themselves. Since ``publish_parts`` returns Unicode strings and - does not know about the output encoding, the "Content-Type" meta - tag's "charset" value is left unresolved, as "%s":: - - <meta http-equiv="Content-Type" content="text/html; charset=%s" /> - - The interpolation should be done by client code. - -_`html_prolog` - ``parts['html_prolog]`` contains the XML declaration and the - doctype declaration. The XML declaration's "encoding" attribute's - value is left unresolved, as "%s":: - - <?xml version="1.0" encoding="%s" ?> - - The interpolation should be done by client code. - -_`html_subtitle` - ``parts['html_subtitle']`` contains the document subtitle, - including the enclosing ``<h2 class="subtitle">`` & ``</h2>`` - tags. - -_`html_title` - ``parts['html_title']`` contains the document title, including the - enclosing ``<h1 class="title">`` & ``</h1>`` tags. - -_`meta` - ``parts['meta']`` contains all ``<meta ... />`` tags. - -_`stylesheet` - ``parts['stylesheet']`` contains the document stylesheet link. - -_`subtitle` - ``parts['subtitle']`` contains the document subtitle text and any - inline markup. It does not include the enclosing ``<h2>`` & - ``</h2>`` tags. - -_`title` - ``parts['title']`` contains the document title text and any inline - markup. It does not include the enclosing ``<h1>`` & ``</h1>`` - tags. diff --git a/docutils/docs/api/runtime-settings.txt b/docutils/docs/api/runtime-settings.txt deleted file mode 100644 index 2d60aa3e1..000000000 --- a/docutils/docs/api/runtime-settings.txt +++ /dev/null @@ -1,192 +0,0 @@ -=========================== - Docutils Runtime Settings -=========================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Introduction -============ - -Docutils runtime settings are assembled from several sources: -component settings specifications, application settings -specifications, configuration files, and command-line options. -Docutils overlays default and explicitly specified values from these -sources such that settings behave the way we want and expect them to -behave. - -To understand how Docutils deals with runtime settings, the attributes -and parameters involved must first be understood. Begin with the the -docstrings of the attributes of the ``docutils.SettingsSpec`` base -class (in the ``docutils/__init__.py`` module): - -* ``settings_spec`` -* ``settings_defaults`` -* ``settings_default_overrides`` -* ``relative_path_settings`` -* ``config_section`` -* ``config_section_dependencies`` - -Next, several _`convenience function parameters` are also significant -(described in the ``docutils.core.publish_programmatically`` function -docstring): - -* The ``settings`` parameter is a runtime settings - (``docutils.frontend.Values``) object which, if present, is assumed - to be complete (it must include all runtime settings). Also, if the - ``settings`` parameter is present, no further runtime settings - processing is done. In other words, the other parameters, described - below, will have no effect. - -* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is - treated like a fourth component (after the Parser, Reader, and - Writer). In other words, it's the settings specification for the - "Application" itself. - -* ``settings_overrides`` is a dictionary which will override the - defaults of the components (from their settings specs). - -* ``config_section`` specifies the name of an application-specific - configuration file section. - - -.. _command-line tools: - -Runtime Settings Processing for Command-Line Tools -================================================== - -Following along with the actual code is recommended. The -``docutils/__init__.py``, ``docutils/core.py``, and -``docutils.frontend.py`` modules are described. - -1. A command-line front-end tool imports and calls - ``docutils.core.publish_cmdline``. The relevant `convenience - function parameters`_ are described above. - -2. ``docutils.core.publish_cmdline`` initializes a - ``docutils.core.Publisher`` object, then calls its ``publish`` - method. - -3. The ``docutils.core.Publisher`` object's ``publish`` method checks - its ``settings`` attribute to see if it's defined. If it is, no - further runtime settings processing is done. - - If ``settings`` is not defined, ``self.process_command_line`` is - called with the following relevant arguments: - - * ``settings_spec`` - * ``config_section`` - * ``settings_overrides`` (in the form of excess keyword - arguments, collected in the ``defaults`` parameter) - -4. ``self.process_command_line`` calls ``self.setup_option_parser``, - passing ``settings_spec``, ``config_section``, and ``defaults``. - -5. ``self.setup_option_parser`` checks its ``config_section`` - parameter; if defined, it adds that config file section to - ``settings_spec`` (or to a new, empty ``docutils.SettingsSpec`` - object), replacing anything defined earlier. (See `Docutils - Configuration Files`_ for details.) Then it instantiates a new - ``docutils.frontend.OptionParser`` object, passing the following - relevant arguments: - - * ``components``: A tuple of ``docutils.SettingsSpec`` objects, - ``(self.parser, self.reader, self.writer, settings_spec)`` - * ``defaults`` (originally from ``settings_overrides``) - -6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method - calls ``self.populate_from_components`` with ``self.components``, - which consists of ``self`` prepended to the ``components`` tuple it - received. ``self`` (``docutils.frontend.OptionParser``) defines - general Docutils settings. - -7. In ``self.populate_from_components``, for each component passed, - ``component.settings_spec`` is processed and - ``component.settings_defaults`` is applied. Then, for each - component, ``component.settings_default_overrides`` is applied. - This two-loop process ensures that - ``component.settings_default_overrides`` can override the default - settings of any other component. - -8. Back in ``docutils.frontend.OptionParser.__init__``, the - ``defaults`` parameter (derived from the ``settings_overrides`` - parameter of ``docutils.core.Publisher.publish``) is overlaid over - ``self.defaults``. So ``settings_overrides`` has priority over all - ``SettingsSpec`` data. - -9. Next, ``docutils.frontend.OptionParser.__init__`` checks if - configuration files are enabled (its ``read_config_files`` - parameter is true, and ``self.defaults['_disable_config']`` is - false). If they are enabled (and normally, they are), - ``self.get_standard_config_settings`` is called. This reads the - `docutils configuration files`_, and returns a dictionary of - settings. This is then overlaid on ``self.defaults``. So - configuration file settings have priority over all software-defined - defaults. - -10. Back in the ``docutils.core.Publisher`` object, - ``self.setup_option_parser`` returns the ``option_parser`` object - to its caller, ``self.process_command_line``. - -11. ``self.process_command_line`` calls ``option_parser.parse_args``, - which parses all command line options and returns a - ``docutils.frontend.Values`` object. This is assigned to the - ``docutils.core.Publisher`` object's ``self.settings``. So - command-line options have priority over configuration file - settings. - - When ``option_parser.parse_args`` is called, the source and - destination command-line arguments are also parsed, and assigned - to the ``_source`` and ``_destination`` attributes of what becomes - the ``docutils.core.Publisher`` object's ``self.settings``. - -12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is - called with no arguments. If either ``self.source`` or - ``self.destination`` are not set, the corresponding - ``self.set_source`` and ``self.set_destination`` are called, - effectively with no arguments. - -13. ``self.set_source`` checks for a ``source_path`` parameter, and if - there is none (which is the case for command-line use), it is - taken from ``self.settings._source``. ``self.source`` is set by - instantiating a ``self.source_class`` object. For command-line - front-end tools, the default ``self.source_class`` is used, - ``docutils.io.FileInput``. - -14. ``self.set_destination`` does the same job for the destination - that ``self.set_source`` does for the source (the default - ``self.destination_class`` is ``docutils.io.FileOutput``). - -.. _Docutils Configuration Files: ../user/config.html - - -Runtime Settings Processing From Applications -============================================= - -Applications process runtime settings in a different way than -`command-line tools`_ do. Instead of calling ``publish_cmdline``, the -application calls one of ``publish_file``, ``publish_string``, or -``publish_parts``. These in turn call ``publish_programmatically``, -which implements a generic programmatic interface. Although an -application may also call ``publish_programmatically`` directly, it is -not recommended (if it does seem to be necessary, please write to the -Docutils-develop_ mailing list). - -``publish_programmatically`` accepts the same `convenience function -parameters`_ as ``publish_cmdline``. Where things differ is that -programmatic use does no command-line processing. Instead of calling -``docutils.Publisher.process_command_line`` (as ``publish_cmdline`` -does, via ``docutils.Publisher.publish``), -``docutils.Publisher.process_programmatic_settings`` is called to set -up the runtime settings. - -.. copy & modify the list from command-line tools? - - -.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop diff --git a/docutils/docs/dev/distributing.txt b/docutils/docs/dev/distributing.txt deleted file mode 100644 index c81807279..000000000 --- a/docutils/docs/dev/distributing.txt +++ /dev/null @@ -1,146 +0,0 @@ -=============================== - Docutils_ Distributor's Guide -=============================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - -This document describes how to create packages of Docutils (e.g. for -shipping with a Linux distribution). If you have any questions, -please direct them to the Docutils-develop_ mailing list. - -First, please download the most current `release tarball`_ and unpack -it. - -.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop -.. _release tarball: http://docutils.sourceforge.net/#download - - -Dependencies -============ - -Docutils has the following dependencies: - -* Python 2.1 or later is required. While the compiler package from - the Tools/ directory of Python's source distribution must be - installed for the test suite to pass with Python 2.1, the - functionality available to end users should be available without the - compiler package as well. So just use ">= Python 2.1" in the - dependencies. - -* Docutils may optionally make use of the PIL (`Python Imaging - Library`_). If PIL is present, it is automatically detected by - Docutils. - -* There are three files in the ``extras/`` directory of the Docutils - distribution, ``optparse.py``, ``textwrap.py``, and ``roman.py``. - For Python 2.1/2.2, all of them must be installed (into the - ``site-packages/`` directory). Python 2.3 and later versions have - ``textwrap`` and ``optparse`` included in the standard library, so - only ``roman.py`` is required here; installing the other files won't - hurt, though. - - These files are automatically installed by the setup script (when - calling "python setup.py install"). - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - - -Python Files -============ - -The Docutils Python files must be installed into the -``site-packages/`` directory of Python. Running ``python setup.py -install`` should do the trick, but if you want to place the files -yourself, you can just install the ``docutils/`` directory of the -Docutils tarball to ``/usr/lib/python/site-packages/docutils/``. In -this case you should also compile the Python files to ``.pyc`` and/or -``.pyo`` files so that Docutils doesn't need to be recompiled every -time it's executed. - - -Executables -=========== - -The executable front-end tools are located in the ``tools/`` directory -of the Docutils tarball. - -The ``rst2*.py`` tools (except ``rst2newlatex.py``) are intended for -end-users. You should install them to ``/usr/bin/``. You do not need -to change the names (e.g. to ``docutils-rst2html.py``) because the -``rst2`` prefix is unique. - - -Documentation -============= - -The documentation should be generated using ``buildhtml.py``. To -generate HTML for all documentation files, go to the ``tools/`` -directory and run:: - - # Place html4css1.css in base directory. - cp ../docutils/writers/html4css1/html4css1.css .. - ./buildhtml.py --stylesheet-path=../html4css1.css .. - -Then install the following files to ``/usr/share/doc/docutils/`` (or -wherever you install documentation): - -* All ``.html`` and ``.txt`` files in the base directory. - -* The ``docs/`` directory. - - Do not install the contents of the ``docs/`` directory directly to - ``/usr/share/doc/docutils/``; it's incomplete and would contain - invalid references! - -* The ``licenses/`` directory. - -* ``html4css1.css`` in the base directory. - - -Removing the ``.txt`` Files ---------------------------- - -If you are tight with disk space, you can remove all ``.txt`` files in -the tree except for: - -* those in the ``licenses/`` directory because they have not been - processed to HTML and - -* ``user/rst/cheatsheet.txt`` and ``user/rst/demo.txt``, which should - be readable in source form. - -Before you remove the ``.txt`` files you should rerun ``buildhtml.py`` -with the ``--no-source-link`` switch to avoid broken references to the -source files. - - -Other Files -=========== - -You may want to install the Emacs-Lisp files -``tools/editors/emacs/*.el`` into the appropriate directory. - - -Configuration File -================== - -It is possible to have a system-wide configuration file at -``/etc/docutils.conf``. However, this is usually not necessary. You -should *not* install ``tools/docutils.conf`` into ``/etc/``. - - -Tests -===== - -While you probably do not need to ship the tests with your -distribution, you can test your package by installing it and then -running ``alltests.py`` from the ``tests/`` directory of the Docutils -tarball. diff --git a/docutils/docs/dev/enthought-plan.txt b/docutils/docs/dev/enthought-plan.txt deleted file mode 100644 index 0ab0d3c83..000000000 --- a/docutils/docs/dev/enthought-plan.txt +++ /dev/null @@ -1,480 +0,0 @@ -=========================================== - Plan for Enthought API Documentation Tool -=========================================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: 2004 by `Enthought, Inc. <http://www.enthought.com>`_ -:License: `Enthought License`_ (BSD-style) - -.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt - -This document should be read in conjunction with the `Enthought API -Documentation Tool RFP`__ prepared by Janet Swisher. - -__ enthought-rfp.html - -.. contents:: -.. sectnum:: - - -Introduction -============ - -In March 2004 at I met Eric Jones, president and CTO of `Enthought, -Inc.`_, at `PyCon 2004`_ in Washington DC. He told me that Enthought -was using reStructuredText_ for source code documentation, but they -had some issues. He asked if I'd be interested in doing some work on -a customized API documentation tool. Shortly after PyCon, Janet -Swisher, Enthought's senior technical writer, contacted me to work out -details. Some email, a trip to Austin in May, and plenty of Texas -hospitality later, we had a project. This document will record the -details, milestones, and evolution of the project. - -In a nutshell, Enthought is sponsoring the implementation of an open -source API documentation tool that meets their needs. Fortuitously, -their needs coincide well with the "Python Source Reader" description -in `PEP 258`_. In other words, Enthought is funding some significant -improvements to Docutils, improvements that were planned but never -implemented due to time and other constraints. The implementation -will take place gradually over several months, on a part-time basis. - -This is an ideal example of cooperation between a corporation and an -open-source project. The corporation, the project, I personally, and -the community all benefit. Enthought, whose commitment to open source -is also evidenced by their sponsorship of SciPy_, benefits by -obtaining a useful piece of software, much more quickly than would -have been possible without their support. Docutils benefits directly -from the implementation of one of its core subsystems. I benefit from -the funding, which allows me to justify the long hours to my wife and -family. All the corporations, projects, and individuals that make up -the community will benefit from the end result, which will be great. - -All that's left now is to actually do the work! - -.. _PyCon 2004: http://pycon.org/dc2004/ -.. _reStructuredText: http://docutils.sf.net/rst.html -.. _SciPy: http://www.scipy.org/ - - -Development Plan -================ - -1. Analyze prior art, most notably Epydoc_ and HappyDoc_, to see how - they do what they do. I have no desire to reinvent wheels - unnecessarily. I want to take the best ideas from each tool, - combined with the outline in `PEP 258`_ (which will evolve), and - build at least the foundation of the definitive Python - auto-documentation tool. - - .. _Epydoc: http://epydoc.sourceforge.net/ - .. _HappyDoc: http://happydoc.sourceforge.net/ - .. _PEP 258: - http://docutils.sf.net/docs/peps/pep-0258.html#python-source-reader - -2. Decide on a base platform. The best way to achieve Enthought's - goals in a reasonable time frame may be to extend Epydoc or - HappyDoc. Or it may be necessary to start fresh. - -3. Extend the reStructuredText parser. See `Proposed Changes to - reStructuredText`_ below. - -4. Depending on the base platform chosen, build or extend the - docstring & doc comment extraction tool. This may be the biggest - part of the project, but I won't be able to break it down into - details until more is known. - - -Repository -========== - -If possible, all software and documentation files will be stored in -the Subversion repository of Docutils and/or the base project, which -are all publicly-available via anonymous pserver access. - -The Docutils project is very open about granting Subversion write -access; so far, everyone who asked has been given access. Any -Enthought staff member who would like Subversion write access will get -it. - -If either Epydoc or HappyDoc is chosen as the base platform, I will -ask the project's administrator for CVS access for myself and any -Enthought staff member who wants it. If sufficient access is not -granted -- although I doubt that there would be any problem -- we may -have to begin a fork, which could be hosted on SourceForge, on -Enthought's Subversion server, or anywhere else deemed appropriate. - - -Copyright & License -=================== - -Most existing Docutils files have been placed in the public domain, as -follows:: - - :Copyright: This document has been placed in the public domain. - -This is in conjunction with the "Public Domain Dedication" section of -COPYING.txt__. - -__ http://docutils.sourceforge.net/COPYING.html - -The code and documentation originating from Enthought funding will -have Enthought's copyright and license declaration. While I will try -to keep Enthought-specific code and documentation separate from the -existing files, there will inevitably be cases where it makes the most -sense to extend existing files. - -I propose the following: - -1. New files related to this Enthought-funded work will be identified - with the following field-list headers:: - - :Copyright: 2004 by Enthought, Inc. - :License: Enthought License (BSD Style) - - The license field text will be linked to the license file itself. - -2. For significant or major changes to an existing file (more than 10% - change), the headers shall change as follows (for example):: - - :Copyright: 2001-2004 by David Goodger - :Copyright: 2004 by Enthought, Inc. - :License: BSD-style - - If the Enthought-funded portion becomes greater than the previously - existing portion, Enthought's copyright line will be shown first. - -3. In cases of insignificant or minor changes to an existing file - (less than 10% change), the public domain status shall remain - unchanged. - -A section describing all of this will be added to the Docutils -`COPYING`__ instructions file. - -If another project is chosen as the base project, similar changes -would be made to their files, subject to negotiation. - -__ http://docutils.sf.net/COPYING.html - - -Proposed Changes to reStructuredText -==================================== - -Doc Comment Syntax ------------------- - -The "traits" construct is implemented as dictionaries, where -standalone strings would be Python syntax errors. Therefore traits -require documentation in comments. We also need a way to -differentiate between ordinary "internal" comments and documentation -comments (doc comments). - -Javadoc uses the following syntax for doc comments:: - - /** - * The first line of a multi-line doc comment begins with a slash - * and *two* asterisks. The doc comment ends normally. - */ - -Python doesn't have multi-line comments; only single-line. A similar -convention in Python might look like this:: - - ## - # The first line of a doc comment begins with *two* hash marks. - # The doc comment ends with the first non-comment line. - 'data' : AnyValue, - - ## The double-hash-marks could occur on the first line of text, - # saving a line in the source. - 'data' : AnyValue, - -How to indicate the end of the doc comment? :: - - ## - # The first line of a doc comment begins with *two* hash marks. - # The doc comment ends with the first non-comment line, or another - # double-hash-mark. - ## - # This is an ordinary, internal, non-doc comment. - 'data' : AnyValue, - - ## First line of a doc comment, terse syntax. - # Second (and last) line. Ends here: ## - # This is an ordinary, internal, non-doc comment. - 'data' : AnyValue, - -Or do we even need to worry about this case? A simple blank line -could be used:: - - ## First line of a doc comment, terse syntax. - # Second (and last) line. Ends with a blank line. - - # This is an ordinary, internal, non-doc comment. - 'data' : AnyValue, - -Other possibilities:: - - #" Instead of double-hash-marks, we could use a hash mark and a - # quotation mark to begin the doc comment. - 'data' : AnyValue, - - ## We could require double-hash-marks on every line. This has the - ## added benefit of delimiting the *end* of the doc comment, as - ## well as working well with line wrapping in Emacs - ## ("fill-paragraph" command). - # Ordinary non-doc comment. - 'data' : AnyValue, - - #" A hash mark and a quotation mark on each line looks funny, and - #" it doesn't work well with line wrapping in Emacs. - 'data' : AnyValue, - -These styles (repeated on each line) work well with line wrapping in -Emacs:: - - ## #> #| #- #% #! #* - -These styles do *not* work well with line wrapping in Emacs:: - - #" #' #: #) #. #/ #@ #$ #^ #= #+ #_ #~ - -The style of doc comment indicator used could be a runtime, global -and/or per-module setting. That may add more complexity than it's -worth though. - - -Recommendation -`````````````` - -I recommend adopting "#*" on every line:: - - # This is an ordinary non-doc comment. - - #* This is a documentation comment, with an asterisk after the - #* hash marks on every line. - 'data' : AnyValue, - -I initially recommended adopting double-hash-marks:: - - # This is an ordinary non-doc comment. - - ## This is a documentation comment, with double-hash-marks on - ## every line. - 'data' : AnyValue, - -But Janet Swisher rightly pointed out that this could collide with -ordinary comments that are then block-commented. This applies to -double-hash-marks on the first line only as well. So they're out. - -On the other hand, the JavaDoc-comment style ("##" on the first line -only, "#" after that) is used in Fredrik Lundh's PythonDoc_. It may -be worthwhile to conform to this syntax, reinforcing it as a standard. -PythonDoc does not support terse doc comments (text after "##" on the -first line). - -.. _PythonDoc: http://effbot.org/zone/pythondoc.htm - - -Update -`````` - -Enthought's Traits system has switched to a metaclass base, and traits -are now defined via ordinary attributes. Therefore doc comments are -no longer absolutely necessary; attribute docstrings will suffice. -Doc comments may still be desirable though, since they allow -documentation to precede the thing being documented. - - -Docstring Density & Whitespace Minimization -------------------------------------------- - -One problem with extensively documented classes & functions, is that -there is a lot of screen space wasted on whitespace. Here's some -current Enthought code (from lib/cp/fluids/gassmann.py):: - - def max_gas(temperature, pressure, api, specific_gravity=.56): - """ - Computes the maximum dissolved gas in oil using Batzle and - Wang (1992). - - Parameters - ---------- - temperature : sequence - Temperature in degrees Celsius - pressure : sequence - Pressure in MPa - api : sequence - Stock tank oil API - specific_gravity : sequence - Specific gravity of gas at STP, default is .56 - - Returns - ------- - max_gor : sequence - Maximum dissolved gas in liters/liter - - Description - ----------- - This estimate is based on equations given by Mavko, Mukerji, - and Dvorkin, (1998, pp. 218-219, or 2003, p. 236) obtained - originally from Batzle and Wang (1992). - """ - code... - -The docstring is 24 lines long. - -Rather than using subsections, field lists (which exist now) can save -6 lines:: - - def max_gas(temperature, pressure, api, specific_gravity=.56): - """ - Computes the maximum dissolved gas in oil using Batzle and - Wang (1992). - - :Parameters: - temperature : sequence - Temperature in degrees Celsius - pressure : sequence - Pressure in MPa - api : sequence - Stock tank oil API - specific_gravity : sequence - Specific gravity of gas at STP, default is .56 - :Returns: - max_gor : sequence - Maximum dissolved gas in liters/liter - :Description: This estimate is based on equations given by - Mavko, Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, - p. 236) obtained originally from Batzle and Wang (1992). - """ - code... - -As with the "Description" field above, field bodies may begin on the -same line as the field name, which also saves space. - -The output for field lists is typically a table structure. For -example: - - :Parameters: - temperature : sequence - Temperature in degrees Celsius - pressure : sequence - Pressure in MPa - api : sequence - Stock tank oil API - specific_gravity : sequence - Specific gravity of gas at STP, default is .56 - :Returns: - max_gor : sequence - Maximum dissolved gas in liters/liter - :Description: - This estimate is based on equations given by Mavko, - Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236) - obtained originally from Batzle and Wang (1992). - -But the definition lists describing the parameters and return values -are still wasteful of space. There are a lot of half-filled lines. - -Definition lists are currently defined as:: - - term : classifier - definition - -Where the classifier part is optional. Ideas for improvements: - -1. We could allow multiple classifiers:: - - term : classifier one : two : three ... - definition - -2. We could allow the definition on the same line as the term, using - some embedded/inline markup: - - * "--" could be used, but only in limited and well-known contexts:: - - term -- definition - - This is the syntax used by StructuredText (one of - reStructuredText's predecessors). It was not adopted for - reStructuredText because it is ambiguous -- people often use "--" - in their text, as I just did. But given a constrained context, - the ambiguity would be acceptable (or would it?). That context - would be: in docstrings, within a field list, perhaps only with - certain well-defined field names (parameters, returns). - - * The "constrained context" above isn't really enough to make the - ambiguity acceptable. Instead, a slightly more verbose but far - less ambiguous syntax is possible:: - - term === definition - - This syntax has advantages. Equals signs lend themselves to the - connotation of "definition". And whereas one or two equals signs - are commonly used in program code, three equals signs in a row - have no conflicting meanings that I know of. (Update: there - *are* uses out there.) - - The problem with this approach is that using inline markup for - structure is inherently ambiguous in reStructuredText. For - example, writing *about* definition lists would be difficult:: - - ``term === definition`` is an example of a compact definition list item - - The parser checks for structural markup before it does inline - markup processing. But the "===" should be protected by its inline - literal context. - -3. We could allow the definition on the same line as the term, using - structural markup. A variation on bullet lists would work well:: - - : term :: definition - : another term :: and a definition that - wraps across lines - - Some ambiguity remains:: - - : term ``containing :: double colons`` :: definition - - But the likelihood of such cases is negligible, and they can be - covered in the documentation. - - Other possibilities for the definition delimiter include:: - - : term : classifier -- definition - : term : classifier --- definition - : term : classifier : : definition - : term : classifier === definition - -The third idea currently has the best chance of being adopted and -implemented. - - -Recommendation -`````````````` - -Combining these ideas, the function definition becomes:: - - def max_gas(temperature, pressure, api, specific_gravity=.56): - """ - Computes the maximum dissolved gas in oil using Batzle and - Wang (1992). - - :Parameters: - : temperature : sequence :: Temperature in degrees Celsius - : pressure : sequence :: Pressure in MPa - : api : sequence :: Stock tank oil API - : specific_gravity : sequence :: Specific gravity of gas at - STP, default is .56 - :Returns: - : max_gor : sequence :: Maximum dissolved gas in liters/liter - :Description: This estimate is based on equations given by - Mavko, Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, - p. 236) obtained originally from Batzle and Wang (1992). - """ - code... - -The docstring is reduced to 14 lines, from the original 24. For -longer docstrings with many parameters and return values, the -difference would be more significant. diff --git a/docutils/docs/dev/enthought-rfp.txt b/docutils/docs/dev/enthought-rfp.txt deleted file mode 100644 index 986f5604f..000000000 --- a/docutils/docs/dev/enthought-rfp.txt +++ /dev/null @@ -1,146 +0,0 @@ -================================== - Enthought API Documentation Tool -================================== ------------------------ - Request for Proposals ------------------------ - -:Author: Janet Swisher, Senior Technical Writer -:Organization: `Enthought, Inc. <http://www.enthought.com>`_ -:Copyright: 2004 by Enthought, Inc. -:License: `Enthought License`_ (BSD Style) - -.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt - -The following is excerpted from the full RFP, and is published here -with permission from `Enthought, Inc.`_ See the `Plan for Enthought -API Documentation Tool`__. - -__ enthought-plan.html - -.. contents:: -.. sectnum:: - - -Requirements -============ - -The documentation tool will address the following high-level goals: - - -Documentation Extraction ------------------------- - -1. Documentation will be generated directly from Python source code, - drawing from the code structure, docstrings, and possibly other - comments. - -2. The tool will extract logical constructs as appropriate, minimizing - the need for comments that are redundant with the code structure. - The output should reflect both documented and undocumented - elements. - - -Source Format -------------- - -1. The docstrings will be formatted in as terse syntax as possible. - Required tags, syntax, and white space should be minimized. - -2. The tool must support the use of Traits. Special comment syntax - for Traits may be necessary. Information about the Traits package - is available at http://code.enthought.com/traits/. In the - following example, each trait definition is prefaced by a plain - comment:: - - __traits__ = { - - # The current selection within the frame. - 'selection' : Trait([], TraitInstance(list)), - - # The frame has been activated or deactivated. - 'activated' : TraitEvent(), - - 'closing' : TraitEvent(), - - # The frame is closed. - 'closed' : TraitEvent(), - } - -3. Support for ReStructuredText (ReST) format is desirable, because - much of the existing docstrings uses ReST. However, the complete - ReST specification need not be supported, if a subset can achieve - the project goals. If the tool does not support ReST, the - contractor should also provide a tool or path to convert existing - docstrings. - - -Output Format -------------- - -1. Documentation will be output as a navigable suite of HTML - files. - -2. The style of the HTML files will be customizable by a cascading - style sheet and/or a customizable template. - -3. Page elements such as headers and footer should be customizable, to - support differing requirements from one documentation project to - the next. - - -Output Structure and Navigation -------------------------------- - -1. The navigation scheme for the HTML files should not rely on frames, - and should harmonize with conversion to Microsoft HTML Help (.chm) - format. - -2. The output should be structured to make navigable the architecture - of the Python code. Packages, modules, classes, traits, and - functions should be presented in clear, logical hierarchies. - Diagrams or trees for inheritance, collaboration, sub-packaging, - etc. are desirable but not required. - -3. The output must include indexes that provide a comprehensive view - of all packages, modules, and classes. These indexes will provide - readers with a clear and exhaustive view of the code base. These - indexes should be presented in a way that is easily accessible and - allows easy navigation. - -4. Cross-references to other documented elements will be used - throughout the documentation, to enable the reader to move quickly - relevant information. For example, where type information for an - element is available, the type definition should be - cross-referenced. - -5. The HTML suite should provide consistent navigation back to the - home page, which will include the following information: - - * Bibliographic information - - - Author - - Copyright - - Release date - - Version number - - * Abstract - - * References - - - Links to related internal docs (i.e., other docs for the same - product) - - - Links to related external docs (e.g., supporting development - docs, Python support docs, docs for included packages) - - It should be possible to specify similar information at the top - level of each package, so that packages can be included as - appropriate for a given application. - - -License -======= - -Enthought intends to release the software under an open-source -("BSD-style") license. diff --git a/docutils/docs/dev/hacking.txt b/docutils/docs/dev/hacking.txt deleted file mode 100644 index d0ec9a3fb..000000000 --- a/docutils/docs/dev/hacking.txt +++ /dev/null @@ -1,264 +0,0 @@ -========================== - Docutils_ Hacker's Guide -========================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -:Abstract: This is the introduction to Docutils for all persons who - want to extend Docutils in some way. -:Prerequisites: You have used reStructuredText_ and played around with - the `Docutils front-end tools`_ before. Some (basic) Python - knowledge is certainly helpful (though not necessary, strictly - speaking). - -.. _Docutils: http://docutils.sourceforge.net/ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Docutils front-end tools: ../user/tools.html - -.. contents:: - - -Overview of the Docutils Architecture -===================================== - -To give you an understanding of the Docutils architecture, we'll dive -right into the internals using a practical example. - -Consider the following reStructuredText file:: - - My *favorite* language is Python_. - - .. _Python: http://www.python.org/ - -Using the ``rst2html.py`` front-end tool, you would get an HTML output -which looks like this:: - - [uninteresting HTML code removed] - <body> - <div class="document"> - <p>My <em>favorite</em> language is <a class="reference" href="http://www.python.org/">Python</a>.</p> - </div> - </body> - </html> - -While this looks very simple, it's enough to illustrate all internal -processing stages of Docutils. Let's see how this document is -processed from the reStructuredText source to the final HTML output: - - -Reading the Document --------------------- - -The **Reader** reads the document from the source file and passes it -to the parser (see below). The default reader is the standalone -reader (``docutils/readers/standalone.py``) which just reads the input -data from a single text file. Unless you want to do really fancy -things, there is no need to change that. - -Since you probably won't need to touch readers, we will just move on -to the next stage: - - -Parsing the Document --------------------- - -The **Parser** analyzes the the input document and creates a **node -tree** representation. In this case we are using the -**reStructuredText parser** (``docutils/parsers/rst/__init__.py``). -To see what that node tree looks like, we call ``quicktest.py`` (which -can be found in the ``tools/`` directory of the Docutils distribution) -with our example file (``test.txt``) as first parameter (Windows users -might need to type ``python quicktest.py test.txt``):: - - $ quicktest.py test.txt - <document source="test.txt"> - <paragraph> - My - <emphasis> - favorite - language is - <reference name="Python" refname="python"> - Python - . - <target ids="python" names="python" refuri="http://www.python.org/"> - -Let us now examine the node tree: - -The top-level node is ``document``. It has a ``source`` attribute -whose value is ``text.txt``. There are two children: A ``paragraph`` -node and a ``target`` node. The ``paragraph`` in turn has children: A -text node ("My "), an ``emphasis`` node, a text node (" language is "), -a ``reference`` node, and again a ``Text`` node ("."). - -These node types (``document``, ``paragraph``, ``emphasis``, etc.) are -all defined in ``docutils/nodes.py``. The node types are internally -arranged as a class hierarchy (for example, both ``emphasis`` and -``reference`` have the common superclass ``Inline``). To get an -overview of the node class hierarchy, use epydoc (type ``epydoc -nodes.py``) and look at the class hierarchy tree. - - -Transforming the Document -------------------------- - -In the node tree above, the ``reference`` node does not contain the -target URI (``http://www.python.org/``) yet. - -Assigning the target URI (from the ``target`` node) to the -``reference`` node is *not* done by the parser (the parser only -translates the input document into a node tree). - -Instead, it's done by a **Transform**. In this case (resolving a -reference), it's done by the ``ExternalTargets`` transform in -``docutils/transforms/references.py``. - -In fact, there are quite a lot of Transforms, which do various useful -things like creating the table of contents, applying substitution -references or resolving auto-numbered footnotes. - -The Transforms are applied after parsing. To see how the node tree -has changed after applying the Transforms, we use the -``rst2pseudoxml.py`` tool: - -.. parsed-literal:: - - $ rst2pseudoxml.py test.txt - <document source="test.txt"> - <paragraph> - My - <emphasis> - favorite - language is - <reference name="Python" **refuri="http://www.python.org/"**> - Python - . - <target ids="python" names="python" ``refuri="http://www.python.org/"``> - -For our small test document, the only change is that the ``refname`` -attribute of the reference has been replaced by a ``refuri`` -attribute |---| the reference has been resolved. - -While this does not look very exciting, transforms are a powerful tool -to apply any kind of transformation on the node tree. - -By the way, you can also get a "real" XML representation of the node -tree by using ``rst2xml.py`` instead of ``rst2pseudoxml.py``. - - -Writing the Document --------------------- - -To get an HTML document out of the node tree, we use a **Writer**, the -HTML writer in this case (``docutils/writers/html4css1.py``). - -The writer receives the node tree and returns the output document. -For HTML output, we can test this using the ``rst2html.py`` tool:: - - $ rst2html.py --link-stylesheet test.txt - <?xml version="1.0" encoding="utf-8" ?> - <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> - <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> - <meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" /> - <title></title> - <link rel="stylesheet" href="../docutils/writers/html4css1/html4css1.css" type="text/css" /> - </head> - <body> - <div class="document"> - <p>My <em>favorite</em> language is <a class="reference" href="http://www.python.org/">Python</a>.</p> - </div> - </body> - </html> - -So here we finally have our HTML output. The actual document contents -are in the fourth-last line. Note, by the way, that the HTML writer -did not render the (invisible) ``target`` node |---| only the -``paragraph`` node and its children appear in the HTML output. - - -Extending Docutils -================== - -Now you'll ask, "how do I actually extend Docutils?" - -First of all, once you are clear about *what* you want to achieve, you -have to decide *where* to implement it |---| in the Parser (e.g. by -adding a directive or role to the reStructuredText parser), as a -Transform, or in the Writer. There is often one obvious choice among -those three (Parser, Transform, Writer). If you are unsure, ask on -the Docutils-develop_ mailing list. - -In order to find out how to start, it is often helpful to look at -similar features which are already implemented. For example, if you -want to add a new directive to the reStructuredText parser, look at -the implementation of a similar directive in -``docutils/parsers/rst/directives/``. - - -Modifying the Document Tree Before It Is Written ------------------------------------------------- - -You can modify the document tree right before the writer is called. -One possibility is to use the publish_doctree_ and -publish_from_doctree_ functions. - -To retrieve the document tree, call:: - - document = docutils.core.publish_doctree(...) - -Please see the docstring of publish_doctree for a list of parameters. - -.. XXX Need to write a well-readable list of (commonly used) options - of the publish_* functions. Probably in api/publisher.txt. - -``document`` is the root node of the document tree. You can now -change the document by accessing the ``document`` node and its -children |---| see `The Node Interface`_ below. - -When you're done with modifying the document tree, you can write it -out by calling:: - - output = docutils.core.publish_from_doctree(document, ...) - -.. _publish_doctree: ../api/publisher.html#publish_doctree -.. _publish_from_doctree: ../api/publisher.html#publish_from_doctree - - -The Node Interface ------------------- - -As described in the overview above, Docutils' internal representation -of a document is a tree of nodes. We'll now have a look at the -interface of these nodes. - -(To be completed.) - - -What Now? -========= - -This document is not complete. Many topics could (and should) be -covered here. To find out with which topics we should write about -first, we are awaiting *your* feedback. So please ask your questions -on the Docutils-develop_ mailing list. - - -.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop - - -.. |---| unicode:: 8212 .. em-dash - :trim: - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/policies.txt b/docutils/docs/dev/policies.txt deleted file mode 100644 index 25fb4f2e9..000000000 --- a/docutils/docs/dev/policies.txt +++ /dev/null @@ -1,549 +0,0 @@ -=========================== - Docutils Project Policies -=========================== - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -The Docutils project group is a meritocracy based on code contribution -and lots of discussion [#bcs]_. A few quotes sum up the policies of -the Docutils project. The IETF's classic credo (by MIT professor Dave -Clark) is an ideal we can aspire to: - - We reject: kings, presidents, and voting. We believe in: rough - consensus and running code. - -As architect, chief cook and bottle-washer, David Goodger currently -functions as BDFN (Benevolent Dictator For Now). (But he would -happily abdicate the throne given a suitable candidate. Any takers?) - -Eric S. Raymond, anthropologist of the hacker subculture, writes in -his essay `The Magic Cauldron`_: - - The number of contributors [to] projects is strongly and inversely - correlated with the number of hoops each project makes a user go - through to contribute. - -We will endeavour to keep the barrier to entry as low as possible. -The policies below should not be thought of as barriers, but merely as -a codification of experience to date. These are "best practices"; -guidelines, not absolutes. Exceptions are expected, tolerated, and -used as a source of improvement. Feedback and criticism is welcome. - -As for control issues, Emmett Plant (CEO of the Xiph.org Foundation, -originators of Ogg Vorbis) put it well when he said: - - Open source dictates that you lose a certain amount of control - over your codebase, and that's okay with us. - -.. [#bcs] Phrase borrowed from `Ben Collins-Sussman of the Subversion - project <http://www.red-bean.com/sussman/svn-anti-fud.html>`__. - -.. _The Magic Cauldron: - http://www.catb.org/~esr/writings/magic-cauldron/ - - -Python Coding Conventions -========================= - -Contributed code will not be refused merely because it does not -strictly adhere to these conditions; as long as it's internally -consistent, clean, and correct, it probably will be accepted. But -don't be surprised if the "offending" code gets fiddled over time to -conform to these conventions. - -The Docutils project shall follow the generic coding conventions as -specified in the `Style Guide for Python Code`_ and `Docstring -Conventions`_ PEPs, summarized, clarified, and extended as follows: - -* 4 spaces per indentation level. No hard tabs. - -* Use only 7-bit ASCII, no 8-bit strings. See `Docutils - Internationalization`_. - -* No one-liner compound statements (i.e., no ``if x: return``: use two - lines & indentation), except for degenerate class or method - definitions (i.e., ``class X: pass`` is OK.). - -* Lines should be no more than 78 characters long. - -* Use "StudlyCaps" for class names (except for element classes in - docutils.nodes). - -* Use "lowercase" or "lowercase_with_underscores" for function, - method, and variable names. For short names, maximum two words, - joined lowercase may be used (e.g. "tagname"). For long names with - three or more words, or where it's hard to parse the split between - two words, use lowercase_with_underscores (e.g., - "note_explicit_target", "explicit_target"). If in doubt, use - underscores. - -* Avoid lambda expressions, which are inherently difficult to - understand. Named functions are preferable and superior: they're - faster (no run-time compilation), and well-chosen names serve to - document and aid understanding. - -* Avoid functional constructs (filter, map, etc.). Use list - comprehensions instead. - -* Avoid ``from __future__ import`` constructs. They are inappropriate - for production code. - -* Use 'single quotes' for string literals, and """triple double - quotes""" for docstrings. - -.. _Style Guide for Python Code: - http://www.python.org/peps/pep-0008.html -.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html -.. _Docutils Internationalization: ../howto/i18n.html#python-code - - -Documentation Conventions -========================= - -* Docutils documentation is written using reStructuredText, of course. - -* Use 7-bit ASCII if at all possible, and Unicode substitutions when - necessary. - -* Use the following section title adornment styles:: - - ================ - Document Title - ================ - - -------------------------------------------- - Document Subtitle, or Major Division Title - -------------------------------------------- - - Section - ======= - - Subsection - ---------- - - Sub-Subsection - `````````````` - - Sub-Sub-Subsection - .................. - -* Use two blank lines before each section/subsection/etc. title. One - blank line is sufficient between immediately adjacent titles. - -* Add a bibliographic field list immediately after the document - title/subtitle. See the beginning of this document for an example. - -* Add an Emacs "local variables" block in a comment at the end of the - document. See the end of this document for an example. - - -Copyrights and Licensing -======================== - -The majority of the Docutils project code and documentation has been -placed in the public domain. Unless clearly and explicitly indicated -otherwise, any patches (modifications to existing files) submitted to -the project for inclusion (via Subversion, SourceForge trackers, -mailing lists, or private email) are assumed to be in the public -domain as well. - -Any new files contributed to the project should clearly state their -intentions regarding copyright, in one of the following ways: - -* Public domain (preferred): include the statement "This - module/document has been placed in the public domain." - -* Copyright & open source license: include a copyright notice, along - with either an embedded license statement, a reference to an - accompanying license file, or a license URL. - -One of the goals of the Docutils project, once complete, is to be -incorporated into the Python standard library. At that time copyright -of the Docutils code will be assumed by or transferred to the Python -Software Foundation (PSF), and will be released under Python's -license. If the copyright/license option is chosen for new files, the -license should be compatible with Python's current license, and the -author(s) of the files should be willing to assign copyright to the -PSF. The PSF accepts the `Academic Free License v. 2.1 -<http://opensource.org/licenses/afl-2.1.php>`_ and the `Apache -License, Version 2.0 <http://opensource.org/licenses/apache2.0.php>`_. - - -Subversion Repository -===================== - -Please see the `repository documentation`_ for details on how to -access Docutils' Subversion repository. Anyone can access the -repository anonymously. Only project developers can make changes. -(If you would like to become a project developer, just ask!) Also see -`Setting Up For Docutils Development`_ below for some useful info. - -Unless you really *really* know what you're doing, please do *not* use -``svn import``. It's quite easy to mess up the repository with an -import. - -.. _repository documentation: repository.html - - -Branches --------- - -(These branch policies go into effect with Docutils 0.4.) - -The "docutils" directory of the **trunk** (a.k.a. the **Docutils -core**) is used for active -- but stable, fully tested, and reviewed --- development. - -There will be at least one active **maintenance branch** at a time, -based on at least the latest feature release. For example, when -Docutils 0.5 is released, its maintenance branch will take over, and -the 0.4.x maintenance branch may be retired. Maintenance branches -will receive bug fixes only; no new features will be allowed here. - -Obvious and uncontroversial bug fixes *with tests* can be checked in -directly to the core and to the maintenance branches. Don't forget to -add test cases! Many (but not all) bug fixes will be applicable both -to the core and to the maintenance branches; these should be applied -to both. No patches or dedicated branches are required for bug fixes, -but they may be used. It is up to the discretion of project -developers to decide which mechanism to use for each case. - -Feature additions and API changes will be done in **feature -branches**. Feature branches will not be managed in any way. -Frequent small checkins are encouraged here. Feature branches must be -discussed on the docutils-develop mailing list and reviewed before -being merged into the core. - - -Review Criteria -``````````````` - -Before a new feature, an API change, or a complex, disruptive, or -controversial bug fix can be checked in to the core or into a -maintenance branch, it must undergo review. These are the criteria: - -* The branch must be complete, and include full documentation and - tests. - -* There should ideally be one branch merge commit per feature or - change. In other words, each branch merge should represent a - coherent change set. - -* The code must be stable and uncontroversial. Moving targets and - features under debate are not ready to be merged. - -* The code must work. The test suite must complete with no failures. - See `Docutils Testing`_. - -The review process will ensure that at least one other set of eyeballs -& brains sees the code before it enters the core. In addition to the -above, the general `Check-ins`_ policy (below) also applies. - -.. _Docutils Testing: testing.html - - -Check-ins ---------- - -Changes or additions to the Docutils core and maintenance branches -carry a commitment to the Docutils user community. Developers must be -prepared to fix and maintain any code they have committed. - -The Docutils core (``trunk/docutils`` directory) and maintenance -branches should always be kept in a stable state (usable and as -problem-free as possible). All changes to the Docutils core or -maintenance branches must be in `good shape`_, usable_, documented_, -tested_, and `reasonably complete`_. - -* _`Good shape` means that the code is clean, readable, and free of - junk code (unused legacy code; by analogy to "junk DNA"). - -* _`Usable` means that the code does what it claims to do. An "XYZ - Writer" should produce reasonable XYZ output. - -* _`Documented`: The more complete the documentation the better. - Modules & files must be at least minimally documented internally. - `Docutils Front-End Tools`_ should have a new section for any - front-end tool that is added. `Docutils Configuration Files`_ - should be modified with any settings/options defined. For any - non-trivial change, the HISTORY.txt_ file should be updated. - -* _`Tested` means that unit and/or functional tests, that catch all - bugs fixed and/or cover all new functionality, have been added to - the test suite. These tests must be checked by running the test - suite under all supported Python versions, and the entire test suite - must pass. See `Docutils Testing`_. - -* _`Reasonably complete` means that the code must handle all input. - Here "handle" means that no input can cause the code to fail (cause - an exception, or silently and incorrectly produce nothing). - "Reasonably complete" does not mean "finished" (no work left to be - done). For example, a writer must handle every standard element - from the Docutils document model; for unimplemented elements, it - must *at the very least* warn that "Output for element X is not yet - implemented in writer Y". - -If you really want to check code directly into the Docutils core, -you can, but you must ensure that it fulfills the above criteria -first. People will start to use it and they will expect it to work! -If there are any issues with your code, or if you only have time for -gradual development, you should put it on a branch or in the sandbox -first. It's easy to move code over to the Docutils core once it's -complete. - -It is the responsibility and obligation of all developers to keep the -Docutils core and maintenance branches stable. If a commit is made to -the core or maintenance branch which breaks any test, the solution is -simply to revert the change. This is not vindictive; it's practical. -We revert first, and discuss later. - -Docutils will pursue an open and trusting policy for as long as -possible, and deal with any aberrations if (and hopefully not when) -they happen. We'd rather see a torrent of loose contributions than -just a trickle of perfect-as-they-stand changes. The occasional -mistake is easy to fix. That's what Subversion is for! - -.. _Docutils Front-End Tools: ../user/tools.html -.. _Docutils Configuration Files: ../user/config.html -.. _HISTORY.txt: ../../HISTORY.txt - - -Version Numbering -================= - -Docutils version numbering uses a ``major.minor.micro`` scheme (x.y.z; -for example, 0.4.1). - -**Major releases** (x.0, e.g. 1.0) will be rare, and will represent -major changes in API, functionality, or commitment. For example, as -long as the major version of Docutils is 0, it is to be considered -*experimental code*. When Docutils reaches version 1.0, the major -APIs will be considered frozen and backward compatibility will become -of paramount importance. - -Releases that change the minor number (x.y, e.g. 0.5) will be -**feature releases**; new features from the `Docutils core`_ will be -included. - -Releases that change the micro number (x.y.z, e.g. 0.4.1) will be -**bug-fix releases**. No new features will be introduced in these -releases; only bug fixes off of `maintenance branches`_ will be -included. - -This policy was adopted in October 2005, and will take effect with -Docutils version 0.4. Prior to version 0.4, Docutils didn't have an -official version numbering policy, and micro releases contained both -bug fixes and new features. - -.. _Docutils core: - http://svn.berlios.de/viewcvs/docutils/trunk/docutils/ -.. _maintenance branches: - http://svn.berlios.de/viewcvs/docutils/branches/ - - -Snapshots -========= - -Snapshot tarballs will be generated regularly from - -* the Docutils core, representing the current cutting-edge state of - development; - -* each active maintenance branch, for bug fixes; - -* each development branch, representing the unstable - seat-of-your-pants bleeding edge. - -The ``sandbox/infrastructure/docutils-update`` shell script, run as an -hourly cron job on the BerliOS server, is responsible for -automatically generating the snapshots and updating the web site. See -the `web site docs <website.html>`__. - - -Setting Up For Docutils Development -=================================== - -When making changes to the code, testing is a must. The code should -be run to verify that it produces the expected results, and the entire -test suite should be run too. The modified Docutils code has to be -accessible to Python for the tests to have any meaning. There are two -ways to keep the Docutils code accessible during development: - -1. Update your ``PYTHONPATH`` environment variable so that Python - picks up your local working copy of the code. This is the - recommended method. - - We'll assume that the Docutils trunk is checked out under your - ~/projects/ directory as follows:: - - svn co svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils/trunk \ - docutils - - For the bash shell, add this to your ``~/.profile``:: - - PYTHONPATH=$HOME/projects/docutils/docutils - PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras - export PYTHONPATH - - The first line points to the directory containing the ``docutils`` - package. The second line adds the directory containing the - third-party modules Docutils depends on. The third line exports - this environment variable. You may also wish to add the ``tools`` - directory to your ``PATH``:: - - PATH=$PATH:$HOME/projects/docutils/docutils/tools - export PATH - -2. Before you run anything, every time you make a change, reinstall - Docutils:: - - python setup.py install - - .. CAUTION:: - - This method is **not** recommended for day-to-day development; - it's too easy to forget. Confusion inevitably ensues. - - If you install Docutils this way, Python will always pick up the - last-installed copy of the code. If you ever forget to - reinstall the "docutils" package, Python won't see your latest - changes. - -A useful addition to the ``docutils`` top-level directory in branches -and alternate copies of the code is a ``set-PATHS`` file -containing the following lines:: - - # source this file - export PYTHONPATH=$PWD:$PWD/extras - export PATH=$PWD/tools:$PATH - -Open a shell for this branch, ``cd`` to the ``docutils`` top-level -directory, and "source" this file. For example, using the bash -shell:: - - $ cd some-branch/docutils - $ . set-PATHS - - -Mailing Lists -============= - -Developers are recommended to subscribe to all `Docutils mailing -lists`_. - -.. _Docutils mailing lists: ../user/mailing-lists.html - - -The Wiki -======== - -There is a development wiki at http://docutils.python-hosting.com/ as -a scratchpad for transient notes. Please use the repository for -permament document storage. - - -The Sandbox -=========== - -The `sandbox directory`_ is a place to play around, to try out and -share ideas. It's a part of the Subversion repository but it isn't -distributed as part of Docutils releases. Feel free to check in code -to the sandbox; that way people can try it out but you won't have to -worry about it working 100% error-free, as is the goal of the Docutils -core. Each developer who wants to play in the sandbox should create -either a project-specific subdirectory or personal subdirectory -(suggested name: SourceForge ID, nickname, or given name + family -initial). It's OK to make a mess in your personal space! But please, -play nice. - -Please update the `sandbox README`_ file with links and a brief -description of your work. - -In order to minimize the work necessary for others to install and try -out new, experimental components, the following sandbox directory -structure is recommended:: - - sandbox/ - project_name/ # For a collaborative project. - # Structure as in userid/component_name below. - userid/ # For personal space. - component_name/ # A verbose name is best. - README.txt # Please explain the requirements, - # purpose/goals, and usage. - docs/ - ... - component.py # The component is a single module. - # *OR* (but *not* both) - component/ # The component is a package. - __init__.py # Contains the Reader/Writer class. - other1.py # Other modules and data files used - data.txt # by this component. - ... - test/ # Test suite. - ... - tools/ # For front ends etc. - ... - setup.py # Use Distutils to install the component - # code and tools/ files into the right - # places in Docutils. - -Some sandbox projects are destined to become Docutils components once -completed. Others, such as add-ons to Docutils or applications of -Docutils, graduate to become `parallel projects`_. - -.. _sandbox README: http://docutils.sf.net/sandbox/README.html -.. _sandbox directory: - http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/ - - -.. _parallel project: - -Parallel Projects -================= - -Parallel projects contain useful code that is not central to the -functioning of Docutils. Examples are specialized add-ons or -plug-ins, and applications of Docutils. They use Docutils, but -Docutils does not require their presence to function. - -An official parallel project will have its own directory beside (or -parallel to) the main ``docutils`` directory in the Subversion -repository. It can have its own web page in the -docutils.sourceforge.net domain, its own file releases and -downloadable snapshots, and even a mailing list if that proves useful. -However, an official parallel project has implications: it is expected -to be maintained and continue to work with changes to the core -Docutils. - -A parallel project requires a project leader, who must commit to -coordinate and maintain the implementation: - -* Answer questions from users and developers. -* Review suggestions, bug reports, and patches. -* Monitor changes and ensure the quality of the code and - documentation. -* Coordinate with Docutils to ensure interoperability. -* Put together official project releases. - -Of course, related projects may be created independently of Docutils. -The advantage of a parallel project is that the SourceForge -environment and the developer and user communities are already -established. Core Docutils developers are available for consultation -and may contribute to the parallel project. It's easier to keep the -projects in sync when there are changes made to the core Docutils -code. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/pysource.dtd b/docutils/docs/dev/pysource.dtd deleted file mode 100644 index fb8af4091..000000000 --- a/docutils/docs/dev/pysource.dtd +++ /dev/null @@ -1,259 +0,0 @@ -<!-- -====================================================================== - Docutils Python Source DTD -====================================================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This DTD has been placed in the public domain. -:Filename: pysource.dtd - -This DTD (document type definition) extends the Generic DTD (see -below). - -More information about this DTD and the Docutils project can be found -at http://docutils.sourceforge.net/. The latest version of this DTD -is available from -http://docutils.sourceforge.net/docs/dev/pysource.dtd. - -The formal public identifier for this DTD is:: - - +//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML ---> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Parameter Entity Overrides -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ENTITY % additional.section.elements - " | package_section | module_section | class_section - | method_section | function_section - | module_attribute_section | function_attribute_section - | class_attribute_section | instance_attribute_section "> - -<!ENTITY % additional.inline.elements - " | package | module | class | method | function - | variable | parameter | type | attribute - | module_attribute | class_attribute | instance_attribute - | exception_class | warning_class "> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Generic DTD -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This DTD extends the Docutils Generic DTD, available from -http://docutils.sourceforge.net/docs/ref/docutils.dtd. ---> - -<!ENTITY % docutils PUBLIC - "+//IDN python.org//DTD Docutils Generic//EN//XML" - "docutils.dtd"> -%docutils; - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Additional Section Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT package_section - (package, fullname?, import_list?, %structure.model;)> -<!ATTLIST package_section %basic.atts;> - -<!ELEMENT module_section - (module, fullname?, import_list?, %structure.model;)> -<!ATTLIST module_section %basic.atts;> - -<!ELEMENT class_section - (class, inheritance_list?, fullname?, subclasses?, - %structure.model;)> -<!ATTLIST class_section %basic.atts;> - -<!ELEMENT method_section - (method, parameter_list?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST method_section %basic.atts;> - -<!ELEMENT function_section - (function, parameter_list?, fullname?, %structure.model;)> -<!ATTLIST function_section %basic.atts;> - -<!ELEMENT module_attribute_section - (attribute, initial_value?, fullname?, %structure.model;)> -<!ATTLIST module_attribute_section %basic.atts;> - -<!ELEMENT function_attribute_section - (attribute, initial_value?, fullname?, %structure.model;)> -<!ATTLIST function_attribute_section %basic.atts;> - -<!ELEMENT class_attribute_section - (attribute, initial_value?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST class_attribute_section %basic.atts;> - -<!ELEMENT instance_attribute_section - (attribute, initial_value?, fullname?, overrides?, - %structure.model;)> -<!ATTLIST instance_attribute_section %basic.atts;> - -<!-- - Section Subelements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT fullname - (package | module | class | method | function | attribute)+> -<!ATTLIST fullname %basic.atts;> - -<!ELEMENT import_list (import_item+)> -<!ATTLIST import_list %basic.atts;> - -<!-- -Support ``import module``, ``import module as alias``, ``from module -import identifier``, and ``from module import identifier as alias``. ---> -<!ELEMENT import_item (fullname, identifier?, alias?)> -<!ATTLIST import_item %basic.atts;> - -<!ELEMENT inheritance_list (class+)> -<!ATTLIST inheritance_list %basic.atts;> - -<!ELEMENT subclasses (class+)> -<!ATTLIST subclasses %basic.atts;> - -<!ELEMENT parameter_list - ((parameter_item+, optional_parameters*) | optional_parameters+)> -<!ATTLIST parameter_list %basic.atts;> - -<!ELEMENT parameter_item - ((parameter | parameter_tuple), parameter_default?)> -<!ATTLIST parameter_item %basic.atts;> - -<!ELEMENT optional_parameters (parameter_item+, optional_parameters*)> -<!ATTLIST optional_parameters %basic.atts;> - -<!ELEMENT parameter_tuple (parameter | parameter_tuple)+> -<!ATTLIST parameter_tuple %basic.atts;> - -<!ELEMENT parameter_default (#PCDATA)> -<!ATTLIST parameter_default %basic.atts;> - -<!ELEMENT overrides (fullname+)> -<!ATTLIST overrides %basic.atts;> - -<!ELEMENT initial_value (#PCDATA)> -<!ATTLIST initial_value %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Additional Inline Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!-- Also used as the `package_section` identifier/title. --> -<!ELEMENT package (#PCDATA)> -<!ATTLIST package - %basic.atts; - %reference.atts;> - -<!-- Also used as the `module_section` identifier/title. --> -<!ELEMENT module (#PCDATA)> -<!ATTLIST module - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `class_section` identifier/title, and in the -`inheritance` element. ---> -<!ELEMENT class (#PCDATA)> -<!ATTLIST class - %basic.atts; - %reference.atts;> - -<!-- Also used as the `method_section` identifier/title. --> -<!ELEMENT method (#PCDATA)> -<!ATTLIST method - %basic.atts; - %reference.atts;> - -<!-- Also used as the `function_section` identifier/title. --> -<!ELEMENT function (#PCDATA)> -<!ATTLIST function - %basic.atts; - %reference.atts;> - -<!-- -??? Use this instead of the ``*_attribute`` elements below? Add a -"type" attribute to differentiate? - -Also used as the identifier/title for `module_attribute_section`, -`class_attribute_section`, and `instance_attribute_section`. ---> -<!ELEMENT attribute (#PCDATA)> -<!ATTLIST attribute - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `module_attribute_section` identifier/title. A module -attribute is an exported module-level global variable. ---> -<!ELEMENT module_attribute (#PCDATA)> -<!ATTLIST module_attribute - %basic.atts; - %reference.atts;> - -<!-- Also used as the `class_attribute_section` identifier/title. --> -<!ELEMENT class_attribute (#PCDATA)> -<!ATTLIST class_attribute - %basic.atts; - %reference.atts;> - -<!-- -Also used as the `instance_attribute_section` identifier/title. ---> -<!ELEMENT instance_attribute (#PCDATA)> -<!ATTLIST instance_attribute - %basic.atts; - %reference.atts;> - -<!ELEMENT variable (#PCDATA)> -<!ATTLIST variable - %basic.atts; - %reference.atts;> - -<!-- Also used in `parameter_list`. --> -<!ELEMENT parameter (#PCDATA)> -<!ATTLIST parameter - %basic.atts; - %reference.atts; - excess_positional %yesorno; #IMPLIED - excess_keyword %yesorno; #IMPLIED> - -<!ELEMENT type (#PCDATA)> -<!ATTLIST type - %basic.atts; - %reference.atts;> - -<!ELEMENT exception_class (#PCDATA)> -<!ATTLIST exception_class - %basic.atts; - %reference.atts;> - -<!ELEMENT warning_class (#PCDATA)> -<!ATTLIST warning_class - %basic.atts; - %reference.atts;> - -<!-- -Local Variables: -mode: sgml -indent-tabs-mode: nil -fill-column: 70 -End: ---> diff --git a/docutils/docs/dev/pysource.txt b/docutils/docs/dev/pysource.txt deleted file mode 100644 index 6f173a709..000000000 --- a/docutils/docs/dev/pysource.txt +++ /dev/null @@ -1,130 +0,0 @@ -====================== - Python Source Reader -====================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -This document explores issues around extracting and processing -docstrings from Python modules. - -For definitive element hierarchy details, see the "Python Plaintext -Document Interface DTD" XML document type definition, pysource.dtd_ -(which modifies the generic docutils.dtd_). Descriptions below list -'DTD elements' (XML 'generic identifiers' or tag names) corresponding -to syntax constructs. - - -.. contents:: - - -Model -===== - -The Python Source Reader ("PySource") model that's evolving in my mind -goes something like this: - -1. Extract the docstring/namespace [#]_ tree from the module(s) and/or - package(s). - - .. [#] See `Docstring Extractor`_ below. - -2. Run the parser on each docstring in turn, producing a forest of - doctrees (per nodes.py). - -3. Join the docstring trees together into a single tree, running - transforms: - - - merge hyperlinks - - merge namespaces - - create various sections like "Module Attributes", "Functions", - "Classes", "Class Attributes", etc.; see pysource.dtd_ - - convert the above special sections to ordinary doctree nodes - -4. Run transforms on the combined doctree. Examples: resolving - cross-references/hyperlinks (including interpreted text on Python - identifiers); footnote auto-numbering; first field list -> - bibliographic elements. - - (Or should step 4's transforms come before step 3?) - -5. Pass the resulting unified tree to the writer/builder. - -I've had trouble reconciling the roles of input parser and output -writer with the idea of modes ("readers" or "directors"). Does the -mode govern the tranformation of the input, the output, or both? -Perhaps the mode should be split into two. - -For example, say the source of our input is a Python module. Our -"input mode" should be the "Python Source Reader". It discovers (from -``__docformat__``) that the input parser is "reStructuredText". If we -want HTML, we'll specify the "HTML" output formatter. But there's a -piece missing. What *kind* or *style* of HTML output do we want? -PyDoc-style, LibRefMan style, etc. (many people will want to specify -and control their own style). Is the output style specific to a -particular output format (XML, HTML, etc.)? Is the style specific to -the input mode? Or can/should they be independent? - -I envision interaction between the input parser, an "input mode" , and -the output formatter. The same intermediate data format would be used -between each of these, being transformed as it progresses. - - -Docstring Extractor -=================== - -We need code that scans a parsed Python module, and returns an ordered -tree containing the names, docstrings (including attribute and -additional docstrings), and additional info (in parentheses below) of -all of the following objects: - -- packages -- modules -- module attributes (+ values) -- classes (+ inheritance) -- class attributes (+ values) -- instance attributes (+ values) -- methods (+ formal parameters & defaults) -- functions (+ formal parameters & defaults) - -(Extract comments too? For example, comments at the start of a module -would be a good place for bibliographic field lists.) - -In order to evaluate interpreted text cross-references, namespaces for -each of the above will also be required. - -See python-dev/docstring-develop thread "AST mining", started on -2001-08-14. - - -Interpreted Text -================ - -DTD elements: package, module, class, method, function, -module_attribute, class_attribute, instance_attribute, variable, -parameter, type, exception_class, warning_class. - -To classify identifiers explicitly, the role is given along with the -identifier in either prefix or suffix form:: - - Use :method:`Keeper.storedata` to store the object's data in - `Keeper.data`:instance_attribute:. - -The role may be one of 'package', 'module', 'class', 'method', -'function', 'module_attribute', 'class_attribute', -'instance_attribute', 'variable', 'parameter', 'type', -'exception_class', 'exception', 'warning_class', or 'warning'. Other -roles may be defined. - -.. _pysource.dtd: pysource.dtd -.. _docutils.dtd: ../ref/docutils.dtd - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - fill-column: 70 - End: diff --git a/docutils/docs/dev/release.txt b/docutils/docs/dev/release.txt deleted file mode 100644 index fa58bc46f..000000000 --- a/docutils/docs/dev/release.txt +++ /dev/null @@ -1,168 +0,0 @@ -============================= - Docutils_ Release Procedure -============================= -:Author: David Goodger; Felix Wiemann; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - - -(Steps in boldface text are *not* covered by the release script at -sandbox/fwiemann/release.sh. "Not covered" means that you aren't even -reminded of them. Note: The release.sh script needs to be updated to -reflect the recent move to Subversion!) - -* **Announce a check-in freeze on Docutils-develop. Post a list of - major changes since the last release and ask for additions.** - - .. _CHANGES.txt: - - **You may want to save this list of changes in a file - (e.g. CHANGES.txt) to have it at hand when you need it for posting - announcements or pasting it into forms.** - -* Change ``__version_details__`` in docutils/docutils/__init__.py to - "release" (from "repository"). - -* Bump the _`version number` in the following files: - - + docutils/setup.py - + docutils/docutils/__init__.py - + docutils/test/functional/expected/* ("Generator: Docutils X.Y.Z") - -* Close the "Changes Since ..." section in docutils/HISTORY.txt. - -* Clear/unset the PYTHONPATH environment variable. - -* Create the release tarball: - - (a) Create a new empty directory and ``cd`` into it. - - (b) Get a clean snapshot of the main tree:: - - svn export svn://svn.berlios.de/docutils/trunk/docutils - - (c) Use Distutils to create the release tarball:: - - cd docutils - python setup.py sdist - -* Expand and _`install` the release tarball in isolation: - - (a) Expand the tarball in a new location, not over any existing - files. - - (b) Remove the old installation from site-packages (including - roman.py, and optparse.py, textwrap.py). - - Install from expanded directory:: - - cd docutils-X.Y.Z - python setup.py install - - The "install" command may require root permissions. - - (c) Repeat step b) for all supported Python versions. - -* Run the _`test suite` from the expanded archive directory with all - supported Python versions: ``cd test ; python -u alltests.py``. - -* Add a directory X.Y.Z (where X.Y.Z is the current version number - of Docutils) in the webroot (i.e. the ``htdocs/`` directory). - Put all documentation files into it:: - - cd docutils-X.Y.Z - rm -rf build - cd tools/ - ./buildhtml.py .. - cd .. - find -name test -type d -prune -o -name \*.css -print0 \ - -o -name \*.html -print0 -o -name \*.txt -print0 \ - | tar -cjvf docutils-docs.tar.bz2 -T - --null - scp docutils-docs.tar.bz2 <username>@shell.sourceforge.net: - - Now log in to shell.sourceforge.net and:: - - cd /home/groups/d/do/docutils/htdocs/ - mkdir -m g+rwxs X.Y.Z - cd X.Y.Z - tar -xjvf ~/docutils-docs.tar.bz2 - rm ~/docutils-docs.tar.bz2 - -* Upload the release tarball:: - - $ ftp upload.sourceforge.net - Connected to osdn.dl.sourceforge.net. - ... - Name (upload.sourceforge.net:david): anonymous - 331 Anonymous login ok, send your complete e-mail address as password. - Password: - ... - 230 Anonymous access granted, restrictions apply. - ftp> bin - 200 Type set to I. - ftp> cd /incoming - 250 CWD command successful. - ftp> put docutils-X.Y.Z.tar.gz - -* Access the _`file release system` on SourceForge (Admin - interface). Fill in the fields: - - :Package ID: docutils - :Release Name: <use release number only, e.g. 0.3> - :Release Date: <today's date> - :Status: Active - :File Name: <select the file just uploaded> - :File Type: Source .gz - :Processor Type: Platform-Independent - :Release Notes: <insert README.txt file here> - :Change Log: <insert summary from CHANGES.txt_> - - Also check the "Preserve my pre-formatted text" box. - -* For verifying the integrity of the release, download the release - tarball (you may need to wait up to 30 minutes), install_ it, and - re-run the `test suite`_. - -* Register with PyPI (``python setup.py register``). - -* Restore ``__version_details__`` in docutils/docutils/__init__.py to - "repository" (from "release"). - -* Bump the `version number`_ again. - -* Add a new empty section "Changes Since ..." in HISTORY.txt. - -* Update the web page (web/index.txt). - -* Run docutils-update on the server. - -* **Send announcement email to:** - - * docutils-develop@lists.sourceforge.net (also announcing the end - of the check-in freeze) - * docutils-users@lists.sourceforge.net - * doc-sig@python.org - * python-announce@python.org - -* **Add a SourceForge News item, with title "Docutils X.Y.Z released" - and containing the release tarball's download URL.** - -* **Register with FreshMeat.** (Add a `new release`__ for the - `Docutils project`__). - - __ http://freshmeat.net/add-release/48702/ - __ http://freshmeat.net/projects/docutils/ - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/repository.txt b/docutils/docs/dev/repository.txt deleted file mode 100644 index 2c613b10e..000000000 --- a/docutils/docs/dev/repository.txt +++ /dev/null @@ -1,217 +0,0 @@ -===================================== - The Docutils_ Subversion Repository -===================================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - -Docutils uses a Subversion_ repository located at ``svn.berlios.de``. -Subversion is exhaustively documented in the `Subversion Book`_ -(svnbook). - -.. _Subversion: http://subversion.tigris.org/ -.. _Subversion Book: http://svnbook.red-bean.com/ - -.. Note:: - - While the repository resides at BerliOS, all other project data - (web site, snapshots, releases, mailing lists, trackers) is hosted - at SourceForge. - -For the project policy on repository use (check-in requirements, -branching, etc.), please see the `Docutils Project Policies`__. - -__ policies.html#subversion-repository - - -Accessing the Repository -======================== - -Web Access ----------- - -The repository can be browsed and examined via the web at -http://svn.berlios.de/viewcvs/docutils/. - - -Anonymous Access ----------------- - -Anonymous (read-only) access is available at ``svn://svn.berlios.de/docutils/``. - -To check out the current main source tree of Docutils, type :: - - svn checkout svn://svn.berlios.de/docutils/trunk/docutils - -To check out everything (main tree, sandboxes, and web site), type :: - - svn checkout svn://svn.berlios.de/docutils/trunk docutils - -This will create a working copy of the whole trunk in a new directory -called ``docutils``. - -If you cannot use the ``svn`` port, you can also use the HTTP access -method by substituting "http://svn.berlios.de/svnroot/repos" for -"svn://svn.berlios.de". - -Note that you should *not* check out ``svn://svn.berlios.de/docutils`` -(without "trunk"), because then you'd end up fetching the whole -Docutils tree for every branch and tag over and over again, wasting -your and BerliOS's bandwidth. - -To update your working copy later on, cd into the working copy and -type :: - - svn update - - -Developer Access ----------------- - -(Developers who had write-access for Docutils' CVS repository on -SourceForge.net should `register at BerliOS`__ and send a message with -their BerliOS user name to `Felix Wiemann <Felix.Wiemann@ososo.de>`_.) - -__ https://developer.berlios.de/account/register.php - -If you are a developer, you get read-write access via -``svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils/``, where -``<user>`` is your BerliOS user account name. So to retrieve a -working copy, type :: - - svn checkout svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils/trunk \ - docutils - -If you previously had an anonymous working copy and gained developer -access, you can switch the URL associated with your working copy by -typing :: - - svn switch --relocate svn://svn.berlios.de/docutils/trunk/docutils \ - svn+ssh://<user>@svn.berlios.de/svnroot/repos/docutils - -(Again, ``<user>`` is your BerliOS user account name.) - -If you cannot use the ``ssh`` port, you can also use the HTTPS access -method by substituting "https://svn.berlios.de" for -"svn+ssh://svn.berlios.de". - - -Setting Up Your Subversion Client For Development -````````````````````````````````````````````````` - -Before commiting changes to the repository, please ensure that the -following lines are contained (and uncommented) in your -~/.subversion/config file, so that new files are added with the -correct properties set:: - - [miscellany] - # For your convenience: - global-ignores = ... *.pyc ... - # For correct properties: - enable-auto-props = yes - - [auto-props] - *.py = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.txt = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.html = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.xml = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.tex = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.css = svn:eol-style=native;svn:keywords=Author Date Id Revision - *.patch = svn:eol-style=native - *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Id Revision - *.png = svn:mime-type=image/png - *.jpg = svn:mime-type=image/jpeg - *.gif = svn:mime-type=image/gif - - -Setting Up SSH Access -````````````````````` - -With a public & private key pair, you can access the shell and -Subversion servers without having to enter your password. There are -two places to add your SSH public key on BerliOS: your web account and -your shell account. - -* Adding your SSH key to your BerliOS web account: - - 1. Log in on the web at https://developer.berlios.de/. Create your - account first if necessary. You should be taken to your "My - Personal Page" (https://developer.berlios.de/my/). - - 2. Choose "Account Options" from the menu below the top banner. - - 3. At the bottom of the "Account Maintenance" page - (https://developer.berlios.de/account/) you'll find a "Shell - Account Information" section; click on "[Edit Keys]". - - 4. Copy and paste your SSH public key into the edit box on this page - (https://developer.berlios.de/account/editsshkeys.php). Further - instructions are available on this page. - -* Adding your SSH key to your BerliOS shell account: - - 1. Log in to the BerliOS shell server:: - - ssh <user>@shell.berlios.de - - You'll be asked for your password, which you set when you created - your account. - - 2. Create a .ssh directory in your home directory, and remove - permissions for group & other:: - - mkdir .ssh - chmod og-rwx .ssh - - Exit the SSH session. - - 3. Copy your public key to the .ssh directory on BerliOS:: - - scp .ssh/id_dsa.pub <user>@shell.berlios.de:.ssh/authorized_keys - - Now you should be able to start an SSH session without needing your - password. - - -Repository Layout -================= - -The following tree shows the repository layout:: - - docutils/ - |-- branches/ - | |-- branch1/ - | | |-- docutils/ - | | |-- sandbox/ - | | `-- web/ - | `-- branch2/ - | |-- docutils/ - | |-- sandbox/ - | `-- web/ - |-- tags/ - | |-- tag1/ - | | |-- docutils/ - | | |-- sandbox/ - | | `-- web/ - | `-- tag2/ - | |-- docutils/ - | |-- sandbox/ - | `-- web/ - `-- trunk/ - |-- docutils/ - |-- sandbox/ - `-- web/ - -``docutils/branches/`` and ``docutils/tags/`` contain (shallow) copies -of the whole trunk. - -The main source tree lives at ``docutils/trunk/docutils/``, next to -the sandboxes (``docutils/trunk/sandbox/``) and the web site files -(``docutils/trunk/web/``). diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt deleted file mode 100644 index 12874c5fb..000000000 --- a/docutils/docs/dev/rst/alternatives.txt +++ /dev/null @@ -1,3129 +0,0 @@ -================================================== - A Record of reStructuredText Syntax Alternatives -================================================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -The following are ideas, alternatives, and justifications that were -considered for reStructuredText syntax, which did not originate with -Setext_ or StructuredText_. For an analysis of constructs which *did* -originate with StructuredText or Setext, please see `Problems With -StructuredText`_. See the `reStructuredText Markup Specification`_ -for full details of the established syntax. - -The ideas are divided into sections: - -* Implemented_: already done. The issues and alternatives are - recorded here for posterity. - -* `Not Implemented`_: these ideas won't be implemented. - -* Tabled_: these ideas should be revisited in the future. - -* `To Do`_: these ideas should be implemented. They're just waiting - for a champion to resolve issues and get them done. - -* `... Or Not To Do?`_: possible but questionable. These probably - won't be implemented, but you never know. - -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage -.. _Problems with StructuredText: problems.html -.. _reStructuredText Markup Specification: - ../../ref/rst/restructuredtext.html - - -.. contents:: - -------------- - Implemented -------------- - -Field Lists -=========== - -Prior to the syntax for field lists being finalized, several -alternatives were proposed. - -1. Unadorned RFC822_ everywhere:: - - Author: Me - Version: 1 - - Advantages: clean, precedent (RFC822-compliant). Disadvantage: - ambiguous (these paragraphs are a prime example). - - Conclusion: rejected. - -2. Special case: use unadorned RFC822_ for the very first or very last - text block of a document:: - - """ - Author: Me - Version: 1 - - The rest of the document... - """ - - Advantages: clean, precedent (RFC822-compliant). Disadvantages: - special case, flat (unnested) field lists only, still ambiguous:: - - """ - Usage: cmdname [options] arg1 arg2 ... - - We obviously *don't* want the like above to be interpreted as a - field list item. Or do we? - """ - - Conclusion: rejected for the general case, accepted for specific - contexts (PEPs, email). - -3. Use a directive:: - - .. fields:: - - Author: Me - Version: 1 - - Advantages: explicit and unambiguous, RFC822-compliant. - Disadvantage: cumbersome. - - Conclusion: rejected for the general case (but such a directive - could certainly be written). - -4. Use Javadoc-style:: - - @Author: Me - @Version: 1 - @param a: integer - - Advantages: unambiguous, precedent, flexible. Disadvantages: - non-intuitive, ugly, not RFC822-compliant. - - Conclusion: rejected. - -5. Use leading colons:: - - :Author: Me - :Version: 1 - - Advantages: unambiguous, obvious (*almost* RFC822-compliant), - flexible, perhaps even elegant. Disadvantages: no precedent, not - quite RFC822-compliant. - - Conclusion: accepted! - -6. Use double colons:: - - Author:: Me - Version:: 1 - - Advantages: unambiguous, obvious? (*almost* RFC822-compliant), - flexible, similar to syntax already used for literal blocks and - directives. Disadvantages: no precedent, not quite - RFC822-compliant, similar to syntax already used for literal blocks - and directives. - - Conclusion: rejected because of the syntax similarity & conflicts. - -Why is RFC822 compliance important? It's a universal Internet -standard, and super obvious. Also, I'd like to support the PEP format -(ulterior motive: get PEPs to use reStructuredText as their standard). -But it *would* be easy to get used to an alternative (easy even to -convert PEPs; probably harder to convert python-deviants ;-). - -Unfortunately, without well-defined context (such as in email headers: -RFC822 only applies before any blank lines), the RFC822 format is -ambiguous. It is very common in ordinary text. To implement field -lists unambiguously, we need explicit syntax. - -The following question was posed in a footnote: - - Should "bibliographic field lists" be defined at the parser level, - or at the DPS transformation level? In other words, are they - reStructuredText-specific, or would they also be applicable to - another (many/every other?) syntax? - -The answer is that bibliographic fields are a -reStructuredText-specific markup convention. Other syntaxes may -implement the bibliographic elements explicitly. For example, there -would be no need for such a transformation for an XML-based markup -syntax. - -.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt - - -Interpreted Text "Roles" -======================== - -The original purpose of interpreted text was as a mechanism for -descriptive markup, to describe the nature or role of a word or -phrase. For example, in XML we could say "<function>len</function>" -to mark up "len" as a function. It is envisaged that within Python -docstrings (inline documentation in Python module source files, the -primary market for reStructuredText) the role of a piece of -interpreted text can be inferred implicitly from the context of the -docstring within the program source. For other applications, however, -the role may have to be indicated explicitly. - -Interpreted text is enclosed in single backquotes (`). - -1. Initially, it was proposed that an explicit role could be indicated - as a word or phrase within the enclosing backquotes: - - - As a prefix, separated by a colon and whitespace:: - - `role: interpreted text` - - - As a suffix, separated by whitespace and a colon:: - - `interpreted text :role` - - There are problems with the initial approach: - - - There could be ambiguity with interpreted text containing colons. - For example, an index entry of "Mission: Impossible" would - require a backslash-escaped colon. - - - The explicit role is descriptive markup, not content, and will - not be visible in the processed output. Putting it inside the - backquotes doesn't feel right; the *role* isn't being quoted. - -2. Tony Ibbs suggested that the role be placed outside the - backquotes:: - - role:`prefix` or `suffix`:role - - This removes the embedded-colons ambiguity, but limits the role - identifier to be a single word (whitespace would be illegal). - Since roles are not meant to be visible after processing, the lack - of whitespace support is not important. - - The suggested syntax remains ambiguous with respect to ratios and - some writing styles. For example, suppose there is a "signal" - identifier, and we write:: - - ...calculate the `signal`:noise ratio. - - "noise" looks like a role. - -3. As an improvement on #2, we can bracket the role with colons:: - - :role:`prefix` or `suffix`:role: - - This syntax is similar to that of field lists, which is fine since - both are doing similar things: describing. - - This is the syntax chosen for reStructuredText. - -4. Another alternative is two colons instead of one:: - - role::`prefix` or `suffix`::role - - But this is used for analogies ("A:B::C:D": "A is to B as C is to - D"). - - Both alternative #2 and #4 lack delimiters on both sides of the - role, making it difficult to parse (by the reader). - -5. Some kind of bracketing could be used: - - - Parentheses:: - - (role)`prefix` or `suffix`(role) - - - Braces:: - - {role}`prefix` or `suffix`{role} - - - Square brackets:: - - [role]`prefix` or `suffix`[role] - - - Angle brackets:: - - <role>`prefix` or `suffix`<role> - - (The overlap of \*ML tags with angle brackets would be too - confusing and precludes their use.) - -Syntax #3 was chosen for reStructuredText. - - -Comments -======== - -A problem with comments (actually, with all indented constructs) is -that they cannot be followed by an indented block -- a block quote -- -without swallowing it up. - -I thought that perhaps comments should be one-liners only. But would -this mean that footnotes, hyperlink targets, and directives must then -also be one-liners? Not a good solution. - -Tony Ibbs suggested a "comment" directive. I added that we could -limit a comment to a single text block, and that a "multi-block -comment" could use "comment-start" and "comment-end" directives. This -would remove the indentation incompatibility. A "comment" directive -automatically suggests "footnote" and (hyperlink) "target" directives -as well. This could go on forever! Bad choice. - -Garth Kidd suggested that an "empty comment", a ".." explicit markup -start with nothing on the first line (except possibly whitespace) and -a blank line immediately following, could serve as an "unindent". An -empty comment does **not** swallow up indented blocks following it, -so block quotes are safe. "A tiny but practical wart." Accepted. - - -Anonymous Hyperlinks -==================== - -Alan Jaffray came up with this idea, along with the following syntax:: - - Search the `Python DOC-SIG mailing list archives`{}_. - - .. _: http://mail.python.org/pipermail/doc-sig/ - -The idea is sound and useful. I suggested a "double underscore" -syntax:: - - Search the `Python DOC-SIG mailing list archives`__. - - .. __: http://mail.python.org/pipermail/doc-sig/ - -But perhaps single underscores are okay? The syntax looks better, but -the hyperlink itself doesn't explicitly say "anonymous":: - - Search the `Python DOC-SIG mailing list archives`_. - - .. _: http://mail.python.org/pipermail/doc-sig/ - -Mixing anonymous and named hyperlinks becomes confusing. The order of -targets is not significant for named hyperlinks, but it is for -anonymous hyperlinks:: - - Hyperlinks: anonymous_, named_, and another anonymous_. - - .. _named: named - .. _: anonymous1 - .. _: anonymous2 - -Without the extra syntax of double underscores, determining which -hyperlink references are anonymous may be difficult. We'd have to -check which references don't have corresponding targets, and match -those up with anonymous targets. Keeping to a simple consistent -ordering (as with auto-numbered footnotes) seems simplest. - -reStructuredText will use the explicit double-underscore syntax for -anonymous hyperlinks. An alternative (see `Reworking Explicit Markup -(Round 1)`_ below) for the somewhat awkward ".. __:" syntax is "__":: - - An anonymous__ reference. - - __ http://anonymous - - -Reworking Explicit Markup (Round 1) -=================================== - -Alan Jaffray came up with the idea of `anonymous hyperlinks`_, added -to reStructuredText. Subsequently it was asserted that hyperlinks -(especially anonymous hyperlinks) would play an increasingly important -role in reStructuredText documents, and therefore they require a -simpler and more concise syntax. This prompted a review of the -current and proposed explicit markup syntaxes with regards to -improving usability. - -1. Original syntax:: - - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - .. Note:: - - The comment text was intentionally made to look like a hyperlink - target. - - Origins: - - * Except for the colon (a delimiter necessary to allow for - phrase-links), hyperlink target ``.. _blah:`` comes from Setext. - * Comment syntax from Setext. - * Footnote syntax from StructuredText ("named links"). - * Directives and anonymous hyperlinks original to reStructuredText. - - Advantages: - - + Consistent explicit markup indicator: "..". - + Consistent hyperlink syntax: ".. _" & ":". - - Disadvantages: - - - Anonymous target markup is awkward: ".. __:". - - The explicit markup indicator ("..") is excessively overloaded? - - Comment text is limited (can't look like a footnote, hyperlink, - or directive). But this is probably not important. - -2. Alan Jaffray's proposed syntax #1:: - - __ _blah internal hyperlink target - __ blah: http://somewhere external hyperlink target - __ blah: blahblah_ indirect hyperlink target - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target - __ [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - The hyperlink-connoted underscores have become first-level syntax. - - Advantages: - - + Anonymous targets are simpler. - + All hyperlink targets are one character shorter. - - Disadvantages: - - - Inconsistent internal hyperlink targets. Unlike all other named - hyperlink targets, there's no colon. There's an extra leading - underscore, but we can't drop it because without it, "blah" looks - like a relative URI. Unless we restore the colon:: - - __ blah: internal hyperlink target - - - Obtrusive markup? - -3. Alan Jaffray's proposed syntax #2:: - - .. _blah internal hyperlink target - .. blah: http://somewhere external hyperlink target - .. blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - !! blah: http://somewhere directive - ## blah: http://somewhere comment - - Leading underscores have been (almost) replaced by "..", while - comments and directives have gained their own syntax. - - Advantages: - - + Anonymous hyperlinks are simpler. - + Unique syntax for comments. Connotation of "comment" from - some programming languages (including our favorite). - + Unique syntax for directives. Connotation of "action!". - - Disadvantages: - - - Inconsistent internal hyperlink targets. Again, unlike all other - named hyperlink targets, there's no colon. There's a leading - underscore, matching the trailing underscores of references, - which no other hyperlink targets have. We can't drop that one - leading underscore though: without it, "blah" looks like a - relative URI. Again, unless we restore the colon:: - - .. blah: internal hyperlink target - - - All (except for internal) hyperlink targets lack their leading - underscores, losing the "hyperlink" connotation. - - - Obtrusive syntax for comments. Alternatives:: - - ;; blah: http://somewhere - (also comment syntax in Lisp & others) - ,, blah: http://somewhere - ("comma comma": sounds like "comment"!) - - - Iffy syntax for directives. Alternatives? - -4. Tony Ibbs' proposed syntax:: - - .. _blah: internal hyperlink target - .. _blah: http://somewhere external hyperlink target - .. _blah: blahblah_ indirect hyperlink target - .. anonymous internal target - .. http://somewhere anonymous external target - .. blahblah_ anonymous indirect target - .. [blah] http://somewhere footnote - .. blah:: http://somewhere directive - .. blah: http://somewhere comment - - This is the same as the current syntax, except for anonymous - targets which drop their "__: ". - - Advantage: - - + Anonymous targets are simpler. - - Disadvantages: - - - Anonymous targets lack their leading underscores, losing the - "hyperlink" connotation. - - Anonymous targets are almost indistinguishable from comments. - (Better to know "up front".) - -5. David Goodger's proposed syntax: Perhaps going back to one of - Alan's earlier suggestions might be the best solution. How about - simply adding "__ " as a synonym for ".. __: " in the original - syntax? These would become equivalent:: - - .. __: anonymous internal target - .. __: http://somewhere anonymous external target - .. __: blahblah_ anonymous indirect target - - __ anonymous internal target - __ http://somewhere anonymous external target - __ blahblah_ anonymous indirect target - -Alternative 5 has been adopted. - - -Backquotes in Phrase-Links -========================== - -[From a 2001-06-05 Doc-SIG post in reply to questions from Doug -Hellmann.] - -The first draft of the spec, posted to the Doc-SIG in November 2000, -used square brackets for phrase-links. I changed my mind because: - -1. In the first draft, I had already decided on single-backquotes for - inline literal text. - -2. However, I wanted to minimize the necessity for backslash escapes, - for example when quoting Python repr-equivalent syntax that uses - backquotes. - -3. The processing of identifiers (function/method/attribute/module - etc. names) into hyperlinks is a useful feature. PyDoc recognizes - identifiers heuristically, but it doesn't take much imagination to - come up with counter-examples where PyDoc's heuristics would result - in embarassing failure. I wanted to do it deterministically, and - that called for syntax. I called this construct "interpreted - text". - -4. Leveraging off the ``*emphasis*/**strong**`` syntax, lead to the - idea of using double-backquotes as syntax. - -5. I worked out some rules for inline markup recognition. - -6. In combination with #5, double backquotes lent themselves to inline - literals, neatly satisfying #2, minimizing backslash escapes. In - fact, the spec says that no interpretation of any kind is done - within double-backquote inline literal text; backslashes do *no* - escaping within literal text. - -7. Single backquotes are then freed up for interpreted text. - -8. I already had square brackets required for footnote references. - -9. Since interpreted text will typically turn into hyperlinks, it was - a natural fit to use backquotes as the phrase-quoting syntax for - trailing-underscore hyperlinks. - -The original inspiration for the trailing underscore hyperlink syntax -was Setext. But for phrases Setext used a very cumbersome -``underscores_between_words_like_this_`` syntax. - -The underscores can be viewed as if they were right-pointing arrows: -``-->``. So ``hyperlink_`` points away from the reference, and -``.. _hyperlink:`` points toward the target. - - -Substitution Mechanism -====================== - -Substitutions arose out of a Doc-SIG thread begun on 2001-10-28 by -Alan Jaffray, "reStructuredText inline markup". It reminded me of a -missing piece of the reStructuredText puzzle, first referred to in my -contribution to "Documentation markup & processing / PEPs" (Doc-SIG -2001-06-21). - -Substitutions allow the power and flexibility of directives to be -shared by inline text. They are a way to allow arbitrarily complex -inline objects, while keeping the details out of the flow of text. -They are the equivalent of SGML/XML's named entities. For example, an -inline image (using reference syntax alternative 4d (vertical bars) -and definition alternative 3, the alternatives chosen for inclusion in -the spec):: - - The |biohazard| symbol must be used on containers used to dispose - of medical waste. - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -The ``|biohazard|`` substitution reference will be replaced in-line by -whatever the ``.. |biohazard|`` substitution definition generates (in -this case, an image). A substitution definition contains the -substitution text bracketed with vertical bars, followed by a an -embedded inline-compatible directive, such as "image". A transform is -required to complete the substitution. - -Syntax alternatives for the reference: - -1. Use the existing interpreted text syntax, with a predefined role - such as "sub":: - - The `biohazard`:sub: symbol... - - Advantages: existing syntax, explicit. Disadvantages: verbose, - obtrusive. - -2. Use a variant of the interpreted text syntax, with a new suffix - akin to the underscore in phrase-link references:: - - (a) `name`@ - (b) `name`# - (c) `name`& - (d) `name`/ - (e) `name`< - (f) `name`:: - (g) `name`: - - - Due to incompatibility with other constructs and ordinary text - usage, (f) and (g) are not possible. - -3. Use interpreted text syntax with a fixed internal format:: - - (a) `:name:` - (b) `name:` - (c) `name::` - (d) `::name::` - (e) `%name%` - (f) `#name#` - (g) `/name/` - (h) `&name&` - (i) `|name|` - (j) `[name]` - (k) `<name>` - (l) `&name;` - (m) `'name'` - - To avoid ML confusion (k) and (l) are definitely out. Square - brackets (j) won't work in the target (the substitution definition - would be indistinguishable from a footnote). - - The ```/name/``` syntax (g) is reminiscent of "s/find/sub" - substitution syntax in ed-like languages. However, it may have a - misleading association with regexps, and looks like an absolute - POSIX path. (i) is visually equivalent and lacking the - connotations. - - A disadvantage of all of these is that they limit interpreted text, - albeit only slightly. - -4. Use specialized syntax, something new:: - - (a) #name# - (b) @name@ - (c) /name/ - (d) |name| - (e) <<name>> - (f) //name// - (g) ||name|| - (h) ^name^ - (i) [[name]] - (j) ~name~ - (k) !name! - (l) =name= - (m) ?name? - (n) >name< - - "#" (a) and "@" (b) are obtrusive. "/" (c) without backquotes - looks just like a POSIX path; it is likely for such usage to appear - in text. - - "|" (d) and "^" (h) are feasible. - -5. Redefine the trailing underscore syntax. See definition syntax - alternative 4, below. - -Syntax alternatives for the definition: - -1. Use the existing directive syntax, with a predefined directive such - as "sub". It contains a further embedded directive resolving to an - inline-compatible object:: - - .. sub:: biohazard - .. image:: biohazard.png - [height=20 width=20] - - .. sub:: parrot - That bird wouldn't *voom* if you put 10,000,000 volts - through it! - - The advantages and disadvantages are the same as in inline - alternative 1. - -2. Use syntax as in #1, but with an embedded directivecompressed:: - - .. sub:: biohazard image:: biohazard.png - [height=20 width=20] - - This is a bit better than alternative 1, but still too much. - -3. Use a variant of directive syntax, incorporating the substitution - text, obviating the need for a special "sub" directive name. If we - assume reference alternative 4d (vertical bars), the matching - definition would look like this:: - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -4. (Suggested by Alan Jaffray on Doc-SIG from 2001-11-06.) - - Instead of adding new syntax, redefine the trailing underscore - syntax to mean "substitution reference" instead of "hyperlink - reference". Alan's example:: - - I had lunch with Jonathan_ today. We talked about Zope_. - - .. _Jonathan: lj [user=jhl] - .. _Zope: http://www.zope.org/ - - A problem with the proposed syntax is that URIs which look like - simple reference names (alphanum plus ".", "-", "_") would be - indistinguishable from substitution directive names. A more - consistent syntax would be:: - - I had lunch with Jonathan_ today. We talked about Zope_. - - .. _Jonathan: lj:: user=jhl - .. _Zope: http://www.zope.org/ - - (``::`` after ``.. _Jonathan: lj``.) - - The "Zope" target is a simple external hyperlink, but the - "Jonathan" target contains a directive. Alan proposed is that the - reference text be replaced by whatever the referenced directive - (the "directive target") produces. A directive reference becomes a - hyperlink reference if the contents of the directive target resolve - to a hyperlink. If the directive target resolves to an icon, the - reference is replaced by an inline icon. If the directive target - resolves to a hyperlink, the directive reference becomes a - hyperlink reference. - - This seems too indirect and complicated for easy comprehension. - - The reference in the text will sometimes become a link, sometimes - not. Sometimes the reference text will remain, sometimes not. We - don't know *at the reference*:: - - This is a `hyperlink reference`_; its text will remain. - This is an `inline icon`_; its text will disappear. - - That's a problem. - -The syntax that has been incorporated into the spec and parser is -reference alternative 4d with definition alternative 3:: - - The |biohazard| symbol... - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - -We can also combine substitution references with hyperlink references, -by appending a "_" (named hyperlink reference) or "__" (anonymous -hyperlink reference) suffix to the substitution reference. This -allows us to click on an image-link:: - - The |biohazard|_ symbol... - - .. |biohazard| image:: biohazard.png - [height=20 width=20] - .. _biohazard: http://www.cdc.gov/ - -There have been several suggestions for the naming of these -constructs, originally called "substitution references" and -"substitutions". - -1. Candidate names for the reference construct: - - (a) substitution reference - (b) tagging reference - (c) inline directive reference - (d) directive reference - (e) indirect inline directive reference - (f) inline directive placeholder - (g) inline directive insertion reference - (h) directive insertion reference - (i) insertion reference - (j) directive macro reference - (k) macro reference - (l) substitution directive reference - -2. Candidate names for the definition construct: - - (a) substitution - (b) substitution directive - (c) tag - (d) tagged directive - (e) directive target - (f) inline directive - (g) inline directive definition - (h) referenced directive - (i) indirect directive - (j) indirect directive definition - (k) directive definition - (l) indirect inline directive - (m) named directive definition - (n) inline directive insertion definition - (o) directive insertion definition - (p) insertion definition - (q) insertion directive - (r) substitution definition - (s) directive macro definition - (t) macro definition - (u) substitution directive definition - (v) substitution definition - -"Inline directive reference" (1c) seems to be an appropriate term at -first, but the term "inline" is redundant in the case of the -reference. Its counterpart "inline directive definition" (2g) is -awkward, because the directive definition itself is not inline. - -"Directive reference" (1d) and "directive definition" (2k) are too -vague. "Directive definition" could be used to refer to any -directive, not just those used for inline substitutions. - -One meaning of the term "macro" (1k, 2s, 2t) is too -programming-language-specific. Also, macros are typically simple text -substitution mechanisms: the text is substituted first and evaluated -later. reStructuredText substitution definitions are evaluated in -place at parse time and substituted afterwards. - -"Insertion" (1h, 1i, 2n-2q) is almost right, but it implies that -something new is getting added rather than one construct being -replaced by another. - -Which brings us back to "substitution". The overall best names are -"substitution reference" (1a) and "substitution definition" (2v). A -long way to go to add one word! - - -Inline External Targets -======================= - -Currently reStructuredText has two hyperlink syntax variations: - -* Named hyperlinks:: - - This is a named reference_ of one word ("reference"). Here is - a `phrase reference`_. Phrase references may even cross `line - boundaries`_. - - .. _reference: http://www.example.org/reference/ - .. _phrase reference: http://www.example.org/phrase_reference/ - .. _line boundaries: http://www.example.org/line_boundaries/ - - + Advantages: - - - The plaintext is readable. - - Each target may be reused multiple times (e.g., just write - ``"reference_"`` again). - - No syncronized ordering of references and targets is necessary. - - + Disadvantages: - - - The reference text must be repeated as target names; could lead - to mistakes. - - The target URLs may be located far from the references, and hard - to find in the plaintext. - -* Anonymous hyperlinks (in current reStructuredText):: - - This is an anonymous reference__. Here is an anonymous - `phrase reference`__. Phrase references may even cross `line - boundaries`__. - - __ http://www.example.org/reference/ - __ http://www.example.org/phrase_reference/ - __ http://www.example.org/line_boundaries/ - - + Advantages: - - - The plaintext is readable. - - The reference text does not have to be repeated. - - + Disadvantages: - - - References and targets must be kept in sync. - - Targets cannot be reused. - - The target URLs may be located far from the references. - -For comparison and historical background, StructuredText also has two -syntaxes for hyperlinks: - -* First, ``"reference text":URL``:: - - This is a "reference":http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase - reference":http://www.example.org/phrase_reference/. - -* Second, ``"reference text", http://example.com/absolute_URL``:: - - This is a "reference", http://www.example.org/reference/ - of one word ("reference"). Here is a "phrase reference", - http://www.example.org/phrase_reference/. - -Both syntaxes share advantages and disadvantages: - -+ Advantages: - - - The target is specified immediately adjacent to the reference. - -+ Disadvantages: - - - Poor plaintext readability. - - Targets cannot be reused. - - Both syntaxes use double quotes, common in ordinary text. - - In the first syntax, the URL and the last word are stuck - together, exacerbating the line wrap problem. - - The second syntax is too magical; text could easily be written - that way by accident (although only absolute URLs are recognized - here, perhaps because of the potential for ambiguity). - -A new type of "inline external hyperlink" has been proposed. - -1. On 2002-06-28, Simon Budig proposed__ a new syntax for - reStructuredText hyperlinks:: - - This is a reference_(http://www.example.org/reference/) of one - word ("reference"). Here is a `phrase - reference`_(http://www.example.org/phrase_reference/). Are - these examples, (single-underscore), named? If so, `anonymous - references`__(http://www.example.org/anonymous/) using two - underscores would probably be preferable. - - __ http://mail.python.org/pipermail/doc-sig/2002-June/002648.html - - The syntax, advantages, and disadvantages are similar to those of - StructuredText. - - + Advantages: - - - The target is specified immediately adjacent to the reference. - - + Disadvantages: - - - Poor plaintext readability. - - Targets cannot be reused (unless named, but the semantics are - unclear). - - + Problems: - - - The ``"`ref`_(URL)"`` syntax forces the last word of the - reference text to be joined to the URL, making a potentially - very long word that can't be wrapped (URLs can be very long). - The reference and the URL should be separate. This is a - symptom of the following point: - - - The syntax produces a single compound construct made up of two - equally important parts, *with syntax in the middle*, *between* - the reference and the target. This is unprecedented in - reStructuredText. - - - The "inline hyperlink" text is *not* a named reference (there's - no lookup by name), so it shouldn't look like one. - - - According to the IETF standards RFC 2396 and RFC 2732, - parentheses are legal URI characters and curly braces are legal - email characters, making their use prohibitively difficult. - - - The named/anonymous semantics are unclear. - -2. After an analysis__ of the syntax of (1) above, we came up with the - following compromise syntax:: - - This is an anonymous reference__ - __<http://www.example.org/reference/> of one word - ("reference"). Here is a `phrase reference`__ - __<http://www.example.org/phrase_reference/>. `Named - references`_ _<http://www.example.org/anonymous/> use single - underscores. - - __ http://mail.python.org/pipermail/doc-sig/2002-July/002670.html - - The syntax builds on that of the existing "inline internal - targets": ``an _`inline internal target`.`` - - + Advantages: - - - The target is specified immediately adjacent to the reference, - improving maintainability: - - - References and targets are easily kept in sync. - - The reference text does not have to be repeated. - - - The construct is executed in two parts: references identical to - existing references, and targets that are new but not too big a - stretch from current syntax. - - - There's overwhelming precedent for quoting URLs with angle - brackets [#]_. - - + Disadvantages: - - - Poor plaintext readability. - - Lots of "line noise". - - Targets cannot be reused (unless named; see below). - - To alleviate the readability issue slightly, we could allow the - target to appear later, such as after the end of the sentence:: - - This is a named reference__ of one word ("reference"). - __<http://www.example.org/reference/> Here is a `phrase - reference`__. __<http://www.example.org/phrase_reference/> - - Problem: this could only work for one reference at a time - (reference/target pairs must be proximate [refA trgA refB trgB], - not interleaved [refA refB trgA trgB] or nested [refA refB trgB - trgA]). This variation is too problematic; references and inline - external targets will have to be kept imediately adjacent (see (3) - below). - - The ``"reference__ __<target>"`` syntax is actually for "anonymous - inline external targets", emphasized by the double underscores. It - follows that single trailing and leading underscores would lead to - *implicitly named* inline external targets. This would allow the - reuse of targets by name. So after ``"reference_ _<target>"``, - another ``"reference_"`` would point to the same target. - - .. [#] - From RFC 2396 (URI syntax): - - The angle-bracket "<" and ">" and double-quote (") - characters are excluded [from URIs] because they are often - used as the delimiters around URI in text documents and - protocol fields. - - Using <> angle brackets around each URI is especially - recommended as a delimiting style for URI that contain - whitespace. - - From RFC 822 (email headers): - - Angle brackets ("<" and ">") are generally used to indicate - the presence of a one machine-usable reference (e.g., - delimiting mailboxes), possibly including source-routing to - the machine. - -3. If it is best for references and inline external targets to be - immediately adjacent, then they might as well be integrated. - Here's an alternative syntax embedding the target URL in the - reference:: - - This is an anonymous `reference <http://www.example.org - /reference/>`__ of one word ("reference"). Here is a `phrase - reference <http://www.example.org/phrase_reference/>`__. - - Advantages and disadvantages are similar to those in (2). - Readability is still an issue, but the syntax is a bit less - heavyweight (reduced line noise). Backquotes are required, even - for one-word references; the target URL is included within the - reference text, forcing a phrase context. - - We'll call this variant "embedded URIs". - - Problem: how to refer to a title like "HTML Anchors: <a>" (which - ends with an HTML/SGML/XML tag)? We could either require more - syntax on the target (like ``"`reference text - __<http://example.com/>`__"``), or require the odd conflicting - title to be escaped (like ``"`HTML Anchors: \<a>`__"``). The - latter seems preferable, and not too onerous. - - Similarly to (2) above, a single trailing underscore would convert - the reference & inline external target from anonymous to implicitly - named, allowing reuse of targets by name. - - I think this is the least objectionable of the syntax alternatives. - -Other syntax variations have been proposed (by Brett Cannon and Benja -Fallenstein):: - - `phrase reference`->http://www.example.com - - `phrase reference`@http://www.example.com - - `phrase reference`__ ->http://www.example.com - - `phrase reference` [-> http://www.example.com] - - `phrase reference`__ [-> http://www.example.com] - - `phrase reference` <http://www.example.com>_ - -None of these variations are clearly superior to #3 above. Some have -problems that exclude their use. - -With any kind of inline external target syntax it comes down to the -conflict between maintainability and plaintext readability. I don't -see a major problem with reStructuredText's maintainability, and I -don't want to sacrifice plaintext readability to "improve" it. - -The proponents of inline external targets want them for easily -maintainable web pages. The arguments go something like this: - -- Named hyperlinks are difficult to maintain because the reference - text is duplicated as the target name. - - To which I said, "So use anonymous hyperlinks." - -- Anonymous hyperlinks are difficult to maintain becuase the - references and targets have to be kept in sync. - - "So keep the targets close to the references, grouped after each - paragraph. Maintenance is trivial." - -- But targets grouped after paragraphs break the flow of text. - - "Surely less than URLs embedded in the text! And if the intent is - to produce web pages, not readable plaintext, then who cares about - the flow of text?" - -Many participants have voiced their objections to the proposed syntax: - - Garth Kidd: "I strongly prefer the current way of doing it. - Inline is spectactularly messy, IMHO." - - Tony Ibbs: "I vehemently agree... that the inline alternatives - being suggested look messy - there are/were good reasons they've - been taken out... I don't believe I would gain from the new - syntaxes." - - Paul Moore: "I agree as well. The proposed syntax is far too - punctuation-heavy, and any of the alternatives discussed are - ambiguous or too subtle." - -Others have voiced their support: - - fantasai: "I agree with Simon. In many cases, though certainly - not in all, I find parenthesizing the url in plain text flows - better than relegating it to a footnote." - - Ken Manheimer: "I'd like to weigh in requesting some kind of easy, - direct inline reference link." - -(Interesting that those *against* the proposal have been using -reStructuredText for a while, and those *for* the proposal are either -new to the list ["fantasai", background unknown] or longtime -StructuredText users [Ken Manheimer].) - -I was initially ambivalent/against the proposed "inline external -targets". I value reStructuredText's readability very highly, and -although the proposed syntax offers convenience, I don't know if the -convenience is worth the cost in ugliness. Does the proposed syntax -compromise readability too much, or should the choice be left up to -the author? Perhaps if the syntax is *allowed* but its use strongly -*discouraged*, for aesthetic/readability reasons? - -After a great deal of thought and much input from users, I've decided -that there are reasonable use cases for this construct. The -documentation should strongly caution against its use in most -situations, recommending independent block-level targets instead. -Syntax #3 above ("embedded URIs") will be used. - - -Doctree Representation of Transitions -===================================== - -(Although not reStructuredText-specific, this section fits best in -this document.) - -Having added the "horizontal rule" construct to the `reStructuredText -Markup Specification`_, a decision had to be made as to how to reflect -the construct in the implementation of the document tree. Given this -source:: - - Document - ======== - - Paragraph 1 - - -------- - - Paragraph 2 - -The horizontal rule indicates a "transition" (in prose terms) or the -start of a new "division". Before implementation, the parsed document -tree would be:: - - <document> - <section names="document"> - <title> - Document - <paragraph> - Paragraph 1 - -------- <--- error here - <paragraph> - Paragraph 2 - -There are several possibilities for the implementation: - -1. Implement horizontal rules as "divisions" or segments. A - "division" is a title-less, non-hierarchical section. The first - try at an implementation looked like this:: - - <document> - <section names="document"> - <title> - Document - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - But the two paragraphs are really at the same level; they shouldn't - appear to be at different levels. There's really an invisible - "first division". The horizontal rule splits the document body - into two segments, which should be treated uniformly. - -2. Treating "divisions" uniformly brings us to the second - possibility:: - - <document> - <section names="document"> - <title> - Document - <division> - <paragraph> - Paragraph 1 - <division> - <paragraph> - Paragraph 2 - - With this change, documents and sections will directly contain - divisions and sections, but not body elements. Only divisions will - directly contain body elements. Even without a horizontal rule - anywhere, the body elements of a document or section would be - contained within a division element. This makes the document tree - deeper. This is similar to the way HTML_ treats document contents: - grouped within a ``<body>`` element. - -3. Implement them as "transitions", empty elements:: - - <document> - <section names="document"> - <title> - Document - <paragraph> - Paragraph 1 - <transition> - <paragraph> - Paragraph 2 - - A transition would be a "point element", not containing anything, - only identifying a point within the document structure. This keeps - the document tree flatter, but the idea of a "point element" like - "transition" smells bad. A transition isn't a thing itself, it's - the space between two divisions. However, transitions are a - practical solution. - -Solution 3 was chosen for incorporation into the document tree model. - -.. _HTML: http://www.w3.org/MarkUp/ - - -Syntax for Line Blocks -====================== - -* An early idea: How about a literal-block-like prefix, perhaps - "``;;``"? (It is, after all, a *semi-literal* literal block, no?) - Example:: - - Take it away, Eric the Orchestra Leader! ;; - - A one, two, a one two three four - - Half a bee, philosophically, - must, *ipso facto*, half not be. - But half the bee has got to be, - *vis a vis* its entity. D'you see? - - But can a bee be said to be - or not to be an entire bee, - when half the bee is not a bee, - due to some ancient injury? - - Singing... - - Kinda lame. - -* Another idea: in an ordinary paragraph, if the first line ends with - a backslash (escaping the newline), interpret the entire paragraph - as a verse block? For example:: - - Add just one backslash\ - And this paragraph becomes - An awful haiku - - (Awful, and arguably invalid, since in Japanese the word "haiku" - contains three syllables not two.) - - This idea was superceded by the rules for escaped whitespace, useful - for `character-level inline markup`_. - -* In a `2004-02-22 docutils-develop message`__, Jarno Elonen proposed - a "plain list" syntax (and also provided a patch):: - - | John Doe - | President, SuperDuper Corp. - | jdoe@example.org - - __ http://thread.gmane.org/gmane.text.docutils.devel/1187 - - This syntax is very natural. However, these "plain lists" seem very - similar to line blocks, and I see so little intrinsic "list-ness" - that I'm loathe to add a new object. I used the term "blurbs" to - remove the "list" connotation from the originally proposed name. - Perhaps line blocks could be refined to add the two properties they - currently lack: - - A) long lines wrap nicely - B) HTML output doesn't look like program code in non-CSS web - browsers - - (A) is an issue of all 3 aspects of Docutils: syntax (construct - behaviour), internal representation, and output. (B) is partly an - issue of internal representation but mostly of output. - -ReStructuredText will redefine line blocks with the "|"-quoting -syntax. The following is my current thinking. - - -Syntax ------- - -Perhaps line block syntax like this would do:: - - | M6: James Bond - | MIB: Mr. J. - | IMF: not decided yet, but probably one of the following: - | Ethan Hunt - | Jim Phelps - | Claire Phelps - | CIA: Felix Leiter - -Note that the "nested" list does not have nested syntax (the "|" are -not further indented); the leading whitespace would still be -significant somehow (more below). As for long lines in the input, -this could suffice:: - - | John Doe - | Founder, President, Chief Executive Officer, Cook, Bottle - Washer, and All-Round Great Guy - | SuperDuper Corp. - | jdoe@example.org - -The lack of "|" on the third line indicates that it's a continuation -of the second line, wrapped. - -I don't see much point in allowing arbitrary nested content. Multiple -paragraphs or bullet lists inside a "blurb" doesn't make sense to me. -Simple nested line blocks should suffice. - - -Internal Representation ------------------------ - -Line blocks are currently represented as text blobs as follows:: - - <!ELEMENT line_block %text.model;> - <!ATTLIST line_block - %basic.atts; - %fixedspace.att;> - -Instead, we could represent each line by a separate element:: - - <!ELEMENT line_block (line+)> - <!ATTLIST line_block %basic.atts;> - - <!ELEMENT line %text.model;> - <!ATTLIST line %basic.atts;> - -We'd keep the significance of the leading whitespace of each line -either by converting it to non-breaking spaces at output, or with a -per-line margin. Non-breaking spaces are simpler (for HTML, anyway) -but kludgey, and wouldn't support indented long lines that wrap. But -should inter-word whitespace (i.e., not leading whitespace) be -preserved? Currently it is preserved in line blocks. - -Representing a more complex line block may be tricky:: - - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - -Perhaps the representation could allow for nested line blocks:: - - <!ELEMENT line_block (line | line_block)+> - -With this model, leading whitespace would no longer be significant. -Instead, left margins are implied by the nesting. The example above -could be represented as follows:: - - <line_block> - <line> - But can a bee be said to be - <line_block> - <line> - or not to be an entire bee, - <line_block> - <line> - when half the bee is not a bee, - <line_block> - <line> - due to some ancient injury? - -I wasn't sure what to do about even more complex line blocks:: - - | Indented - | Not indented - | Indented a bit - | A bit more - | Only one space - -How should that be parsed and nested? Should the first line have -the same nesting level (== indentation in the output) as the fourth -line, or the same as the last line? Mark Nodine suggested that such -line blocks be parsed similarly to complexly-nested block quotes, -which seems reasonable. In the example above, this would result in -the nesting of first line matching the last line's nesting. In -other words, the nesting would be relative to neighboring lines -only. - - -Output ------- - -In HTML, line blocks are currently output as "<pre>" blocks, which -gives us significant whitespace and line breaks, but doesn't allow -long lines to wrap and causes monospaced output without stylesheets. -Instead, we could output "<div>" elements parallelling the -representation above, where each nested <div class="line_block"> would -have an increased left margin (specified in the stylesheet). - -Jarno suggested the following HTML output:: - - <div class="line_block"> - <span class="line">First, top level line</span><br class="hidden"/> - <div class="line_block"><span class="hidden"> </span> - <span class="line">Second, once nested</span><br class="hidden"/> - <span class="line">Third, once nested</span><br class="hidden"/> - ... - </div> - ... - </div> - -The ``<br class="hidden" />`` and ``<span -class="hidden"> </span>`` are meant to support non-CSS and -non-graphical browsers. I understand the case for "br", but I'm not -so sure about hidden " ". I question how much effort should be -put toward supporting non-graphical and especially non-CSS browsers, -at least for html4css1.py output. - -Should the lines themselves be ``<span>`` or ``<div>``? I don't like -mixing inline and block-level elements. - - -Implementation Plan -------------------- - -We'll leave the old implementation in place (via the "line-block" -directive only) until all Writers have been updated to support the new -syntax & implementation. The "line-block" directive can then be -updated to use the new internal representation, and its documentation -will be updated to recommend the new syntax. - - -List-Driven Tables -================== - -The original idea came from Dylan Jay: - - ... to use a two level bulleted list with something to - indicate it should be rendered as a table ... - -It's an interesting idea. It could be implemented in as a directive -which transforms a uniform two-level list into a table. Using a -directive would allow the author to explicitly set the table's -orientation (by column or by row), the presence of row headers, etc. - -Alternatives: - -1. (Implemented in Docutils 0.3.8). - - Bullet-list-tables might look like this:: - - .. list-table:: - - * - Treat - - Quantity - - Description - * - Albatross! - - 299 - - On a stick! - * - Crunchy Frog! - - 1499 - - If we took the bones out, it wouldn't be crunchy, - now would it? - * - Gannet Ripple! - - 199 - - On a stick! - - This list must be written in two levels. This wouldn't work:: - - .. list-table:: - - * Treat - * Albatross! - * Gannet! - * Crunchy Frog! - - * Quantity - * 299 - * 199 - * 1499 - - * Description - * On a stick! - * On a stick! - * If we took the bones out... - - The above is a single list of 12 items. The blank lines are not - significant to the markup. We'd have to explicitly specify how - many columns or rows to use, which isn't a good idea. - -2. Beni Cherniavsky suggested a field list alternative. It could look - like this:: - - .. field-list-table:: - :headrows: 1 - - - :treat: Treat - :quantity: Quantity - :descr: Description - - - :treat: Albatross! - :quantity: 299 - :descr: On a stick! - - - :treat: Crunchy Frog! - :quantity: 1499 - :descr: If we took the bones out, it wouldn't be - crunchy, now would it? - - Column order is determined from the order of fields in the first - row. Field order in all other rows is ignored. As a side-effect, - this allows trivial re-arrangement of columns. By using named - fields, it becomes possible to omit fields in some rows without - losing track of things, which is important for spans. - -3. An alternative to two-level bullet lists would be to use enumerated - lists for the table cells:: - - .. list-table:: - - * 1. Treat - 2. Quantity - 3. Description - * 1. Albatross! - 2. 299 - 3. On a stick! - * 1. Crunchy Frog! - 2. 1499 - 3. If we took the bones out, it wouldn't be crunchy, - now would it? - - That provides better correspondence between cells in the same - column than does bullet-list syntax, but not as good as field list - syntax. I think that were only field-list-tables available, a lot - of users would use the equivalent degenerate case:: - - .. field-list-table:: - - :1: Treat - :2: Quantity - :3: Description - ... - -4. Another natural variant is to allow a description list with field - lists as descriptions:: - - .. list-table:: - :headrows: 1 - - Treat - :quantity: Quantity - :descr: Description - Albatross! - :quantity: 299 - :descr: On a stick! - Crunchy Frog! - :quantity: 1499 - :descr: If we took the bones out, it wouldn't be - crunchy, now would it? - - This would make the whole first column a header column ("stub"). - It's limited to a single column and a single paragraph fitting on - one source line. Also it wouldn't allow for empty cells or row - spans in the first column. But these are limitations that we could - live with, like those of simple tables. - -The List-driven table feature could be done in many ways. Each user -will have their preferred usage. Perhaps a single "list-table" -directive could handle them all, depending on which options and -content are present. - -Issues: - -* How to indicate that there's 1 header row? Perhaps two lists? :: - - .. list-table:: - - + - Treat - - Quantity - - Description - - * - Albatross! - - 299 - - On a stick! - - This is probably too subtle though. Better would be a directive - option, like ``:headrows: 1``. An early suggestion for the header - row(s) was to use a directive option:: - - .. field-list-table:: - :header: - - :treat: Treat - :quantity: Quantity - :descr: Description - - :treat: Albatross! - :quantity: 299 - :descr: On a stick! - - But the table data is at two levels and looks inconsistent. - - In general, we cannot extract the header row from field lists' field - names because field names cannot contain everything one might put in - a table cell. A separate header row also allows shorter field names - and doesn't force one to rewrite the whole table when the header - text changes. But for simpler cases, we can offer a ":header: - fields" option, which does extract header cells from field names:: - - .. field-list-table:: - :header: fields - - - :Treat: Albatross! - :Quantity: 299 - :Description: On a stick! - -* How to indicate the column widths? A directive option? :: - - .. list-table:: - :widths: 15 10 35 - - Automatic defaults from the text used? - -* How to handle row and/or column spans? - - In a field list, column-spans can be indicated by specifying the - first and last fields, separated by space-dash-space or ellipsis:: - - - :foo - baz: quuux - - :foo ... baz: quuux - - Commas were proposed for column spans:: - - - :foo, bar: quux - - But non-adjacent columns become problematic. Should we report an - error, or duplicate the value into each span of adjacent columns (as - was suggested)? The latter suggestion is appealing but may be too - clever. Best perhaps to simply specify the two ends. - - It was suggested that comma syntax should be allowed, too, in order - to allow the user to avoid trouble when changing the column order. - But changing the column order of a table with spans is not trivial; - we shouldn't make it easier to mess up. - - One possible syntax for row-spans is to simply treat any row where a - field is missing as a row-span from the last row where it appeared. - Leaving a field empty would still be possible by writing a field - with empty content. But this is too implicit. - - Another way would be to require an explicit continuation marker - (``...``/``-"-``/``"``?) in all but the first row of a spanned - field. Empty comments could work (".."). If implemented, the same - marker could also be supported in simple tables, which lack - row-spanning abilities. - - Explicit markup like ":rowspan:" and ":colspan:" was also suggested. - - Sometimes in a table, the first header row contains spans. It may - be necessary to provide a way to specify the column field names - independently of data rows. A directive option would do it. - -* We could specify "column-wise" or "row-wise" ordering, with the same - markup structure. For example, with definition data:: - - .. list-table:: - :column-wise: - - Treat - - Albatross! - - Crunchy Frog! - Quantity - - 299 - - 1499 - Description - - On a stick! - - If we took the bones out, it wouldn't be - crunchy, now would it? - -* A syntax for _`stubs in grid tables` is easy to imagine:: - - +------------------------++------------+----------+ - | Header row, column 1 || Header 2 | Header 3 | - +========================++============+==========+ - | body row 1, column 1 || column 2 | column 3 | - +------------------------++------------+----------+ - - Or this idea from Nick Moffitt:: - - +-----+---+---+ - | XOR # T | F | - +=====+===+===+ - | T # F | T | - +-----+---+---+ - | F # T | F | - +-----+---+---+ - - -Auto-Enumerated Lists -===================== - -Implemented 2005-03-24: combination of variation 1 & 2. - -The advantage of auto-numbered enumerated lists would be similar to -that of auto-numbered footnotes: lists could be written and rearranged -without having to manually renumber them. The disadvantages are also -the same: input and output wouldn't match exactly; the markup may be -ugly or confusing (depending on which alternative is chosen). - -1. Use the "#" symbol. Example:: - - #. Item 1. - #. Item 2. - #. Item 3. - - Advantages: simple, explicit. Disadvantage: enumeration sequence - cannot be specified (limited to arabic numerals); ugly. - -2. As a variation on #1, first initialize the enumeration sequence? - For example:: - - a) Item a. - #) Item b. - #) Item c. - - Advantages: simple, explicit, any enumeration sequence possible. - Disadvantages: ugly; perhaps confusing with mixed concrete/abstract - enumerators. - -3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: - - 1. Item 1. - 1. Item 2. - 1. Item 3. - - Advantages: enumeration sequence is explicit (could be multiple - "a." or "(I)" tokens). Disadvantages: perhaps confusing; otherwise - erroneous input (e.g., a duplicate item "1.") would pass silently, - either causing a problem later in the list (if no blank lines - between items) or creating two lists (with blanks). - - Take this input for example:: - - 1. Item 1. - - 1. Unintentional duplicate of item 1. - - 2. Item 2. - - Currently the parser will produce two list, "1" and "1,2" (no - warnings, because of the presence of blank lines). Using Fred's - notation, the current behavior is "1,1,2 -> 1 1,2" (without blank - lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2"). What - should the behavior be with auto-numbering? - - Fred has produced a patch__, whose initial behavior is as follows:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2,3 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2,3 [WARNING] 3 - 1,1,2 -> 1,2 [WARNING] 2 - - (After the "[WARNING]", the "3" would begin a new list.) - - I have mixed feelings about adding this functionality to the spec & - parser. It would certainly be useful to some users (myself - included; I often have to renumber lists). Perhaps it's too - clever, asking the parser to guess too much. What if you *do* want - three one-item lists in a row, each beginning with "1."? You'd - have to use empty comments to force breaks. Also, I question - whether "1,2,2 -> 1,2,3" is optimal behavior. - - In response, Fred came up with "a stricter and more explicit rule - [which] would be to only auto-number silently if *all* the - enumerators of a list were identical". In that case:: - - 1,1,1 -> 1,2,3 - 1,2,2 -> 1,2 [WARNING] 2 - 3,3,3 -> 3,4,5 - 1,2,2,3 -> 1,2 [WARNING] 2,3 - 1,1,2 -> 1,2 [WARNING] 2 - - Should any start-value be allowed ("3,3,3"), or should - auto-numbered lists be limited to begin with ordinal-1 ("1", "A", - "a", "I", or "i")? - - __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802 - &group_id=38414&atid=422032 - -4. Alternative proposed by Tony Ibbs:: - - #1. First item. - #3. Aha - I edited this in later. - #2. Second item. - - The initial proposal required unique enumerators within a list, but - this limits the convenience of a feature of already limited - applicability and convenience. Not a useful requirement; dropped. - - Instead, simply prepend a "#" to a standard list enumerator to - indicate auto-enumeration. The numbers (or letters) of the - enumerators themselves are not significant, except: - - - as a sequence indicator (arabic, roman, alphabetic; upper/lower), - - - and perhaps as a start value (first list item). - - Advantages: explicit, any enumeration sequence possible. - Disadvantages: a bit ugly. - - ------------------ - Not Implemented ------------------ - -Reworking Footnotes -=================== - -As a further wrinkle (see `Reworking Explicit Markup (Round 1)`_ -above), in the wee hours of 2002-02-28 I posted several ideas for -changes to footnote syntax: - - - Change footnote syntax from ``.. [1]`` to ``_[1]``? ... - - Differentiate (with new DTD elements) author-date "citations" - (``[GVR2002]``) from numbered footnotes? ... - - Render footnote references as superscripts without "[]"? ... - -These ideas are all related, and suggest changes in the -reStructuredText syntax as well as the docutils tree model. - -The footnote has been used for both true footnotes (asides expanding -on points or defining terms) and for citations (references to external -works). Rather than dealing with one amalgam construct, we could -separate the current footnote concept into strict footnotes and -citations. Citations could be interpreted and treated differently -from footnotes. Footnotes would be limited to numerical labels: -manual ("1") and auto-numbered (anonymous "#", named "#label"). - -The footnote is the only explicit markup construct (starts with ".. ") -that directly translates to a visible body element. I've always been -a little bit uncomfortable with the ".. " marker for footnotes because -of this; ".. " has a connotation of "special", but footnotes aren't -especially "special". Printed texts often put footnotes at the bottom -of the page where the reference occurs (thus "foot note"). Some HTML -designs would leave footnotes to be rendered the same positions where -they're defined. Other online and printed designs will gather -footnotes into a section near the end of the document, converting them -to "endnotes" (perhaps using a directive in our case); but this -"special processing" is not an intrinsic property of the footnote -itself, but a decision made by the document author or processing -system. - -Citations are almost invariably collected in a section at the end of a -document or section. Citations "disappear" from where they are -defined and are magically reinserted at some well-defined point. -There's more of a connection to the "special" connotation of the ".. " -syntax. The point at which the list of citations is inserted could be -defined manually by a directive (e.g., ".. citations::"), and/or have -default behavior (e.g., a section automatically inserted at the end of -the document) that might be influenced by options to the Writer. - -Syntax proposals: - -+ Footnotes: - - - Current syntax:: - - .. [1] Footnote 1 - .. [#] Auto-numbered footnote. - .. [#label] Auto-labeled footnote. - - - The syntax proposed in the original 2002-02-28 Doc-SIG post: - remove the ".. ", prefix a "_":: - - _[1] Footnote 1 - _[#] Auto-numbered footnote. - _[#label] Auto-labeled footnote. - - The leading underscore syntax (earlier dropped because - ``.. _[1]:`` was too verbose) is a useful reminder that footnotes - are hyperlink targets. - - - Minimal syntax: remove the ".. [" and "]", prefix a "_", and - suffix a ".":: - - _1. Footnote 1. - _#. Auto-numbered footnote. - _#label. Auto-labeled footnote. - - ``_1.``, ``_#.``, and ``_#label.`` are markers, - like list markers. - - Footnotes could be rendered something like this in HTML - - | 1. This is a footnote. The brackets could be dropped - | from the label, and a vertical bar could set them - | off from the rest of the document in the HTML. - - Two-way hyperlinks on the footnote marker ("1." above) would also - help to differentiate footnotes from enumerated lists. - - If converted to endnotes (by a directive/transform), a horizontal - half-line might be used instead. Page-oriented output formats - would typically use the horizontal line for true footnotes. - -+ Footnote references: - - - Current syntax:: - - [1]_, [#]_, [#label]_ - - - Minimal syntax to match the minimal footnote syntax above:: - - 1_, #_, #label_ - - As a consequence, pure-numeric hyperlink references would not be - possible; they'd be interpreted as footnote references. - -+ Citation references: no change is proposed from the current footnote - reference syntax:: - - [GVR2001]_ - -+ Citations: - - - Current syntax (footnote syntax):: - - .. [GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - - - Possible new syntax:: - - _[GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - - _[DJG2002] - Docutils: Python Documentation Utilities project; Goodger - et al.; http://docutils.sourceforge.net/ - - Without the ".. " marker, subsequent lines would either have to - align as in one of the above, or we'd have to allow loose - alignment (I'd rather not):: - - _[GVR2001] Python Documentation; van Rossum, Drake, et al.; - http://www.python.org/doc/ - -I proposed adopting the "minimal" syntax for footnotes and footnote -references, and adding citations and citation references to -reStructuredText's repertoire. The current footnote syntax for -citations is better than the alternatives given. - -From a reply by Tony Ibbs on 2002-03-01: - - However, I think easier with examples, so let's create one:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - .. [1] That is, little bits of referenced text at the - bottom of the page. - .. [2] Because Terry himself does, of course [3]_. - .. [3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - .. [4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - and look at it with the second syntax proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes [1]_ in their own writings than other people - [2]_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style [4]_, particularly in emails (not a medium that - lends itself to footnotes). - - _[1] That is, little bits of referenced text at the - bottom of the page. - _[2] Because Terry himself does, of course [3]_. - _[3] Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _[4] Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - (I note here that if I have gotten the indentation of the - footnotes themselves correct, this is clearly not as nice. And if - the indentation should be to the left margin instead, I like that - even less). - - and the third (new) proposal:: - - Fans of Terry Pratchett are perhaps more likely to use - footnotes 1_ in their own writings than other people - 2_. Of course, in *general*, one only sees footnotes - in academic or technical writing - it's use in fiction - and letter writing is not normally considered good - style 4_, particularly in emails (not a medium that - lends itself to footnotes). - - _1. That is, little bits of referenced text at the - bottom of the page. - _2. Because Terry himself does, of course 3_. - _3. Although he has the distinction of being - *funny* when he does it, and his fans don't always - achieve that aim. - _4. Presumably because it detracts from linear - reading of the text - this is, of course, the point. - - I think I don't, in practice, mind the targets too much (the use - of a dot after the number helps a lot here), but I do have a - problem with the body text, in that I don't naturally separate out - the footnotes as different than the rest of the text - instead I - keep wondering why there are numbers interspered in the text. The - use of brackets around the numbers ([ and ]) made me somehow parse - the footnote references as "odd" - i.e., not part of the body text - - and thus both easier to skip, and also (paradoxically) easier to - pick out so that I could follow them. - - Thus, for the moment (and as always susceptable to argument), I'd - say -1 on the new form of footnote reference (i.e., I much prefer - the existing ``[1]_`` over the proposed ``1_``), and ambivalent - over the proposed target change. - - That leaves David's problem of wanting to distinguish footnotes - and citations - and the only thing I can propose there is that - footnotes are numeric or # and citations are not (which, as a - human being, I can probably cope with!). - -From a reply by Paul Moore on 2002-03-01: - - I think the current footnote syntax ``[1]_`` is *exactly* the - right balance of distinctness vs unobtrusiveness. I very - definitely don't think this should change. - - On the target change, it doesn't matter much to me. - -From a further reply by Tony Ibbs on 2002-03-01, referring to the -"[1]" form and actual usage in email: - - Clearly this is a form people are used to, and thus we should - consider it strongly (in the same way that the usage of ``*..*`` - to mean emphasis was taken partly from email practise). - - Equally clearly, there is something "magical" for people in the - use of a similar form (i.e., ``[1]``) for both footnote reference - and footnote target - it seems natural to keep them similar. - - ... - - I think that this established plaintext usage leads me to strongly - believe we should retain square brackets at both ends of a - footnote. The markup of the reference end (a single trailing - underscore) seems about as minimal as we can get away with. The - markup of the target end depends on how one envisages the thing - - if ".." means "I am a target" (as I tend to see it), then that's - good, but one can also argue that the "_[1]" syntax has a neat - symmetry with the footnote reference itself, if one wishes (in - which case ".." presumably means "hidden/special" as David seems - to think, which is why one needs a ".." *and* a leading underline - for hyperlink targets. - -Given the persuading arguments voiced, we'll leave footnote & footnote -reference syntax alone. Except that these discussions gave rise to -the "auto-symbol footnote" concept, which has been added. Citations -and citation references have also been added. - - -Syntax for Questions & Answers -============================== - -Implement as a generic two-column marked list? As a standalone -(non-directive) construct? (Is the markup ambiguous?) Add support to -parts.contents? - -New elements would be required. Perhaps:: - - <!ELEMENT question_list (question_list_item+)> - <!ATTLIST question_list - numbering (none | local | global) - #IMPLIED - start NUMBER #IMPLIED> - <!ELEMENT question_list_item (question, answer*)> - <!ELEMENT question %text.model;> - <!ELEMENT answer (%body.elements;)+> - -Originally I thought of implementing a Q&A list with special syntax:: - - Q: What am I? - - A: You are a question-and-answer - list. - - Q: What are you? - - A: I am the omniscient "we". - -Where each "Q" and "A" could also be numbered (e.g., "Q1"). However, -a simple enumerated or bulleted list will do just fine for syntax. A -directive could treat the list specially; e.g. the first paragraph -could be treated as a question, the remainder as the answer (multiple -answers could be represented by nested lists). Without special -syntax, this directive becomes low priority. - -As described in the FAQ__, no special syntax or directive is needed -for this application. - -__ http://docutils.sf.net/FAQ.html - #how-can-i-mark-up-a-faq-or-other-list-of-questions-answers - - --------- - Tabled --------- - -Reworking Explicit Markup (Round 2) -=================================== - -See `Reworking Explicit Markup (Round 1)`_ for an earlier discussion. - -In April 2004, a new thread becan on docutils-develop: `Inconsistency -in RST markup`__. Several arguments were made; the first argument -begat later arguments. Below, the arguments are paraphrased "in -quotes", with responses. - -__ http://thread.gmane.org/gmane.text.docutils.devel/1386 - -1. References and targets take this form:: - - targetname_ - - .. _targetname: stuff - - But footnotes, "which generate links just like targets do", are - written as:: - - [1]_ - - .. [1] stuff - - "Footnotes should be written as":: - - [1]_ - - .. _[1]: stuff - - But they're not the same type of animal. That's not a "footnote - target", it's a *footnote*. Being a target is not a footnote's - primary purpose (an arguable point). It just happens to grow a - target automatically, for convenience. Just as a section title:: - - Title - ===== - - isn't a "title target", it's a *title*, which happens to grow a - target automatically. The consistency is there, it's just deeper - than at first glance. - - Also, ".. [1]" was chosen for footnote syntax because it closely - resembles one form of actual footnote rendering. ".. _[1]:" is too - verbose; excessive punctuation is required to get the job done. - - For more of the reasoning behind the syntax, see `Problems With - StructuredText (Hyperlinks) <problems.html#hyperlinks>`__ and - `Reworking Footnotes`_. - -2. "I expect directives to also look like ``.. this:`` [one colon] - because that also closely parallels the link and footnote target - markup." - - There are good reasons for the two-colon syntax: - - Two colons are used after the directive type for these reasons: - - - Two colons are distinctive, and unlikely to be used in common - text. - - - Two colons avoids clashes with common comment text like:: - - .. Danger: modify at your own risk! - - - If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), a - level-3 (error) system message is generated, and the entire - directive block (including the directive itself) will be - included as a literal block. Thus "::" is a natural choice. - - -- `restructuredtext.html#directives - <../../ref/rst/restructuredtext.html#directives>`__ - - The last reason is not particularly compelling; it's more of a - convenient coincidence or mnemonic. - -3. "Comments always seemed too easy. I almost never write comments. - I'd have no problem writing '.. comment:' in front of my comments. - In fact, it would probably be more readable, as comments *should* - be set off strongly, because they are very different from normal - text." - - Many people do use comments though, and some applications of - reStructuredText require it. For example, all reStructuredText - PEPs (and this document!) have an Emacs stanza at the bottom, in a - comment. Having to write ".. comment::" would be very obtrusive. - - Comments *should* be dirt-easy to do. It should be easy to - "comment out" a block of text. Comments in programming languages - and other markup languages are invariably easy. - - Any author is welcome to preface their comments with "Comment:" or - "Do Not Print" or "Note to Editor" or anything they like. A - "comment" directive could easily be implemented. It might be - confused with admonition directives, like "note" and "caution" - though. In unrelated (and unpublished and unfinished) work, adding - a "comment" directive as a true document element was considered:: - - If structure is necessary, we could use a "comment" directive - (to avoid nonsensical DTD changes, the "comment" directive - could produce an untitled topic element). - -4. "One of the goals of reStructuredText is to be *readable* by people - who don't know it. This construction violates that: it is not at - all obvious to the uninitiated that text marked by '..' is a - comment. On the other hand, '.. comment:' would be totally - transparent." - - Totally transparent, perhaps, but also very obtrusive. Another of - `reStructuredText's goals`_ is to be unobtrusive, and - ".. comment::" would violate that. The goals of reStructuredText - are many, and they conflict. Determining the right set of goals - and finding solutions that best fit is done on a case-by-case - basis. - - Even readability is has two aspects. Being readable without any - prior knowledge is one. Being as easily read in raw form as in - processed form is the other. ".." may not contribute to the former - aspect, but ".. comment::" would certainly detract from the latter. - - .. _author's note: - .. _reStructuredText's goals: ../../ref/rst/introduction.html#goals - -5. "Recently I sent someone an rst document, and they got confused; I - had to explain to them that '..' marks comments, *unless* it's a - directive, etc..." - - The explanation of directives *is* roundabout, defining comments in - terms of not being other things. That's definitely a wart. - -6. "Under the current system, a mistyped directive (with ':' instead - of '::') will be silently ignored. This is an error that could - easily go unnoticed." - - A parser option/setting like "--comments-on-stderr" would help. - -7. "I'd prefer to see double-dot-space / command / double-colon as the - standard Docutils markup-marker. It's unusual enough to avoid - being accidently used. Everything that starts with a double-dot - should end with a double-colon." - - That would increase the punctuation verbosity of some constructs - considerably. - -8. Edward Loper proposed the following plan for backwards - compatibility: - - 1. ".. foo" will generate a deprecation warning to stderr, and - nothing in the output (no system messages). - 2. ".. foo: bar" will be treated as a directive foo. If there - is no foo directive, then do the normal error output. - 3. ".. foo:: bar" will generate a deprecation warning to - stderr, and be treated as a directive. Or leave it valid? - - So some existing documents might start printing deprecation - warnings, but the only existing documents that would *break* - would be ones that say something like:: - - .. warning: this should be a comment - - instead of:: - - .. warning:: this should be a comment - - Here, we're trading fairly common a silent error (directive - falsely treated as a comment) for a fairly uncommon explicitly - flagged error (comment falsely treated as directive). To make - things even easier, we could add a sentence to the - unknown-directive error. Something like "If you intended to - create a comment, please use '.. comment:' instead". - -On one hand, I understand and sympathize with the points raised. On -the other hand, I think the current syntax strikes the right balance -(but I acknowledge a possible lack of objectivity). On the gripping -hand, the comment and directive syntax has become well established, so -even if it's a wart, it may be a wart we have to live with. - -Making any of these changes would cause a lot of breakage or at least -deprecation warnings. I'm not sure the benefit is worth the cost. - -For now, we'll treat this as an unresolved legacy issue. - - -------- - To Do -------- - -Nested Inline Markup -==================== - -These are collected notes on a long-discussed issue. The original -mailing list messages should be referred to for details. - -* In a 2001-10-31 discussion I wrote: - - Try, for example, `Ed Loper's 2001-03-21 post`_, which details - some rules for nested inline markup. I think the complexity is - prohibitive for the marginal benefit. (And if you can understand - that tree without going mad, you're a better man than I. ;-) - - Inline markup is already fragile. Allowing nested inline markup - would only be asking for trouble IMHO. If it proves absolutely - necessary, it can be added later. The rules for what can appear - inside what must be well thought out first though. - - .. _Ed Loper's 2001-03-21 post: - http://mail.python.org/pipermail/doc-sig/2001-March/001487.html - - -- http://mail.python.org/pipermail/doc-sig/2001-October/002354.html - -* In a 2001-11-09 Doc-SIG post, I wrote: - - The problem is that in the - what-you-see-is-more-or-less-what-you-get markup language that - is reStructuredText, the symbols used for inline markup ("*", - "**", "`", "``", etc.) may preclude nesting. - - I've rethought this position. Nested markup is not precluded, just - tricky. People and software parse "double and 'single' quotes" all - the time. Continuing, - - I've thought over how we might implement nested inline - markup. The first algorithm ("first identify the outer inline - markup as we do now, then recursively scan for nested inline - markup") won't work; counterexamples were given in my `last post - <http://mail.python.org/pipermail/doc-sig/2001-November/002363.html>`__. - - The second algorithm makes my head hurt:: - - while 1: - scan for start-string - if found: - push on stack - scan for start or end string - if new start string found: - recurse - elif matching end string found: - pop stack - elif non-matching end string found: - if its a markup error: - generate warning - elif the initial start-string was misinterpreted: - # e.g. in this case: ***strong** in emphasis* - restart with the other interpretation - # but it might be several layers back ... - ... - - This is similar to how the parser does section title - recognition, but sections are much more regular and - deterministic. - - Bottom line is, I don't think the benefits are worth the effort, - even if it is possible. I'm not going to try to write the code, - at least not now. If somebody codes up a consistent, working, - general solution, I'll be happy to consider it. - - -- http://mail.python.org/pipermail/doc-sig/2001-November/002388.html - -* In a `2003-05-06 Docutils-Users post`__ Paul Tremblay proposed a new - syntax to allow for easier nesting. It eventually evolved into - this:: - - :role:[inline text] - - The duplication with the existing interpreted text syntax is - problematic though. - - __ http://article.gmane.org/gmane.text.docutils.user/317 - -* Could the parser be extended to parse nested interpreted text? :: - - :emphasis:`Some emphasized text with :strong:`some more - emphasized text` in it and **perhaps** :reference:`a link`` - -* In a `2003-06-18 Docutils-Develop post`__, Mark Nodine reported on - his implementation of a form of nested inline markup in his - Perl-based parser (unpublished). He brought up some interesting - ideas. The implementation was flawed, however, by the change in - semantics required for backslash escapes. - - __ http://article.gmane.org/gmane.text.docutils.devel/795 - -* Docutils-develop threads between David Abrahams, David Goodger, and - Mark Nodine (beginning 2004-01-16__ and 2004-01-19__) hashed out - many of the details of a potentially successful implementation, as - described below. David Abrahams checked in code to the "nesting" - branch of CVS, awaiting thorough review. - - __ http://thread.gmane.org/gmane.text.docutils.devel/1102 - __ http://thread.gmane.org/gmane.text.docutils.devel/1125 - -It may be possible to accomplish nested inline markup in general with -a more powerful inline markup parser. There may be some issues, but -I'm not averse to the idea of nested inline markup in general. I just -don't have the time or inclination to write a new parser now. Of -course, a good patch would be welcome! - -I envisage something like this. Explicit-role interpreted text must -be nestable. Prefix-based is probably preferred, since suffix-based -will look like inline literals:: - - ``text`:role1:`:role2: - -But it can be disambiguated, so it ought to be left up to the author:: - - `\ `text`:role1:`:role2: - -In addition, other forms of inline markup may be nested if -unambiguous:: - - *emphasized ``literal`` and |substitution ref| and link_* - -IOW, the parser ought to be as permissive as possible. - - -Index Entries & Indexes -======================= - -Were I writing a book with an index, I guess I'd need two -different kinds of index targets: inline/implicit and -out-of-line/explicit. For example:: - - In this `paragraph`:index:, several words are being - `marked`:index: inline as implicit `index`:index: - entries. - - .. index:: markup - .. index:: syntax - - The explicit index directives above would refer to - this paragraph. It might also make sense to allow multiple - entries in an ``index`` directive: - - .. index:: - markup - syntax - -The words "paragraph", "marked", and "index" would become index -entries pointing at the words in the first paragraph. The index -entry words appear verbatim in the text. (Don't worry about the -ugly ":index:" part; if indexing is the only/main application of -interpreted text in your documents, it can be implicit and -omitted.) The two directives provide manual indexing, where the -index entry words ("markup" and "syntax") do not appear in the -main text. We could combine the two directives into one:: - - .. index:: markup; syntax - -Semicolons instead of commas because commas could *be* part of the -index target, like:: - - .. index:: van Rossum, Guido - -Another reason for index directives is because other inline markup -wouldn't be possible within inline index targets. - -Sometimes index entries have multiple levels. Given:: - - .. index:: statement syntax: expression statements - -In a hypothetical index, combined with other entries, it might -look like this:: - - statement syntax - expression statements ..... 56 - assignment ................ 57 - simple statements ......... 58 - compound statements ....... 60 - -Inline multi-level index targets could be done too. Perhaps -something like:: - - When dealing with `expression statements <statement syntax:>`, - we must remember ... - -The opposite sense could also be possible:: - - When dealing with `index entries <:multi-level>`, there are - many permutations to consider. - -Also "see / see also" index entries. - -Given:: - - Here's a paragraph. - - .. index:: paragraph - -(The "index" directive above actually targets the *preceding* -object.) The directive should produce something like this XML:: - - <paragraph> - <index_entry text="paragraph"/> - Here's a paragraph. - </paragraph> - -This kind of content model would also allow true inline -index-entries:: - - Here's a `paragraph`:index:. - -If the "index" role were the default for the application, it could be -dropped:: - - Here's a `paragraph`. - -Both of these would result in this XML:: - - <paragraph> - Here's a <index_entry>paragraph</index_entry>. - </paragraph> - - -from 2002-06-24 docutils-develop posts --------------------------------------- - - If all of your index entries will appear verbatim in the text, - this should be sufficient. If not (e.g., if you want "Van Rossum, - Guido" in the index but "Guido van Rossum" in the text), we'll - have to figure out a supplemental mechanism, perhaps using - substitutions. - -I've thought a bit more on this, and I came up with two possibilities: - -1. Using interpreted text, embed the index entry text within the - interpreted text:: - - ... by `Guido van Rossum [Van Rossum, Guido]` ... - - The problem with this is obvious: the text becomes cluttered and - hard to read. The processed output would drop the text in - brackets, which goes against the spirit of interpreted text. - -2. Use substitutions:: - - ... by |Guido van Rossum| ... - - .. |Guido van Rossum| index:: Van Rossum, Guido - - A problem with this is that each substitution definition must have - a unique name. A subsequent ``.. |Guido van Rossum| index:: BDFL`` - would be illegal. Some kind of anonymous substitution definition - mechanism would be required, but I think that's going too far. - -Both of these alternatives are flawed. Any other ideas? - - -------------------- - ... Or Not To Do? -------------------- - -This is the realm of the possible but questionably probable. These -ideas are kept here as a record of what has been proposed, for -posterity and in case any of them prove to be useful. - - -Compound Enumerated Lists -========================= - -Allow for compound enumerators, such as "1.1." or "1.a." or "1(a)", to -allow for nested enumerated lists without indentation? - - -Indented Lists -============== - -Allow for variant styles by interpreting indented lists as if they -weren't indented? For example, currently the list below will be -parsed as a list within a block quote:: - - paragraph - - * list item 1 - * list item 2 - -But a lot of people seem to write that way, and HTML browsers make it -look as if that's the way it should be. The parser could check the -contents of block quotes, and if they contain only a single list, -remove the block quote wrapper. There would be two problems: - -1. What if we actually *do* want a list inside a block quote? - -2. What if such a list comes immediately after an indented construct, - such as a literal block? - -Both could be solved using empty comments (problem 2 already exists -for a block quote after a literal block). But that's a hack. - -Perhaps a runtime setting, allowing or disabling this convenience, -would be appropriate. But that raises issues too: - - User A, who writes lists indented (and their config file is set up - to allow it), sends a file to user B, who doesn't (and their - config file disables indented lists). The result of processing by - the two users will be different. - -It may seem minor, but it adds ambiguity to the parser, which is bad. - -See the `Doc-SIG discussion starting 2001-04-18`__ with Ed Loper's -"Structuring: a summary; and an attempt at EBNF", item 4 (and -follow-ups, here__ and here__). Also `docutils-users, 2003-02-17`__ -and `beginning 2003-08-04`__. - -__ http://mail.python.org/pipermail/doc-sig/2001-April/001776.html -__ http://mail.python.org/pipermail/doc-sig/2001-April/001789.html -__ http://mail.python.org/pipermail/doc-sig/2001-April/001793.html -__ http://sourceforge.net/mailarchive/message.php?msg_id=3838913 -__ http://sf.net/mailarchive/forum.php?thread_id=2957175&forum_id=11444 - - -Sloppy Indentation of List Items -================================ - -Perhaps the indentation shouldn't be so strict. Currently, this is -required:: - - 1. First line, - second line. - -Anything wrong with this? :: - - 1. First line, - second line. - -Problem? :: - - 1. First para. - - Block quote. (no good: requires some indent relative to first - para) - - Second Para. - - 2. Have to carefully define where the literal block ends:: - - Literal block - - Literal block? - -Hmm... Non-strict indentation isn't such a good idea. - - -Lazy Indentation of List Items -============================== - -Another approach: Going back to the first draft of reStructuredText -(2000-11-27 post to Doc-SIG):: - - - This is the fourth item of the main list (no blank line above). - The second line of this item is not indented relative to the - bullet, which precludes it from having a second paragraph. - -Change that to *require* a blank line above and below, to reduce -ambiguity. This "loosening" may be added later, once the parser's -been nailed down. However, a serious drawback of this approach is to -limit the content of each list item to a single paragraph. - - -David's Idea for Lazy Indentation ---------------------------------- - -Consider a paragraph in a word processor. It is a single logical line -of text which ends with a newline, soft-wrapped arbitrarily at the -right edge of the page or screen. We can think of a plaintext -paragraph in the same way, as a single logical line of text, ending -with two newlines (a blank line) instead of one, and which may contain -arbitrary line breaks (newlines) where it was accidentally -hard-wrapped by an application. We can compensate for the accidental -hard-wrapping by "unwrapping" every unindented second and subsequent -line. The indentation of the first line of a paragraph or list item -would determine the indentation for the entire element. Blank lines -would be required between list items when using lazy indentation. - -The following example shows the lazy indentation of multiple body -elements:: - - - This is the first paragraph - of the first list item. - - Here is the second paragraph - of the first list item. - - - This is the first paragraph - of the second list item. - - Here is the second paragraph - of the second list item. - -A more complex example shows the limitations of lazy indentation:: - - - This is the first paragraph - of the first list item. - - Next is a definition list item: - - Term - Definition. The indentation of the term is - required, as is the indentation of the definition's - first line. - - When the definition extends to more than - one line, lazy indentation may occur. (This is the second - paragraph of the definition.) - - - This is the first paragraph - of the second list item. - - - Here is the first paragraph of - the first item of a nested list. - - So this paragraph would be outside of the nested list, - but inside the second list item of the outer list. - - But this paragraph is not part of the list at all. - -And the ambiguity remains:: - - - Look at the hyphen at the beginning of the next line - - is it a second list item marker, or a dash in the text? - - Similarly, we may want to refer to numbers inside enumerated - lists: - - 1. How many socks in a pair? There are - 2. How many pants in a pair? Exactly - 1. Go figure. - -Literal blocks and block quotes would still require consistent -indentation for all their lines. For block quotes, we might be able -to get away with only requiring that the first line of each contained -element be indented. For example:: - - Here's a paragraph. - - This is a paragraph inside a block quote. - Second and subsequent lines need not be indented at all. - - - A bullet list inside - the block quote. - - Second paragraph of the - bullet list inside the block quote. - -Although feasible, this form of lazy indentation has problems. The -document structure and hierarchy is not obvious from the indentation, -making the source plaintext difficult to read. This will also make -keeping track of the indentation while writing difficult and -error-prone. However, these problems may be acceptable for Wikis and -email mode, where we may be able to rely on less complex structure -(few nested lists, for example). - - -Multiple Roles in Interpreted Text -================================== - -In reStructuredText, inline markup cannot be nested (yet; `see -above`__). This also applies to interpreted text. In order to -simultaneously combine multiple roles for a single piece of text, a -syntax extension would be necessary. Ideas: - -1. Initial idea:: - - `interpreted text`:role1,role2: - -2. Suggested by Jason Diamond:: - - `interpreted text`:role1:role2: - -If a document is so complex as to require nested inline markup, -perhaps another markup system should be considered. By design, -reStructuredText does not have the flexibility of XML. - -__ `Nested Inline Markup`_ - - -Parameterized Interpreted Text -============================== - -In some cases it may be expedient to pass parameters to interpreted -text, analogous to function calls. Ideas: - -1. Parameterize the interpreted text role itself (suggested by Jason - Diamond):: - - `interpreted text`:role1(foo=bar): - - Positional parameters could also be supported:: - - `CSS`:acronym(Cascading Style Sheets): is used for HTML, and - `CSS`:acronym(Content Scrambling System): is used for DVDs. - - Technical problem: current interpreted text syntax does not - recognize roles containing whitespace. Design problem: this smells - like programming language syntax, but reStructuredText is not a - programming language. - -2. Put the parameters inside the interpreted text:: - - `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and - `CSS (Content Scrambling System)`:acronym: is used for DVDs. - - Although this could be defined on an individual basis (per role), - we ought to have a standard. Hyperlinks with embedded URIs already - use angle brackets; perhaps they could be used here too:: - - `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and - `CSS <Content Scrambling System>`:acronym: is used for DVDs. - - Do angle brackets connote URLs too much for this to be acceptable? - How about the "tag" connotation -- does it save them or doom them? - -3. `Nested inline markup`_ could prove useful here:: - - `CSS :def:`Cascading Style Sheets``:acronym: is used for HTML, - and `CSS :def:`Content Scrambling System``:acronym: is used for - DVDs. - - Inline markup roles could even define the default roles of nested - inline markup, allowing this cleaner syntax:: - - `CSS `Cascading Style Sheets``:acronym: is used for HTML, and - `CSS `Content Scrambling System``:acronym: is used for DVDs. - -Does this push inline markup too far? Readability becomes a serious -issue. Substitutions may provide a better alternative (at the expense -of verbosity and duplication) by pulling the details out of the text -flow:: - - |CSS| is used for HTML, and |CSS-DVD| is used for DVDs. - - .. |CSS| acronym:: Cascading Style Sheets - .. |CSS-DVD| acronym:: Content Scrambling System - :text: CSS - ----------------------------------------------------------------------- - -This whole idea may be going beyond the scope of reStructuredText. -Documents requiring this functionality may be better off using XML or -another markup system. - -This argument comes up regularly when pushing the envelope of -reStructuredText syntax. I think it's a useful argument in that it -provides a check on creeping featurism. In many cases, the resulting -verbosity produces such unreadable plaintext that there's a natural -desire *not* to use it unless absolutely necessary. It's a matter of -finding the right balance. - - -Syntax for Interpreted Text Role Bindings -========================================= - -The following syntax (idea from Jeffrey C. Jacobs) could be used to -associate directives with roles:: - - .. :rewrite: class:: rewrite - - `She wore ribbons in her hair and it lay with streaks of - grey`:rewrite: - -The syntax is similar to that of substitution declarations, and the -directive/role association may resolve implementation issues. The -semantics, ramifications, and implementation details would need to be -worked out. - -The example above would implement the "rewrite" role as adding a -``class="rewrite"`` attribute to the interpreted text ("inline" -element). The stylesheet would then pick up on the "class" attribute -to do the actual formatting. - -The advantage of the new syntax would be flexibility. Uses other than -"class" may present themselves. The disadvantage is complexity: -having to implement new syntax for a relatively specialized operation, -and having new semantics in existing directives ("class::" would do -something different). - -The `"role" directive`__ has been implemented. - -__ ../../ref/rst/directives.html#role - - -Character Processing -==================== - -Several people have suggested adding some form of character processing -to reStructuredText: - -* Some sort of automated replacement of ASCII sequences: - - - ``--`` to em-dash (or ``--`` to en-dash, and ``---`` to em-dash). - - Convert quotes to curly quote entities. (Essentially impossible - for HTML? Unnecessary for TeX.) - - Various forms of ``:-)`` to smiley icons. - - ``"\ "`` to . Problem with line-wrapping though: it could - end up escaping the newline. - - Escaped newlines to <BR>. - - Escaped period or quote or dash as a disappearing catalyst to - allow character-level inline markup? - -* XML-style character entities, such as "©" for the copyright - symbol. - -Docutils has no need of a character entity subsystem. Supporting -Unicode and text encodings, character entities should be directly -represented in the text: a copyright symbol should be represented by -the copyright symbol character. If this is not possible in an -authoring environment, a pre-processing stage can be added, or a table -of substitution definitions can be devised. - -A "unicode" directive has been implemented to allow direct -specification of esoteric characters. In combination with the -substitution construct, "include" files defining common sets of -character entities can be defined and used. `A set of character -entity set definition files have been defined`__ (`tarball`__). -There's also `a description and instructions for use`__. - -__ http://docutils.sf.net/tmp/charents/ -__ http://docutils.sf.net/tmp/charents.tgz -__ http://docutils.sf.net/tmp/charents/README.html - -To allow for `character-level inline markup`_, a limited form of -character processing has been added to the spec and parser: escaped -whitespace characters are removed from the processed document. Any -further character processing will be of this functional type, rather -than of the character-encoding type. - -.. _character-level inline markup: - ../../ref/rst/restructuredtext.html#character-level-inline-markup - -* Directive idea:: - - .. text-replace:: "pattern" "replacement" - - - Support Unicode "U+XXXX" codes. - - Support regexps, perhaps with alternative "regexp-replace" - directive. - - Flags for regexps; ":flags:" option, or individuals. - - Specifically, should the default be case-sensistive or - -insensitive? - - -Page Or Line Breaks -=================== - -* Should ^L (or something else in reST) be defined to mean - force/suggest page breaks in whatever output we have? - - A "break" or "page-break" directive would be easy to add. A new - doctree element would be required though (perhaps "break"). The - final behavior would be up to the Writer. The directive argument - could be one of page/column/recto/verso for added flexibility. - - Currently ^L (Python's ``\f``) characters are treated as whitespace. - They're converted to single spaces, actually, as are vertical tabs - (^K, Python's ``\v``). It would be possible to recognize form feeds - as markup, but it requires some thought and discussion first. Are - there any downsides? Many editing environments do not allow the - insertion of control characters. Will it cause any harm? It would - be useful as a shorthand for the directive. - - It's common practice to use ^L before Emacs "Local Variables" - lists:: - - ^L - .. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: - - These are already present in many PEPs and Docutils project - documents. From the Emacs manual (info): - - A "local variables list" goes near the end of the file, in the - last page. (It is often best to put it on a page by itself.) - - It would be unfortunate if this construct caused a final blank page - to be generated (for those Writers that recognize the page breaks). - We'll have to add a transform that looks for a "break" plus zero or - more comments at the end of a document, and removes them. - - Probably a bad idea because there is no such thing as a page in a - generic document format. - -* Could the "break" concept above be extended to inline forms? - E.g. "^L" in the middle of a sentence could cause a line break. - Only recognize it at the end of a line (i.e., ``\f\n``)? - - Or is formfeed inappropriate? Perhaps vertical tab (``\v``), but - even that's a stretch. Can't use carriage returns, since they're - commonly used for line endings. - - Probably a bad idea as well because we do not want to use control - characters for well-readable and well-writable markup, and after all - we have the line block syntax for line breaks. - - -Superscript Markup -================== - -Add ``^superscript^`` inline markup? The only common non-markup uses -of "^" I can think of are as short hand for "superscript" itself and -for describing control characters ("^C to cancel"). The former -supports the proposed syntax, and it could be argued that the latter -ought to be literal text anyhow (e.g. "``^C`` to cancel"). - -However, superscripts are seldom needed, and new syntax would break -existing documents. When it's needed, the ``:superscript:`` -(``:sup:``) role can we used as well. - - -Code Execution -============== - -Add the following directives? - -- "exec": Execute Python code & insert the results. Call it - "python" to allow for other languages? - -- "system": Execute an ``os.system()`` call, and insert the results - (possibly as a literal block). Definitely dangerous! How to make - it safe? Perhaps such processing should be left outside of the - document, in the user's production system (a makefile or a script or - whatever). Or, the directive could be disabled by default and only - enabled with an explicit command-line option or config file setting. - Even then, an interactive prompt may be useful, such as: - - The file.txt document you are processing contains a "system" - directive requesting that the ``sudo rm -rf /`` command be - executed. Allow it to execute? (y/N) - -- "eval": Evaluate an expression & insert the text. At parse - time or at substitution time? Dangerous? Perhaps limit to canned - macros; see text.date_. - - .. _text.date: ../todo.html#text-date - -It's too dangerous (or too complicated in the case of "eval"). We do -not want to have such things in the core. - - -``encoding`` Directive -====================== - -Add an "encoding" directive to specify the character encoding of the -input data? Not a good idea for the following reasons: - -- When it sees the directive, the parser will already have read the - input data, and encoding determination will already have been done. - -- If a file with an "encoding" directive is edited and saved with - a different encoding, the directive may cause data corruption. - - -Support for Annotations -======================= - -Add an "annotation" role, as the equivalent of the HTML "title" -attribute? This is secondary information that may "pop up" when the -pointer hovers over the main text. A corresponding directive would be -required to associate annotations with the original text (by name, or -positionally as in anonymous targets?). - -There have not been many requests for such feature, though. Also, -cluttering WYSIWYG plaintext with annotations may not seem like a good -idea, and there is no "tool tip" in formats other than HTML. - - -``term`` Role -============= - -Add a "term" role for unfamiliar or specialized terminology? Probably -not; there is no real use case, and emphasis is enough for most cases. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/rst/problems.txt b/docutils/docs/dev/rst/problems.txt deleted file mode 100644 index bc0101cbf..000000000 --- a/docutils/docs/dev/rst/problems.txt +++ /dev/null @@ -1,872 +0,0 @@ -============================== - Problems With StructuredText -============================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -There are several problems, unresolved issues, and areas of -controversy within StructuredText_ (Classic and Next Generation). In -order to resolve all these issues, this analysis brings all of the -issues out into the open, enumerates all the alternatives, and -proposes solutions to be incorporated into the reStructuredText_ -specification. - - -.. contents:: - - -Formal Specification -==================== - -The description in the original StructuredText.py has been criticized -for being vague. For practical purposes, "the code *is* the spec." -Tony Ibbs has been working on deducing a `detailed description`_ from -the documentation and code of StructuredTextNG_. Edward Loper's -STMinus_ is another attempt to formalize a spec. - -For this kind of a project, the specification should always precede -the code. Otherwise, the markup is a moving target which can never be -adopted as a standard. Of course, a specification may be revised -during lifetime of the code, but without a spec there is no visible -control and thus no confidence. - - -Understanding and Extending the Code -==================================== - -The original StructuredText_ is a dense mass of sparsely commented -code and inscrutable regular expressions. It was not designed to be -extended and is very difficult to understand. StructuredTextNG_ has -been designed to allow input (syntax) and output extensions, but its -documentation (both internal [comments & docstrings], and external) is -inadequate for the complexity of the code itself. - -For reStructuredText to become truly useful, perhaps even part of -Python's standard library, it must have clear, understandable -documentation and implementation code. For the implementation of -reStructuredText to be taken seriously, it must be a sterling example -of the potential of docstrings; the implementation must practice what -the specification preaches. - - -Section Structure via Indentation -================================= - -Setext_ required that body text be indented by 2 spaces. The original -StructuredText_ and StructuredTextNG_ require that section structure -be indicated through indentation, as "inspired by Python". For -certain structures with a very limited, local extent (such as lists, -block quotes, and literal blocks), indentation naturally indicates -structure or hierarchy. For sections (which may have a very large -extent), structure via indentation is unnecessary, unnatural and -ambiguous. Rather, the syntax of the section title *itself* should -indicate that it is a section title. - -The original StructuredText states that "A single-line paragraph whose -immediately succeeding paragraphs are lower level is treated as a -header." Requiring indentation in this way is: - -- Unnecessary. The vast majority of docstrings and standalone - documents will have no more than one level of section structure. - Requiring indentation for such docstrings is unnecessary and - irritating. - -- Unnatural. Most published works use title style (type size, face, - weight, and position) and/or section/subsection numbering rather - than indentation to indicate hierarchy. This is a tradition with a - very long history. - -- Ambiguous. A StructuredText header is indistinguishable from a - one-line paragraph followed by a block quote (precluding the use of - block quotes). Enumerated section titles are ambiguous (is it a - header? is it a list item?). Some additional adornment must be - required to confirm the line's role as a title, both to a parser and - to the human reader of the source text. - -Python's use of significant whitespace is a wonderful (if not -original) innovation, however requiring indentation in ordinary -written text is hypergeneralization. - -reStructuredText_ indicates section structure through title adornment -style (as exemplified by this document). This is far more natural. -In fact, it is already in widespread use in plain text documents, -including in Python's standard distribution (such as the toplevel -README_ file). - - -Character Escaping Mechanism -============================ - -No matter what characters are chosen for markup, some day someone will -want to write documentation *about* that markup or using markup -characters in a non-markup context. Therefore, any complete markup -language must have an escaping or encoding mechanism. For a -lightweight markup system, encoding mechanisms like SGML/XML's '*' -are out. So an escaping mechanism is in. However, with carefully -chosen markup, it should be necessary to use the escaping mechanism -only infrequently. - -reStructuredText_ needs an escaping mechanism: a way to treat -markup-significant characters as the characters themselves. Currently -there is no such mechanism (although ZWiki uses '!'). What are the -candidates? - -1. ``!`` - (http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/NGEscaping) -2. ``\`` -3. ``~`` -4. doubling of characters - -The best choice for this is the backslash (``\``). It's "the single -most popular escaping character in the world!", therefore familiar and -unsurprising. Since characters only need to be escaped under special -circumstances, which are typically those explaining technical -programming issues, the use of the backslash is natural and -understandable. Python docstrings can be raw (prefixed with an 'r', -as in 'r""'), which would obviate the need for gratuitous doubling-up -of backslashes. - -(On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash -escapes, saying, "'nuff said. Backslash it is." Although neither -legally binding nor irrevocable nor any kind of guarantee of anything, -it is a good sign.) - -The rule would be: An unescaped backslash followed by any markup -character escapes the character. The escaped character represents the -character itself, and is prevented from playing a role in any markup -interpretation. The backslash is removed from the output. A literal -backslash is represented by an "escaped backslash," two backslashes in -a row. - -A carefully constructed set of recognition rules for inline markup -will obviate the need for backslash-escapes in almost all cases; see -`Delimitation of Inline Markup`_ below. - -When an expression (requiring backslashes and other characters used -for markup) becomes too complicated and therefore unreadable, a -literal block may be used instead. Inside literal blocks, no markup -is recognized, therefore backslashes (for the purpose of escaping -markup) become unnecessary. - -We could allow backslashes preceding non-markup characters to remain -in the output. This would make describing regular expressions and -other uses of backslashes easier. However, this would complicate the -markup rules and would be confusing. - - -Blank Lines in Lists -==================== - -Oft-requested in Doc-SIG (the earliest reference is dated 1996-08-13) -is the ability to write lists without requiring blank lines between -items. In docstrings, space is at a premium. Authors want to convey -their API or usage information in as compact a form as possible. -StructuredText_ requires blank lines between all body elements, -including list items, even when boundaries are obvious from the markup -itself. - -In reStructuredText, blank lines are optional between list items. -However, in order to eliminate ambiguity, a blank line is required -before the first list item and after the last. Nested lists also -require blank lines before the list start and after the list end. - - -Bullet List Markup -================== - -StructuredText_ includes 'o' as a bullet character. This is dangerous -and counter to the language-independent nature of the markup. There -are many languages in which 'o' is a word. For example, in Spanish:: - - Llamame a la casa - o al trabajo. - - (Call me at home or at work.) - -And in Japanese (when romanized):: - - Senshuu no doyoubi ni tegami - o kakimashita. - - ([I] wrote a letter on Saturday last week.) - -If a paragraph containing an 'o' word wraps such that the 'o' is the -first text on a line, or if a paragraph begins with such a word, it -could be misinterpreted as a bullet list. - -In reStructuredText_, 'o' is not used as a bullet character. '-', -'*', and '+' are the possible bullet characters. - - -Enumerated List Markup -====================== - -StructuredText enumerated lists are allowed to begin with numbers and -letters followed by a period or right-parenthesis, then whitespace. -This has surprising consequences for writing styles. For example, -this is recognized as an enumerated list item by StructuredText:: - - Mr. Creosote. - -People will write enumerated lists in all different ways. It is folly -to try to come up with the "perfect" format for an enumerated list, -and limit the docstring parser's recognition to that one format only. - -Rather, the parser should recognize a variety of enumerator styles. -It is also recommended that the enumerator of the first list item be -ordinal-1 ('1', 'A', 'a', 'I', or 'i'), as output formats may not be -able to begin a list at an arbitrary enumeration. - -An initial idea was to require two or more consistent enumerated list -items in a row. This idea proved impractical and was dropped. In -practice, the presence of a proper enumerator is enough to reliably -recognize an enumerated list item; any ambiguities are reported by the -parser. Here's the original idea for posterity: - - The parser should recognize a variety of enumerator styles, mark - each block as a potential enumerated list item (PELI), and - interpret the enumerators of adjacent PELIs to decide whether they - make up a consistent enumerated list. - - If a PELI is labeled with a "1.", and is immediately followed by a - PELI labeled with a "2.", we've got an enumerated list. Or "(A)" - followed by "(B)". Or "i)" followed by "ii)", etc. The chances - of accidentally recognizing two adjacent and consistently labeled - PELIs, are acceptably small. - - For an enumerated list to be recognized, the following must be - true: - - - the list must consist of multiple adjacent list items (2 or - more) - - the enumerators must all have the same format - - the enumerators must be sequential - - -Definition List Markup -====================== - -StructuredText uses ' -- ' (whitespace, two hyphens, whitespace) on -the first line of a paragraph to indicate a definition list item. The -' -- ' serves to separate the term (on the left) from the definition -(on the right). - -Many people use ' -- ' as an em-dash in their text, conflicting with -the StructuredText usage. Although the Chicago Manual of Style says -that spaces should not be used around an em-dash, Peter Funk pointed -out that this is standard usage in German (according to the Duden, the -official German reference), and possibly in other languages as well. -The widespread use of ' -- ' precludes its use for definition lists; -it would violate the "unsurprising" criterion. - -A simpler, and at least equally visually distinctive construct -(proposed by Guido van Rossum, who incidentally is a frequent user of -' -- ') would do just as well:: - - term 1 - Definition. - - term 2 - Definition 2, paragraph 1. - - Definition 2, paragraph 2. - -A reStructuredText definition list item consists of a term and a -definition. A term is a simple one-line paragraph. A definition is a -block indented relative to the term, and may contain multiple -paragraphs and other body elements. No blank line precedes a -definition (this distinguishes definition lists from block quotes). - - -Literal Blocks -============== - -The StructuredText_ specification has literal blocks indicated by -'example', 'examples', or '::' ending the preceding paragraph. STNG -only recognizes '::'; 'example'/'examples' are not implemented. This -is good; it fixes an unnecessary language dependency. The problem is -what to do with the sometimes- unwanted '::'. - -In reStructuredText_ '::' at the end of a paragraph indicates that -subsequent *indented* blocks are treated as literal text. No further -markup interpretation is done within literal blocks (not even -backslash-escapes). If the '::' is preceded by whitespace, '::' is -omitted from the output; if '::' was the sole content of a paragraph, -the entire paragraph is removed (no 'empty' paragraph remains). If -'::' is preceded by a non-whitespace character, '::' is replaced by -':' (i.e., the extra colon is removed). - -Thus, a section could begin with a literal block as follows:: - - Section Title - ------------- - - :: - - print "this is example literal" - - -Tables -====== - -The table markup scheme in classic StructuredText was horrible. Its -omission from StructuredTextNG is welcome, and its markup will not be -repeated here. However, tables themselves are useful in -documentation. Alternatives: - -1. This format is the most natural and obvious. It was independently - invented (no great feat of creation!), and later found to be the - format supported by the `Emacs table mode`_:: - - +------------+------------+------------+--------------+ - | Header 1 | Header 2 | Header 3 | Header 4 | - +============+============+============+==============+ - | Column 1 | Column 2 | Column 3 & 4 span (Row 1) | - +------------+------------+------------+--------------+ - | Column 1 & 2 span | Column 3 | - Column 4 | - +------------+------------+------------+ - Row 2 & 3 | - | 1 | 2 | 3 | - span | - +------------+------------+------------+--------------+ - - Tables are described with a visual outline made up of the - characters '-', '=', '|', and '+': - - - The hyphen ('-') is used for horizontal lines (row separators). - - The equals sign ('=') is optionally used as a header separator - (as of version 1.5.24, this is not supported by the Emacs table - mode). - - The vertical bar ('|') is used for for vertical lines (column - separators). - - The plus sign ('+') is used for intersections of horizontal and - vertical lines. - - Row and column spans are possible simply by omitting the column or - row separators, respectively. The header row separator must be - complete; in other words, a header cell may not span into the table - body. Each cell contains body elements, and may have multiple - paragraphs, lists, etc. Initial spaces for a left margin are - allowed; the first line of text in a cell determines its left - margin. - -2. Below is a simpler table structure. It may be better suited to - manual input than alternative #1, but there is no Emacs editing - mode available. One disadvantage is that it resembles section - titles; a one-column table would look exactly like section & - subsection titles. :: - - ============ ============ ============ ============== - Header 1 Header 2 Header 3 Header 4 - ============ ============ ============ ============== - Column 1 Column 2 Column 3 & 4 span (Row 1) - ------------ ------------ --------------------------- - Column 1 & 2 span Column 3 - Column 4 - ------------------------- ------------ - Row 2 & 3 - 1 2 3 - span - ============ ============ ============ ============== - - The table begins with a top border of equals signs with a space at - each column boundary (regardless of spans). Each row is - underlined. Internal row separators are underlines of '-', with - spaces at column boundaries. The last of the optional head rows is - underlined with '=', again with spaces at column boundaries. - Column spans have no spaces in their underline. Row spans simply - lack an underline at the row boundary. The bottom boundary of the - table consists of '=' underlines. A blank line is required - following a table. - -3. A minimalist alternative is as follows:: - - ==== ===== ======== ======== ======= ==== ===== ===== - Old State Input Action New State Notes - ----------- -------- ----------------- ----------- - ids types new type sys.msg. dupname ids types - ==== ===== ======== ======== ======= ==== ===== ===== - -- -- explicit -- -- new True - -- -- implicit -- -- new False - None False explicit -- -- new True - old False explicit implicit old new True - None True explicit explicit new None True - old True explicit explicit new,old None True [1] - None False implicit implicit new None False - old False implicit implicit new,old None False - None True implicit implicit new None True - old True implicit implicit new old True - ==== ===== ======== ======== ======= ==== ===== ===== - - The table begins with a top border of equals signs with one or more - spaces at each column boundary (regardless of spans). There must - be at least two columns in the table (to differentiate it from - section headers). Each line starts a new row. The rightmost - column is unbounded; text may continue past the edge of the table. - Each row/line must contain spaces at column boundaries, except for - explicit column spans. Underlines of '-' can be used to indicate - column spans, but should be used sparingly if at all. Lines - containing column span underlines may not contain any other text. - The last of the optional head rows is underlined with '=', again - with spaces at column boundaries. The bottom boundary of the table - consists of '=' underlines. A blank line is required following a - table. - - This table sums up the features. Using all the features in such a - small space is not pretty though:: - - ======== ======== ======== - Header 2 & 3 Span - ------------------ - Header 1 Header 2 Header 3 - ======== ======== ======== - Each line is a new row. - Each row consists of one line only. - Row spans are not possible. - The last column may spill over to the right. - Column spans are possible with an underline joining columns. - ---------------------------- - The span is limited to the row above the underline. - ======== ======== ======== - -4. As a variation of alternative 3, bullet list syntax in the first - column could be used to indicate row starts. Multi-line rows are - possible, but row spans are not. For example:: - - ===== ===== - col 1 col 2 - ===== ===== - - 1 Second column of row 1. - - 2 Second column of row 2. - Second line of paragraph. - - 3 Second column of row 3. - - Second paragraph of row 3, - column 2 - ===== ===== - - Column spans would be indicated on the line after the last line of - the row. To indicate a real bullet list within a first-column - cell, simply nest the bullets. - -5. In a further variation, we could simply assume that whitespace in - the first column implies a multi-line row; the text in other - columns is continuation text. For example:: - - ===== ===== - col 1 col 2 - ===== ===== - 1 Second column of row 1. - 2 Second column of row 2. - Second line of paragraph. - 3 Second column of row 3. - - Second paragraph of row 3, - column 2 - ===== ===== - - Limitations of this approach: - - - Cells in the first column are limited to one line of text. - - - Cells in the first column *must* contain some text; blank cells - would lead to a misinterpretation. An empty comment ("..") is - sufficient. - -6. Combining alternative 3 and 4, a bullet list in the first column - could mean multi-line rows, and no bullet list means single-line - rows only. - -Alternatives 1 and 5 has been adopted by reStructuredText. - - -Delimitation of Inline Markup -============================= - -StructuredText specifies that inline markup must begin with -whitespace, precluding such constructs as parenthesized or quoted -emphatic text:: - - "**What?**" she cried. (*exit stage left*) - -The `reStructuredText markup specification`_ allows for such -constructs and disambiguates inline markup through a set of -recognition rules. These recognition rules define the context of -markup start-strings and end-strings, allowing markup characters to be -used in most non-markup contexts without a problem (or a backslash). -So we can say, "Use asterisks (*) around words or phrases to -*emphasisze* them." The '(*)' will not be recognized as markup. This -reduces the need for markup escaping to the point where an escape -character is *almost* (but not quite!) unnecessary. - - -Underlining -=========== - -StructuredText uses '_text_' to indicate underlining. To quote David -Ascher in his 2000-01-21 Doc-SIG mailing list post, "Docstring -grammar: a very revised proposal": - - The tagging of underlined text with _'s is suboptimal. Underlines - shouldn't be used from a typographic perspective (underlines were - designed to be used in manuscripts to communicate to the - typesetter that the text should be italicized -- no well-typeset - book ever uses underlines), and conflict with double-underscored - Python variable names (__init__ and the like), which would get - truncated and underlined when that effect is not desired. Note - that while *complete* markup would prevent that truncation - ('__init__'), I think of docstring markups much like I think of - type annotations -- they should be optional and above all do no - harm. In this case the underline markup does harm. - -Underlining is not part of the reStructuredText specification. - - -Inline Literals -=============== - -StructuredText's markup for inline literals (text left as-is, -verbatim, usually in a monospaced font; as in HTML <TT>) is single -quotes ('literals'). The problem with single quotes is that they are -too often used for other purposes: - -- Apostrophes: "Don't blame me, 'cause it ain't mine, it's Chris'."; - -- Quoting text: - - First Bruce: "Well Bruce, I heard the prime minister use it. - 'S'hot enough to boil a monkey's bum in 'ere your Majesty,' he - said, and she smiled quietly to herself." - - In the UK, single quotes are used for dialogue in published works. - -- String literals: s = '' - -Alternatives:: - - 'text' \'text\' ''text'' "text" \"text\" ""text"" - #text# @text@ `text` ^text^ ``text'' ``text`` - -The examples below contain inline literals, quoted text, and -apostrophes. Each example should evaluate to the following HTML:: - - Some <TT>code</TT>, with a 'quote', "double", ain't it grand? - Does <TT>a[b] = 'c' + "d" + `2^3`</TT> work? - - 0. Some code, with a quote, double, ain't it grand? - Does a[b] = 'c' + "d" + `2^3` work? - 1. Some 'code', with a \'quote\', "double", ain\'t it grand? - Does 'a[b] = \'c\' + "d" + `2^3`' work? - 2. Some \'code\', with a 'quote', "double", ain't it grand? - Does \'a[b] = 'c' + "d" + `2^3`\' work? - 3. Some ''code'', with a 'quote', "double", ain't it grand? - Does ''a[b] = 'c' + "d" + `2^3`'' work? - 4. Some "code", with a 'quote', \"double\", ain't it grand? - Does "a[b] = 'c' + "d" + `2^3`" work? - 5. Some \"code\", with a 'quote', "double", ain't it grand? - Does \"a[b] = 'c' + "d" + `2^3`\" work? - 6. Some ""code"", with a 'quote', "double", ain't it grand? - Does ""a[b] = 'c' + "d" + `2^3`"" work? - 7. Some #code#, with a 'quote', "double", ain't it grand? - Does #a[b] = 'c' + "d" + `2^3`# work? - 8. Some @code@, with a 'quote', "double", ain't it grand? - Does @a[b] = 'c' + "d" + `2^3`@ work? - 9. Some `code`, with a 'quote', "double", ain't it grand? - Does `a[b] = 'c' + "d" + \`2^3\`` work? - 10. Some ^code^, with a 'quote', "double", ain't it grand? - Does ^a[b] = 'c' + "d" + `2\^3`^ work? - 11. Some ``code'', with a 'quote', "double", ain't it grand? - Does ``a[b] = 'c' + "d" + `2^3`'' work? - 12. Some ``code``, with a 'quote', "double", ain't it grand? - Does ``a[b] = 'c' + "d" + `2^3\``` work? - -Backquotes (#9 & #12) are the best choice. They are unobtrusive and -relatviely rarely used (more rarely than ' or ", anyhow). Backquotes -have the connotation of 'quotes', which other options (like carets, -#10) don't. - -Analogously with ``*emph*`` & ``**strong**``, double-backquotes (#12) -could be used for inline literals. If single-backquotes are used for -'interpreted text' (context-sensitive domain-specific descriptive -markup) such as function name hyperlinks in Python docstrings, then -double-backquotes could be used for absolute-literals, wherein no -processing whatsoever takes place. An advantage of double-backquotes -would be that backslash-escaping would no longer be necessary for -embedded single-backquotes; however, embedded double-backquotes (in an -end-string context) would be illegal. See `Backquotes in -Phrase-Links`__ in `Record of reStructuredText Syntax Alternatives`__. - -__ alternatives.html#backquotes-in-phrase-links -__ alternatives.html - -Alternative choices are carets (#10) and TeX-style quotes (#11). For -examples of TeX-style quoting, see -http://www.zope.org/Members/jim/StructuredTextWiki/CustomizingTheDocumentProcessor. - -Some existing uses of backquotes: - -1. As a synonym for repr() in Python. -2. For command-interpolation in shell scripts. -3. Used as open-quotes in TeX code (and carried over into plaintext - by TeXies). - -The inline markup start-string and end-string recognition rules -defined by the `reStructuredText markup specification`_ would allow -all of these cases inside inline literals, with very few exceptions. -As a fallback, literal blocks could handle all cases. - -Outside of inline literals, the above uses of backquotes would require -backslash-escaping. However, these are all prime examples of text -that should be marked up with inline literals. - -If either backquotes or straight single-quotes are used as markup, -TeX-quotes are too troublesome to support, so no special-casing of -TeX-quotes should be done (at least at first). If TeX-quotes have to -be used outside of literals, a single backslash-escaped would suffice: -\``TeX quote''. Ugly, true, but very infrequently used. - -Using literal blocks is a fallback option which removes the need for -backslash-escaping:: - - like this:: - - Here, we can do ``absolutely'' anything `'`'\|/|\ we like! - -No mechanism for inline literals is perfect, just as no escaping -mechanism is perfect. No matter what we use, complicated inline -expressions involving the inline literal quote and/or the backslash -will end up looking ugly. We can only choose the least often ugly -option. - -reStructuredText will use double backquotes for inline literals, and -single backqoutes for interpreted text. - - -Hyperlinks -========== - -There are three forms of hyperlink currently in StructuredText_: - -1. (Absolute & relative URIs.) Text enclosed by double quotes - followed by a colon, a URI, and concluded by punctuation plus white - space, or just white space, is treated as a hyperlink:: - - "Python":http://www.python.org/ - -2. (Absolute URIs only.) Text enclosed by double quotes followed by a - comma, one or more spaces, an absolute URI and concluded by - punctuation plus white space, or just white space, is treated as a - hyperlink:: - - "mail me", mailto:me@mail.com - -3. (Endnotes.) Text enclosed by brackets link to an endnote at the - end of the document: at the beginning of the line, two dots, a - space, and the same text in brackets, followed by the end note - itself:: - - Please refer to the fine manual [GVR2001]. - - .. [GVR2001] Python Documentation, Release 2.1, van Rossum, - Drake, et al., http://www.python.org/doc/ - -The problem with forms 1 and 2 is that they are neither intuitive nor -unobtrusive (they break design goals 5 & 2). They overload -double-quotes, which are too often used in ordinary text (potentially -breaking design goal 4). The brackets in form 3 are also too common -in ordinary text (such as [nested] asides and Python lists like [12]). - -Alternatives: - -1. Have no special markup for hyperlinks. - -2. A. Interpret and mark up hyperlinks as any contiguous text - containing '://' or ':...@' (absolute URI) or '@' (email - address) after an alphanumeric word. To de-emphasize the URI, - simply enclose it in parentheses: - - Python (http://www.python.org/) - - B. Leave special hyperlink markup as a domain-specific extension. - Hyperlinks in ordinary reStructuredText documents would be - required to be standalone (i.e. the URI text inline in the - document text). Processed hyperlinks (where the URI text is - hidden behind the link) are important enough to warrant syntax. - -3. The original Setext_ introduced a mechanism of indirect hyperlinks. - A source link word ('hot word') in the text was given a trailing - underscore:: - - Here is some text with a hyperlink_ built in. - - The hyperlink itself appeared at the end of the document on a line - by itself, beginning with two dots, a space, the link word with a - leading underscore, whitespace, and the URI itself:: - - .. _hyperlink http://www.123.xyz - - Setext used ``underscores_instead_of_spaces_`` for phrase links. - -With some modification, alternative 3 best satisfies the design goals. -It has the advantage of being readable and relatively unobtrusive. -Since each source link must match up to a target, the odd variable -ending in an underscore can be spared being marked up (although it -should generate a "no such link target" warning). The only -disadvantage is that phrase-links aren't possible without some -obtrusive syntax. - -We could achieve phrase-links if we enclose the link text: - -1. in double quotes:: - - "like this"_ - -2. in brackets:: - - [like this]_ - -3. or in backquotes:: - - `like this`_ - -Each gives us somewhat obtrusive markup, but that is unavoidable. The -bracketed syntax (#2) is reminiscent of links on many web pages -(intuitive), although it is somewhat obtrusive. Alternative #3 is -much less obtrusive, and is consistent with interpreted text: the -trailing underscore indicates the interpretation of the phrase, as a -hyperlink. #3 also disambiguates hyperlinks from footnote references. -Alternative #3 wins. - -The same trailing underscore markup can also be used for footnote and -citation references, removing the problem with ordinary bracketed text -and Python lists:: - - Please refer to the fine manual [GVR2000]_. - - .. [GVR2000] Python Documentation, van Rossum, Drake, et al., - http://www.python.org/doc/ - -The two-dots-and-a-space syntax was generalized by Setext for -comments, which are removed from the (visible) processed output. -reStructuredText uses this syntax for comments, footnotes, and link -target, collectively termed "explicit markup". For link targets, in -order to eliminate ambiguity with comments and footnotes, -reStructuredText specifies that a colon always follow the link target -word/phrase. The colon denotes 'maps to'. There is no reason to -restrict target links to the end of the document; they could just as -easily be interspersed. - -Internal hyperlinks (links from one point to another within a single -document) can be expressed by a source link as before, and a target -link with a colon but no URI. In effect, these targets 'map to' the -element immediately following. - -As an added bonus, we now have a perfect candidate for -reStructuredText directives, a simple extension mechanism: explicit -markup containing a single word followed by two colons and whitespace. -The interpretation of subsequent data on the directive line or -following is directive-dependent. - -To summarize:: - - .. This is a comment. - - .. The line below is an example of a directive. - .. version:: 1 - - This is a footnote [1]_. - - This internal hyperlink will take us to the footnotes_ area below. - - Here is a one-word_ external hyperlink. - - Here is `a hyperlink phrase`_. - - .. _footnotes: - .. [1] Footnote text goes here. - - .. external hyperlink target mappings: - .. _one-word: http://www.123.xyz - .. _a hyperlink phrase: http://www.123.xyz - -The presence or absence of a colon after the target link -differentiates an indirect hyperlink from a footnote, respectively. A -footnote requires brackets. Backquotes around a target link word or -phrase are required if the phrase contains a colon, optional -otherwise. - -Below are examples using no markup, the two StructuredText hypertext -styles, and the reStructuredText hypertext style. Each example -contains an indirect link, a direct link, a footnote/endnote, and -bracketed text. In HTML, each example should evaluate to:: - - <P>A <A HREF="http://spam.org">URI</A>, see <A HREF="#eggs2000"> - [eggs2000]</A> (in Bacon [Publisher]). Also see - <A HREF="http://eggs.org">http://eggs.org</A>.</P> - - <P><A NAME="eggs2000">[eggs2000]</A> "Spam, Spam, Spam, Eggs, - Bacon, and Spam"</P> - -1. No markup:: - - A URI http://spam.org, see eggs2000 (in Bacon [Publisher]). - Also see http://eggs.org. - - eggs2000 "Spam, Spam, Spam, Eggs, Bacon, and Spam" - -2. StructuredText absolute/relative URI syntax - ("text":http://www.url.org):: - - A "URI":http://spam.org, see [eggs2000] (in Bacon [Publisher]). - Also see "http://eggs.org":http://eggs.org. - - .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" - - Note that StructuredText does not recognize standalone URIs, - forcing doubling up as shown in the second line of the example - above. - -3. StructuredText absolute-only URI syntax - ("text", mailto:you@your.com):: - - A "URI", http://spam.org, see [eggs2000] (in Bacon - [Publisher]). Also see "http://eggs.org", http://eggs.org. - - .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" - -4. reStructuredText syntax:: - - 4. A URI_, see [eggs2000]_ (in Bacon [Publisher]). - Also see http://eggs.org. - - .. _URI: http:/spam.org - .. [eggs2000] "Spam, Spam, Spam, Eggs, Bacon, and Spam" - -The bracketed text '[Publisher]' may be problematic with -StructuredText (syntax 2 & 3). - -reStructuredText's syntax (#4) is definitely the most readable. The -text is separated from the link URI and the footnote, resulting in -cleanly readable text. - -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _detailed description: - http://homepage.ntlworld.com/tibsnjoan/docutils/STNG-format.html -.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/stminus.html -.. _StructuredTextNG: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG -.. _README: http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/ - python/python/dist/src/README -.. _Emacs table mode: http://table.sourceforge.net/ -.. _reStructuredText Markup Specification: - ../../ref/rst/restructuredtext.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/semantics.txt b/docutils/docs/dev/semantics.txt deleted file mode 100644 index cd20e15f6..000000000 --- a/docutils/docs/dev/semantics.txt +++ /dev/null @@ -1,119 +0,0 @@ -===================== - Docstring Semantics -===================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -These are notes for a possible future PEP providing the final piece of -the Python docstring puzzle: docstring semantics or documentation -methodology. `PEP 257`_, Docstring Conventions, sketches out some -guidelines, but does not get into methodology details. - -I haven't explored documentation methodology more because, in my -opinion, it is a completely separate issue from syntax, and it's even -more controversial than syntax. Nobody wants to be told how to lay -out their documentation, a la JavaDoc_. I think the JavaDoc way is -butt-ugly, but it *is* an established standard for the Java world. -Any standard documentation methodology has to be formal enough to be -useful but remain light enough to be usable. If the methodology is -too strict, too heavy, or too ugly, many/most will not want to use it. - -I think a standard methodology could benefit the Python community, but -it would be a hard sell. A PEP would be the place to start. For most -human-readable documentation needs, the free-form text approach is -adequate. We'd only need a formal methodology if we want to extract -the parameters into a data dictionary, index, or summary of some kind. - - -PythonDoc -========= - -(Not to be confused with Daniel Larsson's pythondoc_ project.) - -A Python version of the JavaDoc_ semantics (not syntax). A set of -conventions which are understood by the Docutils. What JavaDoc has -done is to establish a syntax that enables a certain documentation -methodology, or standard *semantics*. JavaDoc is not just syntax; it -prescribes a methodology. - -- Use field lists or definition lists for "tagged blocks". By this I - mean that field lists can be used similarly to JavaDoc's ``@tag`` - syntax. That's actually one of the motivators behind field lists. - For example, we could have:: - - """ - :Parameters: - - `lines`: a list of one-line strings without newlines. - - `until_blank`: Stop collecting at the first blank line if - true (1). - - `strip_indent`: Strip common leading indent if true (1, - default). - - :Return: - - a list of indented lines with mininum indent removed; - - the amount of the indent; - - whether or not the block finished with a blank line or at - the end of `lines`. - """ - - This is taken straight out of docutils/statemachine.py, in which I - experimented with a simple documentation methodology. Another - variation I've thought of exploits the Grouch_-compatible - "classifier" element of definition lists. For example:: - - :Parameters: - `lines` : [string] - List of one-line strings without newlines. - `until_blank` : boolean - Stop collecting at the first blank line if true (1). - `strip_indent` : boolean - Strip common leading indent if true (1, default). - -- Field lists could even be used in a one-to-one correspondence with - JavaDoc ``@tags``, although I doubt if I'd recommend it. Several - ports of JavaDoc's ``@tag`` methodology exist in Python, most - recently Ed Loper's "epydoc_". - - -Other Ideas -=========== - -- Can we extract comments from parsed modules? Could be handy for - documenting function/method parameters:: - - def method(self, - source, # path of input file - dest # path of output file - ): - - This would save having to repeat parameter names in the docstring. - - Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG] - Documentation tool": - - it would be quite hard to add a new param to this method without - realising you should document it - -- Frederic Giacometti's `iPhrase Python documentation conventions`_ is - an attachment to his Doc-SIG post of 2001-05-30. - - -.. _PEP 257: http://www.python.org/peps/pep-0257.html -.. _JavaDoc: http://java.sun.com/j2se/javadoc/ -.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ -.. _Grouch: http://www.mems-exchange.org/software/grouch/ -.. _epydoc: http://epydoc.sf.net/ -.. _iPhrase Python documentation conventions: - http://mail.python.org/pipermail/doc-sig/2001-May/001840.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/testing.txt b/docutils/docs/dev/testing.txt deleted file mode 100644 index bde54116f..000000000 --- a/docutils/docs/dev/testing.txt +++ /dev/null @@ -1,246 +0,0 @@ -=================== - Docutils_ Testing -=================== - -:Author: Felix Wiemann -:Author: David Goodger -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - -When adding new functionality (or fixing bugs), be sure to add test -cases to the test suite. Practise test-first programming; it's fun, -it's addictive, and it works! - -This document describes how to run the Docutils test suite, how the -tests are organized and how to add new tests or modify existing tests. - - -Running the Test Suite -====================== - -Before checking in any changes, run the entire Docutils test suite to -be sure that you haven't broken anything. From a shell:: - - cd docutils/test - ./alltests.py - - -Python Versions -=============== - -The Docutils 0.4 release supports Python 2.1 [#py21]_ or later, with -some features only working (and being tested) with Python 2.3+. -Therefore, you should actually have Pythons 2.1 [#py21]_, 2.2, 2.3, as -well as the latest Python installed and always run the tests on all of -them. (A good way to do that is to always run the test suite through -a short script that runs ``alltests.py`` under each version of -Python.) If you can't afford intalling 3 or more Python versions, the -edge cases (2.1 and 2.3) should cover most of it. - -.. [#py21] Python 2.1 may be used providing the compiler package is - installed. The compiler package can be found in the Tools/ - directory of Python 2.1's source distribution. - -Good resources covering the differences between Python versions: - -* `What's New in Python 2.2`__ -* `What's New in Python 2.3`__ -* `What's New in Python 2.4`__ -* `PEP 290 - Code Migration and Modernization`__ - -__ http://www.python.org/doc/2.2.3/whatsnew/whatsnew22.html -__ http://www.python.org/doc/2.3.5/whatsnew/whatsnew23.html -__ http://www.python.org/doc/2.4.1/whatsnew/whatsnew24.html -__ http://www.python.org/peps/pep-0290.html - -.. _Python Check-in Policies: http://www.python.org/dev/tools.html -.. _sandbox directory: - http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/ -.. _nightly repository tarball: - http://svn.berlios.de/svndumps/docutils-repos.gz - - -Unit Tests -========== - -Unit tests test single functions or modules (i.e. whitebox testing). - -If you are implementing a new feature, be sure to write a test case -covering its functionality. It happens very frequently that your -implementation (or even only a part of it) doesn't work with an older -(or even newer) Python version, and the only reliable way to detect -those cases is using tests. - -Often, it's easier to write the test first and then implement the -functionality required to make the test pass. - - -Writing New Tests ------------------ - -When writing new tests, it very often helps to see how a similar test -is implemented. For example, the files in the -``test_parsers/test_rst/`` directory all look very similar. So when -adding a test, you don't have to reinvent the wheel. - -If there is no similar test, you can write a new test from scratch -using Python's ``unittest`` module. For an example, please have a -look at the following imaginary ``test_square.py``:: - - #! /usr/bin/env python - - # Author: your name - # Contact: your email address - # Revision: $Revision$ - # Date: $Date$ - # Copyright: This module has been placed in the public domain. - - """ - Test module for docutils.square. - """ - - import unittest - import docutils.square - - - class SquareTest(unittest.TestCase): - - def test_square(self): - self.assertEqual(docutils.square.square(0), 0) - self.assertEqual(docutils.square.square(5), 25) - self.assertEqual(docutils.square.square(7), 49) - - def test_square_root(self): - self.assertEqual(docutils.square.sqrt(49), 7) - self.assertEqual(docutils.square.sqrt(0), 0) - self.assertRaises(docutils.square.SquareRootError, - docutils.square.sqrt, 20) - - - if __name__ == '__main__': - unittest.main() - -For more details on how to write tests, please refer to the -documentation of the ``unittest`` module. - - -.. _functional: - -Functional Tests -================ - -The directory ``test/functional/`` contains data for functional tests. - -Performing functional testing means testing the Docutils system as a -whole (i.e. blackbox testing). - - -Directory Structure -------------------- - -+ ``functional/`` The main data directory. - - + ``input/`` The input files. - - - ``some_test.txt``, for example. - - + ``output/`` The actual output. - - - ``some_test.html``, for example. - - + ``expected/`` The expected output. - - - ``some_test.html``, for example. - - + ``tests/`` The config files for processing the input files. - - - ``some_test.py``, for example. - - - ``_default.py``, the `default configuration file`_. - - -The Testing Process -------------------- - -When running ``test_functional.py``, all config files in -``functional/tests/`` are processed. (Config files whose names begin -with an underscore are ignored.) The current working directory is -always Docutils' main test directory (``test/``). - -For example, ``functional/tests/some_test.py`` could read like this:: - - # Source and destination file names. - test_source = "some_test.txt" - test_destination = "some_test.html" - - # Keyword parameters passed to publish_file. - reader_name = "standalone" - parser_name = "rst" - writer_name = "html" - settings_overrides['output-encoding'] = 'utf-8' - # Relative to main ``test/`` directory. - settings_overrides['stylesheet_path'] = '../docutils/writers/html4css1/html4css1.css' - -The two variables ``test_source`` and ``test_destination`` contain the -input file name (relative to ``functional/input/``) and the output -file name (relative to ``functional/output/`` and -``functional/expected/``). Note that the file names can be chosen -arbitrarily. However, the file names in ``functional/output/`` *must* -match the file names in ``functional/expected/``. - -If defined, ``_test_more`` must be a function with the following -signature:: - - def _test_more(expected_dir, output_dir, test_case, parameters): - -This function is called from the test case to perform tests beyond the -simple comparison of expected and actual output files. - -``test_source`` and ``test_destination`` are removed from the -namespace, as are all variables whose names begin with an underscore -("_"). The remaining names are passed as keyword arguments to -``docutils.core.publish_file``, so you can set reader, parser, writer -and anything else you want to configure. Note that -``settings_overrides`` is already initialized as a dictionary *before* -the execution of the config file. - - -Creating New Tests ------------------- - -In order to create a new test, put the input test file into -``functional/input/``. Then create a config file in -``functional/tests/`` which sets at least input and output file names, -reader, parser and writer. - -Now run ``test_functional.py``. The test will fail, of course, -because you do not have an expected output yet. However, an output -file will have been generated in ``functional/output/``. Check this -output file for validity and correctness. Then copy the file to -``functional/expected/``. - -If you rerun ``test_functional.py`` now, it should pass. - -If you run ``test_functional.py`` later and the actual output doesn't -match the expected output anymore, the test will fail. - -If this is the case and you made an intentional change, check the -actual output for validity and correctness, copy it to -``functional/expected/`` (overwriting the old expected output), and -commit the change. - - -.. _default configuration file: - -The Default Configuration File ------------------------------- - -The file ``functional/tests/_default.py`` contains default settings. -It is executed just before the actual configuration files, which has -the same effect as if the contents of ``_default.py`` were prepended -to every configuration file. diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt deleted file mode 100644 index 6f1c6291d..000000000 --- a/docutils/docs/dev/todo.txt +++ /dev/null @@ -1,1964 +0,0 @@ -====================== - Docutils_ To Do List -====================== - -:Author: David Goodger (with input from many); open to all Docutils - developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. contents:: - - -Priority items are marked with "@" symbols. The more @s, the higher -the priority. Items in question form (containing "?") are ideas which -require more thought and debate; they are potential to-do's. - -Many of these items are awaiting champions. If you see something -you'd like to tackle, please do! If there's something you'd like to -see done but are unable to implement it yourself, please consider -donating to Docutils: |donate| - -.. |donate| image:: http://images.sourceforge.net/images/project-support.jpg - :target: http://sourceforge.net/donate/index.php?group_id=38414 - :align: middle - :width: 88 - :height: 32 - :alt: Support the Docutils project! - -Please see also the Bugs_ document for a list of bugs in Docutils. - -.. _bugs: ../../BUGS.html - - -Release 0.4 -=========== - -We should get Docutils 0.4 out soon, but we shouldn't just cut a -"frozen snapshot" release. Here's a list of features (achievable in -the short term) to include: - -* [DONE in rev. 3901] Move support files to docutils/writers/support. - -* [DONE in rev. 4163] Convert ``docutils/writers/support/*`` into - individual writer packages. - -* [DONE in rev. 3901] Remove docutils.transforms.html.StylesheetCheck - (no longer needed because of the above change). - -* [DONE in rev. 3962] Incorporate new branch policy into the docs. - ("Development strategy" thread on Docutils-develop) - -* [DONE in rev. 4152] Added East-Asian double-width character support. - -* [DONE in rev. 4156] Merge the S5 branch. - -Anything else? - -Once released, - -* Tag it and create a maintenance branch (perhaps "maint-0-4"). - -* Declare that: - - - Docutils 0.4.x is the last version that will support Python 2.1 - (and perhaps higher?) - - - Docutils 0.4.x is the last version that will support (make - compromises for) Netscape Navigator 4 - - -Minimum Requirements for Python Standard Library Candidacy -========================================================== - -Below are action items that must be added and issues that must be -addressed before Docutils can be considered suitable to be proposed -for inclusion in the Python standard library. - -* Support for `document splitting`_. May require some major code - rework. - -* Support for subdocuments (see `large documents`_). - -* `Object numbering and object references`_. - -* `Nested inline markup`_. - -* `Python Source Reader`_. - -* The HTML writer needs to be rewritten (or a second HTML writer - added) to allow for custom classes, and for arbitrary splitting - (stack-based?). - -* Documentation_ of the architecture. Other docs too. - -* Plugin support. - -* A LaTeX writer making use of (La)TeX's power, so that the rendering - of the resulting documents is more easily customizable. (Similar to - what you wrote about a new HTML Writer.) - -* Suitability for `Python module documentation - <http://docutils.sf.net/sandbox/README.html#documenting-python>`_. - - -General -======= - -* Allow different report levels for STDERR and system_messages inside - the document? - -* Change the docutils-update script (in sandbox/infrastructure), to - support arbitrary branch snapshots. - -* Add a generic "container" element, equivalent to "inline", to which - a "class" attribute can be attached. Will require a reST directive - also. - -* Move some general-interest sandboxes out of individuals' - directories, into subprojects? - -* Add option for file (and URL) access restriction to make Docutils - usable in Wikis and similar applications. - - 2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled`` - settings. These partially solve the problem, allowing or disabling - **all** file accesses, but not limited access. - -* Configuration file handling needs discussion: - - - There should be some error checking on the contents of config - files. How much checking should be done? How loudly should - Docutils complain if it encounters an error/problem? - - - Docutils doesn't complain when it doesn't find a configuration - file supplied with the ``--config`` option. Should it? (If yes, - error or warning?) - -* Internationalization: - - - I18n needs refactoring, the language dictionaries are difficult to - maintain. Maybe have a look at gettext or similar tools. - - - Language modules: in accented languages it may be useful to have - both accented and unaccented entries in the - ``bibliographic_fields`` mapping for versatility. - - - Add a "--strict-language" option & setting: no English fallback - for language-dependent features. - - - Add internationalization to _`footer boilerplate text` (resulting - from "--generator", "--source-link", and "--date" etc.), allowing - translations. - -* Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP. - -* In ``docutils.readers.get_reader_class`` (& ``parsers`` & - ``writers`` too), should we be importing "standalone" or - "docutils.readers.standalone"? (This would avoid importing - top-level modules if the module name is not in docutils/readers. - Potential nastiness.) - -* Perhaps store a _`name-to-id mapping file`? This could be stored - permanently, read by subsequent processing runs, and updated with - new entries. ("Persistent ID mapping"?) - -* Perhaps the ``Component.supports`` method should deal with - individual features ("meta" etc.) instead of formats ("html" etc.)? - -* Add _`object numbering and object references` (tables & figures). - These would be the equivalent of DocBook's "formal" elements. - - We may need _`persistent sequences`, such as chapter numbers. See - `OpenOffice.org XML`_ "fields". Should the sequences be automatic - or manual (user-specifyable)? - - We need to name the objects: - - - "name" option for the "figure" directive? :: - - .. figure:: image.png - :name: image's name - - Same for the "table" directive:: - - .. table:: optional title here - :name: table's name - - ===== ===== - x not x - ===== ===== - True False - False True - ===== ===== - - This would also allow other options to be set, like border - styles. The same technique could be used for other objects. - - A preliminary "table" directive has been implemented, supporting - table titles. Perhaps the name should derive from the title. - - - The object could also be done this way:: - - .. _figure name: - - .. figure:: image.png - - This may be a more general solution, equally applicable to tables. - However, explicit naming using an option seems simpler to users. - - - Perhaps the figure name could be incorporated into the figure - definition, as an optional inline target part of the directive - argument:: - - .. figure:: _`figure name` image.png - - Maybe with a delimiter:: - - .. figure:: _`figure name`: image.png - - Or some other, simpler syntax. - - We'll also need syntax for object references. See `OpenOffice.org - XML`_ "reference fields": - - - Parameterized substitutions? For example:: - - See |figure (figure name)| on |page (figure name)|. - - .. |figure (name)| figure-ref:: (name) - .. |page (name)| page-ref:: (name) - - The result would be:: - - See figure 3.11 on page 157. - - But this would require substitution directives to be processed at - reference-time, not at definition-time as they are now. Or, - perhaps the directives could just leave ``pending`` elements - behind, and the transforms do the work? How to pass the data - through? Too complicated. - - - An interpreted text approach is simpler and better:: - - See :figure:`figure name` on :page:`figure name`. - - The "figure" and "page" roles could generate appropriate - boilerplate text. The position of the role (prefix or suffix) - could also be utilized. - - See `Interpreted Text`_ below. - - - We could leave the boilerplate text up to the document:: - - See Figure :fig:`figure name` on page :pg:`figure name`. - - - Reference boilerplate could be specified in the document - (defaulting to nothing):: - - .. fignum:: - :prefix-ref: "Figure " - :prefix-caption: "Fig. " - :suffix-caption: : - - .. _OpenOffice.org XML: http://xml.openoffice.org/ - -* Think about _`large documents` made up of multiple subdocument - files. Issues: continuity (`persistent sequences`_ above), - cross-references (`name-to-id mapping file`_ above and `targets in - other documents`_ below), splitting (`document splitting`_ below). - - When writing a book, the author probably wants to split it up into - files, perhaps one per chapter (but perhaps even more detailed). - However, we'd like to be able to have references from one chapter to - another, and have continuous numbering (pages and chapters, as - applicable). Of course, none of this is implemented yet. There has - been some thought put into some aspects; see `the "include" - directive`__ and the `Reference Merging`_ transform below. - - When I was working with SGML in Japan, we had a system where there - was a top-level coordinating file, book.sgml, which contained the - top-level structure of a book: the <book> element, containing the - book <title> and empty component elements (<preface>, <chapter>, - <appendix>, etc.), each with filename attributes pointing to the - actual source for the component. Something like this:: - - <book id="bk01"> - <title>Title of the Book</title> - <preface inrefid="pr01"></preface> - <chapter inrefid="ch01"></chapter> - <chapter inrefid="ch02"></chapter> - <chapter inrefid="ch03"></chapter> - <appendix inrefid="ap01"></appendix> - </book> - - (The "inrefid" attribute stood for "insertion reference ID".) - - The processing system would process each component separately, but - it would recognize and use the book file to coordinate chapter and - page numbering, and keep a persistent ID to (title, page number) - mapping database for cross-references. Docutils could use a similar - system for large-scale, multipart documents. - - __ ../ref/rst/directives.html#including-an-external-document-fragment - - Aahz's idea: - - First the ToC:: - - .. ToC-list:: - Introduction.txt - Objects.txt - Data.txt - Control.txt - - Then a sample use:: - - .. include:: ToC.txt - - As I said earlier in chapter :chapter:`Objects.txt`, the - reference count gets increased every time a binding is made. - - Which produces:: - - As I said earlier in chapter 2, the - reference count gets increased every time a binding is made. - - The ToC in this form doesn't even need to be references to actual - reST documents; I'm simply doing it that way for a minimum of - future-proofing, in case I do want to add the ability to pick up - references within external chapters. - - Perhaps, instead of ToC (which would overload the "contents" - directive concept already in use), we could use "manifest". A - "manifest" directive might associate local reference names with - files:: - - .. manifest:: - intro: Introduction.txt - objects: Objects.txt - data: Data.txt - control: Control.txt - - Then the sample becomes:: - - .. include:: manifest.txt - - As I said earlier in chapter :chapter:`objects`, the - reference count gets increased every time a binding is made. - -* Add support for _`multiple output files`. - -* Add testing for Docutils' front end tools? - -* Publisher: "Ordinary setup" shouldn't requre specific ordering; at - the very least, there ought to be error checking higher up in the - call chain. [Aahz] - - ``Publisher.get_settings`` requires that all components be set up - before it's called. Perhaps the I/O *objects* shouldn't be set, but - I/O *classes*. Then options are set up (``.set_options``), and - ``Publisher.set_io`` (or equivalent code) is called with source & - destination paths, creating the I/O objects. - - Perhaps I/O objects shouldn't be instantiated until required. For - split output, the Writer may be called multiple times, once for each - doctree, and each doctree should have a separate Output object (with - a different path). Is the "Builder" pattern applicable here? - -* Perhaps I/O objects should become full-fledged components (i.e. - subclasses of ``docutils.Component``, as are Readers, Parsers, and - Writers now), and thus have associated option/setting specs and - transforms. - -* Multiple file I/O suggestion from Michael Hudson: use a file-like - object or something you can iterate over to get file-like objects. - -* Add an "--input-language" option & setting? Specify a different - language module for input (bibliographic fields, directives) than - for output. The "--language" option would set both input & output - languages. - -* Auto-generate reference tables for language-dependent features? - Could be generated from the source modules. A special command-line - option could be added to Docutils front ends to do this. (Idea from - Engelbert Gruber.) - -* Enable feedback of some kind from internal decisions, such as - reporting the successful input encoding. Modify runtime settings? - System message? Simple stderr output? - -* Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings. - -* Merge docs/user/latex.txt info into tools.txt and config.txt. - -* Add an "--include file" command-line option (config setting too?), - equivalent to ".. include:: file" as the first line of the doc text? - Especially useful for character entity sets, text transform specs, - boilerplate, etc. - -* Parameterize the Reporter object or class? See the `2004-02-18 - "rest checking and source path"`_ thread. - - .. _2004-02-18 "rest checking and source path": - http://thread.gmane.org/gmane.text.docutils.user/1112 - -* Add a "disable_transforms" setting? And a dummy Writer subclass - that does nothing when its .write() method is called? Would allow - for easy syntax checking. See the `2004-02-18 "rest checking and - source path"`_ thread. - -* Add a generic meta-stylesheet mechanism? An external file could - associate style names ("class" attributes) with specific elements. - Could be generalized to arbitrary output attributes; useful for HTML - & XMLs. Aahz implemented something like this in - sandbox/aahz/Effective/EffMap.py. - -* .. _classes for table cells: - - William Dode suggested that table cells be assigned "class" - attributes by columns, so that stylesheets can affect text - alignment. Unfortunately, there doesn't seem to be a way (in HTML - at least) to leverage the "colspec" elements (HTML "col" tags) by - adding classes to them. The resulting HTML is very verbose:: - - <td class="col1">111</td> - <td class="col2">222</td> - ... - - At the very least, it should be an option. People who don't use it - shouldn't be penalized by increases in their HTML file sizes. - - Table rows could also be assigned classes (like odd/even). That - would be easier to implement. - - How should it be implemented? - - * There could be writer options (column classes & row classes) with - standard values. - - * The table directive could grow some options. Something like - ":cell-classes: col1 col2 col3" (either must match the number of - columns, or repeat to fill?) and ":row-classes: odd even" (repeat - to fill; body rows only, or header rows too?). - - Probably per-table directive options are best. The "class" values - could be used by any writer, and applying such classes to all tables - in a document with writer options is too broad. - -* Add file-specific settings support to config files, like:: - - [file index.txt] - compact-lists: no - - Is this even possible? Should the criterion be the name of the - input file or the output file? - -* The "validator" support added to OptionParser is very similar to - "traits_" in SciPy_. Perhaps something could be done with them? - (Had I known about traits when I was implementing docutils.frontend, - I may have used them instead of rolling my own.) - - .. _traits: http://code.enthought.com/traits/ - .. _SciPy: http://www.scipy.org/ - -* tools/buildhtml.py: Extend the --prune option ("prune" config - setting) to accept file names (generic path) in addition to - directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should - *not* be converted to HTML). - -* Add support for _`plugins`. - -* _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, & - /etc/docutils.conf are read as configuration files. Proposal: allow - ~/.docutils to be a a configuration *directory*, along with - /etc/docutils/ and ./docutils.conf/. Within these directories, - check for config.txt files. We can also have subdirectories here, - for plugins, S5 themes, components (readers/writers/parsers) etc. - - Docutils will continue to support configuration files for backwards - compatibility. - -* Add support for document decorations other than headers & footers? - For example, top/bottom/side navigation bars for web pages. Generic - decorations? - - Seems like a bad idea as long as it isn't independent from the ouput - format (for example, navigation bars are only useful for web pages). - -* docutils_update: Check for a ``Makefile`` in a directory, and run - ``make`` if found? This would allow for variant processing on - specific source files, such as running rst2s5.py instead of - rst2html.py. - -* Add a "disable table of contents" setting? The S5 writer could set - it as a default. Rationale: - - The ``contents`` (table of contents) directive must not be used - [in S5/HTML documents]. It changes the CSS class of headings - and they won't show up correctly in the screen presentation. - - -- `Easy Slide Shows With reStructuredText & S5 - <../user/slide-shows.html>`_ - - -Documentation -============= - -User Docs ---------- - -* Add a FAQ entry about using Docutils (with reStructuredText) on a - server and that it's terribly slow. See the first paragraphs in - <http://article.gmane.org/gmane.text.docutils.user/1584>. - -* Add document about what Docutils has previously been used for - (web/use-cases.txt?). - - -Developer Docs --------------- - -* Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_. - -* Improve the internal module documentation (docstrings in the code). - Specific deficiencies listed below. - - - docutils.parsers.rst.states.State.build_table: data structure - required (including StringList). - - - docutils.parsers.rst.states: more complete documentation of parser - internals. - -* docs/ref/doctree.txt: DTD element structural relationships, - semantics, and attributes. In progress; element descriptions to be - completed. - -* Document the ``pending`` elements, how they're generated and what - they do. - -* Document the transforms (perhaps in docstrings?): how they're used, - what they do, dependencies & order considerations. - -* Document the HTML classes used by html4css1.py. - -* Write an overview of the Docutils architecture, as an introduction - for developers. What connects to what, why, and how. Either update - PEP 258 (see PEPs_ below) or as a separate doc. - -* Give information about unit tests. Maybe as a howto? - -* Document the docutils.nodes APIs. - -* Complete the docs/api/publisher.txt docs. - - -How-Tos -------- - -* Creating Docutils Writers - -* Creating Docutils Readers - -* Creating Docutils Transforms - -* Creating Docutils Parsers - -* Using Docutils as a Library - - -PEPs ----- - -* Complete PEP 258 Docutils Design Specification. - - - Fill in the blanks in API details. - - - Specify the nodes.py internal data structure implementation? - - [Tibs:] Eventually we need to have direct documentation in - there on how it all hangs together - the DTD is not enough - (indeed, is it still meant to be correct? [Yes, it is. - --DG]). - -* Rework PEP 257, separating style from spec from tools, wrt Docutils? - See Doc-SIG from 2001-06-19/20. - - -Python Source Reader -==================== - -General: - -* Analyze Tony Ibbs' PySource code. - -* Analyze Doug Hellmann's HappyDoc project. - -* Investigate how POD handles literate programming. - -* Take the best ideas and integrate them into Docutils. - -Miscellaneous ideas: - -* Ask Python-dev for opinions (GvR for a pronouncement) on special - variables (__author__, __version__, etc.): convenience vs. namespace - pollution. Ask opinions on whether or not Docutils should recognize - & use them. - -* If we can detect that a comment block begins with ``##``, a la - JavaDoc, it might be useful to indicate interspersed section headers - & explanatory text in a module. For example:: - - """Module docstring.""" - - ## - # Constants - # ========= - - a = 1 - b = 2 - - ## - # Exception Classes - # ================= - - class MyException(Exception): pass - - # etc. - -* Should standalone strings also become (module/class) docstrings? - Under what conditions? We want to prevent arbitrary strings from - becomming docstrings of prior attribute assignments etc. Assume - that there must be no blank lines between attributes and attribute - docstrings? (Use lineno of NEWLINE token.) - - Triple-quotes are sometimes used for multi-line comments (such as - commenting out blocks of code). How to reconcile? - -* HappyDoc's idea of using comment blocks when there's no docstring - may be useful to get around the conflict between `additional - docstrings`_ and ``from __future__ import`` for module docstrings. - A module could begin like this:: - - #!/usr/bin/env python - # :Author: Me - # :Copyright: whatever - - """This is the public module docstring (``__doc__``).""" - - # More docs, in comments. - # All comments at the beginning of a module could be - # accumulated as docstrings. - # We can't have another docstring here, because of the - # ``__future__`` statement. - - from __future__ import division - - Using the JavaDoc convention of a doc-comment block beginning with - ``##`` is useful though. It allows doc-comments and implementation - comments. - - .. _additional docstrings: - ../peps/pep-0258.html#additional-docstrings - -* HappyDoc uses an initial comment block to set "parser configuration - values". Do the same thing for Docutils, to set runtime settings on - a per-module basis? I.e.:: - - # Docutils:setting=value - - Could be used to turn on/off function parameter comment recognition - & other marginal features. Could be used as a general mechanism to - augment config files and command-line options (but which takes - precedence?). - -* Multi-file output should be divisible at arbitrary level. - -* Support all forms of ``import`` statements: - - - ``import module``: listed as "module" - - ``import module as alias``: "alias (module)" - - ``from module import identifier``: "identifier (from module)" - - ``from module import identifier as alias``: "alias (identifier - from module)" - - ``from module import *``: "all identifiers (``*``) from module" - -* Have links to colorized Python source files from API docs? And - vice-versa: backlinks from the colorized source files to the API - docs! - -* In summaries, use the first *sentence* of a docstring if the first - line is not followed by a blank line. - - -reStructuredText Parser -======================= - -Also see the `... Or Not To Do?`__ list. - -__ rst/alternatives.html#or-not-to-do - -* Treat enumerated lists that are not arabic and consist of only one - item in a single line as ordinary paragraphs. See - <http://article.gmane.org/gmane.text.docutils.user/2635>. - -* The citation syntax could use some enhancements. See - <http://thread.gmane.org/gmane.text.docutils.user/2499> and - <http://thread.gmane.org/gmane.text.docutils.user/2443>. - -* The current list-recognition logic has too many false positives, as - in :: - - * Aorta - * V. cava superior - * V. cava inferior - - Here ``V.`` is recognized as an enumerator, which leads to - confusion. We need to find a solution that resolves such problems - without complicating the spec to much. - - See <http://thread.gmane.org/gmane.text.docutils.user/2524>. - -* Add indirect links via citation references & footnote references. - Example:: - - `Goodger (2005)`_ is helpful. - - .. _Goodger (2005): [goodger2005]_ - .. [goodger2005] citation text - - See <http://thread.gmane.org/gmane.text.docutils.user/2499>. - -* Allow multiple block quotes, only separated by attributions - (http://article.gmane.org/gmane.text.docutils.devel/2985), e.g.:: - - quote 1 - - ---Attrib 1 - - quote 2 - - ---Attrib 2 - -* Change the specification so that more punctuation is allowed - before/after inline markup start/end string - (http://article.gmane.org/gmane.text.docutils.cvs/3824). - -* Complain about bad URI characters - (http://article.gmane.org/gmane.text.docutils.user/2046) and - disallow internal whitespace - (http://article.gmane.org/gmane.text.docutils.user/2214). - -* Create ``info``-level system messages for unnecessarily - backslash-escaped characters (as in ``"\something"``, rendered as - "something") to allow checking for errors which silently slipped - through. - -* Add (functional) tests for untested roles. - -* Add test for ":figwidth: image" option of "figure" directive. (Test - code needs to check if PIL is available on the system.) - -* Add support for CJK double-width whitespace (indentation) & - punctuation characters (markup; e.g. double-width "*", "-", "+")? - -* Add motivation sections for constructs in spec. - -* Support generic hyperlink references to _`targets in other - documents`? Not in an HTML-centric way, though (it's trivial to say - ``http://www.example.com/doc#name``, and useless in non-HTML - contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG - 2001-08-10. - -* .. _adaptable file extensions: - - In target URLs, it would be useful to not explicitly specify the - file extension. If we're generating HTML, then ".html" is - appropriate; if PDF, then ".pdf"; etc. How about using ".*" to - indicate "choose the most appropriate filename extension"? For - example:: - - .. _Another Document: another.* - - What is to be done for output formats that don't *have* hyperlinks? - For example, LaTeX targeted at print. Hyperlinks may be "called - out", as footnotes with explicit URLs. - - But then there's also LaTeX targeted at PDFs, which *can* have - links. Perhaps a runtime setting for "*" could explicitly provide - the extension, defaulting to the output file's extension. - - Should the system check for existing files? No, not practical. - - Handle documents only, or objects (images, etc.) also? - - If this handles images also, how to differentiate between document - and image links? Element context (within "image")? Which image - extension to use for which document format? Again, a runtime - setting would suffice. - - This may not be just a parser issue; it may need framework support. - - Mailing list threads: `Images in both HTML and LaTeX`__ (especially - `this summary of Felix's objections`__), `more-universal links?`__, - `Output-format-sensitive link targets?`__ - - __ http://thread.gmane.org/gmane.text.docutils.user/1239 - __ http://article.gmane.org/gmane.text.docutils.user/1278 - __ http://thread.gmane.org/gmane.text.docutils.user/1915 - __ http://thread.gmane.org/gmane.text.docutils.user/2438 - -* Implement the header row separator modification to table.el. (Wrote - to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting - support for "=====" header rows. On 2001-08-17 he replied, saying - he'd put it on his to-do list, but "don't hold your breath".) - -* Fix the parser's indentation handling to conform with the stricter - definition in the spec. (Explicit markup blocks should be strict or - forgiving?) - - .. XXX What does this mean? Can you elaborate, David? - -* Make the parser modular. Allow syntax constructs to be added or - disabled at run-time. Subclassing is probably not enough because it - makes it difficult to apply multiple extensions. - -* Generalize the "doctest block" construct (which is overly - Python-centric) to other interactive sessions? "Doctest block" - could be renamed to "I/O block" or "interactive block", and each of - these could also be recognized as such by the parser: - - - Shell sessions:: - - $ cat example1.txt - A block beginning with a "$ " prompt is interpreted as a shell - session interactive block. As with Doctest blocks, the - interactive block ends with the first blank line, and wouldn't - have to be indented. - - - Root shell sessions:: - - # cat example2.txt - A block beginning with a "# " prompt is interpreted as a root - shell session (the user is or has to be logged in as root) - interactive block. Again, the block ends with a blank line. - - Other standard (and unambiguous) interactive session prompts could - easily be added (such as "> " for WinDOS). - - Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread - "docutils feedback"). - -* The "doctest" element should go away. The construct could simply be - a front-end to generic literal blocks. We could immediately (in - 0.4, or 0.5) remove the doctest node from the doctree, but leave the - syntax in reST. The reST parser could represent doctest blocks as - literal blocks with a class attribute. The syntax could be left in - reST for a set period of time. - -* Add support for pragma (syntax-altering) directives. - - Some pragma directives could be local-scope unless explicitly - specified as global/pragma using ":global:" options. - -* Support whitespace in angle-bracketed standalone URLs according to - Appendix E ("Recommendations for Delimiting URI in Context") of `RFC - 2396`_. - - .. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt - -* Use the vertical spacing of the source text to determine the - corresponding vertical spacing of the output? - -* [From Mark Nodine] For cells in simple tables that comprise a - single line, the justification can be inferred according to the - following rules: - - 1. If the text begins at the leftmost column of the cell, - then left justification, ELSE - 2. If the text begins at the rightmost column of the cell, - then right justification, ELSE - 3. Center justification. - - The onus is on the author to make the text unambiguous by adding - blank columns as necessary. There should be a parser setting to - turn off justification-recognition (normally on would be fine). - - Decimal justification? - - All this shouldn't be done automatically. Only when it's requested - by the user, e.g. with something like this:: - - .. table:: - :auto-indent: - - (Table goes here.) - - Otherwise it will break existing documents. - -* Generate a warning or info message for paragraphs which should have - been lists, like this one:: - - 1. line one - 3. line two - -* Generalize the "target-notes" directive into a command-line option - somehow? See docutils-develop 2003-02-13. - -* Allow a "::"-only paragraph (first line, actually) to introduce a - _`literal block without a blank line`? (Idea from Paul Moore.) :: - - :: - This is a literal block - - Is indentation enough to make the separation between a paragraph - which contains just a ``::`` and the literal text unambiguous? - (There's one problem with this concession: If one wants a definition - list item which defines the term "::", we'd have to escape it.) It - would only be reasonable to apply it to "::"-only paragraphs though. - I think the blank line is visually necessary if there's text before - the "::":: - - The text in this paragraph needs separation - from the literal block following:: - This doesn't look right. - -* Add new syntax for _`nested inline markup`? Or extend the parser to - parse nested inline markup somehow? See the `collected notes - <rst/alternatives.html#nested-inline-markup>`__. - -* Drop the backticks from embedded URIs with omitted reference text? - Should the angle brackets be kept in the output or not? :: - - <file_name>_ - - Probably not worth the trouble. - -* Add _`math markup`. We should try for a general solution, that's - applicable to any output format. Using a standard, such as MathML_, - would be best. TeX (or itex_) would be acceptable as a *front-end* - to MathML. See `the culmination of a relevant discussion - <http://article.gmane.org/gmane.text.docutils.user/118>`__. - - Both a directive and an interpreted text role will be necessary (for - each markup). Directive example:: - - .. itex:: - \alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda) - - The same thing inline:: - - The equation in question is :itex:`\alpha_t(i) = P(O_1, O_2, - \dots O_t, q_t = S_i \lambda)`. - - .. _MathML: http://www.w3.org/TR/MathML2/ - .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html - -* How about a syntax for alternative hyperlink behavior, such as "open - in a new window" (as in HTML's ``<a target="_blank">``)? Double - angle brackets might work for inline targets:: - - The `reference docs <<url>>`__ may be handy. - - But what about explicit targets? - - The MoinMoin wiki uses a caret ("^") at the beginning of the URL - ("^" is not a legal URI character). That could work for both inline - and explicit targets:: - - The `reference docs <^url>`__ may be handy. - - .. _name: ^url - - This may be too specific to HTML. It hasn't been requested very - often either. - -* Add an option to add URI schemes at runtime. - -* _`Segmented lists`:: - - : segment : segment : segment - : segment : segment : very long - segment - : segment : segment : segment - - The initial colon (":") can be thought of as a type of bullet - - We could even have segment titles:: - - :: title : title : title - : segment : segment : segment - : segment : segment : segment - - This would correspond well to DocBook's SegmentedList. Output could - be tabular or "name: value" pairs, as described in DocBook's docs. - -* Allow backslash-escaped colons in field names:: - - :Case Study\: Event Handling: This chapter will be dropped. - -* _`footnote spaces`: - - When supplying the command line options - --footnote-references=brackets and --use-latex-footnotes with the - LaTeX writer (which might very well happen when using configuration - files), the spaces in front of footnote references aren't trimmed. - -* Enable grid _`tables inside XML comments`, where "--" ends comments. - I see three implementation possibilities: - - 1. Make the table syntax characters into "table" directive options. - This is the most flexible but most difficult, and we probably - don't need that much flexibility. - - 2. Substitute "~" for "-" with a specialized directive option - (e.g. ":tildes:"). - - 3. Make the standard table syntax recognize "~" as well as "-", even - without a directive option. Individual tables would have to be - internally consistent. - - Directive options are preferable to configuration settings, because - tables are document-specific. A pragma directive would be another - approach, to set the syntax once for a whole document. - - In the meantime, the list-table_ directive is a good replacement for - grid tables inside XML comments. - - .. _list-table: ../ref/rst/directives.html#list-table - -* Generalize docinfo contents (bibliographic fields): remove specific - fields, and have only a single generic "field"? - - -Directives ----------- - -Directives below are often referred to as "module.directive", the -directive function. The "module." is not part of the directive name -when used in a document. - -* Make the _`directive interface` object-oriented - (http://article.gmane.org/gmane.text.docutils.user/1871). - -* Allow for field lists in list tables. See - <http://thread.gmane.org/gmane.text.docutils.devel/3392>. - -* .. _unify tables: - - Unify table implementations and unify options of table directives - (http://article.gmane.org/gmane.text.docutils.user/1857). - -* Allow directives to be added at run-time? - -* Use the language module for directive option names? - -* Add "substitution_only" and "substitution_ok" function attributes, - and automate context checking? - -* Change directive functions to directive classes? Superclass' - ``__init__()`` could handle all the bookkeeping. - -* Implement options or features on existing directives: - - - Add a "name" option to directives, to set an author-supplied - identifier? - - - All directives that produce titled elements should grow implicit - reference names based on the titles. - - - Allow the _`:trim:` option for all directives when they occur in a - substitution definition, not only the unicode_ directive. - - .. _unicode: ../ref/rst/directives.html#unicode-character-codes - - - _`images.figure`: "title" and "number", to indicate a formal - figure? - - - _`parts.sectnum`: "local"?, "refnum" - - A "local" option could enable numbering for sections from a - certain point down, and sections in the rest of the document are - not numbered. For example, a reference section of a manual might - be numbered, but not the rest. OTOH, an all-or-nothing approach - would probably be enough. - - The "sectnum" directive should be usable multiple times in a - single document. For example, in a long document with "chapter" - and "appendix" sections, there could be a second "sectnum" before - the first appendix, changing the sequence used (from 1,2,3... to - A,B,C...). This is where the "local" concept comes in. This part - of the implementation can be left for later. - - A "refnum" option (better name?) would insert reference names - (targets) consisting of the reference number. Then a URL could be - of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow - internal references by number? Allow name-based *and* - number-based ids at the same time, or only one or the other (which - would the table of contents use)? Usage issue: altering the - section structure of a document could render hyperlinks invalid. - - - _`parts.contents`: Add a "suppress" or "prune" option? It would - suppress contents display for sections in a branch from that point - down. Or a new directive, like "prune-contents"? - - Add an option to include topics in the TOC? Another for sidebars? - The "topic" directive could have a "contents" option, or the - "contents" directive" could have an "include-topics" option. See - docutils-develop 2003-01-29. - - - _`parts.header` & _`parts.footer`: Support multiple, named headers - & footers? For example, separate headers & footers for odd, even, - and the first page of a document. - - This may be too specific to output formats which have a notion of - "pages". - - - _`misc.class`: - - - Add a ``:parent:`` option for setting the parent's class - (http://article.gmane.org/gmane.text.docutils.devel/3165). - - - _`misc.include`: - - - Option to select a range of lines? - - - Option to label lines? - - - How about an environment variable, say RSTINCLUDEPATH or - RSTPATH, for standard includes (as in ``.. include:: <name>``)? - This could be combined with a setting/option to allow - user-defined include directories. - - - Add support for inclusion by URL? :: - - .. include:: - :url: http://www.example.org/inclusion.txt - - - _`misc.raw`: add a "destination" option to the "raw" directive? :: - - .. raw:: html - :destination: head - - <link ...> - - It needs thought & discussion though, to come up with a consistent - set of destination labels and consistent behavior. - - And placing HTML code inside the <head> element of an HTML - document is rather the job of a templating system. - - - _`body.sidebar`: Allow internal section structure? Adornment - styles would be independent of the main document. - - That is really complicated, however, and the document model - greatly benefits from its simplicity. - -* Implement directives. Each of the list items below begins with an - identifier of the form, "module_name.directive_function_name". The - directive name itself could be the same as the - directive_function_name, or it could differ. - - - _`html.imagemap` - - It has the disadvantage that it's only easily implementable for - HTML, so it's specific to one output format. - - (For non-HTML writers, the imagemap would have to be replaced with - the image only.) - - - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_. - - - _`parts.citations`: See `Footnote & Citation Gathering`_. - - - _`misc.language`: Specify (= change) the language of a document at - parse time. - - - _`misc.settings`: Set any(?) Docutils runtime setting from within - a document? Needs much thought and discussion. - - - _`misc.gather`: Gather (move, or copy) all instances of a specific - element. A generalization of the "endnotes" & "citations" ideas. - - - Add a custom "directive" directive, equivalent to "role"? For - example:: - - .. directive:: incr - - .. class:: incremental - - .. incr:: - - "``.. incr::``" above is equivalent to "``.. class:: incremental``". - - Another example:: - - .. directive:: printed-links - - .. topic:: Links - :class: print-block - - .. target-notes:: - :class: print-inline - - This acts like macros. The directive contents will have to be - evaluated when referenced, not when defined. - - * Needs a better name? "Macro", "substitution"? - * What to do with directive arguments & options when the - macro/directive is referenced? - - - .. _conditional directives: - - Docutils already has the ability to say "use this content for - Writer X" (via the "raw" directive), but it doesn't have the - ability to say "use this content for any Writer other than X". It - wouldn't be difficult to add this ability though. - - My first idea would be to add a set of conditional directives. - Let's call them "writer-is" and "writer-is-not" for discussion - purposes (don't worry about implemention details). We might - have:: - - .. writer-is:: text-only - - :: - - +----------+ - | SNMP | - +----------+ - | UDP | - +----------+ - | IP | - +----------+ - | Ethernet | - +----------+ - - .. writer-is:: pdf - - .. figure:: protocol_stack.eps - - .. writer-is-not:: text-only pdf - - .. figure:: protocol_stack.png - - This could be an interface to the Filter transform - (docutils.transforms.components.Filter). - - The ideas in `adaptable file extensions`_ above may also be - applicable here. - - SVG's "switch" statement may provide inspiration. - - Here's an example of a directive that could produce multiple - outputs (*both* raw troff pass-through *and* a GIF, for example) - and allow the Writer to select. :: - - .. eqn:: - - .EQ - delim %% - .EN - %sum from i=o to inf c sup i~=~lim from {m -> inf} - sum from i=0 to m sup i% - .EQ - delim off - .EN - - - _`body.example`: Examples; suggested by Simon Hefti. Semantics as - per Docbook's "example"; admonition-style, numbered, reference, - with a caption/title. - - - _`body.index`: Index targets. - - See `Index Entries & Indexes - <./rst/alternatives.html#index-entries-indexes>`__. - - - _`body.literal`: Literal block, possibly "formal" (see `object - numbering and object references`_ above). Possible options: - - - "highlight" a range of lines - - - include only a specified range of lines - - - "number" or "line-numbers" - - - "styled" could indicate that the directive should check for - style comments at the end of lines to indicate styling or - markup. - - Specific derivatives (i.e., a "python-interactive" directive) - could interpret style based on cues, like the ">>> " prompt and - "input()"/"raw_input()" calls. - - See docutils-users 2003-03-03. - - - _`body.listing`: Code listing with title (to be numbered - eventually), equivalent of "figure" and "table" directives. - - - _`colorize.python`: Colorize Python code. Fine for HTML output, - but what about other formats? Revert to a literal block? Do we - need some kind of "alternate" mechanism? Perhaps use a "pending" - transform, which could switch its output based on the "format" in - use. Use a factory function "transformFF()" which returns either - "HTMLTransform()" instance or "GenericTransform" instance? - - If we take a Python-to-HTML pretty-printer and make it output a - Docutils internal doctree (as per nodes.py) instead of HTML, then - each output format's stylesheet (or equivalent) mechanism could - take care of the rest. The pretty-printer code could turn this - doctree fragment:: - - <literal_block xml:space="preserve"> - print 'This is Python code.' - for i in range(10): - print i - </literal_block> - - into something like this ("</>" is end-tag shorthand):: - - <literal_block xml:space="preserve" class="python"> - <keyword>print</> <string>'This is Python code.'</> - <keyword>for</> <identifier>i</> <keyword - >in</> <expression>range(10)</>: - <keyword>print</> <expression>i</> - </literal_block> - - But I'm leaning toward adding a single new general-purpose - element, "phrase", equivalent to HTML's <span>. Here's the - example rewritten using the generic "phrase":: - - <literal_block xml:space="preserve" class="python"> - <phrase class="keyword">print</> <phrase - class="string">'This is Python code.'</> - <phrase class="keyword">for</> <phrase - class="identifier">i</> <phrase class="keyword">in</> <phrase - class="expression">range(10)</>: - <phrase class="keyword">print</> <phrase - class="expression">i</> - </literal_block> - - It's more verbose but more easily extensible and more appropriate - for the case at hand. It allows us to edit style sheets to add - support for new formats, not the Docutils code itself. - - Perhaps a single directive with a format parameter would be - better:: - - .. colorize:: python - - print 'This is Python code.' - for i in range(10): - print i - - But directives can have synonyms for convenience. "format:: - python" was suggested, but "format" seems too generic. - - - _`pysource.usage`: Extract a usage message from the program, - either by running it at the command line with a ``--help`` option - or through an exposed API. [Suggestion for Optik.] - - -Interpreted Text ----------------- - -Interpreted text is entirely a reStructuredText markup construct, a -way to get around built-in limitations of the medium. Some roles are -intended to introduce new doctree elements, such as "title-reference". -Others are merely convenience features, like "RFC". - -All supported interpreted text roles must already be known to the -Parser when they are encountered in a document. Whether pre-defined -in core/client code, or in the document, doesn't matter; the roles -just need to have already been declared. Adding a new role may -involve adding a new element to the DTD and may require extensive -support, therefore such additions should be well thought-out. There -should be a limited number of roles. - -The only place where no limit is placed on variation is at the start, -at the Reader/Parser interface. Transforms are inserted by the Reader -into the Transformer's queue, where non-standard elements are -converted. Once past the Transformer, no variation from the standard -Docutils doctree is possible. - -An example is the Python Source Reader, which will use interpreted -text extensively. The default role will be "Python identifier", which -will be further interpreted by namespace context into <class>, -<method>, <module>, <attribute>, etc. elements (see pysource.dtd), -which will be transformed into standard hyperlink references, which -will be processed by the various Writers. No Writer will need to have -any knowledge of the Python-Reader origin of these elements. - -* Add explicit interpreted text roles for the rest of the implicit - inline markup constructs: named-reference, anonymous-reference, - footnote-reference, citation-reference, substitution-reference, - target, uri-reference (& synonyms). - -* Add directives for each role as well? This would allow indirect - nested markup:: - - This text contains |nested inline markup|. - - .. |nested inline markup| emphasis:: - - nested ``inline`` markup - -* Implement roles: - - - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text - around role contents. - - For example, the following reStructuredText source ... :: - - .. role:: red(raw-formatting) - :prefix: - :html: <font color="red"> - :latex: {\color{red} - :suffix: - :html: </font> - :latex: } - - colored :red:`text` - - ... will yield the following document fragment:: - - <paragraph> - colored - <inline classes="red"> - <raw format="html"> - <font color="red"> - <raw format="latex"> - {\color{red} - <inline classes="red"> - text - <raw format="html"> - </font> - <raw format="latex"> - } - - Possibly without the intermediate "inline" node. - - - "acronym" and "abbreviation": Associate the full text with a short - form. Jason Diamond's description: - - I want to translate ```reST`:acronym:`` into ``<acronym - title='reStructuredText'>reST</acronym>``. The value of the - title attribute has to be defined out-of-band since you can't - parameterize interpreted text. Right now I have them in a - separate file but I'm experimenting with creating a directive - that will use some form of reST syntax to let you define them. - - Should Docutils complain about undefined acronyms or - abbreviations? - - What to do if there are multiple definitions? How to - differentiate between CSS (Content Scrambling System) and CSS - (Cascading Style Sheets) in a single document? David Priest - responds, - - The short answer is: you don't. Anyone who did such a thing - would be writing very poor documentation indeed. (Though I - note that `somewhere else in the docs`__, there's mention of - allowing replacement text to be associated with the - abbreviation. That takes care of the duplicate - acronyms/abbreviations problem, though a writer would be - foolish to ever need it.) - - __ `inline parameter syntax`_ - - How to define the full text? Possibilities: - - 1. With a directive and a definition list? :: - - .. acronyms:: - - reST - reStructuredText - DPS - Docstring Processing System - - Would this list remain in the document as a glossary, or would - it simply build an internal lookup table? A "glossary" - directive could be used to make the intention clear. - Acronyms/abbreviations and glossaries could work together. - - Then again, a glossary could be formed by gathering individual - definitions from around the document. - - 2. Some kind of `inline parameter syntax`_? :: - - `reST <reStructuredText>`:acronym: is `WYSIWYG <what you - see is what you get>`:acronym: plaintext markup. - - .. _inline parameter syntax: - rst/alternatives.html#parameterized-interpreted-text - - 3. A combination of 1 & 2? - - The multiple definitions issue could be handled by establishing - rules of priority. For example, directive-based lookup tables - have highest priority, followed by the first inline definition. - Multiple definitions in directive-based lookup tables would - trigger warnings, similar to the rules of `implicit hyperlink - targets`__. - - __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets - - 4. Using substitutions? :: - - .. |reST| acronym:: reST - :text: reStructuredText - - What do we do for other formats than HTML which do not support - tool tips? Put the full text in parentheses? - - - "figure", "table", "listing", "chapter", "page", etc: See `object - numbering and object references`_ above. - - - "glossary-term": This would establish a link to a glossary. It - would require an associated "glossary-entry" directive, whose - contents could be a definition list:: - - .. glossary-entry:: - - term1 - definition1 - term2 - definition2 - - This would allow entries to be defined anywhere in the document, - and collected (via a "glossary" directive perhaps) at one point. - - -Unimplemented Transforms -======================== - -* _`Footnote & Citation Gathering` - - Collect and move footnotes & citations to the end of a document. - (Separate transforms.) - -* _`Reference Merging` - - When merging two or more subdocuments (such as docstrings), - conflicting references may need to be resolved. There may be: - - * duplicate reference and/or substitution names that need to be made - unique; and/or - * duplicate footnote numbers that need to be renumbered. - - Should this be done before or after reference-resolving transforms - are applied? What about references from within one subdocument to - inside another? - -* _`Document Splitting` - - If the processed document is written to multiple files (possibly in - a directory tree), it will need to be split up. Internal references - will have to be adjusted. - - (HTML only? Initially, yes. Eventually, anything should be - splittable.) - - Ideas: - - - Insert a "destination" attribute into the root element of each - split-out document, containing the path/filename. The Output - object or Writer will recognize this attribute and split out the - files accordingly. Must allow for common headers & footers, - prev/next, breadcrumbs, etc. - - - Transform a single-root document into a document containing - multiple subdocuments, recursively. The content model of the - "document" element would have to change to:: - - <!ELEMENT document - ( (title, subtitle?)?, - decoration?, - (docinfo, transition?)?, - %structure.model;, - document* )> - - (I.e., add the last line -- 0 or more document elements.) - - Let's look at the case of hierarchical (directories and files) - HTML output. Each document element containing further document - elements would correspond to a directory (with an index.html file - for the content preceding the subdocuments). Each document - element containing no subdocuments (i.e., structure model elements - only) corresponds to a concrete file with no directory. - - The natural transform would be to map sections to subdocuments, - but possibly only a given number of levels deep. - -* _`Navigation` - - If a document is split up, each segment will need navigation links: - parent, children (small TOC), previous (preorder), next (preorder). - Part of `Document Splitting`_? - -* _`List of System Messages` - - The ``system_message`` elements are inserted into the document tree, - adjacent to the problems themselves where possible. Some (those - generated post-parse) are kept until later, in - ``document.messages``, and added as a special final section, - "Docutils System Messages". - - Docutils could be made to generate hyperlinks to all known - system_messages and add them to the document, perhaps to the end of - the "Docutils System Messages" section. - - Fred L. Drake, Jr. wrote: - - I'd like to propose that both parse- and transformation-time - messages are included in the "Docutils System Messages" section. - If there are no objections, I can make the change. - - The advantage of the current way of doing things is that parse-time - system messages don't require a transform; they're already in the - document. This is valuable for testing (unit tests, - tools/quicktest.py). So if we do decide to make a change, I think - the insertion of parse-time system messages ought to remain as-is - and the Messages transform ought to move all parse-time system - messages (remove from their originally inserted positions, insert in - System Messages section). - -* _`Index Generation` - - -HTML Writer -=========== - -* Add support for _`multiple stylesheets`. See - <http://thread.gmane.org/gmane.text.docutils.cvs/4336>. - -* Idea for field-list rendering: hanging indent:: - - Field name (bold): First paragraph of field body begins - with the field name inline. - - If the first item of a field body is not a paragraph, - it would begin on the following line. - -* Add more support for <link> elements, especially for navigation - bars. - - The framework does not have a notion of document relationships, so - probably raw.destination_ should be used. - - We'll have framework support for document relationships when support - for `multiple output files`_ is added. The HTML writer could - automatically generate <link> elements then. - - .. _raw.destination: misc.raw_ - -* Base list compaction on the spacing of source list? Would require - parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.) - -* Add a tool tip ("title" attribute?) to footnote back-links - identifying them as such. Text in Docutils language module. - - -PEP/HTML Writer -=============== - -* Remove the generic style information (duplicated from html4css1.css) - from pep.css to avoid redundancy. - - We need support for `multiple stylesheets`_ first, though. - - -LaTeX writer -============ - -* Add an ``--embed-stylesheet`` (and ``--link-stylesheet``) option. - - -HTML SlideShow Writer -===================== - -Add a Writer for presentations, derivative of the HTML Writer. Given -an input document containing one section per slide, the output would -consist of a master document for the speaker, and a slide file (or set -of filess, one (or more) for each slide). Each slide would contain -the slide text (large, stylesheet-controlled) and images, plus "next" -and "previous" links in consistent places. The speaker's master -document would contain a small version of the slide text with -speaker's notes interspersed. The master document could use -``target="whatever"`` to direct links to a separate window on a second -monitor (e.g., a projector). - -Ideas: - -* Base the output on |S5|_. I discovered |S5| a few weeks before it - appeared on Slashdot, after writing most of this section. It turns - out that |S5| does most of what I wanted. - - Chris Liechti has `integrated S5 with the HTML writer - <http://homepage.hispeed.ch/py430/python/index.html#rst2s5>`__. - - .. |S5| replace:: S\ :sup:`5` - .. _S5: http://www.meyerweb.com/eric/tools/s5/ - -Below, "[S5]" indicates that |S5| already implements the feature or -may implement all or part of the feature. "[S5 1.1]" indicates that -|S5| version 1.1 implements the feature (a preview of the 1.1 beta is -available in the `S5 testbed`_). - -.. _S5 testbed: http://meyerweb.com/eric/tools/s5/testbed/ - -Features & issues: - -* [S5 1.1] Incremental slides, where each slide adds to the one before - (ticking off items in a list, delaying display of later items). The - speaker's master document would list each transition in the TOC and - provide links in the content. - - * Use transitions to separate stages. Problem with transitions is - that they can't be used everywhere -- not, for example, within a - list (see the example below). - - * Use a special directive to separate stages. Possible names: - pause, delay, break, cut, continue, suspend, hold, stay, stop. - Should the directive be available in all contexts (and ineffectual - in all but SlideShow context), or added at runtime by the - SlideShow Writer? Probably such a "pause" directive should only - be available for slide shows; slide shows are too much of a - special case to justify adding a directive (and node?) to the - core. - - The directive could accept text content, which would be rendered - while paused but would disappear when the slide is continued (the - text could also be a link to the next slide). In the speaker's - master document, the text "paused:" could appear, prefixed to the - directive text. - - * Use a special directive or class to declare incremental content. - This works best with the S5 ideas. For example:: - - Slide Title - =========== - - .. incremental:: - - * item one - * item two - * item three - - Add an option to make all bullet lists implicitly incremental? - -* Speaker's notes -- how to intersperse? Could use reST comments - (".."), but make them visible in the speaker's master document. If - structure is necessary, we could use a "comment" directive (to avoid - nonsensical DTD changes, the "comment" directive could produce an - untitled topic element). - - The speaker's notes could (should?) be separate from S5's handout - content. - -* The speaker's master document could use frames for easy navigation: - TOC on the left, content on the right. - - - It would be nice if clicking in the TOC frame simultaneously - linked to both the speaker's notes frame and to the slide window, - synchronizing both. Needs JavaScript? - - - TOC would have to be tightly formatted -- minimal indentation. - - - TOC auto-generated, as in the PEP Reader. (What if there already - is a "contents" directive in the document?) - - - There could be another frame on the left (top-left or bottom-left) - containing a single "Next" link, always pointing to the next slide - (synchronized, of course). Also "Previous" link? FF/Rew go to - the beginning of the next/current parent section? First/Last - also? Tape-player-style buttons like ``|<< << < > >> >>|``? - -* [S5] Need to support templating of some kind, for uniform slide - layout. S5 handles this via CSS. - - Build in support for limited features? E.g., top/bottom or - left/right banners, images on each page, background color and/or - image, etc. - -* [S5?] One layout for all slides, or allow some variation? - - While S5 seems to support only one style per HTML file, it's - pretty easy to split a presentation in different files and - insert a hyperlink to the last slide of the first part and load - the second part by a click on it. - - -- Chris Liechti - -* For nested sections, do we show the section's ancestry on each - slide? Optional? No -- leave the implementation to someone who - wants it. - -* [S5] Stylesheets for slides: - - - Tweaked for different resolutions, 1024x768 etc. - - Some layout elements have fixed positions. - - Text must be quite large. - - Allow 10 lines of text per slide? 15? - - Title styles vary by level, but not so much? - -* [not required with S5.] Need a transform to number slides for - output filenames?, and for hyperlinks? - -* Directive to begin a new, untitled (blank) slide? - -* Directive to begin a new slide, continuation, using the same title - as the previous slide? (Unnecessary?) - -* Have a timeout on incremental items, so the colour goes away after 1 - second. - -Here's an example that I was hoping to show at PyCon DC 2005:: - - ======================== - The Docutils SlideShow - ======================== - - Welcome To The Docutils SlideShow! - ================================== - - .. pause:: - - David Goodger - - goodger@python.org - - http://python.net/~goodger - - .. (introduce yourself) - - Hi, I'm David Goodger from Montreal, Canada. - - I've been working on Docutils since 2000. - Time flies! - - .. pause:: - - Docutils - - http://docutils.sourceforge.net - - .. I also volunteer as a Python Enhancement Proposal (or PEP) - editor. - - .. SlideShow is a new feature of Docutils. This presentation was - written using the Docutils SlideShow system. The slides you - are seeing are HTML, rendered by a standard Mozilla Firefox - browser. - - - The Docutils SlideShow System - ============================= - - .. The Docutils SlideShow System provides - - Easy and open presentations. - - - Features - ======== - - * reStructuredText-based input files. - - .. reStructuredText is a what-you-see-is-what-you-get - plaintext format. Easy to read & write, non-proprietary, - editable in your favourite text editor. - - .. Parsers for other markup languages can be added to Docutils. - In the future, I hope some are. - - .. pause:: ... - - * Stylesheet-driven HTML output. - - .. The format of all elements of the output slides are - controlled by CSS (cascading stylesheets). - - .. pause:: ... - - * Works with any modern browser. - - .. that supports CSS, frames, and JavaScript. - Tested with Mozilla Firefox. - - .. pause:: ... - - * Works on any OS. - - - Etc. - ==== - - That's as far as I got, but you get the idea... - - -Front-End Tools -=============== - -* What about if we don't know which Reader and/or Writer we are - going to use? If the Reader/Writer is specified on the - command-line? (Will this ever happen?) - - Perhaps have different types of front ends: - - a) _`Fully qualified`: Reader and Writer are hard-coded into the - front end (e.g. ``pep2html [options]``, ``pysource2pdf - [options]``). - - b) _`Partially qualified`: Reader is hard-coded, and the Writer is - specified a sub-command (e.g. ``pep2 html [options]``, - ``pysource2 pdf [options]``). The Writer is known before option - processing happens, allowing the OptionParser to be built - dynamically. Alternatively, the Writer could be hard-coded and - the Reader specified as a sub-command (e.g. ``htmlfrom pep - [options]``). - - c) _`Unqualified`: Reader and Writer are specified as subcommands - (e.g. ``publish pep html [options]``, ``publish pysource pdf - [options]``). A single front end would be sufficient, but - probably only useful for testing purposes. - - d) _`Dynamic`: Reader and/or Writer are specified by options, with - defaults if unspecified (e.g. ``publish --writer pdf - [options]``). Is this possible? The option parser would have - to be told about new options it needs to handle, on the fly. - Component-specific options would have to be specified *after* - the component-specifying option. - - Allow common options before subcommands, as in CVS? Or group all - options together? In the case of the `fully qualified`_ - front ends, all the options will have to be grouped together - anyway, so there's no advantage (we can't use it to avoid - conflicts) to splitting common and component-specific options - apart. - -* Parameterize help text & defaults somehow? Perhaps a callback? Or - initialize ``settings_spec`` in ``__init__`` or ``init_options``? - -* Disable common options that don't apply? - -* Add ``--section-numbering`` command line option. The "sectnum" - directive should override the ``--no-section-numbering`` command - line option then. - -* Create a single dynamic_ or unqualified_ front end that can be - installed? - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/dev/website.txt b/docutils/docs/dev/website.txt deleted file mode 100644 index 193e9c0f2..000000000 --- a/docutils/docs/dev/website.txt +++ /dev/null @@ -1,46 +0,0 @@ -=================== - Docutils Web Site -=================== - -:Author: David Goodger; open to all Docutils developers -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -The Docutils web site, <http://docutils.sourceforge.net/>, is -maintained automatically by the ``docutils-update`` script, run as an -hourly cron job on shell.berlios.de (by user "felixwiemann"). The -script will process any .txt file which is newer than the -corresponding .html file in the project's web directory on -shell.berlios.de (``/home/groups/docutils/htdocs/aux/htdocs/``) and -upload the changes to the web site at SourceForge. For a new .txt -file, just SSH to ``<username>@shell.berlios.de`` and :: - - cd /home/groups/docutils/htdocs/aux/htdocs/ - touch filename.html - chmod g+w filename.html - sleep 1 - touch filename.txt - -The script will take care of the rest within an hour. Thereafter -whenever the .txt file is modified (checked in to SVN), the .html will -be regenerated automatically. - -After adding directories to SVN, allow the script to run once to -create the directories in the filesystem before preparing for HTML -processing as described above. - -The docutils-update__ script is located at -``sandbox/infrastructure/docutils-update``. - -__ http://docutils.sf.net/sandbox/infrastructure/docutils-update - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/howto/html-stylesheets.txt b/docutils/docs/howto/html-stylesheets.txt deleted file mode 100644 index 9369f2d3c..000000000 --- a/docutils/docs/howto/html-stylesheets.txt +++ /dev/null @@ -1,76 +0,0 @@ -============================================== - Writing HTML (CSS) Stylesheets for Docutils_ -============================================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. _Docutils: http://docutils.sourceforge.net/ - - -The look of Docutils' HTML output is customizable via a CSS -stylesheet. The default stylesheet is called ``html4css1.css`` and -can be found in the ``writers/html4css1/`` directory of the Docutils -installation. Use the command ``rst2html.py --help`` and look at the -description of the ``--stylesheet-path`` command-line option for the -exact machine-specific location. - -To customize the stylesheet, first copy ``html4css1.css`` to the same -place as your output HTML files will go. Next, place a new file -(e.g. called ``my-docutils.css``) in the same directory and use the -following template:: - - /* - :Author: Your Name - :Contact: Your Email Address - :Copyright: This stylesheet has been placed in the public domain. - - Stylesheet for use with Docutils. [Optionally place a more - detailed description here.] - */ - - @import url(html4css1.css); - - /* Your customizations go here. For example: */ - - h1, h2, h3, h4, h5, h6, p.topic-title { - font-family: sans-serif } - -For help on the CSS syntax, please see `the WDG's guide to Cascading -Style Sheets`__ and, in particular, their `list of CSS1 properties`__. - -__ http://www.htmlhelp.com/reference/css/ -__ http://www.htmlhelp.com/reference/css/all-properties.html - -It is important that you do not edit a copy of ``html4css1.css`` -directly because ``html4css1.css`` is frequently updated with each new -release of Docutils. - -Also make sure that you import ``html4css1.css`` (using "``@import -url(html4css1.css);``") because the definitions contained in the -default stylesheet are required for correct rendering (margins, -alignment, etc.). - -If you think your stylesheet is fancy and you would like to let others -benefit from your efforts, you are encouraged to post the stylesheet -to the Docutils-users_ mailing list. We can upload it to the -`Docutils repository`__ if you would like us to do so. - -If you decide to share you stylesheet with other users of Docutils, -please keep website-specific customizations not applicable to -Docutils' HTML code in a separate stylesheet. - -.. _Docutils-users: ../user/mailing-lists.html#docutils-users -__ http://docutils.sourceforge.net/sandbox/stylesheets/ - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/howto/i18n.txt b/docutils/docs/howto/i18n.txt deleted file mode 100644 index 4a5b1de5a..000000000 --- a/docutils/docs/howto/i18n.txt +++ /dev/null @@ -1,191 +0,0 @@ -================================ - Docutils_ Internationalization -================================ - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - - -.. contents:: - - -This document describes the internationalization facilities of the -Docutils_ project. `Introduction to i18n`_ by Tomohiro KUBOTA is a -good general reference. "Internationalization" is often abbreviated -as "i18n": "i" + 18 letters + "n". - -.. Note:: - - The i18n facilities of Docutils should be considered a "first - draft". They work so far, but improvements are welcome. - Specifically, standard i18n facilities like "gettext" have yet to - be explored. - -Docutils is designed to work flexibly with text in multiple languages -(one language at a time). Language-specific features are (or should -be [#]_) fully parameterized. To enable a new language, two modules -have to be added to the project: one for Docutils itself (the -`Docutils Language Module`_) and one for the reStructuredText parser -(the `reStructuredText Language Module`_). - -.. [#] If anything in Docutils is insufficiently parameterized, it - should be considered a bug. Please report bugs to the Docutils - project bug tracker on SourceForge at - http://sourceforge.net/tracker/?group_id=38414&atid=422030. - -.. _Docutils: http://docutils.sourceforge.net/ -.. _Introduction to i18n: - http://www.debian.org/doc/manuals/intro-i18n/ - - -Language Module Names -===================== - -Language modules are named using a case-insensitive language -identifier as defined in `RFC 1766`_, converting hyphens to -underscores [#]_. A typical language identifier consists of a -2-letter language code from `ISO 639`_ (3-letter codes can be used if -no 2-letter code exists; RFC 1766 is currently being revised to allow -3-letter codes). The language identifier can have an optional subtag, -typically for variations based on country (from `ISO 3166`_ 2-letter -country codes). If no language identifier is specified, the default -is "en" for English. Examples of module names include ``en.py``, -``fr.py``, ``ja.py``, and ``pt_br.py``. - -.. [#] Subtags are separated from primary tags by underscores instead - of hyphens, to conform to Python naming rules. - -.. _RFC 1766: http://www.faqs.org/rfcs/rfc1766.html -.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html -.. _ISO 3166: http://www.iso.ch/iso/en/prods-services/iso3166ma/ - 02iso-3166-code-lists/index.html - - -Python Code -=========== - -All Python code in Docutils will be ASCII-only. In language modules, -Unicode-escapes will have to be used for non-ASCII characters. -Although it may be possible for some developers to store non-ASCII -characters directly in strings, it will cause problems for other -developers whose locales are set up differently. - -`PEP 263`_ introduces source code encodings to Python modules, -implemented beginning in Python 2.3. Until PEP 263 is fully -implemented as a well-established convention, proven robust in daily -use, and the tools (editors, CVS, email, etc.) recognize this -convention, Docutils shall remain conservative. - -As mentioned in the note above, developers are invited to explore -"gettext" and other i18n technologies. - -.. _PEP 263: http://www.python.org/peps/pep-0263.html - - -Docutils Language Module -======================== - -Modules in ``docutils/languages`` contain language mappings for -markup-independent language-specific features of Docutils. To make a -new language module, just copy the ``en.py`` file, rename it with the -code for your language (see `Language Module Names`_ above), and -translate the terms as described below. - -Each Docutils language module contains three module attributes: - -``labels`` - This is a mapping of node class names to language-dependent - boilerplate label text. The label text is used by Writer - components when they encounter document tree elements whose class - names are the mapping keys. - - The entry values (*not* the keys) should be translated to the - target language. - -``bibliographic_fields`` - This is a mapping of language-dependent field names (converted to - lower case) to canonical field names (keys of - ``DocInfo.biblio_notes`` in ``docutils.transforms.frontmatter``). - It is used when transforming bibliographic fields. - - The keys should be translated to the target language. - -``author_separators`` - This is a list of strings used to parse the 'Authors' - bibliographic field. They separate individual authors' names, and - are tried in order (i.e., earlier items take priority, and the - first item that matches wins). The English-language module - defines them as ``[';', ',']``; semi-colons can be used to - separate names like "Arthur Pewtie, Esq.". - - Most languages won't have to "translate" this list. - - -reStructuredText Language Module -================================ - -Modules in ``docutils/parsers/rst/languages`` contain language -mappings for language-specific features of the reStructuredText -parser. To make a new language module, just copy the ``en.py`` file, -rename it with the code for your language (see `Language Module -Names`_ above), and translate the terms as described below. - -Each reStructuredText language module contains two module attributes: - -``directives`` - This is a mapping from language-dependent directive names to - canonical directive names. The canonical directive names are - registered in ``docutils/parsers/rst/directives/__init__.py``, in - ``_directive_registry``. - - The keys should be translated to the target language. Synonyms - (multiple keys with the same values) are allowed; this is useful - for abbreviations. - -``roles`` - This is a mapping language-dependent role names to canonical role - names for interpreted text. The canonical directive names are - registered in ``docutils/parsers/rst/states.py``, in - ``Inliner._interpreted_roles`` (this may change). - - The keys should be translated to the target language. Synonyms - (multiple keys with the same values) are allowed; this is useful - for abbreviations. - - -Testing the Language Modules -============================ - -Whenever a new language module is added or an existing one modified, -the unit tests should be run. The test modules can be found in the -docutils/test directory from CVS_ or from the `latest CVS snapshot`_. - -The ``test_language.py`` module can be run as a script. With no -arguments, it will test all language modules. With one or more -language codes, it will test just those languages. For example:: - - $ python test_language.py en - .. - ---------------------------------------- - Ran 2 tests in 0.095s - - OK - -Use the "alltests.py" script to run all test modules, exhaustively -testing the parser and other parts of the Docutils system. - -.. _CVS: http://sourceforge.net/cvs/?group_id=38414 -.. _latest CVS snapshot: http://docutils.sf.net/docutils-snapshot.tgz - - -Submitting the Language Modules -=============================== - -If you do not have CVS write access and want to contribute your -language modules, feel free to submit them at the `SourceForge patch -tracker`__. - -__ http://sourceforge.net/tracker/?group_id=38414&atid=422032 diff --git a/docutils/docs/howto/rst-directives.txt b/docutils/docs/howto/rst-directives.txt deleted file mode 100644 index 6210940c8..000000000 --- a/docutils/docs/howto/rst-directives.txt +++ /dev/null @@ -1,399 +0,0 @@ -====================================== - Creating reStructuredText Directives -====================================== - -:Authors: Dethe Elza, David Goodger -:Contact: delza@enfoldingsystems.com -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -Directives are the primary extension mechanism of reStructuredText. -This document aims to make the creation of new directives as easy and -understandable as possible. There are only a couple of -reStructuredText-specific features the developer needs to know to -create a basic directive. - -The syntax of directives is detailed in the `reStructuredText Markup -Specification`_, and standard directives are described in -`reStructuredText Directives`_. - -Directives are a reStructuredText markup/parser concept. There is no -"directive" element, no single element that corresponds exactly to the -concept of directives. Instead, choose the most appropriate elements -from the existing Docutils elements. Directives build structures -using the existing building blocks. See `The Docutils Document Tree`_ -and the ``docutils.nodes`` module for more about the building blocks -of Docutils documents. - -.. _reStructuredText Markup Specification: - ../ref/rst/restructuredtext.html#directives -.. _reStructuredText Directives: ../ref/rst/directives.html -.. _The Docutils Document Tree: ../ref/doctree.html - - -.. contents:: Table of Contents - - -Define the Directive Function -============================= - -The directive function does any processing that the directive -requires. This may require the use of other parts of the -reStructuredText parser. This is where the directive actually *does* -something. - -The directive implementation itself is a callback function whose -signature is as follows:: - - def directive_fn(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - code... - - # Set function attributes: - directive_fn.arguments = ... - directive_fn.options = ... - direcitve_fn.content = ... - -Function attributes are described below (see `Specify Directive -Arguments, Options, and Content`_). The directive function parameters -are as follows: - -- ``name`` is the directive type or name. - -- ``arguments`` is a list of positional arguments, as specified in the - ``arguments`` function attribute. - -- ``options`` is a dictionary mapping option names to values. The - options handled by a directive function are specified in the - ``options`` function attribute. - -- ``content`` is a list of strings, the directive content. Use the - ``content`` function attribute to allow directive content. - -- ``lineno`` is the line number of the first line of the directive. - -- ``content_offset`` is the line offset of the first line of the - content from the beginning of the current input. Used when - initiating a nested parse. - -- ``block_text`` is a string containing the entire directive. Include - it as the content of a literal block in a system message if there is - a problem. - -- ``state`` is the state which called the directive function. - -- ``state_machine`` is the state machine which controls the state - which called the directive function. - -Directive functions return a list of nodes which will be inserted into -the document tree at the point where the directive was encountered. -This can be an empty list if there is nothing to insert. For ordinary -directives, the list must contain body elements or structural -elements. Some directives are intended specifically for substitution -definitions, and must return a list of ``Text`` nodes and/or inline -elements (suitable for inline insertion, in place of the substitution -reference). Such directives must verify substitution definition -context, typically using code like this:: - - if not isinstance(state, states.SubstitutionDef): - error = state_machine.reporter.error( - 'Invalid context: the "%s" directive can only be used ' - 'within a substitution definition.' % (name), - nodes.literal_block(block_text, block_text), line=lineno) - return [error] - - -Specify Directive Arguments, Options, and Content -================================================= - -Function attributes are interpreted by the directive parser (from the -``docutils.parsers.rst.states.Body.run_directive()`` method). If -unspecified, directive function attributes are assumed to have the -value ``None``. Three directive function attributes are recognized: - -- ``arguments``: A 3-tuple specifying the expected positional - arguments, or ``None`` if the directive has no arguments. The 3 - items in the tuple are: - - 1. The number of required arguments. - 2. The number of optional arguments. - 3. A boolean, indicating if the final argument may contain whitespace. - - Arguments are normally single whitespace-separated words. The final - argument may contain whitespace when indicated by the value 1 (True) - for the third item in the argument spec tuple. In this case, the - final argument in the ``arguments`` parameter to the directive - function will contain spaces and/or newlines, preserved from the - input text. - - If the form of the arguments is more complex, specify only one - argument (either required or optional) and indicate that final - whitespace is OK (1/True); the client code must do any - context-sensitive parsing. - -- ``options``: The option specification. ``None`` or an empty dict - implies no options to parse. - - An option specification must be defined detailing the options - available to the directive. An option spec is a mapping of option - name to conversion function; conversion functions are applied to - each option value to check validity and convert them to the expected - type. Python's built-in conversion functions are often usable for - this, such as ``int``, ``float``, and ``bool`` (included in Python - from version 2.2.1). Other useful conversion functions are included - in the ``docutils.parsers.rst.directives`` package (in the - ``__init__.py`` module): - - - ``flag``: For options with no option arguments. Checks for an - argument (raises ``ValueError`` if found), returns ``None`` for - valid flag options. - - - ``unchanged_required``: Returns the text argument, unchanged. - Raises ``ValueError`` if no argument is found. - - - ``unchanged``: Returns the text argument, unchanged. Returns an - empty string ("") if no argument is found. - - - ``path``: Returns the path argument unwrapped (with newlines - removed). Raises ``ValueError`` if no argument is found. - - - ``uri``: Returns the URI argument with whitespace removed. Raises - ``ValueError`` if no argument is found. - - - ``nonnegative_int``: Checks for a nonnegative integer argument, - and raises ``ValueError`` if not. - - - ``class_option``: Converts the argument into an ID-compatible - string and returns it. Raises ``ValueError`` if no argument is - found. - - - ``unicode_code``: Convert a Unicode character code to a Unicode - character. - - - ``single_char_or_unicode``: A single character is returned as-is. - Unicode characters codes are converted as in ``unicode_code``. - - - ``single_char_or_whitespace_or_unicode``: As with - ``single_char_or_unicode``, but "tab" and "space" are also - supported. - - - ``positive_int``: Converts the argument into an integer. Raises - ValueError for negative, zero, or non-integer values. - - - ``positive_int_list``: Converts a space- or comma-separated list - of integers into a Python list of integers. Raises ValueError for - non-positive-integer values. - - - ``encoding``: Verfies the encoding argument by lookup. Raises - ValueError for unknown encodings. - - A further utility function, ``choice``, is supplied to enable - options whose argument must be a member of a finite set of possible - values. A custom conversion function must be written to use it. - For example:: - - from docutils.parsers.rst import directives - - def yesno(argument): - return directives.choice(argument, ('yes', 'no')) - - For example, here is an option spec for a directive which allows two - options, "name" and "value", each with an option argument:: - - directive_fn.options = {'name': unchanged, 'value': int} - -- ``content``: A boolean; true if content is allowed. Directive - functions must handle the case where content is required but not - present in the input text (an empty content list will be supplied). - -The final step of the ``run_directive()`` method is to call the -directive function itself. - - -Register the Directive -====================== - -If the directive is a general-use addition to the Docutils core, it -must be registered with the parser and language mappings added: - -1. Register the new directive using its canonical name in - ``docutils/parsers/rst/directives/__init__.py``, in the - ``_directive_registry`` dictionary. This allows the - reStructuredText parser to find and use the directive. - -2. Add an entry to the ``directives`` dictionary in - ``docutils/parsers/rst/languages/en.py`` for the directive, mapping - the English name to the canonical name (both lowercase). Usually - the English name and the canonical name are the same. - -3. Update all the other language modules as well. For languages in - which you are proficient, please add translations. For other - languages, add the English directive name plus "(translation - required)". - -If the directive is application-specific, use the -``register_directive`` function:: - - from docutils.parsers.rst import directives - directives.register_directive(directive_name, directive_function) - - -Examples -======== - -For the most direct and accurate information, "Use the Source, Luke!". -All standard directives are documented in `reStructuredText -Directives`_, and the source code implementing them is located in the -``docutils/parsers/rst/directives`` package. The ``__init__.py`` -module contains a mapping of directive name to module & function name. -Several representative directives are described below. - - -Admonitions ------------ - -Admonition directives, such as "note" and "caution", are quite simple. -They have no directive arguments or options. Admonition directive -content is interpreted as ordinary reStructuredText. The directive -function simply hands off control to a generic directive function:: - - def note(*args): - return admonition(nodes.note, *args) - - attention.content = 1 - -Note that the only thing distinguishing the various admonition -directives is the element (node class) generated. In the code above, -the node class is passed as the first argument to the generic -directive function (early version), where the actual processing takes -place:: - - def admonition(node_class, name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - text = '\n'.join(content) - admonition_node = node_class(text) - if text: - state.nested_parse(content, content_offset, admonition_node) - return [admonition_node] - else: - warning = state_machine.reporter.warning( - 'The "%s" admonition is empty; content required.' - % (name), '', - nodes.literal_block(block_text, block_text), line=lineno) - return [warning] - -Three things are noteworthy in the function above: - -1. The ``admonition_node = node_class(text)`` line creates the wrapper - element, using the class passed in from the initial (stub) - directive function. - -2. The call to ``state.nested_parse()`` is what does the actual - processing. It parses the directive content and adds any generated - elements as child elements of ``admonition_node``. - -3. If there was no directive content, a warning is generated and - returned. The call to ``state_machine.reporter.warning()`` - includes a literal block containing the entire directive text - (``block_text``) and the line (``lineno``) of the top of the - directive. - - -"image" -------- - -The "image" directive is used to insert a picture into a document. -This directive has one argument, the path to the image file, and -supports several options. There is no directive content. Here's an -early version of the image directive function:: - - def image(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - reference = directives.uri(arguments[0]) - options['uri'] = reference - image_node = nodes.image(block_text, **options) - return [image_node] - - image.arguments = (1, 0, 1) - image.options = {'alt': directives.unchanged, - 'height': directives.nonnegative_int, - 'width': directives.nonnegative_int, - 'scale': directives.nonnegative_int, - 'align': align} - -Several things are noteworthy in the code above: - -1. The "image" directive requires a single argument, which is allowed - to contain whitespace (see the argument spec above, - ``image.arguments = (1, 0, 1)``). This is to allow for long URLs - which may span multiple lines. The first line of the ``image`` - function joins the URL, discarding any embedded whitespace. - -2. The reference is added to the ``options`` dictionary under the - "uri" key; this becomes an attribute of the ``nodes.image`` element - object. Any other attributes have already been set explicitly in - the source text. - -3. The "align" option depends on the following definitions (which - actually occur earlier in the source code):: - - align_values = ('top', 'middle', 'bottom', 'left', 'center', - 'right') - - def align(argument): - return directives.choice(argument, align_values) - - -"contents" ----------- - -The "contents" directive is used to insert an auto-generated table of -contents (TOC) into a document. It takes one optional argument, a -title for the TOC. If no title is specified, a default title is used -instead. The directive also handles several options. Here's an early -version of the code:: - - def contents(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Table of contents.""" - if arguments: - title_text = arguments[0] - text_nodes, messages = state.inline_text(title_text, lineno) - title = nodes.title(title_text, '', *text_nodes) - else: - messages = [] - title = None - pending = nodes.pending(parts.Contents, {'title': title}, - block_text) - pending.details.update(options) - state_machine.document.note_pending(pending) - return [pending] + messages - - contents.arguments = (0, 1, 1) - contents.options = {'depth': directives.nonnegative_int, - 'local': directives.flag, - 'backlinks': backlinks} - -Aspects of note include: - -1. The ``contents.arguments = (0, 1, 1)`` function attribute specifies - a single, *optional* argument. If no argument is present, the - ``arguments`` parameter to the directive function will be an empty - list. - -2. If an argument *is* present, its text is passed to - ``state.inline_text()`` for parsing. Titles may contain inline - markup, such as emphasis or inline literals. - -3. The table of contents is not generated right away. Typically, a - TOC is placed near the beginning of a document, and is a summary or - outline of the section structure of the document. The entire - document must already be processed before a summary can be made. - This directive leaves a ``nodes.pending`` placeholder element in - the document tree, marking the position of the TOC and including a - ``details`` internal attribute containing all the directive - options, effectively communicating the options forward. The actual - table of contents processing is performed by a transform, - ``docutils.transforms.parts.Contents``, after the rest of the - document has been parsed. diff --git a/docutils/docs/howto/rst-roles.txt b/docutils/docs/howto/rst-roles.txt deleted file mode 100644 index f8ce08bca..000000000 --- a/docutils/docs/howto/rst-roles.txt +++ /dev/null @@ -1,228 +0,0 @@ -================================================== - Creating reStructuredText Interpreted Text Roles -================================================== - -:Authors: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -Interpreted text roles are an extension mechanism for inline markup in -reStructuredText. This document aims to make the creation of new -roles as easy and understandable as possible. - -Standard roles are described in `reStructuredText Interpreted Text -Roles`_. See the `Interpreted Text`_ section in the `reStructuredText -Markup Specification`_ for syntax details. - -.. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html -.. _Interpreted Text: - ../ref/rst/restructuredtext.html#interpreted-text -.. _reStructuredText Markup Specification: - ../ref/rst/restructuredtext.html - - -.. contents:: - - -Define the Role Function -======================== - -The role function creates and returns inline elements (nodes) and does -any additional processing required. Its signature is as follows:: - - def role_fn(name, rawtext, text, lineno, inliner, - options={}, content=[]): - code... - - # Set function attributes for customization: - role_fn.options = ... - role_fn.content = ... - -Function attributes are described below (see `Specify Role Function -Options and Content`_). The role function parameters are as follows: - -* ``name``: The local name of the interpreted role, the role name - actually used in the document. - -* ``rawtext``: A string containing the enitre interpreted text input, - including the role and markup. Return it as a ``problematic`` node - linked to a system message if a problem is encountered. - -* ``text``: The interpreted text content. - -* ``lineno``: The line number where the interpreted text begins. - -* ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that - called role_fn. It contains the several attributes useful for error - reporting and document tree access. - -* ``options``: A dictionary of directive options for customization - (from the `"role" directive`_), to be interpreted by the role - function. Used for additional attributes for the generated elements - and other functionality. - -* ``content``: A list of strings, the directive content for - customization (from the `"role" directive`_). To be interpreted by - the role function. - -Role functions return a tuple of two values: - -* A list of nodes which will be inserted into the document tree at the - point where the interpreted role was encountered (can be an empty - list). - -* A list of system messages, which will be inserted into the document tree - immediately after the end of the current block (can also be empty). - - -Specify Role Function Options and Content -========================================= - -Function attributes are for customization, and are interpreted by the -`"role" directive`_. If unspecified, role function attributes are -assumed to have the value ``None``. Two function attributes are -recognized: - -- ``options``: The option specification. All role functions - implicitly support the "class" option, unless disabled with an - explicit ``{'class': None}``. - - An option specification must be defined detailing the options - available to the "role" directive. An option spec is a mapping of - option name to conversion function; conversion functions are applied - to each option value to check validity and convert them to the - expected type. Python's built-in conversion functions are often - usable for this, such as ``int``, ``float``, and ``bool`` (included - in Python from version 2.2.1). Other useful conversion functions - are included in the ``docutils.parsers.rst.directives`` package. - For further details, see `Creating reStructuredText Directives`_. - -- ``content``: A boolean; true if "role" directive content is allowed. - Role functions must handle the case where content is required but - not supplied (an empty content list will be supplied). - - As of this writing, no roles accept directive content. - -Note that unlike directives, the "arguments" function attribute is not -supported for role customization. Directive arguments are handled by -the "role" directive itself. - -.. _"role" directive: ../ref/rst/directives.html#role -.. _Creating reStructuredText Directives: - rst-directives.html#specify-directive-arguments-options-and-content - - -Register the Role -================= - -If the role is a general-use addition to the Docutils core, it must be -registered with the parser and language mappings added: - -1. Register the new role using the canonical name:: - - from docutils.parsers.rst import roles - roles.register_canonical_role(name, role_function) - - This code is normally placed immediately after the definition of - the role funtion. - -2. Add an entry to the ``roles`` dictionary in - ``docutils/parsers/rst/languages/en.py`` for the role, mapping the - English name to the canonical name (both lowercase). Usually the - English name and the canonical name are the same. Abbreviations - and other aliases may also be added here. - -3. Update all the other language modules as well. For languages in - which you are proficient, please add translations. For other - languages, add the English role name plus "(translation required)". - -If the role is application-specific, use the ``register_local_role`` -function:: - - from docutils.parsers.rst import roles - roles.register_local_role(name, role_function) - - -Examples -======== - -For the most direct and accurate information, "Use the Source, Luke!". -All standard roles are documented in `reStructuredText Interpreted -Text Roles`_, and the source code implementing them is located in the -``docutils/parsers/rst/roles.py`` module. Several representative -roles are described below. - - -Generic Roles -------------- - -Many roles simply wrap a given element around the text. There's a -special helper function, ``register_generic_role``, which generates a -role function from the canonical role name and node class:: - - register_generic_role('emphasis', nodes.emphasis) - -For the implementation of ``register_generic_role``, see the -``docutils.parsers.rst.roles`` module. - - -RFC Reference Role ------------------- - -This role allows easy references to RFCs_ (Request For Comments -documents) by automatically providing the base URL, -http://www.faqs.org/rfcs/, and appending the RFC document itself -(rfcXXXX.html, where XXXX is the RFC number). For example:: - - See :RFC:`2822` for information about email headers. - -This is equivalent to:: - - See `RFC 2822`__ for information about email headers. - - __ http://www.faqs.org/rfcs/rfc2822.html - -Here is the implementation of the role:: - - def rfc_reference_role(role, rawtext, text, lineno, inliner, - options={}, content=[]): - try: - rfcnum = int(text) - if rfcnum <= 0: - raise ValueError - except ValueError: - msg = inliner.reporter.error( - 'RFC number must be a number greater than or equal to 1; ' - '"%s" is invalid.' % text, line=lineno) - prb = inliner.problematic(rawtext, rawtext, msg) - return [prb], [msg] - # Base URL mainly used by inliner.rfc_reference, so this is correct: - ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum - set_classes(options) - node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref, - **options) - return [node], [] - - register_canonical_role('rfc-reference', rfc_reference_role) - -Noteworthy in the code above are: - -1. The interpreted text itself should contain the RFC number. The - ``try`` clause verifies by converting it to an integer. If the - conversion fails, the ``except`` clause is executed: a system - message is generated, the entire interpreted text construct (in - ``rawtext``) is wrapped in a ``problematic`` node (linked to the - system message), and the two are returned. - -2. The RFC reference itself is constructed from a stock URI, set as - the "refuri" attribute of a "reference" element. - -3. The ``options`` function parameter, a dictionary, may contain a - "class" customization attribute; it is interpreted and replaced - with a "classes" attribute by the ``set_classes()`` function. The - resulting "classes" attribute is passed through to the "reference" - element node constructor. - -.. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search diff --git a/docutils/docs/index.txt b/docutils/docs/index.txt deleted file mode 100644 index 18761f312..000000000 --- a/docutils/docs/index.txt +++ /dev/null @@ -1,236 +0,0 @@ -========================================== - Docutils_ Project Documentation Overview -========================================== - -:Author: David Goodger -:Contact: goodger@python.org -:Date: $Date$ -:Revision: $Revision$ -:Copyright: This document has been placed in the public domain. - -The latest working documents may be accessed individually below, or -from the ``docs`` directory of the `Docutils distribution`_. - -.. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils distribution: http://docutils.sourceforge.net/#download - -.. contents:: - - -Docutils Stakeholders -===================== - -Docutils stakeholders can be categorized in several groups: - -1. End-users: users of reStructuredText and the Docutils tools. - Although some are developers (e.g. Python developers utilizing - reStructuredText for docstrings in their source), many are not. - -2. Client-developers: developers using Docutils as a library, - programmers developing *with* Docutils. - -3. Component-developers: those who implement application-specific - components, directives, and/or roles, separately from Docutils. - -4. Core-developers: developers of the Docutils codebase and - participants in the Docutils project community. - -5. Re-implementers: developers of alternate implementations of - Docutils. - -There's a lot of overlap between these groups. Most (perhaps all) -core-developers, component-developers, client-developers, and -re-implementers are also end-users. Core-developers are also -client-developers, and may also be component-developers in other -projects. Component-developers are also client-developers. - - -Project Fundamentals -==================== - -These files are for all Docutils stakeholders. They are kept at the -top level of the Docutils project directory. - -:README.txt_: Project overview: quick-start, requirements, - installation, and usage. -:COPYING.txt_: Conditions for Docutils redistribution, with links to - licenses. -:FAQ.txt_: Docutils Frequently Asked Questions. If you have a - question or issue, there's a good chance it's already - answered here. -:BUGS.txt_: A list of known bugs, and how to report a bug. -:RELEASE-NOTES.txt_: Summary of the major changes in recent releases. -:HISTORY.txt_: Detailed change history log. -:THANKS.txt_: Acknowledgements. - -.. _README.txt: ../README.html -.. _BUGS.txt: ../BUGS.html -.. _COPYING.txt: ../COPYING.html -.. _Docutils FAQ: -.. _FAQ.txt: ../FAQ.html -.. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html -.. _HISTORY.txt: ../HISTORY.html -.. _THANKS.txt: ../THANKS.html - - -.. _user: - -``user/``: Introductory & Tutorial Material for End-Users -========================================================= - -Docutils-general: - -* `Docutils Front-End Tools <user/tools.html>`__ -* `Docutils Configuration Files <user/config.html>`__ -* `Docutils Mailing Lists <user/mailing-lists.html>`__ -* `Docutils Link List <user/links.html>`__ - -Writer-specific: - -* `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__ -* `Docutils LaTeX Writer <user/latex.html>`__ - -`reStructuredText <http://docutils.sourceforge.net/rst.html>`_: - -* `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or - `text source <user/rst/quickstart.txt>`__) -* `Quick reStructuredText <user/rst/quickref.html>`__ (user reference) -* `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text - only; 1 page for syntax, 1 page directive & role reference) -* `reStructuredText Demonstration <user/rst/demo.html>`_ (a - demonstration of most reStructuredText features; you can also have a - look at the `text source <user/rst/demo.txt>`__) - -Editor support: - -* `Emacs support for reStructuredText <user/emacs.html>`_ - - -.. _ref: - -``ref/``: Reference Material for All Groups -=========================================== - -Many of these files began as developer specifications, but now that -they're mature and used by end-users and client-developers, they have -become reference material. Successful specs evolve into refs. - -Docutils-general: - -* `The Docutils Document Tree <ref/doctree.html>`__ (incomplete) -* `Docutils Transforms <ref/transforms.html>`__ -* `Docutils Generic DTD <ref/docutils.dtd>`__ -* `OASIS XML Exchange Table Model Declaration Module - <ref/soextblx.dtd>`__ (CALS tables DTD module) - -Although not in the "ref" directory, `PEP 258`_ is a must-read -reference for any Docutils developer. - -reStructuredText_: - -* `An Introduction to reStructuredText <ref/rst/introduction.html>`__ - (includes the `Goals <ref/rst/introduction.html#goals>`__ and - `History <ref/rst/introduction.html#history>`__ of reStructuredText) -* `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__ -* `reStructuredText Directives <ref/rst/directives.html>`__ -* `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__ -* `reStructuredText Standard Definition Files - <ref/rst/definitions.html>`_ - -Prehistoric: - -* `Setext Documents Mirror - <http://docutils.sourceforge.net/mirror/setext.html>`__ - - -.. _peps: - -``peps/``: Python Enhancement Proposals -======================================= - -* `PEP 256: Docstring Processing System Framework`__ is a high-level - generic proposal. [`PEP 256`__ in the `master repository`_] -* `PEP 257: Docstring Conventions`__ addresses docstring style and - touches on content. [`PEP 257`__ in the `master repository`_] -* `PEP 258: Docutils Design Specification`__ is an overview of the - architecture of Docutils. It documents design issues and - implementation details. [`PEP 258`__ in the `master repository`_] -* `PEP 287: reStructuredText Docstring Format`__ proposes a standard - markup syntax. [`PEP 287`__ in the `master repository`_] - -Please note that PEPs in the `master repository`_ may not be current, -whereas the local versions are. - -__ peps/pep-0256.html -__ http://www.python.org/peps/pep-0256.html -__ peps/pep-0257.html -__ http://www.python.org/peps/pep-0257.html -.. _PEP 258: -__ peps/pep-0258.html -__ http://www.python.org/peps/pep-0258.html -__ peps/pep-0287.html -__ http://www.python.org/peps/pep-0287.html -.. _master repository: http://www.python.org/peps/ - - -.. _api: - -``api/``: API Reference Material for Client-Developers -====================================================== - -* `The Docutils Publisher <api/publisher.html>`__ -* `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__ -* `Docutils Runtime Settings <api/runtime-settings.html>`__ -* (`Docutils Transforms <ref/transforms.html>`__ should be moved here) - -`PEP 258`_ is an overview of the architecture of Docutils. - - -.. _howto: - -``howto/``: Instructions for Developers -======================================= - -* `Writing HTML (CSS) Stylesheets for Docutils - <howto/html-stylesheets.html>`__ -* `Docutils Internationalization <howto/i18n.html>`__ -* `Creating reStructuredText Directives <howto/rst-directives.html>`__ -* `Creating reStructuredText Interpreted Text Roles - <howto/rst-roles.html>`__ - - -.. _dev: - -``dev/``: Development Notes and Plans for Core-Developers -========================================================= - -Docutils-general: - -* `Docutils Hacker's Guide <dev/hacking.html>`__ -* `Docutils Distributor's Guide <dev/distributing.html>`__ -* `Docutils To Do List <dev/todo.html>`__ -* `Docutils Project Policies <dev/policies.html>`__ -* `Docutils Web Site <dev/website.html>`__ -* `Docutils Release Procedure <dev/release.html>`__ -* `The Docutils Subversion Repository <dev/repository.html>`__ -* `Docutils Testing <dev/testing.html>`__ -* `Docstring Semantics <dev/semantics.html>`__ (incomplete) -* `Python Source Reader <dev/pysource.html>`_ (incomplete) -* `Docutils Python DTD <dev/pysource.dtd>`_ (experimental) -* `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_ -* `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_ - -reStructuredText_: - -* `A Record of reStructuredText Syntax Alternatives - <dev/rst/alternatives.html>`__ -* `Problems With StructuredText <dev/rst/problems.html>`__ - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/peps/pep-0256.txt b/docutils/docs/peps/pep-0256.txt deleted file mode 100644 index 1e5e87e35..000000000 --- a/docutils/docs/peps/pep-0256.txt +++ /dev/null @@ -1,297 +0,0 @@ -PEP: 256 -Title: Docstring Processing System Framework -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net> -Discussions-To: <doc-sig@python.org> -Status: Draft -Type: Standards Track -Content-Type: text/x-rst -Created: 01-Jun-2001 -Post-History: 13-Jun-2001 - - -Abstract -======== - -Python lends itself to inline documentation. With its built-in -docstring syntax, a limited form of `Literate Programming`_ is easy to -do in Python. However, there are no satisfactory standard tools for -extracting and processing Python docstrings. The lack of a standard -toolset is a significant gap in Python's infrastructure; this PEP aims -to fill the gap. - -The issues surrounding docstring processing have been contentious and -difficult to resolve. This PEP proposes a generic Docstring -Processing System (DPS) framework, which separates out the components -(program and conceptual), enabling the resolution of individual issues -either through consensus (one solution) or through divergence (many). -It promotes standard interfaces which will allow a variety of plug-in -components (input context readers, markup parsers, and output format -writers) to be used. - -The concepts of a DPS framework are presented independently of -implementation details. - - -Road Map to the Docstring PEPs -============================== - -There are many aspects to docstring processing. The "Docstring PEPs" -have broken up the issues in order to deal with each of them in -isolation, or as close as possible. The individual aspects and -associated PEPs are as follows: - -* Docstring syntax. PEP 287, "reStructuredText Docstring Format" - [#PEP-287]_, proposes a syntax for Python docstrings, PEPs, and - other uses. - -* Docstring semantics consist of at least two aspects: - - - Conventions: the high-level structure of docstrings. Dealt with - in PEP 257, "Docstring Conventions" [#PEP-257]_. - - - Methodology: rules for the informational content of docstrings. - Not addressed. - -* Processing mechanisms. This PEP (PEP 256) outlines the high-level - issues and specification of an abstract docstring processing system - (DPS). PEP 258, "Docutils Design Specification" [#PEP-258]_, is an - overview of the design and implementation of one DPS under - development. - -* Output styles: developers want the documentation generated from - their source code to look good, and there are many different ideas - about what that means. PEP 258 touches on "Stylist Transforms". - This aspect of docstring processing has yet to be fully explored. - -By separating out the issues, we can form consensus more easily -(smaller fights ;-), and accept divergence more readily. - - -Rationale -========= - -There are standard inline documentation systems for some other -languages. For example, Perl has POD_ ("Plain Old Documentation") and -Java has Javadoc_, but neither of these mesh with the Pythonic way. -POD syntax is very explicit, but takes after Perl in terms of -readability. Javadoc is HTML-centric; except for "``@field``" tags, -raw HTML is used for markup. There are also general tools such as -Autoduck_ and Web_ (Tangle & Weave), useful for multiple languages. - -There have been many attempts to write auto-documentation systems -for Python (not an exhaustive list): - -- Marc-Andre Lemburg's doc.py_ - -- Daniel Larsson's pythondoc_ & gendoc_ - -- Doug Hellmann's HappyDoc_ - -- Laurence Tratt's Crystal (no longer available on the web) - -- Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard - library; see below) - -- Tony Ibbs' docutils_ (Tony has donated this name to the `Docutils - project`_) - -- Edward Loper's STminus_ formalization and related efforts - -These systems, each with different goals, have had varying degrees of -success. A problem with many of the above systems was over-ambition -combined with inflexibility. They provided a self-contained set of -components: a docstring extraction system, a markup parser, an -internal processing system and one or more output format writers with -a fixed style. Inevitably, one or more aspects of each system had -serious shortcomings, and they were not easily extended or modified, -preventing them from being adopted as standard tools. - -It has become clear (to this author, at least) that the "all or -nothing" approach cannot succeed, since no monolithic self-contained -system could possibly be agreed upon by all interested parties. A -modular component approach designed for extension, where components -may be multiply implemented, may be the only chance for success. -Standard inter-component APIs will make the DPS components -comprehensible without requiring detailed knowledge of the whole, -lowering the barrier for contributions, and ultimately resulting in a -rich and varied system. - -Each of the components of a docstring processing system should be -developed independently. A "best of breed" system should be chosen, -either merged from existing systems, and/or developed anew. This -system should be included in Python's standard library. - - -PyDoc & Other Existing Systems ------------------------------- - -PyDoc became part of the Python standard library as of release 2.1. -It extracts and displays docstrings from within the Python interactive -interpreter, from the shell command line, and from a GUI window into a -web browser (HTML). Although a very useful tool, PyDoc has several -deficiencies, including: - -- In the case of the GUI/HTML, except for some heuristic hyperlinking - of identifier names, no formatting of the docstrings is done. They - are presented within ``<p><small><tt>`` tags to avoid unwanted line - wrapping. Unfortunately, the result is not attractive. - -- PyDoc extracts docstrings and structural information (class - identifiers, method signatures, etc.) from imported module objects. - There are security issues involved with importing untrusted code. - Also, information from the source is lost when importing, such as - comments, "additional docstrings" (string literals in non-docstring - contexts; see PEP 258 [#PEP-258]_), and the order of definitions. - -The functionality proposed in this PEP could be added to or used by -PyDoc when serving HTML pages. The proposed docstring processing -system's functionality is much more than PyDoc needs in its current -form. Either an independent tool will be developed (which PyDoc may -or may not use), or PyDoc could be expanded to encompass this -functionality and *become* the docstring processing system (or one -such system). That decision is beyond the scope of this PEP. - -Similarly for other existing docstring processing systems, their -authors may or may not choose compatibility with this framework. -However, if this framework is accepted and adopted as the Python -standard, compatibility will become an important consideration in -these systems' future. - - -Specification -============= - -The docstring processing system framework is broken up as follows: - -1. Docstring conventions. Documents issues such as: - - - What should be documented where. - - - First line is a one-line synopsis. - - PEP 257 [#PEP-257]_ documents some of these issues. - -2. Docstring processing system design specification. Documents - issues such as: - - - High-level spec: what a DPS does. - - - Command-line interface for executable script. - - - System Python API. - - - Docstring extraction rules. - - - Readers, which encapsulate the input context. - - - Parsers. - - - Document tree: the intermediate internal data structure. The - output of the Parser and Reader, and the input to the Writer all - share the same data structure. - - - Transforms, which modify the document tree. - - - Writers for output formats. - - - Distributors, which handle output management (one file, many - files, or objects in memory). - - These issues are applicable to any docstring processing system - implementation. PEP 258 [#PEP-258]_ documents these issues. - -3. Docstring processing system implementation. - -4. Input markup specifications: docstring syntax. PEP 287 [#PEP-287]_ - proposes a standard syntax. - -5. Input parser implementations. - -6. Input context readers ("modes": Python source code, PEP, standalone - text file, email, etc.) and implementations. - -7. Stylists: certain input context readers may have associated - stylists which allow for a variety of output document styles. - -8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer - implementations. - -Components 1, 2/3/5, and 4 are the subject of individual companion -PEPs. If there is another implementation of the framework or -syntax/parser, additional PEPs may be required. Multiple -implementations of each of components 6 and 7 will be required; the -PEP mechanism may be overkill for these components. - - -Project Web Site -================ - -A SourceForge project has been set up for this work at -http://docutils.sourceforge.net/. - - -References and Footnotes -======================== - -.. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger - (http://www.python.org/peps/pep-0287.html) - -.. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum - (http://www.python.org/peps/pep-0257.html) - -.. [#PEP-258] PEP 258, Docutils Design Specification, Goodger - (http://www.python.org/peps/pep-0258.html) - -.. _Literate Programming: http://www.literateprogramming.com/ - -.. _POD: http://perldoc.perl.org/perlpod.html - -.. _Javadoc: http://java.sun.com/j2se/javadoc/ - -.. _Autoduck: - http://www.helpmaster.com/hlp-developmentaids-autoduck.htm - -.. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html - -.. _doc.py: - http://www.egenix.com/files/python/SoftwareDescriptions.html#doc.py - -.. _pythondoc: -.. _gendoc: http://starship.python.net/crew/danilo/pythondoc/ - -.. _HappyDoc: http://happydoc.sourceforge.net/ - -.. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html - -.. _docutils: http://www.tibsnjoan.co.uk/docutils.html - -.. _Docutils project: http://docutils.sourceforge.net/ - -.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/ - -.. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/ - - -Copyright -========= - -This document has been placed in the public domain. - - -Acknowledgements -================ - -This document borrows ideas from the archives of the `Python -Doc-SIG`_. Thanks to all members past & present. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/peps/pep-0257.txt b/docutils/docs/peps/pep-0257.txt deleted file mode 100644 index 23094c56a..000000000 --- a/docutils/docs/peps/pep-0257.txt +++ /dev/null @@ -1,328 +0,0 @@ -PEP: 257 -Title: Docstring Conventions -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net>, - Guido van Rossum <guido@python.org> -Discussions-To: doc-sig@python.org -Status: Active -Type: Informational -Content-Type: text/x-rst -Created: 29-May-2001 -Post-History: 13-Jun-2001 - - -Abstract -======== - -This PEP documents the semantics and conventions associated with -Python docstrings. - - -Rationale -========= - -The aim of this PEP is to standardize the high-level structure of -docstrings: what they should contain, and how to say it (without -touching on any markup syntax within docstrings). The PEP contains -conventions, not laws or syntax. - - "A universal convention supplies all of maintainability, clarity, - consistency, and a foundation for good programming habits too. - What it doesn't do is insist that you follow it against your will. - That's Python!" - - -- Tim Peters on comp.lang.python, 2001-06-16 - -If you violate these conventions, the worst you'll get is some dirty -looks. But some software (such as the Docutils_ docstring processing -system [1]_ [2]_) will be aware of the conventions, so following them -will get you the best results. - - -Specification -============= - -What is a Docstring? --------------------- - -A docstring is a string literal that occurs as the first statement in -a module, function, class, or method definition. Such a docstring -becomes the ``__doc__`` special attribute of that object. - -All modules should normally have docstrings, and all functions and -classes exported by a module should also have docstrings. Public -methods (including the ``__init__`` constructor) should also have -docstrings. A package may be documented in the module docstring of -the ``__init__.py`` file in the package directory. - -String literals occurring elsewhere in Python code may also act as -documentation. They are not recognized by the Python bytecode -compiler and are not accessible as runtime object attributes (i.e. not -assigned to ``__doc__``), but two types of extra docstrings may be -extracted by software tools: - -1. String literals occurring immediately after a simple assignment at - the top level of a module, class, or ``__init__`` method are called - "attribute docstrings". - -2. String literals occurring immediately after another docstring are - called "additional docstrings". - -Please see PEP 258, "Docutils Design Specification" [2]_, for a -detailed description of attribute and additional docstrings. - -XXX Mention docstrings of 2.2 properties. - -For consistency, always use ``"""triple double quotes"""`` around -docstrings. Use ``r"""raw triple double quotes"""`` if you use any -backslashes in your docstrings. For Unicode docstrings, use -``u"""Unicode triple-quoted strings"""``. - -There are two forms of docstrings: one-liners and multi-line -docstrings. - - -One-line Docstrings --------------------- - -One-liners are for really obvious cases. They should really fit on -one line. For example:: - - def kos_root(): - """Return the pathname of the KOS root directory.""" - global _kos_root - if _kos_root: return _kos_root - ... - -Notes: - -- Triple quotes are used even though the string fits on one line. - This makes it easy to later expand it. - -- The closing quotes are on the same line as the opening quotes. This - looks better for one-liners. - -- There's no blank line either before or after the docstring. - -- The docstring is a phrase ending in a period. It prescribes the - function or method's effect as a command ("Do this", "Return that"), - not as a description; e.g. don't write "Returns the pathname ...". - -- The one-line docstring should NOT be a "signature" reiterating the - function/method parameters (which can be obtained by introspection). - Don't do:: - - def function(a, b): - """function(a, b) -> list""" - - This type of docstring is only appropriate for C functions (such as - built-ins), where introspection is not possible. However, the - nature of the *return value* cannot be determined by introspection, - so it should be mentioned. The preferred form for such a docstring - would be something like:: - - def function(a, b): - """Do X and return a list.""" - - (Of course "Do X" should be replaced by a useful description!) - - -Multi-line Docstrings ----------------------- - -Multi-line docstrings consist of a summary line just like a one-line -docstring, followed by a blank line, followed by a more elaborate -description. The summary line may be used by automatic indexing -tools; it is important that it fits on one line and is separated from -the rest of the docstring by a blank line. The summary line may be on -the same line as the opening quotes or on the next line. The entire -docstring is indented the same as the quotes at its first line (see -example below). - -Insert a blank line before and after all docstrings (one-line or -multi-line) that document a class -- generally speaking, the class's -methods are separated from each other by a single blank line, and the -docstring needs to be offset from the first method by a blank line; -for symmetry, put a blank line between the class header and the -docstring. Docstrings documenting functions or methods generally -don't have this requirement, unless the function or method's body is -written as a number of blank-line separated sections -- in this case, -treat the docstring as another section, and precede it with a blank -line. - -The docstring of a script (a stand-alone program) should be usable as -its "usage" message, printed when the script is invoked with incorrect -or missing arguments (or perhaps with a "-h" option, for "help"). -Such a docstring should document the script's function and command -line syntax, environment variables, and files. Usage messages can be -fairly elaborate (several screens full) and should be sufficient for a -new user to use the command properly, as well as a complete quick -reference to all options and arguments for the sophisticated user. - -The docstring for a module should generally list the classes, -exceptions and functions (and any other objects) that are exported by -the module, with a one-line summary of each. (These summaries -generally give less detail than the summary line in the object's -docstring.) The docstring for a package (i.e., the docstring of the -package's ``__init__.py`` module) should also list the modules and -subpackages exported by the package. - -The docstring for a function or method should summarize its behavior -and document its arguments, return value(s), side effects, exceptions -raised, and restrictions on when it can be called (all if applicable). -Optional arguments should be indicated. It should be documented -whether keyword arguments are part of the interface. - -The docstring for a class should summarize its behavior and list the -public methods and instance variables. If the class is intended to be -subclassed, and has an additional interface for subclasses, this -interface should be listed separately (in the docstring). The class -constructor should be documented in the docstring for its ``__init__`` -method. Individual methods should be documented by their own -docstring. - -If a class subclasses another class and its behavior is mostly -inherited from that class, its docstring should mention this and -summarize the differences. Use the verb "override" to indicate that a -subclass method replaces a superclass method and does not call the -superclass method; use the verb "extend" to indicate that a subclass -method calls the superclass method (in addition to its own behavior). - -*Do not* use the Emacs convention of mentioning the arguments of -functions or methods in upper case in running text. Python is case -sensitive and the argument names can be used for keyword arguments, so -the docstring should document the correct argument names. It is best -to list each argument on a separate line. For example:: - - def complex(real=0.0, imag=0.0): - """Form a complex number. - - Keyword arguments: - real -- the real part (default 0.0) - imag -- the imaginary part (default 0.0) - - """ - if imag == 0.0 and real == 0.0: return complex_zero - ... - -The BDFL [3]_ recommends inserting a blank line between the last -paragraph in a multi-line docstring and its closing quotes, placing -the closing quotes on a line by themselves. This way, Emacs' -``fill-paragraph`` command can be used on it. - - -Handling Docstring Indentation ------------------------------- - -Docstring processing tools will strip a uniform amount of indentation -from the second and further lines of the docstring, equal to the -minimum indentation of all non-blank lines after the first line. Any -indentation in the first line of the docstring (i.e., up to the first -newline) is insignificant and removed. Relative indentation of later -lines in the docstring is retained. Blank lines should be removed -from the beginning and end of the docstring. - -Since code is much more precise than words, here is an implementation -of the algorithm:: - - def trim(docstring): - if not docstring: - return '' - # Convert tabs to spaces (following the normal Python rules) - # and split into a list of lines: - lines = docstring.expandtabs().splitlines() - # Determine minimum indentation (first line doesn't count): - indent = sys.maxint - for line in lines[1:]: - stripped = line.lstrip() - if stripped: - indent = min(indent, len(line) - len(stripped)) - # Remove indentation (first line is special): - trimmed = [lines[0].strip()] - if indent < sys.maxint: - for line in lines[1:]: - trimmed.append(line[indent:].rstrip()) - # Strip off trailing and leading blank lines: - while trimmed and not trimmed[-1]: - trimmed.pop() - while trimmed and not trimmed[0]: - trimmed.pop(0) - # Return a single string: - return '\n'.join(trimmed) - -The docstring in this example contains two newline characters and is -therefore 3 lines long. The first and last lines are blank:: - - def foo(): - """ - This is the second line of the docstring. - """ - -To illustrate:: - - >>> print repr(foo.__doc__) - '\n This is the second line of the docstring.\n ' - >>> foo.__doc__.splitlines() - ['', ' This is the second line of the docstring.', ' '] - >>> trim(foo.__doc__) - 'This is the second line of the docstring.' - -Once trimmed, these docstrings are equivalent:: - - def foo(): - """A multi-line - docstring. - """ - - def bar(): - """ - A multi-line - docstring. - """ - - -References and Footnotes -======================== - -.. [1] PEP 256, Docstring Processing System Framework, Goodger - (http://www.python.org/peps/pep-0256.html) - -.. [2] PEP 258, Docutils Design Specification, Goodger - (http://www.python.org/peps/pep-0258.html) - -.. [3] Guido van Rossum, Python's creator and Benevolent Dictator For - Life. - -.. _Docutils: http://docutils.sourceforge.net/ - -.. _Python Style Guide: - http://www.python.org/doc/essays/styleguide.html - -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - - -Copyright -========= - -This document has been placed in the public domain. - - -Acknowledgements -================ - -The "Specification" text comes mostly verbatim from the `Python Style -Guide`_ essay by Guido van Rossum. - -This document borrows ideas from the archives of the Python Doc-SIG_. -Thanks to all members past and present. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - fill-column: 70 - sentence-end-double-space: t - End: diff --git a/docutils/docs/peps/pep-0258.txt b/docutils/docs/peps/pep-0258.txt deleted file mode 100644 index 0d646bb82..000000000 --- a/docutils/docs/peps/pep-0258.txt +++ /dev/null @@ -1,1029 +0,0 @@ -PEP: 258 -Title: Docutils Design Specification -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net> -Discussions-To: <doc-sig@python.org> -Status: Draft -Type: Standards Track -Content-Type: text/x-rst -Requires: 256, 257 -Created: 31-May-2001 -Post-History: 13-Jun-2001 - - -========== - Abstract -========== - -This PEP documents design issues and implementation details for -Docutils, a Python Docstring Processing System (DPS). The rationale -and high-level concepts of a DPS are documented in PEP 256, "Docstring -Processing System Framework" [#PEP-256]_. Also see PEP 256 for a -"Road Map to the Docstring PEPs". - -Docutils is being designed modularly so that any of its components can -be replaced easily. In addition, Docutils is not limited to the -processing of Python docstrings; it processes standalone documents as -well, in several contexts. - -No changes to the core Python language are required by this PEP. Its -deliverables consist of a package for the standard library and its -documentation. - - -=============== - Specification -=============== - -Docutils Project Model -====================== - -Project components and data flow:: - - +---------------------------+ - | Docutils: | - | docutils.core.Publisher, | - | docutils.core.publish_*() | - +---------------------------+ - / | \ - / | \ - 1,3,5 / 6 | \ 7 - +--------+ +-------------+ +--------+ - | READER | ----> | TRANSFORMER | ====> | WRITER | - +--------+ +-------------+ +--------+ - / \\ | - / \\ | - 2 / 4 \\ 8 | - +-------+ +--------+ +--------+ - | INPUT | | PARSER | | OUTPUT | - +-------+ +--------+ +--------+ - -The numbers above each component indicate the path a document's data -takes. Double-width lines between Reader & Parser and between -Transformer & Writer indicate that data sent along these paths should -be standard (pure & unextended) Docutils doc trees. Single-width -lines signify that internal tree extensions or completely unrelated -representations are possible, but they must be supported at both ends. - - -Publisher ---------- - -The ``docutils.core`` module contains a "Publisher" facade class and -several convenience functions: "publish_cmdline()" (for command-line -front ends), "publish_file()" (for programmatic use with file-like -I/O), and "publish_string()" (for programmatic use with string I/O). -The Publisher class encapsulates the high-level logic of a Docutils -system. The Publisher class has overall responsibility for -processing, controlled by the ``Publisher.publish()`` method: - -1. Set up internal settings (may include config files & command-line - options) and I/O objects. - -2. Call the Reader object to read data from the source Input object - and parse the data with the Parser object. A document object is - returned. - -3. Set up and apply transforms via the Transformer object attached to - the document. - -4. Call the Writer object which translates the document to the final - output format and writes the formatted data to the destination - Output object. Depending on the Output object, the output may be - returned from the Writer, and then from the ``publish()`` method. - -Calling the "publish" function (or instantiating a "Publisher" object) -with component names will result in default behavior. For custom -behavior (customizing component settings), create custom component -objects first, and pass *them* to the Publisher or ``publish_*`` -convenience functions. - - -Readers -------- - -Readers understand the input context (where the data is coming from), -send the whole input or discrete "chunks" to the parser, and provide -the context to bind the chunks together back into a cohesive whole. - -Each reader is a module or package exporting a "Reader" class with a -"read" method. The base "Reader" class can be found in the -``docutils/readers/__init__.py`` module. - -Most Readers will have to be told what parser to use. So far (see the -list of examples below), only the Python Source Reader ("PySource"; -still incomplete) will be able to determine the parser on its own. - -Responsibilities: - -* Get input text from the source I/O. - -* Pass the input text to the parser, along with a fresh `document - tree`_ root. - -Examples: - -* Standalone (Raw/Plain): Just read a text file and process it. - The reader needs to be told which parser to use. - - The "Standalone Reader" has been implemented in module - ``docutils.readers.standalone``. - -* Python Source: See `Python Source Reader`_ below. This Reader is - currently in development in the Docutils sandbox. - -* Email: RFC-822 headers, quoted excerpts, signatures, MIME parts. - -* PEP: RFC-822 headers, "PEP xxxx" and "RFC xxxx" conversion to URIs. - The "PEP Reader" has been implemented in module - ``docutils.readers.pep``; see PEP 287 and PEP 12. - -* Wiki: Global reference lookups of "wiki links" incorporated into - transforms. (CamelCase only or unrestricted?) Lazy - indentation? - -* Web Page: As standalone, but recognize meta fields as meta tags. - Support for templates of some sort? (After ``<body>``, before - ``</body>``?) - -* FAQ: Structured "question & answer(s)" constructs. - -* Compound document: Merge chapters into a book. Master manifest - file? - - -Parsers -------- - -Parsers analyze their input and produce a Docutils `document tree`_. -They don't know or care anything about the source or destination of -the data. - -Each input parser is a module or package exporting a "Parser" class -with a "parse" method. The base "Parser" class can be found in the -``docutils/parsers/__init__.py`` module. - -Responsibilities: Given raw input text and a doctree root node, -populate the doctree by parsing the input text. - -Example: The only parser implemented so far is for the -reStructuredText markup. It is implemented in the -``docutils/parsers/rst/`` package. - -The development and integration of other parsers is possible and -encouraged. - - -.. _transforms: - -Transformer ------------ - -The Transformer class, in ``docutils/transforms/__init__.py``, stores -transforms and applies them to documents. A transformer object is -attached to every new document tree. The Publisher_ calls -``Transformer.apply_transforms()`` to apply all stored transforms to -the document tree. Transforms change the document tree from one form -to another, add to the tree, or prune it. Transforms resolve -references and footnote numbers, process interpreted text, and do -other context-sensitive processing. - -Some transforms are specific to components (Readers, Parser, Writers, -Input, Output). Standard component-specific transforms are specified -in the ``default_transforms`` attribute of component classes. After -the Reader has finished processing, the Publisher_ calls -``Transformer.populate_from_components()`` with a list of components -and all default transforms are stored. - -Each transform is a class in a module in the ``docutils/transforms/`` -package, a subclass of ``docutils.tranforms.Transform``. Transform -classes each have a ``default_priority`` attribute which is used by -the Transformer to apply transforms in order (low to high). The -default priority can be overridden when adding transforms to the -Transformer object. - -Transformer responsibilities: - -* Apply transforms to the document tree, in priority order. - -* Store a mapping of component type name ('reader', 'writer', etc.) to - component objects. These are used by certain transforms (such as - "components.Filter") to determine suitability. - -Transform responsibilities: - -* Modify a doctree in-place, either purely transforming one structure - into another, or adding new structures based on the doctree and/or - external data. - -Examples of transforms (in the ``docutils/transforms/`` package): - -* frontmatter.DocInfo: Conversion of document metadata (bibliographic - information). - -* references.AnonymousHyperlinks: Resolution of anonymous references - to corresponding targets. - -* parts.Contents: Generates a table of contents for a document. - -* document.Merger: Combining multiple populated doctrees into one. - (Not yet implemented or fully understood.) - -* document.Splitter: Splits a document into a tree-structure of - subdocuments, perhaps by section. It will have to transform - references appropriately. (Neither implemented not remotely - understood.) - -* components.Filter: Includes or excludes elements which depend on a - specific Docutils component. - - -Writers -------- - -Writers produce the final output (HTML, XML, TeX, etc.). Writers -translate the internal `document tree`_ structure into the final data -format, possibly running Writer-specific transforms_ first. - -By the time the document gets to the Writer, it should be in final -form. The Writer's job is simply (and only) to translate from the -Docutils doctree structure to the target format. Some small -transforms may be required, but they should be local and -format-specific. - -Each writer is a module or package exporting a "Writer" class with a -"write" method. The base "Writer" class can be found in the -``docutils/writers/__init__.py`` module. - -Responsibilities: - -* Translate doctree(s) into specific output formats. - - - Transform references into format-native forms. - -* Write the translated output to the destination I/O. - -Examples: - -* XML: Various forms, such as: - - - Docutils XML (an expression of the internal document tree, - implemented as ``docutils.writers.docutils_xml``). - - - DocBook (being implemented in the Docutils sandbox). - -* HTML (XHTML implemented as ``docutils.writers.html4css1``). - -* PDF (a ReportLabs interface is being developed in the Docutils - sandbox). - -* TeX (a LaTeX Writer is being implemented in the sandbox). - -* Docutils-native pseudo-XML (implemented as - ``docutils.writers.pseudoxml``, used for testing). - -* Plain text - -* reStructuredText? - - -Input/Output ------------- - -I/O classes provide a uniform API for low-level input and output. -Subclasses will exist for a variety of input/output mechanisms. -However, they can be considered an implementation detail. Most -applications should be satisfied using one of the convenience -functions associated with the Publisher_. - -I/O classes are currently in the preliminary stages; there's a lot of -work yet to be done. Issues: - -* How to represent multi-file input (files & directories) in the API? - -* How to represent multi-file output? Perhaps "Writer" variants, one - for each output distribution type? Or Output objects with - associated transforms? - -Responsibilities: - -* Read data from the input source (Input objects) or write data to the - output destination (Output objects). - -Examples of input sources: - -* A single file on disk or a stream (implemented as - ``docutils.io.FileInput``). - -* Multiple files on disk (``MultiFileInput``?). - -* Python source files: modules and packages. - -* Python strings, as received from a client application - (implemented as ``docutils.io.StringInput``). - -Examples of output destinations: - -* A single file on disk or a stream (implemented as - ``docutils.io.FileOutput``). - -* A tree of directories and files on disk. - -* A Python string, returned to a client application (implemented as - ``docutils.io.StringOutput``). - -* No output; useful for programmatic applications where only a portion - of the normal output is to be used (implemented as - ``docutils.io.NullOutput``). - -* A single tree-shaped data structure in memory. - -* Some other set of data structures in memory. - - -Docutils Package Structure -========================== - -* Package "docutils". - - - Module "__init__.py" contains: class "Component", a base class for - Docutils components; class "SettingsSpec", a base class for - specifying runtime settings (used by docutils.frontend); and class - "TransformSpec", a base class for specifying transforms. - - - Module "docutils.core" contains facade class "Publisher" and - convenience functions. See `Publisher`_ above. - - - Module "docutils.frontend" provides runtime settings support, for - programmatic use and front-end tools (including configuration file - support, and command-line argument and option processing). - - - Module "docutils.io" provides a uniform API for low-level input - and output. See `Input/Output`_ above. - - - Module "docutils.nodes" contains the Docutils document tree - element class library plus tree-traversal Visitor pattern base - classes. See `Document Tree`_ below. - - - Module "docutils.statemachine" contains a finite state machine - specialized for regular-expression-based text filters and parsers. - The reStructuredText parser implementation is based on this - module. - - - Module "docutils.urischemes" contains a mapping of known URI - schemes ("http", "ftp", "mail", etc.). - - - Module "docutils.utils" contains utility functions and classes, - including a logger class ("Reporter"; see `Error Handling`_ - below). - - - Package "docutils.parsers": markup parsers_. - - - Function "get_parser_class(parser_name)" returns a parser module - by name. Class "Parser" is the base class of specific parsers. - (``docutils/parsers/__init__.py``) - - - Package "docutils.parsers.rst": the reStructuredText parser. - - - Alternate markup parsers may be added. - - See `Parsers`_ above. - - - Package "docutils.readers": context-aware input readers. - - - Function "get_reader_class(reader_name)" returns a reader module - by name or alias. Class "Reader" is the base class of specific - readers. (``docutils/readers/__init__.py``) - - - Module "docutils.readers.standalone" reads independent document - files. - - - Module "docutils.readers.pep" reads PEPs (Python Enhancement - Proposals). - - - Module "docutils.readers.doctree" is used to re-read a - previously stored document tree for reprocessing. - - - Readers to be added for: Python source code (structure & - docstrings), email, FAQ, and perhaps Wiki and others. - - See `Readers`_ above. - - - Package "docutils.writers": output format writers. - - - Function "get_writer_class(writer_name)" returns a writer module - by name. Class "Writer" is the base class of specific writers. - (``docutils/writers/__init__.py``) - - - Package "docutils.writers.html4css1" is a simple HyperText - Markup Language document tree writer for HTML 4.01 and CSS1. - - - Package "docutils.writers.pep_html" generates HTML from - reStructuredText PEPs. - - - Package "docutils.writers.s5_html" generates S5/HTML slide - shows. - - - Package "docutils.writers.latex2e" writes LaTeX. - - - Package "docutils.writers.newlatex2e" also writes LaTeX; it is a - new implementation. - - - Module "docutils.writers.docutils_xml" writes the internal - document tree in XML form. - - - Module "docutils.writers.pseudoxml" is a simple internal - document tree writer; it writes indented pseudo-XML. - - - Module "docutils.writers.null" is a do-nothing writer; it is - used for specialized purposes such as storing the internal - document tree. - - - Writers to be added: HTML 3.2 or 4.01-loose, XML (various forms, - such as DocBook), PDF, plaintext, reStructuredText, and perhaps - others. - - Subpackages of "docutils.writers" contain modules and data files - (such as stylesheets) that support the individual writers. - - See `Writers`_ above. - - - Package "docutils.transforms": tree transform classes. - - - Class "Transformer" stores transforms and applies them to - document trees. (``docutils/transforms/__init__.py``) - - - Class "Transform" is the base class of specific transforms. - (``docutils/transforms/__init__.py``) - - - Each module contains related transform classes. - - See `Transforms`_ above. - - - Package "docutils.languages": Language modules contain - language-dependent strings and mappings. They are named for their - language identifier (as defined in `Choice of Docstring Format`_ - below), converting dashes to underscores. - - - Function "get_language(language_code)", returns matching - language module. (``docutils/languages/__init__.py``) - - - Modules: en.py (English), de.py (German), fr.py (French), it.py - (Italian), sk.py (Slovak), sv.py (Swedish). - - - Other languages to be added. - -* Third-party modules: "extras" directory. These modules are - installed only if they're not already present in the Python - installation. - - - ``extras/optparse.py`` and ``extras/textwrap.py`` provide - option parsing and command-line help; from Greg Ward's - http://optik.sf.net/ project, included for convenience. - - - ``extras/roman.py`` contains Roman numeral conversion routines. - - -Front-End Tools -=============== - -The ``tools/`` directory contains several front ends for common -Docutils processing. See `Docutils Front-End Tools`_ for details. - -.. _Docutils Front-End Tools: - http://docutils.sourceforge.net/docs/user/tools.html - - -Document Tree -============= - -A single intermediate data structure is used internally by Docutils, -in the interfaces between components; it is defined in the -``docutils.nodes`` module. It is not required that this data -structure be used *internally* by any of the components, just -*between* components as outlined in the diagram in the `Docutils -Project Model`_ above. - -Custom node types are allowed, provided that either (a) a transform -converts them to standard Docutils nodes before they reach the Writer -proper, or (b) the custom node is explicitly supported by certain -Writers, and is wrapped in a filtered "pending" node. An example of -condition (a) is the `Python Source Reader`_ (see below), where a -"stylist" transform converts custom nodes. The HTML ``<meta>`` tag is -an example of condition (b); it is supported by the HTML Writer but -not by others. The reStructuredText "meta" directive creates a -"pending" node, which contains knowledge that the embedded "meta" node -can only be handled by HTML-compatible writers. The "pending" node is -resolved by the ``docutils.transforms.components.Filter`` transform, -which checks that the calling writer supports HTML; if it doesn't, the -"pending" node (and enclosed "meta" node) is removed from the -document. - -The document tree data structure is similar to a DOM tree, but with -specific node names (classes) instead of DOM's generic nodes. The -schema is documented in an XML DTD (eXtensible Markup Language -Document Type Definition), which comes in two parts: - -* the Docutils Generic DTD, docutils.dtd_, and - -* the OASIS Exchange Table Model, soextbl.dtd_. - -The DTD defines a rich set of elements, suitable for many input and -output formats. The DTD retains all information necessary to -reconstruct the original input text, or a reasonable facsimile -thereof. - -See `The Docutils Document Tree`_ for details (incomplete). - - -Error Handling -============== - -When the parser encounters an error in markup, it inserts a system -message (DTD element "system_message"). There are five levels of -system messages: - -* Level-0, "DEBUG": an internal reporting issue. There is no effect - on the processing. Level-0 system messages are handled separately - from the others. - -* Level-1, "INFO": a minor issue that can be ignored. There is little - or no effect on the processing. Typically level-1 system messages - are not reported. - -* Level-2, "WARNING": an issue that should be addressed. If ignored, - there may be minor problems with the output. Typically level-2 - system messages are reported but do not halt processing. - -* Level-3, "ERROR": a major issue that should be addressed. If - ignored, the output will contain unpredictable errors. Typically - level-3 system messages are reported but do not halt processing. - -* Level-4, "SEVERE": a critical error that must be addressed. - Typically level-4 system messages are turned into exceptions which - do halt processing. If ignored, the output will contain severe - errors. - -Although the initial message levels were devised independently, they -have a strong correspondence to `VMS error condition severity -levels`_; the names in quotes for levels 1 through 4 were borrowed -from VMS. Error handling has since been influenced by the `log4j -project`_. - - -Python Source Reader -==================== - -The Python Source Reader ("PySource") is the Docutils component that -reads Python source files, extracts docstrings in context, then -parses, links, and assembles the docstrings into a cohesive whole. It -is a major and non-trivial component, currently under experimental -development in the Docutils sandbox. High-level design issues are -presented here. - - -Processing Model ----------------- - -This model will evolve over time, incorporating experience and -discoveries. - -1. The PySource Reader uses an Input class to read in Python packages - and modules, into a tree of strings. - -2. The Python modules are parsed, converting the tree of strings into - a tree of abstract syntax trees with docstring nodes. - -3. The abstract syntax trees are converted into an internal - representation of the packages/modules. Docstrings are extracted, - as well as code structure details. See `AST Mining`_ below. - Namespaces are constructed for lookup in step 6. - -4. One at a time, the docstrings are parsed, producing standard - Docutils doctrees. - -5. PySource assembles all the individual docstrings' doctrees into a - Python-specific custom Docutils tree paralleling the - package/module/class structure; this is a custom Reader-specific - internal representation (see the `Docutils Python Source DTD`_). - Namespaces must be merged: Python identifiers, hyperlink targets. - -6. Cross-references from docstrings (interpreted text) to Python - identifiers are resolved according to the Python namespace lookup - rules. See `Identifier Cross-References`_ below. - -7. A "Stylist" transform is applied to the custom doctree (by the - Transformer_), custom nodes are rendered using standard nodes as - primitives, and a standard document tree is emitted. See `Stylist - Transforms`_ below. - -8. Other transforms are applied to the standard doctree by the - Transformer_. - -9. The standard doctree is sent to a Writer, which translates the - document into a concrete format (HTML, PDF, etc.). - -10. The Writer uses an Output class to write the resulting data to its - destination (disk file, directories and files, etc.). - - -AST Mining ----------- - -Abstract Syntax Tree mining code will be written (or adapted) that -scans a parsed Python module, and returns an ordered tree containing -the names, docstrings (including attribute and additional docstrings; -see below), and additional info (in parentheses below) of all of the -following objects: - -* packages -* modules -* module attributes (+ initial values) -* classes (+ inheritance) -* class attributes (+ initial values) -* instance attributes (+ initial values) -* methods (+ parameters & defaults) -* functions (+ parameters & defaults) - -(Extract comments too? For example, comments at the start of a module -would be a good place for bibliographic field lists.) - -In order to evaluate interpreted text cross-references, namespaces for -each of the above will also be required. - -See the python-dev/docstring-develop thread "AST mining", started on -2001-08-14. - - -Docstring Extraction Rules --------------------------- - -1. What to examine: - - a) If the "``__all__``" variable is present in the module being - documented, only identifiers listed in "``__all__``" are - examined for docstrings. - - b) In the absence of "``__all__``", all identifiers are examined, - except those whose names are private (names begin with "_" but - don't begin and end with "__"). - - c) 1a and 1b can be overridden by runtime settings. - -2. Where: - - Docstrings are string literal expressions, and are recognized in - the following places within Python modules: - - a) At the beginning of a module, function definition, class - definition, or method definition, after any comments. This is - the standard for Python ``__doc__`` attributes. - - b) Immediately following a simple assignment at the top level of a - module, class definition, or ``__init__`` method definition, - after any comments. See `Attribute Docstrings`_ below. - - c) Additional string literals found immediately after the - docstrings in (a) and (b) will be recognized, extracted, and - concatenated. See `Additional Docstrings`_ below. - - d) @@@ 2.2-style "properties" with attribute docstrings? Wait for - syntax? - -3. How: - - Whenever possible, Python modules should be parsed by Docutils, not - imported. There are several reasons: - - - Importing untrusted code is inherently insecure. - - - Information from the source is lost when using introspection to - examine an imported module, such as comments and the order of - definitions. - - - Docstrings are to be recognized in places where the byte-code - compiler ignores string literal expressions (2b and 2c above), - meaning importing the module will lose these docstrings. - - Of course, standard Python parsing tools such as the "parser" - library module should be used. - - When the Python source code for a module is not available - (i.e. only the ``.pyc`` file exists) or for C extension modules, to - access docstrings the module can only be imported, and any - limitations must be lived with. - -Since attribute docstrings and additional docstrings are ignored by -the Python byte-code compiler, no namespace pollution or runtime bloat -will result from their use. They are not assigned to ``__doc__`` or -to any other attribute. The initial parsing of a module may take a -slight performance hit. - - -Attribute Docstrings -'''''''''''''''''''' - -(This is a simplified version of PEP 224 [#PEP-224]_.) - -A string literal immediately following an assignment statement is -interpreted by the docstring extraction machinery as the docstring of -the target of the assignment statement, under the following -conditions: - -1. The assignment must be in one of the following contexts: - - a) At the top level of a module (i.e., not nested inside a compound - statement such as a loop or conditional): a module attribute. - - b) At the top level of a class definition: a class attribute. - - c) At the top level of the "``__init__``" method definition of a - class: an instance attribute. Instance attributes assigned in - other methods are assumed to be implementation details. (@@@ - ``__new__`` methods?) - - d) A function attribute assignment at the top level of a module or - class definition. - - Since each of the above contexts are at the top level (i.e., in the - outermost suite of a definition), it may be necessary to place - dummy assignments for attributes assigned conditionally or in a - loop. - -2. The assignment must be to a single target, not to a list or a tuple - of targets. - -3. The form of the target: - - a) For contexts 1a and 1b above, the target must be a simple - identifier (not a dotted identifier, a subscripted expression, - or a sliced expression). - - b) For context 1c above, the target must be of the form - "``self.attrib``", where "``self``" matches the "``__init__``" - method's first parameter (the instance parameter) and "attrib" - is a simple identifier as in 3a. - - c) For context 1d above, the target must be of the form - "``name.attrib``", where "``name``" matches an already-defined - function or method name and "attrib" is a simple identifier as - in 3a. - -Blank lines may be used after attribute docstrings to emphasize the -connection between the assignment and the docstring. - -Examples:: - - g = 'module attribute (module-global variable)' - """This is g's docstring.""" - - class AClass: - - c = 'class attribute' - """This is AClass.c's docstring.""" - - def __init__(self): - """Method __init__'s docstring.""" - - self.i = 'instance attribute' - """This is self.i's docstring.""" - - def f(x): - """Function f's docstring.""" - return x**2 - - f.a = 1 - """Function attribute f.a's docstring.""" - - -Additional Docstrings -''''''''''''''''''''' - -(This idea was adapted from PEP 216 [#PEP-216]_.) - -Many programmers would like to make extensive use of docstrings for -API documentation. However, docstrings do take up space in the -running program, so some programmers are reluctant to "bloat up" their -code. Also, not all API documentation is applicable to interactive -environments, where ``__doc__`` would be displayed. - -Docutils' docstring extraction tools will concatenate all string -literal expressions which appear at the beginning of a definition or -after a simple assignment. Only the first strings in definitions will -be available as ``__doc__``, and can be used for brief usage text -suitable for interactive sessions; subsequent string literals and all -attribute docstrings are ignored by the Python byte-code compiler and -may contain more extensive API information. - -Example:: - - def function(arg): - """This is __doc__, function's docstring.""" - """ - This is an additional docstring, ignored by the byte-code - compiler, but extracted by Docutils. - """ - pass - -.. topic:: Issue: ``from __future__ import`` - - This would break "``from __future__ import``" statements introduced - in Python 2.1 for multiple module docstrings (main docstring plus - additional docstring(s)). The Python Reference Manual specifies: - - A future statement must appear near the top of the module. The - only lines that can appear before a future statement are: - - * the module docstring (if any), - * comments, - * blank lines, and - * other future statements. - - Resolution? - - 1. Should we search for docstrings after a ``__future__`` - statement? Very ugly. - - 2. Redefine ``__future__`` statements to allow multiple preceding - string literals? - - 3. Or should we not even worry about this? There probably - shouldn't be ``__future__`` statements in production code, after - all. Perhaps modules with ``__future__`` statements will simply - have to put up with the single-docstring limitation. - - -Choice of Docstring Format --------------------------- - -Rather than force everyone to use a single docstring format, multiple -input formats are allowed by the processing system. A special -variable, ``__docformat__``, may appear at the top level of a module -before any function or class definitions. Over time or through -decree, a standard format or set of formats should emerge. - -A module's ``__docformat__`` variable only applies to the objects -defined in the module's file. In particular, the ``__docformat__`` -variable in a package's ``__init__.py`` file does not apply to objects -defined in subpackages and submodules. - -The ``__docformat__`` variable is a string containing the name of the -format being used, a case-insensitive string matching the input -parser's module or package name (i.e., the same name as required to -"import" the module or package), or a registered alias. If no -``__docformat__`` is specified, the default format is "plaintext" for -now; this may be changed to the standard format if one is ever -established. - -The ``__docformat__`` string may contain an optional second field, -separated from the format name (first field) by a single space: a -case-insensitive language identifier as defined in RFC 1766. A -typical language identifier consists of a 2-letter language code from -`ISO 639`_ (3-letter codes used only if no 2-letter code exists; RFC -1766 is currently being revised to allow 3-letter codes). If no -language identifier is specified, the default is "en" for English. -The language identifier is passed to the parser and can be used for -language-dependent markup features. - - -Identifier Cross-References ---------------------------- - -In Python docstrings, interpreted text is used to classify and mark up -program identifiers, such as the names of variables, functions, -classes, and modules. If the identifier alone is given, its role is -inferred implicitly according to the Python namespace lookup rules. -For functions and methods (even when dynamically assigned), -parentheses ('()') may be included:: - - This function uses `another()` to do its work. - -For class, instance and module attributes, dotted identifiers are used -when necessary. For example (using reStructuredText markup):: - - class Keeper(Storer): - - """ - Extend `Storer`. Class attribute `instances` keeps track - of the number of `Keeper` objects instantiated. - """ - - instances = 0 - """How many `Keeper` objects are there?""" - - def __init__(self): - """ - Extend `Storer.__init__()` to keep track of instances. - - Keep count in `Keeper.instances`, data in `self.data`. - """ - Storer.__init__(self) - Keeper.instances += 1 - - self.data = [] - """Store data in a list, most recent last.""" - - def store_data(self, data): - """ - Extend `Storer.store_data()`; append new `data` to a - list (in `self.data`). - """ - self.data = data - -Each of the identifiers quoted with backquotes ("`") will become -references to the definitions of the identifiers themselves. - - -Stylist Transforms ------------------- - -Stylist transforms are specialized transforms specific to the PySource -Reader. The PySource Reader doesn't have to make any decisions as to -style; it just produces a logically constructed document tree, parsed -and linked, including custom node types. Stylist transforms -understand the custom nodes created by the Reader and convert them -into standard Docutils nodes. - -Multiple Stylist transforms may be implemented and one can be chosen -at runtime (through a "--style" or "--stylist" command-line option). -Each Stylist transform implements a different layout or style; thus -the name. They decouple the context-understanding part of the Reader -from the layout-generating part of processing, resulting in a more -flexible and robust system. This also serves to "separate style from -content", the SGML/XML ideal. - -By keeping the piece of code that does the styling small and modular, -it becomes much easier for people to roll their own styles. The -"barrier to entry" is too high with existing tools; extracting the -stylist code will lower the barrier considerably. - - -========================== - References and Footnotes -========================== - -.. [#PEP-256] PEP 256, Docstring Processing System Framework, Goodger - (http://www.python.org/peps/pep-0256.html) - -.. [#PEP-224] PEP 224, Attribute Docstrings, Lemburg - (http://www.python.org/peps/pep-0224.html) - -.. [#PEP-216] PEP 216, Docstring Format, Zadka - (http://www.python.org/peps/pep-0216.html) - -.. _docutils.dtd: - http://docutils.sourceforge.net/docs/ref/docutils.dtd - -.. _soextbl.dtd: - http://docutils.sourceforge.net/docs/ref/soextblx.dtd - -.. _The Docutils Document Tree: - http://docutils.sourceforge.net/docs/ref/doctree.html - -.. _VMS error condition severity levels: - http://www.openvms.compaq.com:8000/73final/5841/841pro_027.html - #error_cond_severity - -.. _log4j project: http://logging.apache.org/log4j/docs/index.html - -.. _Docutils Python Source DTD: - http://docutils.sourceforge.net/docs/dev/pysource.dtd - -.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html - -.. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/ - - - -================== - Project Web Site -================== - -A SourceForge project has been set up for this work at -http://docutils.sourceforge.net/. - - -=========== - Copyright -=========== - -This document has been placed in the public domain. - - -================== - Acknowledgements -================== - -This document borrows ideas from the archives of the `Python -Doc-SIG`_. Thanks to all members past & present. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/peps/pep-0287.txt b/docutils/docs/peps/pep-0287.txt deleted file mode 100644 index 689d6b919..000000000 --- a/docutils/docs/peps/pep-0287.txt +++ /dev/null @@ -1,815 +0,0 @@ -PEP: 287 -Title: reStructuredText Docstring Format -Version: $Revision$ -Last-Modified: $Date$ -Author: David Goodger <goodger@users.sourceforge.net> -Discussions-To: <doc-sig@python.org> -Status: Draft -Type: Informational -Content-Type: text/x-rst -Created: 25-Mar-2002 -Post-History: 02-Apr-2002 -Replaces: 216 - - -Abstract -======== - -When plaintext hasn't been expressive enough for inline documentation, -Python programmers have sought out a format for docstrings. This PEP -proposes that the `reStructuredText markup`_ be adopted as a standard -markup format for structured plaintext documentation in Python -docstrings, and for PEPs and ancillary documents as well. -reStructuredText is a rich and extensible yet easy-to-read, -what-you-see-is-what-you-get plaintext markup syntax. - -Only the low-level syntax of docstrings is addressed here. This PEP -is not concerned with docstring semantics or processing at all (see -PEP 256 for a "Road Map to the Docstring PEPs"). Nor is it an attempt -to deprecate pure plaintext docstrings, which are always going to be -legitimate. The reStructuredText markup is an alternative for those -who want more expressive docstrings. - - -Benefits -======== - -Programmers are by nature a lazy breed. We reuse code with functions, -classes, modules, and subsystems. Through its docstring syntax, -Python allows us to document our code from within. The "holy grail" -of the Python Documentation Special Interest Group (Doc-SIG_) has been -a markup syntax and toolset to allow auto-documentation, where the -docstrings of Python systems can be extracted in context and processed -into useful, high-quality documentation for multiple purposes. - -Document markup languages have three groups of customers: the authors -who write the documents, the software systems that process the data, -and the readers, who are the final consumers and the most important -group. Most markups are designed for the authors and software -systems; readers are only meant to see the processed form, either on -paper or via browser software. ReStructuredText is different: it is -intended to be easily readable in source form, without prior knowledge -of the markup. ReStructuredText is entirely readable in plaintext -format, and many of the markup forms match common usage (e.g., -``*emphasis*``), so it reads quite naturally. Yet it is rich enough -to produce complex documents, and extensible so that there are few -limits. Of course, to write reStructuredText documents some prior -knowledge is required. - -The markup offers functionality and expressivity, while maintaining -easy readability in the source text. The processed form (HTML etc.) -makes it all accessible to readers: inline live hyperlinks; live links -to and from footnotes; automatic tables of contents (with live -links!); tables; images for diagrams etc.; pleasant, readable styled -text. - -The reStructuredText parser is available now, part of the Docutils_ -project. Standalone reStructuredText documents and PEPs can be -converted to HTML; other output format writers are being worked on and -will become available over time. Work is progressing on a Python -source "Reader" which will implement auto-documentation from -docstrings. Authors of existing auto-documentation tools are -encouraged to integrate the reStructuredText parser into their -projects, or better yet, to join forces to produce a world-class -toolset for the Python standard library. - -Tools will become available in the near future, which will allow -programmers to generate HTML for online help, XML for multiple -purposes, and eventually PDF, DocBook, and LaTeX for printed -documentation, essentially "for free" from the existing docstrings. -The adoption of a standard will, at the very least, benefit docstring -processing tools by preventing further "reinventing the wheel". - -Eventually PyDoc, the one existing standard auto-documentation tool, -could have reStructuredText support added. In the interim it will -have no problem with reStructuredText markup, since it treats all -docstrings as preformatted plaintext. - - -Goals -===== - -These are the generally accepted goals for a docstring format, as -discussed in the Doc-SIG: - -1. It must be readable in source form by the casual observer. - -2. It must be easy to type with any standard text editor. - -3. It must not need to contain information which can be deduced from - parsing the module. - -4. It must contain sufficient information (structure) so it can be - converted to any reasonable markup format. - -5. It must be possible to write a module's entire documentation in - docstrings, without feeling hampered by the markup language. - -reStructuredText meets and exceeds all of these goals, and sets its -own goals as well, even more stringent. See `Docstring-Significant -Features`_ below. - -The goals of this PEP are as follows: - -1. To establish reStructuredText as a standard structured plaintext - format for docstrings (inline documentation of Python modules and - packages), PEPs, README-type files and other standalone documents. - "Accepted" status will be sought through Python community consensus - and eventual BDFL pronouncement. - - Please note that reStructuredText is being proposed as *a* - standard, not *the only* standard. Its use will be entirely - optional. Those who don't want to use it need not. - -2. To solicit and address any related concerns raised by the Python - community. - -3. To encourage community support. As long as multiple competing - markups are out there, the development community remains fractured. - Once a standard exists, people will start to use it, and momentum - will inevitably gather. - -4. To consolidate efforts from related auto-documentation projects. - It is hoped that interested developers will join forces and work on - a joint/merged/common implementation. - -Once reStructuredText is a Python standard, effort can be focused on -tools instead of arguing for a standard. Python needs a standard set -of documentation tools. - -With regard to PEPs, one or both of the following strategies may be -applied: - -a) Keep the existing PEP section structure constructs (one-line - section headers, indented body text). Subsections can either be - forbidden, or supported with reStructuredText-style underlined - headers in the indented body text. - -b) Replace the PEP section structure constructs with the - reStructuredText syntax. Section headers will require underlines, - subsections will be supported out of the box, and body text need - not be indented (except for block quotes). - -Strategy (b) is recommended, and its implementation is complete. - -Support for RFC 2822 headers has been added to the reStructuredText -parser for PEPs (unambiguous given a specific context: the first -contiguous block of the document). It may be desired to concretely -specify what over/underline styles are allowed for PEP section -headers, for uniformity. - - -Rationale -========= - -The lack of a standard syntax for docstrings has hampered the -development of standard tools for extracting and converting docstrings -into documentation in standard formats (e.g., HTML, DocBook, TeX). -There have been a number of proposed markup formats and variations, -and many tools tied to these proposals, but without a standard -docstring format they have failed to gain a strong following and/or -floundered half-finished. - -Throughout the existence of the Doc-SIG, consensus on a single -standard docstring format has never been reached. A lightweight, -implicit markup has been sought, for the following reasons (among -others): - -1. Docstrings written within Python code are available from within the - interactive interpreter, and can be "print"ed. Thus the use of - plaintext for easy readability. - -2. Programmers want to add structure to their docstrings, without - sacrificing raw docstring readability. Unadorned plaintext cannot - be transformed ("up-translated") into useful structured formats. - -3. Explicit markup (like XML or TeX) is widely considered unreadable - by the uninitiated. - -4. Implicit markup is aesthetically compatible with the clean and - minimalist Python syntax. - -Many alternative markups for docstrings have been proposed on the -Doc-SIG over the years; a representative sample is listed below. Each -is briefly analyzed in terms of the goals stated above. Please note -that this is *not* intended to be an exclusive list of all existing -markup systems; there are many other markups (Texinfo, Doxygen, TIM, -YODL, AFT, ...) which are not mentioned. - -- XML_, SGML_, DocBook_, HTML_, XHTML_ - - XML and SGML are explicit, well-formed meta-languages suitable for - all kinds of documentation. XML is a variant of SGML. They are - best used behind the scenes, because to untrained eyes they are - verbose, difficult to type, and too cluttered to read comfortably as - source. DocBook, HTML, and XHTML are all applications of SGML - and/or XML, and all share the same basic syntax and the same - shortcomings. - -- TeX_ - - TeX is similar to XML/SGML in that it's explicit, but not very easy - to write, and not easy for the uninitiated to read. - -- `Perl POD`_ - - Most Perl modules are documented in a format called POD (Plain Old - Documentation). This is an easy-to-type, very low level format with - strong integration with the Perl parser. Many tools exist to turn - POD documentation into other formats: info, HTML and man pages, - among others. However, the POD syntax takes after Perl itself in - terms of readability. - -- JavaDoc_ - - Special comments before Java classes and functions serve to document - the code. A program to extract these, and turn them into HTML - documentation is called javadoc, and is part of the standard Java - distribution. However, JavaDoc has a very intimate relationship - with HTML, using HTML tags for most markup. Thus it shares the - readability problems of HTML. - -- Setext_, StructuredText_ - - Early on, variants of Setext (Structure Enhanced Text), including - Zope Corp's StructuredText, were proposed for Python docstring - formatting. Hereafter these variants will collectively be called - "STexts". STexts have the advantage of being easy to read without - special knowledge, and relatively easy to write. - - Although used by some (including in most existing Python - auto-documentation tools), until now STexts have failed to become - standard because: - - - STexts have been incomplete. Lacking "essential" constructs that - people want to use in their docstrings, STexts are rendered less - than ideal. Note that these "essential" constructs are not - universal; everyone has their own requirements. - - - STexts have been sometimes surprising. Bits of text are - unexpectedly interpreted as being marked up, leading to user - frustration. - - - SText implementations have been buggy. - - - Most STexts have have had no formal specification except for the - implementation itself. A buggy implementation meant a buggy spec, - and vice-versa. - - - There has been no mechanism to get around the SText markup rules - when a markup character is used in a non-markup context. In other - words, no way to escape markup. - -Proponents of implicit STexts have vigorously opposed proposals for -explicit markup (XML, HTML, TeX, POD, etc.), and the debates have -continued off and on since 1996 or earlier. - -reStructuredText is a complete revision and reinterpretation of the -SText idea, addressing all of the problems listed above. - - -Specification -============= - -The specification and user documentaton for reStructuredText is -quite extensive. Rather than repeating or summarizing it all -here, links to the originals are provided. - -Please first take a look at `A ReStructuredText Primer`_, a short and -gentle introduction. The `Quick reStructuredText`_ user reference -quickly summarizes all of the markup constructs. For complete and -extensive details, please refer to the following documents: - -- `An Introduction to reStructuredText`_ - -- `reStructuredText Markup Specification`_ - -- `reStructuredText Directives`_ - -In addition, `Problems With StructuredText`_ explains many markup -decisions made with regards to StructuredText, and `A Record of -reStructuredText Syntax Alternatives`_ records markup decisions made -independently. - - -Docstring-Significant Features -============================== - -- A markup escaping mechanism. - - Backslashes (``\``) are used to escape markup characters when needed - for non-markup purposes. However, the inline markup recognition - rules have been constructed in order to minimize the need for - backslash-escapes. For example, although asterisks are used for - *emphasis*, in non-markup contexts such as "*" or "(*)" or "x * y", - the asterisks are not interpreted as markup and are left unchanged. - For many non-markup uses of backslashes (e.g., describing regular - expressions), inline literals or literal blocks are applicable; see - the next item. - -- Markup to include Python source code and Python interactive - sessions: inline literals, literal blocks, and doctest blocks. - - Inline literals use ``double-backquotes`` to indicate program I/O or - code snippets. No markup interpretation (including backslash-escape - [``\``] interpretation) is done within inline literals. - - Literal blocks (block-level literal text, such as code excerpts or - ASCII graphics) are indented, and indicated with a double-colon - ("::") at the end of the preceding paragraph (right here -->):: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - - Doctest blocks begin with ">>> " and end with a blank line. Neither - indentation nor literal block double-colons are required. For - example:: - - Here's a doctest block: - - >>> print 'Python-specific usage examples; begun with ">>>"' - Python-specific usage examples; begun with ">>>" - >>> print '(cut and pasted from interactive sessions)' - (cut and pasted from interactive sessions) - -- Markup that isolates a Python identifier: interpreted text. - - Text enclosed in single backquotes is recognized as "interpreted - text", whose interpretation is application-dependent. In the - context of a Python docstring, the default interpretation of - interpreted text is as Python identifiers. The text will be marked - up with a hyperlink connected to the documentation for the - identifier given. Lookup rules are the same as in Python itself: - LGB namespace lookups (local, global, builtin). The "role" of the - interpreted text (identifying a class, module, function, etc.) is - determined implicitly from the namespace lookup. For example:: - - class Keeper(Storer): - - """ - Keep data fresher longer. - - Extend `Storer`. Class attribute `instances` keeps track - of the number of `Keeper` objects instantiated. - """ - - instances = 0 - """How many `Keeper` objects are there?""" - - def __init__(self): - """ - Extend `Storer.__init__()` to keep track of - instances. Keep count in `self.instances` and data - in `self.data`. - """ - Storer.__init__(self) - self.instances += 1 - - self.data = [] - """Store data in a list, most recent last.""" - - def storedata(self, data): - """ - Extend `Storer.storedata()`; append new `data` to a - list (in `self.data`). - """ - self.data = data - - Each piece of interpreted text is looked up according to the local - namespace of the block containing its docstring. - -- Markup that isolates a Python identifier and specifies its type: - interpreted text with roles. - - Although the Python source context reader is designed not to require - explicit roles, they may be used. To classify identifiers - explicitly, the role is given along with the identifier in either - prefix or suffix form:: - - Use :method:`Keeper.storedata` to store the object's data in - `Keeper.data`:instance_attribute:. - - The syntax chosen for roles is verbose, but necessarily so (if - anyone has a better alternative, please post it to the Doc-SIG_). - The intention of the markup is that there should be little need to - use explicit roles; their use is to be kept to an absolute minimum. - -- Markup for "tagged lists" or "label lists": field lists. - - Field lists represent a mapping from field name to field body. - These are mostly used for extension syntax, such as "bibliographic - field lists" (representing document metadata such as author, date, - and version) and extension attributes for directives (see below). - They may be used to implement methodologies (docstring semantics), - such as identifying parameters, exceptions raised, etc.; such usage - is beyond the scope of this PEP. - - A modified RFC 2822 syntax is used, with a colon *before* as well as - *after* the field name. Field bodies are more versatile as well; - they may contain multiple field bodies (even nested field lists). - For example:: - - :Date: 2002-03-22 - :Version: 1 - :Authors: - - Me - - Myself - - I - - Standard RFC 2822 header syntax cannot be used for this construct - because it is ambiguous. A word followed by a colon at the - beginning of a line is common in written text. - -- Markup extensibility: directives and substitutions. - - Directives are used as an extension mechanism for reStructuredText, - a way of adding support for new block-level constructs without - adding new syntax. Directives for images, admonitions (note, - caution, etc.), and tables of contents generation (among others) - have been implemented. For example, here's how to place an image:: - - .. image:: mylogo.png - - Substitution definitions allow the power and flexibility of - block-level directives to be shared by inline text. For example:: - - The |biohazard| symbol must be used on containers used to - dispose of medical waste. - - .. |biohazard| image:: biohazard.png - -- Section structure markup. - - Section headers in reStructuredText use adornment via underlines - (and possibly overlines) rather than indentation. For example:: - - This is a Section Title - ======================= - - This is a Subsection Title - -------------------------- - - This paragraph is in the subsection. - - This is Another Section Title - ============================= - - This paragraph is in the second section. - - -Questions & Answers -=================== - -1. Is reStructuredText rich enough? - - Yes, it is for most people. If it lacks some construct that is - required for a specific application, it can be added via the - directive mechanism. If a useful and common construct has been - overlooked and a suitably readable syntax can be found, it can be - added to the specification and parser. - -2. Is reStructuredText *too* rich? - - For specific applications or individuals, perhaps. In general, no. - - Since the very beginning, whenever a docstring markup syntax has - been proposed on the Doc-SIG_, someone has complained about the - lack of support for some construct or other. The reply was often - something like, "These are docstrings we're talking about, and - docstrings shouldn't have complex markup." The problem is that a - construct that seems superfluous to one person may be absolutely - essential to another. - - reStructuredText takes the opposite approach: it provides a rich - set of implicit markup constructs (plus a generic extension - mechanism for explicit markup), allowing for all kinds of - documents. If the set of constructs is too rich for a particular - application, the unused constructs can either be removed from the - parser (via application-specific overrides) or simply omitted by - convention. - -3. Why not use indentation for section structure, like StructuredText - does? Isn't it more "Pythonic"? - - Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post: - - I still think that using indentation to indicate sectioning is - wrong. If you look at how real books and other print - publications are laid out, you'll notice that indentation is - used frequently, but mostly at the intra-section level. - Indentation can be used to offset lists, tables, quotations, - examples, and the like. (The argument that docstrings are - different because they are input for a text formatter is wrong: - the whole point is that they are also readable without - processing.) - - I reject the argument that using indentation is Pythonic: text - is not code, and different traditions and conventions hold. - People have been presenting text for readability for over 30 - centuries. Let's not innovate needlessly. - - See `Section Structure via Indentation`__ in `Problems With - StructuredText`_ for further elaboration. - - __ http://docutils.sourceforge.net/docs/dev/rst/problems.html - #section-structure-via-indentation - -4. Why use reStructuredText for PEPs? What's wrong with the existing - standard? - - The existing standard for PEPs is very limited in terms of general - expressibility, and referencing is especially lacking for such a - reference-rich document type. PEPs are currently converted into - HTML, but the results (mostly monospaced text) are less than - attractive, and most of the value-added potential of HTML - (especially inline hyperlinks) is untapped. - - Making reStructuredText a standard markup for PEPs will enable much - richer expression, including support for section structure, inline - markup, graphics, and tables. In several PEPs there are ASCII - graphics diagrams, which are all that plaintext documents can - support. Since PEPs are made available in HTML form, the ability - to include proper diagrams would be immediately useful. - - Current PEP practices allow for reference markers in the form "[1]" - in the text, and the footnotes/references themselves are listed in - a section toward the end of the document. There is currently no - hyperlinking between the reference marker and the - footnote/reference itself (it would be possible to add this to - pep2html.py, but the "markup" as it stands is ambiguous and - mistakes would be inevitable). A PEP with many references (such as - this one ;-) requires a lot of flipping back and forth. When - revising a PEP, often new references are added or unused references - deleted. It is painful to renumber the references, since it has to - be done in two places and can have a cascading effect (insert a - single new reference 1, and every other reference has to be - renumbered; always adding new references to the end is suboptimal). - It is easy for references to go out of sync. - - PEPs use references for two purposes: simple URL references and - footnotes. reStructuredText differentiates between the two. A PEP - might contain references like this:: - - Abstract - - This PEP proposes adding frungible doodads [1] to the core. - It extends PEP 9876 [2] via the BCA [3] mechanism. - - ... - - References and Footnotes - - [1] http://www.example.org/ - - [2] PEP 9876, Let's Hope We Never Get Here - http://www.python.org/peps/pep-9876.html - - [3] "Bogus Complexity Addition" - - Reference 1 is a simple URL reference. Reference 2 is a footnote - containing text and a URL. Reference 3 is a footnote containing - text only. Rewritten using reStructuredText, this PEP could look - like this:: - - Abstract - ======== - - This PEP proposes adding `frungible doodads`_ to the core. It - extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism. - - ... - - References & Footnotes - ====================== - - .. _frungible doodads: http://www.example.org/ - - .. [#pep9876] PEP 9876, Let's Hope We Never Get Here - - .. [#] "Bogus Complexity Addition" - - URLs and footnotes can be defined close to their references if - desired, making them easier to read in the source text, and making - the PEPs easier to revise. The "References and Footnotes" section - can be auto-generated with a document tree transform. Footnotes - from throughout the PEP would be gathered and displayed under a - standard header. If URL references should likewise be written out - explicitly (in citation form), another tree transform could be - used. - - URL references can be named ("frungible doodads"), and can be - referenced from multiple places in the document without additional - definitions. When converted to HTML, references will be replaced - with inline hyperlinks (HTML <a> tags). The two footnotes are - automatically numbered, so they will always stay in sync. The - first footnote also contains an internal reference name, "pep9876", - so it's easier to see the connection between reference and footnote - in the source text. Named footnotes can be referenced multiple - times, maintaining consistent numbering. - - The "#pep9876" footnote could also be written in the form of a - citation:: - - It extends PEP 9876 [PEP9876]_ ... - - .. [PEP9876] PEP 9876, Let's Hope We Never Get Here - - Footnotes are numbered, whereas citations use text for their - references. - -5. Wouldn't it be better to keep the docstring and PEP proposals - separate? - - The PEP markup proposal may be removed if it is deemed that there - is no need for PEP markup, or it could be made into a separate PEP. - If accepted, PEP 1, PEP Purpose and Guidelines [#PEP-1]_, and PEP - 9, Sample PEP Template [#PEP-9]_ will be updated. - - It seems natural to adopt a single consistent markup standard for - all uses of structured plaintext in Python, and to propose it all - in one place. - -6. The existing pep2html.py script converts the existing PEP format to - HTML. How will the new-format PEPs be converted to HTML? - - A new version of pep2html.py with integrated reStructuredText - parsing has been completed. The Docutils project supports PEPs - with a "PEP Reader" component, including all functionality - currently in pep2html.py (auto-recognition of PEP & RFC references, - email masking, etc.). - -7. Who's going to convert the existing PEPs to reStructuredText? - - PEP authors or volunteers may convert existing PEPs if they like, - but there is no requirement to do so. The reStructuredText-based - PEPs will coexist with the old PEP standard. The pep2html.py - mentioned in answer 6 processes both old and new standards. - -8. Why use reStructuredText for README and other ancillary files? - - The reasoning given for PEPs in answer 4 above also applies to - README and other ancillary files. By adopting a standard markup, - these files can be converted to attractive cross-referenced HTML - and put up on python.org. Developers of other projects can also - take advantage of this facility for their own documentation. - -9. Won't the superficial similarity to existing markup conventions - cause problems, and result in people writing invalid markup (and - not noticing, because the plaintext looks natural)? How forgiving - is reStructuredText of "not quite right" markup? - - There will be some mis-steps, as there would be when moving from - one programming language to another. As with any language, - proficiency grows with experience. Luckily, reStructuredText is a - very little language indeed. - - As with any syntax, there is the possibility of syntax errors. It - is expected that a user will run the processing system over their - input and check the output for correctness. - - In a strict sense, the reStructuredText parser is very unforgiving - (as it should be; "In the face of ambiguity, refuse the temptation - to guess" [#Zen]_ applies to parsing markup as well as computer - languages). Here's design goal 3 from `An Introduction to - reStructuredText`_: - - Unambiguous. The rules for markup must not be open for - interpretation. For any given input, there should be one and - only one possible output (including error output). - - While unforgiving, at the same time the parser does try to be - helpful by producing useful diagnostic output ("system messages"). - The parser reports problems, indicating their level of severity - (from least to most: debug, info, warning, error, severe). The - user or the client software can decide on reporting thresholds; - they can ignore low-level problems or cause high-level problems to - bring processing to an immediate halt. Problems are reported - during the parse as well as included in the output, often with - two-way links between the source of the problem and the system - message explaining it. - -10. Will the docstrings in the Python standard library modules be - converted to reStructuredText? - - No. Python's library reference documentation is maintained - separately from the source. Docstrings in the Python standard - library should not try to duplicate the library reference - documentation. The current policy for docstrings in the Python - standard library is that they should be no more than concise - hints, simple and markup-free (although many *do* contain ad-hoc - implicit markup). - -11. I want to write all my strings in Unicode. Will anything - break? - - The parser fully supports Unicode. Docutils supports arbitrary - input and output encodings. - -12. Why does the community need a new structured text design? - - The existing structured text designs are deficient, for the - reasons given in "Rationale" above. reStructuredText aims to be a - complete markup syntax, within the limitations of the "readable - plaintext" medium. - -13. What is wrong with existing documentation methodologies? - - What existing methodologies? For Python docstrings, there is - **no** official standard markup format, let alone a documentation - methodology akin to JavaDoc. The question of methodology is at a - much higher level than syntax (which this PEP addresses). It is - potentially much more controversial and difficult to resolve, and - is intentionally left out of this discussion. - - -References & Footnotes -====================== - -.. [#PEP-1] PEP 1, PEP Guidelines, Warsaw, Hylton - (http://www.python.org/peps/pep-0001.html) - -.. [#PEP-9] PEP 9, Sample PEP Template, Warsaw - (http://www.python.org/peps/pep-0009.html) - -.. [#Zen] From `The Zen of Python (by Tim Peters)`__ (or just - "``import this``" in Python) - -__ http://www.python.org/doc/Humor.html#zen - -.. [#PEP-216] PEP 216, Docstring Format, Zadka - (http://www.python.org/peps/pep-0216.html) - -.. _reStructuredText markup: http://docutils.sourceforge.net/rst.html - -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - -.. _XML: http://www.w3.org/XML/ - -.. _SGML: http://www.oasis-open.org/cover/general.html - -.. _DocBook: http://docbook.org/tdg/en/html/docbook.html - -.. _HTML: http://www.w3.org/MarkUp/ - -.. _XHTML: http://www.w3.org/MarkUp/#xhtml1 - -.. _TeX: http://www.tug.org/interest.html - -.. _Perl POD: http://perldoc.perl.org/perlpod.html - -.. _JavaDoc: http://java.sun.com/j2se/javadoc/ - -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html - -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage - -.. _A ReStructuredText Primer: - http://docutils.sourceforge.net/docs/user/rst/quickstart.html - -.. _Quick reStructuredText: - http://docutils.sourceforge.net/docs/user/rst/quickref.html - -.. _An Introduction to reStructuredText: - http://docutils.sourceforge.net/docs/ref/rst/introduction.html - -.. _reStructuredText Markup Specification: - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html - -.. _reStructuredText Directives: - http://docutils.sourceforge.net/docs/ref/rst/directives.html - -.. _Problems with StructuredText: - http://docutils.sourceforge.net/docs/dev/rst/problems.html - -.. _A Record of reStructuredText Syntax Alternatives: - http://docutils.sourceforge.net/docs/dev/rst/alternatives.html - -.. _Docutils: http://docutils.sourceforge.net/ - - -Copyright -========= - -This document has been placed in the public domain. - - -Acknowledgements -================ - -Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by -Moshe Zadka. - -Special thanks to all members past & present of the Python Doc-SIG_. - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt deleted file mode 100644 index 25e5f9594..000000000 --- a/docutils/docs/ref/doctree.txt +++ /dev/null @@ -1,4970 +0,0 @@ -============================ - The Docutils Document Tree -============================ - -A Guide to the Docutils DTD -*************************** - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - - -.. contents:: :depth: 1 - - -This document describes the XML data structure of Docutils_ documents: -the relationships and semantics of elements and attributes. The -Docutils document structure is formally defined by the `Docutils -Generic DTD`_ XML document type definition, docutils.dtd_, which is -the definitive source for details of element structural relationships. - -This document does not discuss implementation details. Those can be -found in internal documentation (docstrings) for the -``docutils.nodes`` module, where the document tree data structure is -implemented in a class library. - -The reader is assumed to have some familiarity with XML or SGML, and -an understanding of the data structure meaning of "tree". For a list -of introductory articles, see `Introducing the Extensible Markup -Language (XML)`_. - -The reStructuredText_ markup is used for illustrative examples -throughout this document. For a gentle introduction, see `A -ReStructuredText Primer`_. For complete technical details, see the -`reStructuredText Markup Specification`_. - - -.. _Docutils: http://docutils.sourceforge.net/ -.. _Docutils Generic DTD: -.. _Docutils DTD: -.. _docutils.dtd: docutils.dtd -.. _Introducing the Extensible Markup Language (XML): - http://xml.coverpages.org/xmlIntro.html -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _A ReStructuredText Primer: ../user/rst/quickstart.html -.. _reStructuredText Markup Specification: rst/restructuredtext.html - - -------------------- - Element Hierarchy -------------------- - -.. contents:: :local: - -Below is a simplified diagram of the hierarchy of elements in the -Docutils document tree structure. An element may contain any other -elements immediately below it in the diagram. Notes are written in -square brackets. Element types in parentheses indicate recursive or -one-to-many relationships; sections may contain (sub)sections, tables -contain further body elements, etc. :: - - +--------------------------------------------------------------------+ - | document [may begin with a title, subtitle, decoration, docinfo] | - | +--------------------------------------+ - | | sections [each begins with a title] | - +-----------------------------+-------------------------+------------+ - | [body elements:] | (sections) | - | | - literal | - lists | | - hyperlink +------------+ - | | blocks | - tables | | targets | - | para- | - doctest | - block | foot- | - sub. defs | - | graphs | blocks | quotes | notes | - comments | - +---------+-----------+----------+-------+--------------+ - | [text]+ | [text] | (body elements) | [text] | - | (inline +-----------+------------------+--------------+ - | markup) | - +---------+ - -The Docutils document model uses a simple, recursive model for section -structure. A document_ node may contain body elements and section_ -elements. Sections in turn may contain body elements and sections. -The level (depth) of a section element is determined from its physical -nesting level; unlike other document models (``<h1>`` in HTML_, -``<sect1>`` in DocBook_, ``<div1>`` in XMLSpec_) the level is not -incorporated into the element name. - -The Docutils document model uses strict element content models. Every -element has a unique structure and semantics, but elements may be -classified into general categories (below). Only elements which are -meant to directly contain text data have a mixed content model, where -text data and inline elements may be intermixed. This is unlike the -much looser HTML_ document model, where paragraphs and text data may -occur at the same level. - - -Structural Elements -=================== - -Structural elements may only contain child elements; they do not -directly contain text data. Structural elements may contain body -elements or further structural elements. Structural elements can only -be child elements of other structural elements. - -Category members: document_, section_, topic_, sidebar_ - - -Structural Subelements ----------------------- - -Structural subelements are child elements of structural elements. -Simple structuctural subelements (title_, subtitle_) contain text -data; the others are compound and do not directly contain text data. - -Category members: title_, subtitle_, decoration_, docinfo_, -transition_ - - -Bibliographic Elements -`````````````````````` - -The docinfo_ element is an optional child of document_. It groups -bibliographic elements together. All bibliographic elements except -authors_ and field_ contain text data. authors_ contains further -bibliographic elements (most notably author_). field_ contains -field_name_ and field_body_ body subelements. - -Category members: address_, author_, authors_, contact_, copyright_, -date_, field_, organization_, revision_, status_, version_ - - -Decorative Elements -``````````````````` - -The decoration_ element is also an optional child of document_. It -groups together elements used to generate page headers and footers. - -Category members: footer_, header_ - - -Body Elements -============= - -Body elements are contained within structural elements and compound -body elements. There are two subcategories of body elements: simple -and compound. - -Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, comment_, compound_, container_, danger_, -definition_list_, doctest_block_, enumerated_list_, error_, -field_list_, figure_, footnote_, hint_, image_, important_, -line_block_, literal_block_, note_, option_list_, paragraph_, -pending_, raw_, rubric_, substitution_definition_, system_message_, -table_, target_, tip_, warning_ - - -Simple Body Elements --------------------- - -Simple body elements are empty or directly contain text data. Those -that contain text data may also contain inline elements. Such -elements therefore have a "mixed content model". - -Category members: comment_, doctest_block_, image_, literal_block_, -paragraph_, pending_, raw_, rubric_, substitution_definition_, target_ - - -Compound Body Elements ----------------------- - -Compound body elements contain local substructure (body subelements) -and further body elements. They do not directly contain text data. - -Category members: admonition_, attention_, block_quote_, bullet_list_, -caution_, citation_, compound_, container_, danger_, definition_list_, -enumerated_list_, error_, field_list_, figure_, footnote_, hint_, -important_, line_block, note_, option_list_, system_message_, table_, -tip_, warning_ - - -Body Subelements -```````````````` - -Compound body elements contain specific subelements (e.g. bullet_list_ -contains list_item_). Subelements may themselves be compound elements -(containing further child elements, like field_) or simple data -elements (containing text data, like field_name_). These subelements -always occur within specific parent elements, never at the body -element level (beside paragraphs, etc.). - -Category members (simple): attribution_, caption_, classifier_, -colspec_, field_name_, label_, line_, option_argument_, -option_string_, term_ - -Category members (compound): definition_, definition_list_item_, -description_, entry_, field_, field_body_, legend_, list_item_, -option_, option_group_, option_list_item_, row_, tbody_, tgroup_, -thead_ - - -Inline Elements -=============== - -Inline elements directly contain text data, and may also contain -further inline elements. Inline elements are contained within simple -body elements. Most inline elements have a "mixed content model". - -Category members: abbreviation_, acronym_, citation_reference_, -emphasis_, footnote_reference_, generated_, image_, inline_, literal_, -problematic_, reference_, strong_, subscript_, -substitution_reference_, superscript_, target_, title_reference_, raw_ - - -.. _HTML: http://www.w3.org/MarkUp/ -.. _DocBook: http://docbook.org/tdg/en/html/docbook.html -.. _XMLSpec: http://www.w3.org/XML/1998/06/xmlspec-report.htm - - -------------------- - Element Reference -------------------- - -.. contents:: :local: - :depth: 1 - -Each element in the DTD (document type definition) is described in its -own section below. Each section contains an introduction plus the -following subsections: - -* Details (of element relationships and semantics): - - - Category: One or more references to the element categories in - `Element Hierarchy`_ above. Some elements belong to more than one - category. - - - Parents: A list of elements which may contain the element. - - - Children: A list of elements which may occur within the element. - - - Analogues: Describes analogous elements in well-known document - models such as HTML_ or DocBook_. Lists similarities and - differences. - - - Processing: Lists formatting or rendering recommendations for the - element. - -* Content Model: - - The formal XML content model from the `Docutils DTD`_, followed by: - - - Attributes: Describes (or refers to descriptions of) the possible - values and semantics of each attribute. - - - Parameter Entities: Lists the parameter entities which directly or - indirectly include the element. - -* Examples: reStructuredText_ examples are shown along with - fragments of the document trees resulting from parsing. - _`Pseudo-XML` is used for the results of parsing and processing. - Pseudo-XML is a representation of XML where nesting is indicated by - indentation and end-tags are not shown. Some of the precision of - real XML is given up in exchange for easier readability. For - example, the following are equivalent: - - - Real XML:: - - <document> - <section ids="a-title" names="a title"> - <title>A Title</title> - <paragraph>A paragraph.</paragraph> - </section> - </document> - - - Pseudo-XML:: - - <document> - <section ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - --------------------- - -Many of the element reference sections below are marked "_`to be -completed`". Please help complete this document by contributing to -its writing. - - -``abbreviation`` -================ - -`To be completed`_. - - -``acronym`` -=========== - -`To be completed`_. - - -``address`` -=========== - -The ``address`` element holds the surface mailing address information -for the author (individual or group) of the document, or a third-party -contact address. Its structure is identical to that of the -literal_block_ element: whitespace is significant, especially -newlines. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - The following elements may contain ``address``: docinfo_, authors_ - -:Children: - ``address`` elements contain text data plus `inline elements`_. - -:Analogues: - ``address`` is analogous to the DocBook "address" element. - -:Processing: - As with the literal_block_ element, newlines and other whitespace - is significant and must be preserved. However, a monospaced - typeface need not be used. - - See also docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``address`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``address``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Address: 123 Example Ave. - Example, EX - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <address> - 123 Example Ave. - Example, EX - -See docinfo_ for a more complete example, including processing -context. - - -``admonition`` -============== - -This element is a generic, titled admonition. Also see the specific -admonition elements Docutils offers (in alphabetical order): caution_, -danger_, error_, hint_, important_, note_, tip_, warning_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``admonition``. - -:Children: - ``admonition`` elements begin with a title_ and may contain one or - more `body elements`_. - -:Analogues: - ``admonition`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.). - - -Content Model -------------- - -.. parsed-literal:: - - (title_, (`%body.elements;`_)+) - -:Attributes: - The ``admonition`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``admonition``. The `%structure.model;`_ parameter entity - indirectly includes ``admonition``. - - -Examples --------- - -reStructuredText source:: - - .. admonition:: And, by the way... - - You can make up your own admonition too. - -Pseudo-XML_ fragment from simple parsing:: - - <admonition class="admonition-and-by-the-way"> - <title> - And, by the way... - <paragraph> - You can make up your own admonition too. - - -``attention`` -============= - -The ``attention`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): caution_, danger_, error_, -hint_, important_, note_, tip_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``attention``. - -:Children: - ``attention`` elements contain one or more `body elements`_. - -:Analogues: - ``attention`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Attention!" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``attention`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``attention``. The `%structure.model;`_ parameter entity - indirectly includes ``attention``. - - -Examples --------- - -reStructuredText source:: - - .. Attention:: All your base are belong to us. - -Pseudo-XML_ fragment from simple parsing:: - - <attention> - <paragraph> - All your base are belong to us. - - -``attribution`` -=============== - -`To be completed`_. - - -``author`` -========== - -The ``author`` element holds the name of the author of the document. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - The following elements may contain ``author``: docinfo_, authors_ - -:Children: - ``author`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``author`` is analogous to the DocBook "author" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``author`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``author``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Author: J. Random Hacker - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <author> - J. Random Hacker - -See docinfo_ for a more complete example, including processing -context. - - -``authors`` -=========== - -The ``authors`` element is a container for author information for -documents with multiple authors. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``authors``. - -:Children: - ``authors`` elements may contain the following elements: author_, - organization_, address_, contact_ - -:Analogues: - ``authors`` is analogous to the DocBook "authors" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - ((author_, organization_?, address_?, contact_?)+) - -:Attributes: - The ``authors`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``authors``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Authors: J. Random Hacker; Jane Doe - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <authors> - <author> - J. Random Hacker - <author> - Jane Doe - -In reStructuredText, multiple author's names are separated with -semicolons (";") or commas (","); semicolons take precedence. There -is currently no way to represent the author's organization, address, -or contact in a reStructuredText "Authors" field. - -See docinfo_ for a more complete example, including processing -context. - - -``block_quote`` -=============== - -The ``block_quote`` element is used for quotations set off from the -main text (standalone). - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``block_quote``. - -:Children: - ``block_quote`` elements contain `body elements`_ followed by an - optional attribution_ element. - -:Analogues: - ``block_quote`` is analogous to the "blockquote" element in both - HTML and DocBook. - -:Processing: - ``block_quote`` elements serve to set their contents off from the - main text, typically with indentation and/or other decoration. - - -Content Model -------------- - -.. parsed-literal:: - - ((`%body.elements;`_)+, attribution_?) - -:Attributes: - The ``block_quote`` element contains only the `common - attributes`_: ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``block_quote``. The `%structure.model;`_ parameter entity - indirectly includes ``block_quote``. - - -Examples --------- - -reStructuredText source:: - - As a great paleontologist once said, - - This theory, that is mine, is mine. - - -- Anne Elk (Miss) - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - As a great paleontologist once said, - <block_quote> - <paragraph> - This theory, that is mine, is mine. - <attribution> - Anne Elk (Miss) - - -``bullet_list`` -=============== - -The ``bullet_list`` element contains list_item_ elements which are -uniformly marked with bullets. Bullets are typically simple dingbats -(symbols) such as circles and squares. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``bullet_list``. - -:Children: - ``bullet_list`` elements contain one or more list_item_ elements. - -:Analogues: - ``bullet_list`` is analogous to the HTML "ul" element and to the - DocBook "itemizedlist" element. HTML's "ul" is short for - "unordered list", which we consider to be a misnomer. "Unordered" - implies that the list items may be randomly rearranged without - affecting the meaning of the list. Bullet lists *are* often - ordered; the ordering is simply left implicit. - -:Processing: - Each list item should begin a new vertical block, prefaced by a - bullet/dingbat. - - -Content Model -------------- - -.. parsed-literal:: - - (list_item_ +) - -:Attributes: - The ``bullet_list`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus bullet_. - - ``bullet`` is used to record the style of bullet from the input - data. In documents processed from reStructuredText_, it contains - one of "-", "+", or "*". It may be ignored in processing. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``bullet_list``. The `%structure.model;`_ parameter entity - indirectly includes ``bullet_list``. - - -Examples --------- - -reStructuredText_ source:: - - - Item 1, paragraph 1. - - Item 1, paragraph 2. - - - Item 2. - -Pseudo-XML_ fragment from simple parsing:: - - <bullet_list bullet="-"> - <list_item> - <paragraph> - Item 1, paragraph 1. - <paragraph> - Item 1, paragraph 2. - <list_item> - <paragraph> - Item 2. - -See list_item_ for another example. - - -``caption`` -=========== - -`To be completed`_. - - -``caution`` -=========== - -The ``caution`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, danger_, error_, -hint_, important_, note_, tip_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``caution``. - -:Children: - ``caution`` elements contain one or more `body elements`_. - -:Analogues: - ``caution`` is analogous to the DocBook "caution" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Caution" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``caution`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``caution``. The `%structure.model;`_ parameter entity - indirectly includes ``caution``. - - -Examples --------- - -reStructuredText source:: - - .. Caution:: Don't take any wooden nickels. - -Pseudo-XML_ fragment from simple parsing:: - - <caution> - <paragraph> - Don't take any wooden nickels. - - -``citation`` -============ - -`To be completed`_. - - -``citation_reference`` -====================== - -`To be completed`_. - - -``classifier`` -============== - -The ``classifier`` element contains the classification or type of the -term_ being defined in a definition_list_. For example, it can be -used to indicate the type of a variable. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the definition_list_item_ element contains ``classifier``. - -:Children: - ``classifier`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``classifier`` has no direct analogues in common DTDs. It can be - emulated with primitives or type effects. - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``classifier`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -Here is a hypothetical data dictionary. reStructuredText_ source:: - - name : string - Customer name. - i : int - Temporary index variable. - -Pseudo-XML_ fragment from simple parsing:: - - <definition_list> - <definition_list_item> - <term> - name - <classifier> - string - <definition> - <paragraph> - Customer name. - <definition_list_item> - <term> - i - <classifier> - int - <definition> - <paragraph> - Temporary index variable. - - -``colspec`` -=========== - -`To be completed`_. - - -``comment`` -=========== - -`To be completed`_. - - -``compound`` -============ - -`To be completed`_. - - -``contact`` -=========== - -The ``contact`` element holds contact information for the author -(individual or group) of the document, or a third-party contact. It -is typically used for an email or web address. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - The following elements may contain ``contact``: docinfo_, authors_ - -:Children: - ``contact`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``contact`` is analogous to the DocBook "email" element. The HTML - "address" element serves a similar purpose. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``contact`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``contact``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Contact: jrh@example.com - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <contact> - <reference refuri="mailto:jrh@example.com"> - jrh@example.com - -See docinfo_ for a more complete example, including processing -context. - - -``container`` -============= - -`To be completed`_. - - -``copyright`` -============= - -The ``copyright`` element contains the document's copyright statement. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``copyright``. - -:Children: - ``copyright`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``copyright`` is analogous to the DocBook "copyright" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``copyright`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``copyright``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Copyright: This document has been placed in the public domain. - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <copyright> - This document has been placed in the public domain. - -See docinfo_ for a more complete example, including processing -context. - - -``danger`` -========== - -The ``danger`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, error_, -hint_, important_, note_, tip_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``danger``. - -:Children: - ``danger`` elements contain one or more `body elements`_. - -:Analogues: - ``danger`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "!DANGER!" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``danger`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``danger``. The `%structure.model;`_ parameter entity - indirectly includes ``danger``. - - -Examples --------- - -reStructuredText source:: - - .. DANGER:: Mad scientist at work! - -Pseudo-XML_ fragment from simple parsing:: - - <danger> - <paragraph> - Mad scientist at work! - - -``date`` -======== - -The ``date`` element contains the date of publication, release, or -last modification of the document. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``date``. - -:Children: - ``date`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``date`` is analogous to the DocBook "date" element. - -:Processing: - Often used with the RCS/CVS keyword "Date". See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``date`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``date``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Date: 2002-08-20 - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <date> - 2002-08-20 - -See docinfo_ for a more complete example, including processing -context. - - -``decoration`` -============== - -The ``decoration`` element is a container for header_ and footer_ -elements and potential future extensions. These elements are used for -notes, time/datestamp, processing information, etc. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - Only the document_ element contains ``decoration``. - -:Children: - ``decoration`` elements may contain `decorative elements`_. - -:Analogues: - There are no direct analogies to ``decoration`` in HTML or in - DocBook. Equivalents are typically constructed from primitives - and/or generated by the processing system. - -:Processing: - See the individual `decorative elements`_. - - -Content Model -------------- - -.. parsed-literal:: - - (header_?, footer_?) - -Although the content model doesn't specifically require contents, no -empty ``decoration`` elements are ever created. - -:Attributes: - The ``decoration`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - A paragraph. - -Complete pseudo-XML_ result after parsing and applying transforms, -assuming that the datestamp command-line option or configuration -setting has been supplied:: - - <document> - <decoration> - <footer> - <paragraph> - Generated on: 2002-08-20. - <paragraph> - A paragraph. - - -``definition`` -============== - -The ``definition`` element is a container for the body elements used -to define a term_ in a definition_list_. - - -Details -------- - -:Category: - `Body Subelements`_ (compound) - -:Parents: - Only definition_list_item_ elements contain ``definition``. - -:Children: - ``definition`` elements may contain `body elements`_. - -:Analogues: - ``definition`` is analogous to the HTML "dd" element and to the - DocBook "listitem" element (inside a "variablelistentry" element). - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``definition`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the definition_list_, definition_list_item_, and -classifier_ elements. - - -``definition_list`` -=================== - -The ``definition_list`` element contains a list of terms and their -definitions. It can be used for glossaries or dictionaries, to -describe or classify things, for dialogues, or to itemize subtopics -(such as in this reference). - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``definition_list``. - -:Children: - ``definition_list`` elements contain one or more - definition_list_item_ elements. - -:Analogues: - ``definition_list`` is analogous to the HTML "dl" element and to - the DocBook "variablelist" element. - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - (definition_list_item_ +) - -:Attributes: - The ``definition_list`` element contains only the `common - attributes`_: ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``definition_list``. The `%structure.model;`_ parameter entity - indirectly includes ``definition_list``. - - -Examples --------- - -reStructuredText_ source:: - - Term - Definition. - - Term : classifier - The ' : ' indicates a classifier in - definition list item terms only. - -Pseudo-XML_ fragment from simple parsing:: - - <definition_list> - <definition_list_item> - <term> - Term - <definition> - <paragraph> - Definition. - <definition_list_item> - <term> - Term - <classifier> - classifier - <definition> - <paragraph> - The ' : ' indicates a classifier in - definition list item terms only. - -See definition_list_item_ and classifier_ for further examples. - - -``definition_list_item`` -======================== - -The ``definition_list_item`` element contains a single -term_/definition_ pair (with optional classifier_). - - -Details -------- - -:Category: - `Body Subelements`_ (compound) - -:Parents: - Only the definition_list_ element contains - ``definition_list_item``. - -:Children: - ``definition_list_item`` elements each contain a single term_, - an optional classifier_, and a definition_. - -:Analogues: - ``definition_list_item`` is analogous to the DocBook - "variablelistentry" element. - -:Processing: - The optional classifier_ can be rendered differently from the - term_. They should be separated visually, typically by spaces - plus a colon or dash. - - -Content Model -------------- - -.. parsed-literal:: - - (term_, classifier_?, definition_) - -:Attributes: - The ``definition_list_item`` element contains only the `common - attributes`_: ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - Tyrannosaurus Rex : carnivore - Big and scary; the "Tyrant King". - - Brontosaurus : herbivore - All brontosauruses are thin at one end, - much much thicker in the middle - and then thin again at the far end. - - -- Anne Elk (Miss) - -Pseudo-XML_ fragment from simple parsing:: - - <definition_list> - <definition_list_item> - <term> - Tyrannosaurus Rex - <classifier> - carnivore - <definition> - <paragraph> - Big and scary; the "Tyrant King". - <definition_list_item> - <term> - Brontosaurus - <classifier> - herbivore - <definition> - <paragraph> - All brontosauruses are thin at one end, - much much thicker in the middle - and then thin again at the far end. - <paragraph> - -- Anne Elk (Miss) - -See definition_list_ and classifier_ for further examples. - - -``description`` -=============== - -The ``description`` element contains body elements, describing the -purpose or effect of a command-line option or group of options. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_list_item_ element contains ``description``. - -:Children: - ``description`` elements may contain `body elements`_. - -:Analogues: - ``description`` has no direct analogues in common DTDs. - -:Processing: - See option_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``description`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``docinfo`` -=========== - -The ``docinfo`` element is a container for document bibliographic -data, or meta-data (data about the document). It corresponds to the -front matter of a book, such as the title page and copyright page. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - Only the document_ element contains ``docinfo``. - -:Children: - ``docinfo`` elements contain `bibliographic elements`_. - -:Analogues: - ``docinfo`` is analogous to DocBook "info" elements ("bookinfo" - etc.). There are no directly analogous HTML elements; the "meta" - element carries some of the same information, albeit invisibly. - -:Processing: - The ``docinfo`` element may be rendered as a two-column table or - in other styles. It may even be invisible or omitted from the - processed output. Meta-data may be extracted from ``docinfo`` - children; for example, HTML ``<meta>`` tags may be constructed. - - When Docutils_ transforms a reStructuredText_ field_list_ into a - ``docinfo`` element (see the examples below), RCS/CVS keywords are - normally stripped from simple (one paragraph) field bodies. For - complete details, please see `RCS Keywords`_ in the - `reStructuredText Markup Specification`_. - - .. _RCS Keywords: rst/restructuredtext.html#rcs-keywords - - -Content Model -------------- - -.. parsed-literal:: - - (`%bibliographic.elements;`_)+ - -:Attributes: - The ``docinfo`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -Docinfo is represented in reStructuredText_ by a field_list_ in a -bibliographic context: the first non-comment element of a document_, -after any document title_/subtitle_. The field list is transformed -into a ``docinfo`` element and its children by a transform. Source:: - - Docinfo Example - =============== - - :Author: J. Random Hacker - :Contact: jrh@example.com - :Date: 2002-08-18 - :Status: Work In Progress - :Version: 1 - :Filename: $RCSfile$ - :Copyright: This document has been placed in the public domain. - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="docinfo-example" names="docinfo example"> - <title> - Docinfo Example - <docinfo> - <author> - J. Random Hacker - <contact> - <reference refuri="mailto:jrh@example.com"> - jrh@example.com - <date> - 2002-08-18 - <status> - Work In Progress - <version> - 1 - <field> - <field_name> - Filename - <field_body> - <paragraph> - doctree.txt - <copyright> - This document has been placed in the public domain. - -Note that "Filename" is a non-standard ``docinfo`` field, so becomes a -generic ``field`` element. Also note that the "RCSfile" keyword -syntax has been stripped from the "Filename" data. - -See field_list_ for an example in a non-bibliographic context. Also -see the individual examples for the various `bibliographic elements`_. - - -``doctest_block`` -================= - -The ``doctest_block`` element is a Python-specific variant of -literal_block_. It is a block of text where line breaks and -whitespace are significant and must be preserved. ``doctest_block`` -elements are used for interactive Python interpreter sessions, which -are distinguished by their input prompt: ``>>>``. They are meant to -illustrate usage by example, and provide an elegant and powerful -testing environment via the `doctest module`_ in the Python standard -library. - -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html - - -Details -------- - -:Category: - `Simple Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``doctest_block``. - -:Children: - ``doctest_block`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``doctest_block`` is analogous to the HTML "pre" element and to - the DocBook "programlisting" and "screen" elements. - -:Processing: - As with literal_block_, ``doctest_block`` elements are typically - rendered in a monospaced typeface. It is crucial that all - whitespace and line breaks are preserved in the rendered form. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``doctest_block`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``doctest_block``. The `%structure.model;`_ parameter entity - indirectly includes ``doctest_block``. - - -Examples --------- - -reStructuredText source:: - - This is an ordinary paragraph. - - >>> print 'this is a Doctest block' - this is a Doctest block - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - This is an ordinary paragraph. - <doctest_block xml:space="preserve"> - >>> print 'this is a Doctest block' - this is a Doctest block - - -``document`` -============ - -The ``document`` element is the root (topmost) element of the Docutils -document tree. ``document`` is the direct or indirect ancestor of -every other element in the tree. It encloses the entire document -tree. It is the starting point for a document. - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The ``document`` element has no parents. - -:Children: - ``document`` elements may contain `structural subelements`_, - `structural elements`_, and `body elements`_. - -:Analogues: - ``document`` is analogous to the HTML "html" element and to - several DocBook elements such as "book". - - -Content Model -------------- - -.. parsed-literal:: - - ( (title_, subtitle_?)?, - decoration_?, - (docinfo_, transition_?)?, - `%structure.model;`_ ) - -Depending on the source of the data and the stage of processing, the -"document" may not initially contain a "title". A document title is -not directly representable in reStructuredText_. Instead, a lone -top-level section may have its title promoted to become the document -title_, and similarly for a lone second-level (sub)section's title to -become the document subtitle_. - -The contents of "decoration_" may be specified in a document, -constructed programmatically, or both. The "docinfo_" may be -transformed from an initial field_list_. - -See the `%structure.model;`_ parameter entity for details of the body -of a ``document``. - -:Attributes: - The ``document`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus an optional title__ - attribute which stores the document title metadata. - - __ `title (attribute)`_ - - -Examples --------- - -reStructuredText_ source:: - - A Title - ======= - - A paragraph. - -Complete pseudo-XML_ result from simple parsing:: - - <document> - <section ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - -After applying transforms, the section title is promoted to become the -document title:: - - <document ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - - -``emphasis`` -============ - -`To be completed`_. - - -``entry`` -========= - -`To be completed`_. - - -``enumerated_list`` -=================== - -The ``enumerated_list`` element contains list_item_ elements which are -uniformly marked with enumerator labels. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``enumerated_list``. - -:Children: - ``enumerated_list`` elements contain one or more list_item_ - elements. - -:Analogues: - ``enumerated_list`` is analogous to the HTML "ol" element and to - the DocBook "orderedlist" element. - -:Processing: - Each list item should begin a new vertical block, prefaced by a - enumeration marker (such as "1."). - - -Content Model -------------- - -.. parsed-literal:: - - (list_item_ +) - -:Attributes: - The ``enumerated_list`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus enumtype_, - prefix_, suffix_, and start_. - - ``enumtype`` is used to record the intended enumeration sequence, - one of "arabic" (1, 2, 3, ...), "loweralpha" (a, b, c, ..., z), - "upperalpha" (A, B, C, ..., Z), "lowerroman" (i, ii, iii, iv, ..., - mmmmcmxcix [4999]), or "upperroman" (I, II, III, IV, ..., - MMMMCMXCIX [4999]). - - ``prefix`` stores the formatting characters used before the - enumerator. In documents originating from reStructuredText_ data, - it will contain either "" (empty string) or "(" (left - parenthesis). It may or may not affect processing. - - ``suffix`` stores the formatting characters used after the - enumerator. In documents originating from reStructuredText_ data, - it will contain either "." (period) or ")" (right parenthesis). - Depending on the capabilities of the output format, this attribute - may or may not affect processing. - - ``start`` contains the ordinal value of the first item in the - list, in decimal. For lists beginning at value 1 ("1", "a", "A", - "i", or "I"), this attribute may be omitted. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``enumerated_list``. The `%structure.model;`_ parameter entity - indirectly includes ``enumerated_list``. - - -Examples --------- - -reStructuredText_ source:: - - 1. Item 1. - - (A) Item A. - (B) Item B. - (C) Item C. - - 2. Item 2. - -Pseudo-XML_ fragment from simple parsing:: - - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Item 1. - <enumerated_list enumtype="upperalpha" prefix="(" suffix=")"> - <list_item> - <paragraph> - Item A. - <list_item> - <paragraph> - Item B. - <list_item> - <paragraph> - Item C. - <list_item> - <paragraph> - Item 2. - -See list_item_ for another example. - - -``error`` -========= - -The ``error`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, hint_, important_, note_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``error``. - -:Children: - ``error`` elements contain one or more `body elements`_. - -:Analogues: - ``error`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Error" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``error`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``error``. The `%structure.model;`_ parameter entity indirectly - includes ``error``. - - -Examples --------- - -reStructuredText source:: - - .. Error:: Does not compute. - -Pseudo-XML_ fragment from simple parsing:: - - <error> - <paragraph> - Does not compute. - - -``field`` -========= - -The ``field`` element contains a pair of field_name_ and field_body_ -elements. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - The following elements may contain ``field``: docinfo_, - field_list_ - -:Children: - Each ``field`` element contains one field_name_ and one - field_body_ element. - -:Analogues: - ``field`` has no direct analogues in common DTDs. - -:Processing: - See field_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (field_name_, field_body_) - -:Attributes: - The ``field`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``field``. - - -Examples --------- - -See the examples for the field_list_ and docinfo_ elements. - - -``field_body`` -============== - -The ``field_body`` element contains body elements. It is analogous to -a database field's data. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the field_ element contains ``field_body``. - -:Children: - ``field_body`` elements may contain `body elements`_. - -:Analogues: - ``field_body`` has no direct analogues in common DTDs. - -:Processing: - See field_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)* - -:Attributes: - The ``field_body`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the field_list_ and docinfo_ elements. - - -``field_list`` -============== - -The ``field_list`` element contains two-column table-like structures -resembling database records (label & data pairs). Field lists are -often meant for further processing. In reStructuredText_, field lists -are used to represent bibliographic fields (contents of the docinfo_ -element) and directive options. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``field_list``. - -:Children: - ``field_list`` elements contain one or more field_ elements. - -:Analogues: - ``field_list`` has no direct analogues in common DTDs. It can be - emulated with primitives such as tables. - -:Processing: - A ``field_list`` is typically rendered as a two-column list, where - the first column contains "labels" (usually with a colon suffix). - However, field lists are often used for extension syntax or - special processing. Such structures do not survive as field lists - to be rendered. - - -Content Model -------------- - -.. parsed-literal:: - - (field_ +) - -:Attributes: - The ``field_list`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``field_list``. The `%structure.model;`_ parameter entity - indirectly includes ``field_list``. - - -Examples --------- - -reStructuredText_ source:: - - :Author: Me - :Version: 1 - :Date: 2001-08-11 - :Parameter i: integer - -Pseudo-XML_ fragment from simple parsing:: - - <field_list> - <field> - <field_name> - Author - <field_body> - <paragraph> - Me - <field> - <field_name> - Version - <field_body> - <paragraph> - 1 - <field> - <field_name> - Date - <field_body> - <paragraph> - 2001-08-11 - <field> - <field_name> - Parameter i - <field_body> - <paragraph> - integer - - -``field_name`` -============== - -The ``field_name`` element contains text; it is analogous to a -database field's name. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the field_ element contains ``field_name``. - -:Children: - ``field_name`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``field_name`` has no direct analogues in common DTDs. - -:Processing: - See field_list_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``field_name`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the field_list_ and docinfo_ elements. - - -``figure`` -========== - -`To be completed`_. - - -``footer`` -========== - -The ``footer`` element is a container element whose contents are meant -to appear at the bottom of a web page, or repeated at the bottom of -every printed page. The ``footer`` element may contain processing -information (datestamp, a link to Docutils_, etc.) as well as custom -content. - - -Details -------- - -:Category: - `Decorative Elements`_ - -:Parents: - Only the decoration_ element contains ``footer``. - -:Children: - ``footer`` elements may contain `body elements`_. - -:Analogues: - There are no direct analogies to ``footer`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``footer`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - A paragraph. - -Complete pseudo-XML_ result after parsing and applying transforms, -assuming that the datestamp command-line option or configuration -setting has been supplied:: - - <document> - <decoration> - <footer> - <paragraph> - Generated on: 2002-08-20. - <paragraph> - A paragraph. - - -``footnote`` -============ - -`To be completed`_. - - -``footnote_reference`` -====================== - -`To be completed`_. - - -``generated`` -============= - -Docutils wraps ``generated`` elements around text that is inserted -(generated) by Docutils; i.e., text that was not in the document, like -section numbers inserted by the "sectnum" directive. - -`To be completed`_. - - -``header`` -========== - -The ``header`` element is a container element whose contents are meant -to appear at the top of a web page, or at the top of every printed -page. - - -Details -------- - -:Category: - `Decorative Elements`_ - -:Parents: - Only the decoration_ element contains ``header``. - -:Children: - ``header`` elements may contain `body elements`_. - -:Analogues: - There are no direct analogies to ``header`` in HTML or DocBook. - Equivalents are typically constructed from primitives and/or - generated by the processing system. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``header`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText source fragment:: - - .. header:: This space for rent. - -Pseudo-XML_ fragment from simple parsing:: - - <document> - <decoration> - <header> - <paragraph> - This space for rent. - - -``hint`` -======== - -The ``hint`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, important_, note_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``hint``. - -:Children: - ``hint`` elements contain one or more `body elements`_. - -:Analogues: - ``hint`` has no direct analogues in common DTDs. It can be - emulated with primitives and type effects. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Hint" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``hint`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``hint``. The `%structure.model;`_ parameter entity indirectly - includes ``hint``. - - -Examples --------- - -reStructuredText source:: - - .. Hint:: It's bigger than a bread box. - -Pseudo-XML_ fragment from simple parsing:: - - <hint> - <paragraph> - It's bigger than a bread box. - - -``image`` -========= - -`To be completed`_. - - -``important`` -============= - -The ``important`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, note_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``important``. - -:Children: - ``important`` elements contain one or more `body elements`_. - -:Analogues: - ``important`` is analogous to the DocBook "important" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Important" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``important`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``important``. The `%structure.model;`_ parameter entity - indirectly includes ``important``. - - -Examples --------- - -reStructuredText source:: - - .. Important:: - - * Wash behind your ears. - * Clean up your room. - * Back up your data. - * Call your mother. - -Pseudo-XML_ fragment from simple parsing:: - - <important> - <bullet_list> - <list_item> - <paragraph> - Wash behind your ears. - <list_item> - <paragraph> - Clean up your room. - <list_item> - <paragraph> - Back up your data. - <list_item> - <paragraph> - Call your mother. - - -``inline`` -========== - -`To be completed`_. - - -``label`` -========= - -`To be completed`_. - - -``legend`` -========== - -`To be completed`_. - - -``line`` -======== - -The ``line`` element contains a single line of text, part of a -`line_block`_. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the `line_block`_ element contains ``line``. - -:Children: - ``line`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``line`` has no direct analogues in common DTDs. It can be - emulated with primitives or type effects. - -:Processing: - See `line_block`_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``line`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus `xml:space`_. - - -Examples --------- - -See `line_block`_. - - -``line_block`` -============== - -The ``line_block`` element contains a sequence of lines and nested -line blocks. Line breaks (implied between elements) and leading -whitespace (indicated by nesting) is significant and must be -preserved. ``line_block`` elements are commonly used for verse and -addresses. See `literal_block`_ for an alternative useful for program -listings and interactive computer sessions. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``line_block``. - -:Children: - ``line_block`` elements may contain line_ elements and nested - ``line_block`` elements. - -:Analogues: - ``line_block`` is analogous to the DocBook "literallayout" element - and to the HTML "pre" element (with modifications to typeface - styles). - -:Processing: - Unline ``literal_block``, ``line_block`` elements are typically - rendered in an ordinary text typeface. It is crucial that leading - whitespace and line breaks are preserved in the rendered form. - - -Content Model -------------- - -.. parsed-literal:: - - (line_ | line_block_)+ - -:Attributes: - The ``line_block`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``line_block``. The `%structure.model;`_ parameter entity - indirectly includes ``line_block``. - - -Examples --------- - -reStructuredText uses a directive to indicate a ``line_block``. -Example source:: - - Take it away, Eric the Orchestra Leader! - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - Take it away, Eric the Orchestra Leader! - <line_block> - <line> - A one, two, a one two three four - <line> - <line> - Half a bee, philosophically, - <line_block> - <line> - must, - <emphasis> - ipso facto - , half not be. - <line> - But half the bee has got to be, - <line_block> - <line> - <emphasis> - vis a vis - its entity. D'you see? - <line> - <line> - But can a bee be said to be - <line_block> - <line> - or not to be an entire bee, - <line_block> - <line> - when half the bee is not a bee, - <line_block> - <line> - due to some ancient injury? - <line> - <line> - Singing... - - -``list_item`` -============= - -The ``list_item`` element is a container for the elements of a list -item. - - -Details -------- - -:Category: - `Body Subelements`_ (compound) - -:Parents: - The bullet_list_ and enumerated_list_ elements contain - ``list_item``. - -:Children: - ``list_item`` elements may contain `body elements`_. - -:Analogues: - ``list_item`` is analogous to the HTML "li" element and to the - DocBook "listitem" element. - -:Processing: - See bullet_list_ or enumerated_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)* - -:Attributes: - The ``list_item`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - 1. Outer list, item 1. - - * Inner list, item 1. - * Inner list, item 2. - - 2. Outer list, item 2. - -Pseudo-XML_ fragment from simple parsing:: - - <enumerated_list enumtype="arabic" prefix="" suffix="."> - <list_item> - <paragraph> - Outer list, item 1. - <bullet_list bullet="*"> - <list_item> - <paragraph> - Inner list, item 1. - <list_item> - <paragraph> - Inner list, item 2. - <list_item> - <paragraph> - Outer list, item 2. - -See bullet_list_ or enumerated_list_ for further examples. - - -``literal`` -=========== - -`To be completed`_. - - -``literal_block`` -================= - -The ``literal_block`` element contains a block of text where line -breaks and whitespace are significant and must be preserved. -``literal_block`` elements are commonly used for program listings and -interactive computer sessions. See `line_block`_ for an alternative -useful for verse and addresses. - - -Details -------- - -:Category: - `Simple Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``literal_block``. - -:Children: - ``literal_block`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``literal_block`` is analogous to the HTML "pre" element and to - the DocBook "programlisting" and "screen" elements. - -:Processing: - ``literal_block`` elements are typically rendered in a monospaced - typeface. It is crucial that all whitespace and line breaks are - preserved in the rendered form. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``literal_block`` element contains the `common attributes`_ - (ids_, names_, dupnames_, source_, and classes_), plus `xml:space`_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``literal_block``. The `%structure.model;`_ parameter entity - indirectly includes ``literal_block``. - - -Examples --------- - -reStructuredText source:: - - Here is a literal block:: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - Here is a literal block: - <literal_block xml:space="preserve"> - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - - -``note`` -======== - -The ``note`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, important_, tip_, warning_, and the generic -admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``note``. - -:Children: - ``note`` elements contain one or more `body elements`_. - -:Analogues: - ``note`` is analogous to the DocBook "note" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Note" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``note`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``note``. The `%structure.model;`_ parameter entity indirectly - includes ``note``. - - -Examples --------- - -reStructuredText source:: - - .. Note:: Admonitions can be handy to break up a - long boring technical document. - -Pseudo-XML_ fragment from simple parsing:: - - <note> - <paragraph> - Admonitions can be handy to break up a - long boring technical document. - -``option`` -========== - -The ``option`` element groups an option string together with zero or -more option argument placeholders. Note that reStructuredText_ -currently supports only one argument per option. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_group_ element contains ``option``. - -:Children: - Each ``option`` element contains one option_string_ and zero or - more option_argument_ elements. - -:Analogues: - ``option`` has no direct analogues in common DTDs. - -:Processing: - See option_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (option_string_, option_argument_ \*) - -:Attributes: - The ``option`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_argument`` -=================== - -The ``option_argument`` element contains placeholder text for option -arguments. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_ element contains ``option_argument``. - -:Children: - ``option_argument`` elements contain text data only. - -:Analogues: - ``option_argument`` has no direct analogues in common DTDs. - -:Processing: - The value of the "delimiter" attribute is prefixed to the - ``option_argument``, separating it from its option_string_ or a - preceding ``option_argument``. The ``option_argument`` text is - typically rendered in a monospaced typeface, possibly italicized - or otherwise altered to indicate its placeholder nature. - - -Content Model -------------- - -.. parsed-literal:: - - (#PCDATA) - -:Attributes: - The ``option_argument`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus delimiter_. - - ``delimiter`` contains the text preceding the ``option_argument``: - either the text separating it from the option_string_ (typically - either "=" or " ") or the text between option arguments (typically - either "," or " "). - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_group`` -================ - -The ``option_group`` element groups together one or more option_ -elements, all synonyms. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_list_item_ element contains ``option_group``. - -:Children: - ``option_group`` elements contain one or more option_ elements. - - ``option_group`` is an empty element and has no children. - - Each ``option_group`` element contains one _ and - one _ element. - -:Analogues: - ``option_group`` has no direct analogues in common DTDs. - -:Processing: - Typically option_ elements within an ``option_group`` are joined - together in a comma-separated list. - - -Content Model -------------- - -.. parsed-literal:: - - (option_group_, description_) - -:Attributes: - The ``option_group`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_list`` -=============== - -Each ``option_list`` element contains a two-column list of -command-line options and descriptions, documenting a program's -options. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``option_list``. - -:Children: - ``option_list`` elements contain one or more option_list_item_ - elements. - -:Analogues: - ``option_list`` has no direct analogues in common DTDs. It can be - emulated with primitives such as tables. - -:Processing: - An ``option_list`` is typically rendered as a two-column list, - where the first column contains option strings and arguments, and - the second column contains descriptions. - - -Content Model -------------- - -.. parsed-literal:: - - (option_list_item_ +) - -:Attributes: - The ``option_list`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``option_list``. The `%structure.model;`_ parameter entity - indirectly includes ``option_list``. - - -Examples --------- - -reStructuredText_ source:: - - -a command-line option "a" - -1 file, --one=file, --two file - Multiple options with arguments. - -Pseudo-XML_ fragment from simple parsing:: - - <option_list> - <option_list_item> - <option_group> - <option> - <option_string> - -a - <description> - <paragraph> - command-line option "a" - <option_list_item> - <option_group> - <option> - <option_string> - -1 - <option_argument delimiter=" "> - file - <option> - <option_string> - --one - <option_argument delimiter="="> - file - <option> - <option_string> - --two - <option_argument delimiter=" "> - file - <description> - <paragraph> - Multiple options with arguments. - - -``option_list_item`` -==================== - -The ``option_list_item`` element is a container for a pair of -option_group_ and description_ elements. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_list_ element contains ``option_list_item``. - -:Children: - Each ``option_list_item`` element contains one option_group_ and - one description_ element. - -:Analogues: - ``option_list_item`` has no direct analogues in common DTDs. - -:Processing: - See option_list_. - - -Content Model -------------- - -.. parsed-literal:: - - (option_group_, description_) - -:Attributes: - The ``option_list_item`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``option_string`` -================= - -The ``option_string`` element contains the text of a command-line -option. - - -Details -------- - -:Category: - `Body Subelements`_ - -:Parents: - Only the option_ element contains ``option_string``. - -:Children: - ``option_string`` elements contain text data only. - -:Analogues: - ``option_string`` has no direct analogues in common DTDs. - -:Processing: - The ``option_string`` text is typically rendered in a monospaced - typeface. - - -Content Model -------------- - -.. parsed-literal:: - - (#PCDATA) - -:Attributes: - The ``option_string`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the option_list_ element. - - -``organization`` -================ - -The ``organization`` element contains the name of document author's -organization, or the organization responsible for the document. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``organization``. - -:Children: - ``organization`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``organization`` is analogous to the DocBook "orgname", - "corpname", or "publishername" elements. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``organization`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``organization``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Organization: Humankind - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <organization> - Humankind - -See docinfo_ for a more complete example, including processing -context. - - -``paragraph`` -============= - -The ``paragraph`` element contains the text and inline elements of a -single paragraph, a fundamental building block of documents. - - -Details -------- - -:Category: - `Simple Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``paragraph``. - -:Children: - ``paragraph`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``paragraph`` is analogous to the HTML "p" element and to the - DocBook "para" elements. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``paragraph`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``paragraph``. The `%structure.model;`_ parameter entity - indirectly includes ``paragraph``. - - -Examples --------- - -reStructuredText_ source:: - - A paragraph. - -Pseudo-XML_ fragment from simple parsing:: - - <paragraph> - A paragraph. - - -``pending`` -=========== - -`To be completed`_. - - -``problematic`` -=============== - -`To be completed`_. - - -``raw`` -======= - -`To be completed`_. - - -``reference`` -============= - -`To be completed`_. - - -``revision`` -============ - -The ``revision`` element contains the revision number of the document. -It can be used alone or in conjunction with version_. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``revision``. - -:Children: - ``revision`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``revision`` is analogous to but simpler than the DocBook - "revision" element. It closely matches the DocBook "revnumber" - element, but in a simpler context. - -:Processing: - Often used with the RCS/CVS keyword "Revision". See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``revision`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``revision``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Version: 1 - :Revision: b - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <version> - 1 - <revision> - b - -See docinfo_ for a more complete example, including processing -context. - - -``row`` -======= - -`To be completed`_. - - -``rubric`` -========== - - rubric n. 1. a title, heading, or the like, in a manuscript, - book, statute, etc., written or printed in red or otherwise - distinguished from the rest of the text. ... - - -- Random House Webster's College Dictionary, 1991 - -A rubric is like an informal heading that doesn't correspond to the -document's structure. - -`To be completed`_. - - -``section`` -=========== - -The ``section`` element is the main unit of hierarchy for Docutils -documents. Docutils ``section`` elements are a recursive structure; a -``section`` may contain other ``section`` elements, without limit. -Paragraphs and other body elements may occur before a ``section``, but -not after it. - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The following elements may contain ``section``: document_, - section_ - -:Children: - ``section`` elements begin with a title_, and may contain `body - elements`_ as well as transition_, topic_, and sidebar_ elements. - -:Analogues: - ``section`` is analogous to DocBook recursive "section" elements, - and to HTML "div" elements combined with "h1" etc. title elements. - - -Content Model -------------- - -.. parsed-literal:: - - (title_, - `%structure.model;`_) - -See the `%structure.model;`_ parameter entity for details of the body -of a ``section``. - -:Attributes: - The ``section`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%section.elements;`_ parameter entity directly includes - ``section``. The `%structure.model;`_ parameter entity indirectly - includes ``section``. - - -Examples --------- - -reStructuredText_ source:: - - Title 1 - ======= - Paragraph 1. - - Title 2 - ------- - Paragraph 2. - - Title 3 - ======= - Paragraph 3. - - Title 4 - ------- - Paragraph 4. - -Complete pseudo-XML_ result after parsing:: - - <document> - <section ids="title-1" names="title 1"> - <title> - Title 1 - <paragraph> - Paragraph 1. - <section ids="title-2" names="title 2"> - <title> - Title 2 - <paragraph> - Paragraph 2. - <section ids="title-3" names="title 3"> - <title> - Title 3 - <paragraph> - Paragraph 3. - <section ids="title-4" names="title 4"> - <title> - Title 4 - <paragraph> - Paragraph 4. - - -``sidebar`` -=========== - -Sidebars are like miniature, parallel documents that occur inside -other documents, providing related or reference material. A -``sidebar`` is typically offset by a border and "floats" to the side -of the page; the document's main text may flow around it. Sidebars -can also be likened to super-footnotes; their content is outside of -the flow of the document's main text. - -The ``sidebar`` element is a nonrecursive section_-like construct -which may occur at the top level of a section_ wherever a body element -(list, table, etc.) is allowed. In other words, ``sidebar`` elements -cannot nest inside body elements, so you can't have a ``sidebar`` -inside a ``table`` or a ``list``, or inside another ``sidebar`` (or -topic_). - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The following elements may contain ``sidebar``: document_, - section_ - -:Children: - ``sidebar`` elements begin with a title_ and an optional subtitle_ - and contain `body elements`_ and topic_ elements. - -:Analogues: - ``sidebar`` is analogous to the DocBook "sidebar" element. - -:Processing: - A ``sidebar`` element should be set off from the rest of the - document somehow, typically with a border. Sidebars typically - "float" to the side of the page and the document's main text flows - around them. - - -Content Model -------------- - -.. parsed-literal:: - - (title_, subtitle_?, - (`%body.elements;`_ | topic_)+) - -:Attributes: - The ``sidebar`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%structure.model;`_ parameter entity directly includes - ``sidebar``. - - -Examples --------- - -The `"sidebar" directive`_ is used to create a ``sidebar`` element. -reStructuredText_ source:: - - .. sidebar:: Title - :subtitle: If Desired - - Body. - -Pseudo-XML_ fragment from simple parsing:: - - <sidebar> - <title> - Title - <subtitle> - If Desired - <paragraph> - Body. - -.. _"sidebar" directive: rst/directives.html#sidebar - - -``status`` -========== - -The ``status`` element contains a status statement for the document, -such as "Draft", "Final", "Work In Progress", etc. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``status``. - -:Children: - ``status`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``status`` is analogous to the DocBook "status" element. - -:Processing: - See docinfo_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``status`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``status``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Status: Work In Progress - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <status> - Work In Progress - -See docinfo_ for a more complete example, including processing -context. - - -``strong`` -========== - -`To be completed`_. - - -``subscript`` -============= - -`To be completed`_. - - -``substitution_definition`` -=========================== - -`To be completed`_. - - -``substitution_reference`` -========================== - -`To be completed`_. - - -``subtitle`` -============ - -The ``subtitle`` element stores the subtitle of a document_. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - The document_ and sidebar_ elements may contain ``subtitle``. - -:Children: - ``subtitle`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``subtitle`` is analogous to HTML header elements ("h2" etc.) and - to the DocBook "subtitle" element. - -:Processing: - A document's subtitle is usually rendered smaller than its title_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``subtitle`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -reStructuredText_ source:: - - ======= - Title - ======= - ---------- - Subtitle - ---------- - - A paragraph. - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="title" names="title"> - <title> - Title - <subtitle ids="subtitle" names="subtitle"> - Subtitle - <paragraph> - A paragraph. - -Note how two section levels have collapsed, promoting their titles to -become the document's title and subtitle. Since there is only one -structural element (document), the subsection's ``ids`` and ``names`` -attributes are stored in the ``subtitle`` element. - - -``superscript`` -=============== - -`To be completed`_. - - -``system_message`` -================== - -`To be completed`_. - - -``table`` -========= - -`To be completed`_. - - -``target`` -========== - -`To be completed`_. - - -``tbody`` -========= - -`To be completed`_. - - -``term`` -======== - -The ``term`` element contains a word or phrase being defined in a -definition_list_. - - -Details -------- - -:Category: - `Body Subelements`_ (simple) - -:Parents: - Only the definition_list_item_ element contains ``term``. - -:Children: - ``term`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``term`` is analogous to the HTML "dt" element and to the DocBook - "term" element. - -:Processing: - See definition_list_item_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``term`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - - -Examples --------- - -See the examples for the definition_list_, definition_list_item_, and -classifier_ elements. - - -``tgroup`` -========== - -`To be completed`_. - - -``thead`` -========= - -`To be completed`_. - - -``tip`` -======= - -The ``tip`` element is an admonition, a distinctive and self-contained -notice. Also see the other admonition elements Docutils offers (in -alphabetical order): attention_, caution_, danger_, error_, hint_, -important_, note_, warning_, and the generic admonition_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``tip``. - -:Children: - ``tip`` elements contain one or more `body elements`_. - -:Analogues: - ``tip`` is analogous to the DocBook "tip" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Tip" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``tip`` element contains only the `common attributes`_: ids_, - names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes ``tip``. - The `%structure.model;`_ parameter entity indirectly includes - ``tip``. - - -Examples --------- - -reStructuredText source:: - - .. Tip:: 15% if the service is good. - -Pseudo-XML_ fragment from simple parsing:: - - <tip> - <paragraph> - 15% if the service is good. - - -.. _title: - -``title`` -========= - -The ``title`` element stores the title of a document_, section_, -topic_, sidebar_, or generic admonition_. - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - The following elements may contain ``title``: document_, section_, - topic_, sidebar_, admonition_ - -:Children: - ``title`` elements may contain text data plus `inline elements`_. - -:Analogues: - ``title`` is analogous to HTML "title" and header ("h1" etc.) - elements, and to the DocBook "title" element. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``title`` element contains the `common attributes`_ (ids_, - names_, dupnames_, source_, and classes_), plus refid_ and auto_. - - ``refid`` is used as a backlink to a table of contents entry. - - ``auto`` is used to indicate (with value "1") that the ``title`` - has been numbered automatically. - - -Examples --------- - -reStructuredText_ source:: - - A Title - ======= - - A paragraph. - -Pseudo-XML_ fragment from simple parsing:: - - <section ids="a-title" names="a title"> - <title> - A Title - <paragraph> - A paragraph. - - -``title_reference`` -=================== - -`To be completed`_. - - -``topic`` -========= - -The ``topic`` element is a nonrecursive section_-like construct which -may occur at the top level of a section_ wherever a body element -(list, table, etc.) is allowed. In other words, ``topic`` elements -cannot nest inside body elements, so you can't have a ``topic`` inside -a ``table`` or a ``list``, or inside another ``topic``. - - -Details -------- - -:Category: - `Structural Elements`_ - -:Parents: - The following elements may contain ``topic``: document_, section_, - sidebar_ - -:Children: - ``topic`` elements begin with a title_ and may contain `body - elements`_. - -:Analogues: - ``topic`` is analogous to the DocBook "simplesect" element. - -:Processing: - A ``topic`` element should be set off from the rest of the - document somehow, such as with indentation or a border. - - -Content Model -------------- - -.. parsed-literal:: - - (title_?, - (`%body.elements;`_)+) - -:Attributes: - The ``topic`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%structure.model;`_ parameter entity directly includes - ``topic``. - - -Examples --------- - -The `"topic" directive`_ is used to create a ``topic`` element. -reStructuredText_ source:: - - .. topic:: Title - - Body. - -Pseudo-XML_ fragment from simple parsing:: - - <topic> - <title> - Title - <paragraph> - Body. - -.. _"topic" directive: rst/directives.html#topic - - -``transition`` -============== - -The ``transition`` element is commonly seen in novels and short -fiction, as a gap spanning one or more lines, with or without a type -ornament such as a row of asterisks. Transitions separate body -elements and sections, dividing a section into untitled divisions. A -transition may not begin or end a section [#]_ or document, nor may -two transitions be immediately adjacent. - -See `Doctree Representation of Transitions`__ in `A Record of -reStructuredText Syntax Alternatives`__. - -.. [#] In reStructuredText markup, a transition may appear to fall at - the end of a section immediately before another section. A - transform recognizes this case and moves the transition so it - separates the sections. - -__ ../dev/rst/alternatives.html#doctree-representation-of-transitions -__ ../dev/rst/alternatives.html - - -Details -------- - -:Category: - `Structural Subelements`_ - -:Parents: - The following elements may contain ``transition``: document_, - section_ - -:Children: - ``transition`` is an empty element and has no children. - -:Analogues: - ``transition`` is analogous to the HTML "hr" element. - -:Processing: - The ``transition`` element is typically rendered as vertical - whitespace (more than that separating paragraphs), with or without - a horizontal line or row of asterisks. In novels, transitions are - often represented as a row of three well-spaced asterisks with - vertical space above and below. - - -Content Model -------------- - -:: - - EMPTY - -The ``transition`` element has no content; it is a "point element". - -:Attributes: - The ``transition`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%structure.model;`_ parameter entity directly includes - ``transition``. - - -Examples --------- - -reStructuredText_ source:: - - Paragraph 1. - - -------- - - Paragraph 2. - -Complete pseudo-XML_ result after parsing:: - - <document> - <paragraph> - Paragraph 1. - <transition> - <paragraph> - Paragraph 2. - - -``version`` -=========== - -The ``version`` element contains the version number of the document. -It can be used alone or in conjunction with revision_. - - -Details -------- - -:Category: - `Bibliographic Elements`_ - -:Parents: - Only the docinfo_ element contains ``version``. - -:Children: - ``version`` elements may contain text data plus `inline - elements`_. - -:Analogues: - ``version`` may be considered analogous to the DocBook "revision", - "revnumber", or "biblioid" elements. - -:Processing: - Sometimes used with the RCS/CVS keyword "Revision". See docinfo_ - and revision_. - - -Content Model -------------- - -.. parsed-literal:: - - `%text.model;`_ - -:Attributes: - The ``version`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%bibliographic.elements;`_ parameter entity directly includes - ``version``. - - -Examples --------- - -reStructuredText_ source:: - - Document Title - ============== - - :Version: 1.1 - -Complete pseudo-XML_ result after parsing and applying transforms:: - - <document ids="document-title" names="document title"> - <title> - Document Title - <docinfo> - <version> - 1.1 - -See docinfo_ for a more complete example, including processing -context. - - -``warning`` -=========== - -The ``warning`` element is an admonition, a distinctive and -self-contained notice. Also see the other admonition elements -Docutils offers (in alphabetical order): attention_, caution_, -danger_, error_, hint_, important_, note_, tip_. - - -Details -------- - -:Category: - `Compound Body Elements`_ - -:Parents: - All elements employing the `%body.elements;`_ or - `%structure.model;`_ parameter entities in their content models - may contain ``warning``. - -:Children: - ``warning`` elements contain one or more `body elements`_. - -:Analogues: - ``warning`` is analogous to the DocBook "warning" element. - -:Processing: - Rendered distinctly (inset and/or in a box, etc.), with the - generated title "Warning" (or similar). - - -Content Model -------------- - -.. parsed-literal:: - - (`%body.elements;`_)+ - -:Attributes: - The ``warning`` element contains only the `common attributes`_: - ids_, names_, dupnames_, source_, and classes_. - -:Parameter Entities: - The `%body.elements;`_ parameter entity directly includes - ``warning``. The `%structure.model;`_ parameter entity indirectly - includes ``warning``. - - -Examples --------- - -reStructuredText source:: - - .. WARNING:: Reader discretion is strongly advised. - -Pseudo-XML_ fragment from simple parsing:: - - <warning> - <paragraph> - Reader discretion is strongly advised. - - ---------------------- - Attribute Reference ---------------------- - -.. contents:: :local: - :depth: 1 - -_`Common Attributes`: Through the `%basic.atts;`_ parameter entity, -all elements contain the following attributes: ids_, names_, dupnames_, -source_, and classes_. - -.. _attribute type: - -Attribute types: - -``CDATA`` - Character data. ``CDATA`` attributes may contain arbitrary text. - -``ID`` - Like a ``NMTOKEN``, but it must begin with a letter (a "name - production"). Identical ``ID`` values must not appear more than - once in a document; i.e., ID values must uniquely identify their - elements. - -``IDREF`` - A reference to an ``ID`` value (a name production) of another - element. - -``IDREFS`` - One or more space-separated ``ID`` references (name productions). - -``NMTOKEN`` - A "name token". One or more of letters, digits, ".", "-", and - "_". - -``NMTOKENS`` - One or more space-separated ``NMTOKEN`` names. - -``%yesorno;`` - No if zero ("0"), yes if any other value. This is a parameter - entity which resolves to a ``NMTOKEN`` attribute type. - -``%number;`` - This emphasizes that the attribute value must be a number. This - is a parameter entity which resolves to a ``NMTOKEN`` attribute - type. - -enumeration - The attribute value may be one of a specified list of values. - - -``anonymous`` -============= - -`Attribute type`_: ``%yesorno;``. Default value: none (implies no). - -The ``anonymous`` attribute is used for unnamed hyperlinks in the -target_ and reference_ elements (via the `%anonymous.att;`_ parameter -entity). - - -``auto`` -======== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``auto`` attribute is used to indicate automatically-numbered -footnote_, footnote_reference_ and title_ elements (via the -`%auto.att;`_ parameter entity). - - -``backrefs`` -============ - -`Attribute type`_: ``IDREFS``. Default value: none. - -The ``backrefs`` attribute contains a space-separated list of ids_ -references, used for backlinks from footnote_, citation_, and -system_message_ elements (via the `%backrefs.att;`_ parameter entity). - - -``bullet`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``bullet`` attribute is used in the bullet_list_ element. - - -``classes`` -=========== - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``classes`` attribute is a list containing one or more names used -to classify an element. The purpose of the attribute is to indicate -an "is-a" variant relationship, to allow an extensible way of defining -sub-classes of existing elements. It can be used to carry context -forward between a Docutils Reader and Writer, when a custom structure -is reduced to a standardized document tree. One common use is in -conjunction with stylesheets, to add selection criteria. It should -not be used to carry formatting instructions or arbitrary content. - -The ``classes`` attribute's contents should be ignorable. Writers that -are not familiar with the variant expressed should be able to ignore -the attribute. - -``classes`` is one of the `common attributes`_, shared by all Docutils -elements. - - -``delimiter`` -============= - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``delimiter`` attribute is used in the option_argument_ element. - - -``dupnames`` -============ - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``dupnames`` attribute is a list containing the names of an -element when there has been a naming conflict. The contents of the -``dupnames`` attribute would have been transferred from the `names`_ -attribute. An element may have at most one of the ``names`` or -``dupnames`` attributes, but not both. ``dupnames`` is one of the -`common attributes`_, shared by all Docutils elements. - - -``enumtype`` -============ - -`Attribute type`_: enumeration, one of "arabic", "loweralpha", -"upperalpha", "lowerroman", or "upperroman". Default value: none. - -The ``enumtype`` attribute is used in the enumerated_list_ element. - - -``ids`` -======= - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``ids`` attribute is a list containing one or more unique -identifier keys. ``ids`` is one of the `common attributes`_, shared -by all Docutils elements. - - -``names`` -========= - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``names`` attribute is a list containing the names of an element, -typically originating from the element's title or content. Each name -in ``names`` must be unique; if there are name conflicts (two or more -elements want to the same name), the contents will be transferred to -the `dupnames`_ attribute on the duplicate elements. An element may -have at most one of the ``names`` or ``dupnames`` attributes, but not -both. ``names`` is one of the `common attributes`_, shared by all -Docutils elements. - - -``prefix`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``prefix`` attribute is used in the enumerated_list_ element. - - -``refid`` -========= - -`Attribute type`_: ``IDREF``. Default value: none. - -The ``refid`` attribute contains references to `ids`_ attributes in -other elements. It is used by the target_, reference_, -footnote_reference_, citation_reference_, title_ and problematic_ -elements (via the `%refid.att;`_ and `%reference.atts;`_ parameter -entities). - - -``refname`` -=========== - -`Attribute type`_: ``NMTOKENS``. Default value: none. - -The ``refname`` attribute contains an internal reference to the -`names`_ attribute of another element. On a `target`_ element, -``refname`` indicates an indirect target which may resolve to either -an internal or external reference. ``refname`` is used by the -target_, reference_, footnote_reference_, citation_reference_, and -substitution_reference_ elements (via the `%refname.att;`_ and -`%reference.atts;`_ parameter entities). - - -``refuri`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``refuri`` attribute contains an external reference to a URI/URL. -It is used by the target_, reference_, footnote_reference_, and -citation_reference_ elements (via the `%reference.atts;`_ parameter -entity). - - -``source`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``source`` attribute is used to store the path or URL to the -source text that was used to produce the document tree. It is one of -the `common attributes`_, shared by all Docutils elements. - - -``start`` -========= - -`Attribute type`_: ``%number;``. Default value: none. - -The ``start`` attribute is used in the enumerated_list_ element. - - -``suffix`` -========== - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``suffix`` attribute is used in the enumerated_list_ element. - - -``xml:space`` -============= - -`Attribute type`_: one of "default" or "preserve". Default value: -"preserve" (fixed). - -The ``xml:space`` attribute is a standard XML attribute for -whitespace-preserving elements. It is used by the literal_block_, -line_block_, doctest_block_, comment_, and raw_ elements (via the -`%fixedspace.att;`_ parameter entity). It is a fixed attribute, meant -to communicate to an XML parser that the element contains significant -whitespace. The attribute value should not be set in a document -instance. - - -.. _title (attribute): - -``title`` -========= - -`Attribute type`_: ``CDATA``. Default value: none. - -The ``title`` attribute stores the title metadata of a document. This -title is typically not part of the rendered document. It may for -example be used in HTML's ``title`` element. - - ----------------------------- - Parameter Entity Reference ----------------------------- - -.. contents:: :local: - :depth: 1 - -Parameter entities are used to simplify the DTD (to share definitions -and reduce duplication) and to allow the DTD to be customized by -wrapper DTDs (external client DTDs that use or import the Docutils -DTD). Parameter entities may be overridden by wrapper DTDs, replacing -the definitions below with custom definitions. Parameter entities -whose names begin with "additional" are meant to allow easy extension -by wrapper DTDs. - - -``%anonymous.att;`` -=================== - -The ``%anonymous.att;`` parameter entity contains the anonymous_ -attribute, used for unnamed hyperlinks. - -Entity definition: - -.. parsed-literal:: - - anonymous_ %yesorno; #IMPLIED - -The reference_ and target_ elements directly employ the -``%anonymous.att;`` parameter entity in their attribute lists. - - -``%auto.att;`` -============== - -The ``%auto.att;`` parameter entity contains the auto_ attribute, used -to indicate an automatically-numbered footnote or title. - -Entity definition: - -.. parsed-literal:: - - auto_ CDATA #IMPLIED - -The footnote_, footnote_reference_, and title_ elements directly -employ the ``%auto.att;`` parameter entity in their attribute lists. - - -``%backrefs.att;`` -================== - -The ``%backrefs.att;`` parameter entity contains the backrefs_ -attribute, a space-separated list of id references, for backlinks. - -Entity definition: - -.. parsed-literal:: - - backrefs_ IDREFS #IMPLIED - -The citation_, footnote_, and system_message_ elements directly employ -the ``%backrefs.att;`` parameter entity in their attribute lists. - - -``%basic.atts;`` -================ - -The ``%basic.atts;`` parameter entity lists attributes common to all -Docutils elements. See `Common Attributes`_. - -Entity definition: - -.. parsed-literal:: - - ids_ NMTOKENS #IMPLIED - names_ CDATA #IMPLIED - dupnames_ CDATA #IMPLIED - source_ CDATA #IMPLIED - classes_ NMTOKENS #IMPLIED - %additional.basic.atts; - -The ``%additional.basic.atts;`` parameter entity can be used by -wrapper DTDs to extend ``%basic.atts;``. - - -``%bibliographic.elements;`` -============================ - -The ``%bibliographic.elements;`` parameter entity contains an OR-list of all -`bibliographic elements`_. - -Entity definition: - -.. parsed-literal:: - - author_ | authors_ | organization_ | contact_ | address_ - | version_ | revision_ | status_ | date_ | copyright_ - | field_ - %additional.bibliographic.elements; - -The ``%additional.bibliographic.elements;`` parameter entity can be used by -wrapper DTDs to extend ``%bibliographic.elements;``. - -Only the docinfo_ element directly employs the -``%bibliographic.elements;`` parameter entity in its content model. - - -``%body.elements;`` -=================== - -The ``%body.elements;`` parameter entity contains an OR-list of all -`body elements`_. ``%body.elements;`` is itself contained within the -`%structure.model;`_ parameter entity. - -Entity definition: - -.. parsed-literal:: - - paragraph_ | compound_ | container_ | literal_block_ | doctest_block_ - | line_block_ | block_quote_ - | table_ | figure_ | image_ | footnote_ | citation_ | rubric_ - | bullet_list_ | enumerated_list_ | definition_list_ | field_list_ - | option_list_ - | attention_ | caution_ | danger_ | error_ | hint_ | important_ | note_ - | tip_ | warning_ | admonition_ - | reference_ | target_ | substitution_definition_ | comment_ | pending_ - | system_message_ | raw_ - %additional.body.elements; - -The ``%additional.body.elements;`` parameter entity can be used by -wrapper DTDs to extend ``%body.elements;``. - -The ``%body.elements;`` parameter entity is directly employed in the -content models of the following elements: admonition_, attention_, -block_quote_, caution_, citation_, compound_, danger_, definition_, -description_, entry_, error_, field_body_, footer_, footnote_, -header_, hint_, important_, legend_, list_item_, note_, sidebar_, -system_message_, tip_, topic_, warning_ - -Via `%structure.model;`_, the ``%body.elements;`` parameter entity is -indirectly employed in the content models of the document_ and -section_ elements. - - -``%fixedspace.att;`` -==================== - -The ``%fixedspace.att;`` parameter entity contains the `xml:space`_ -attribute, a standard XML attribute for whitespace-preserving -elements. - -Entity definition: - -.. parsed-literal:: - - `xml:space`_ (default | preserve) #FIXED 'preserve' - -The ``%fixedspace.att;`` parameter entity is directly employed in the -attribute lists of the following elements: address_, comment_, -doctest_block_, line_block_, literal_block_, raw_ - - -``%inline.elements;`` -===================== - -The ``%inline.elements;`` parameter entity contains an OR-list of all -`inline elements`_. - -Entity definition: - -.. parsed-literal:: - - emphasis_ | strong_ | literal_ - | reference_ | footnote_reference_ | citation_reference_ - | substitution_reference_ | title_reference_ - | abbreviation_ | acronym_ | subscript_ | superscript_ - | inline_ | problematic_ | generated_ - | target_ | image_ | raw_ - %additional.inline.elements; - -The ``%additional.inline.elements;`` parameter entity can be used by -wrapper DTDs to extend ``%inline.elements;``. - -Via `%text.model;`_, the ``%inline.elements;`` parameter entity is -indirectly employed in the content models of the following elements: -abbreviation_, acronym_, address_, attribution_, author_, caption_, -classifier_, contact_, copyright_, date_, doctest_block_, emphasis_, -generated_, inline_, line_block_, literal_block_, organization_, -paragraph_, problematic_, raw_, reference_, revision_, rubric_, -status_, strong_, subscript_, substitution_definition_, -substitution_reference_, subtitle_, superscript_, target_, term_, -title_, title_reference_, version_ - - -``%reference.atts;`` -==================== - -The ``%reference.atts;`` parameter entity groups together the refuri_, -refid_, and refname_ attributes. - -Entity definition: - -.. parsed-literal:: - - `%refuri.att;`_ - `%refid.att;`_ - `%refname.att;`_ - %additional.reference.atts; - -The ``%additional.reference.atts;`` parameter entity can be used by -wrapper DTDs to extend ``%additional.reference.atts;``. - -The citation_reference_, footnote_reference_, reference_, and target_ -elements directly employ the ``%reference.att;`` parameter entity in -their attribute lists. - - -``%refid.att;`` -================ - -The ``%refid.att;`` parameter entity contains the refid_ attribute, an -internal reference to the `ids`_ attribute of another element. - -Entity definition: - -.. parsed-literal:: - - refid_ CDATA #IMPLIED - -The title_ and problematic_ elements directly employ the -``%refid.att;`` parameter entity in their attribute lists. - -Via `%reference.atts;`_, the ``%refid.att;`` parameter entity is -indirectly employed in the attribute lists of the citation_reference_, -footnote_reference_, reference_, and target_ elements. - - -``%refname.att;`` -================= - -The ``%refname.att;`` parameter entity contains the refname_ -attribute, an internal reference to the `names`_ attribute of another -element. On a `target`_ element, ``refname`` indicates an indirect -target which may resolve to either an internal or external -reference. - -Entity definition: - -.. parsed-literal:: - - refname_ NMTOKENS #IMPLIED - -The substitution_reference_ element directly employs the -``%refname.att;`` parameter entity in its attribute list. - -Via `%reference.atts;`_, the ``%refname.att;`` parameter entity is -indirectly employed in the attribute lists of the citation_reference_, -footnote_reference_, reference_, and target_ elements. - - -``%refuri.att;`` -================ - -The ``%refuri.att;`` parameter entity contains the refuri_ attribute, -an external reference to a URI/URL. - -Entity definition: - -.. parsed-literal:: - - refuri_ CDATA #IMPLIED - -Via `%reference.atts;`_, the ``%refuri.att;`` parameter entity is -indirectly employed in the attribute lists of the citation_reference_, -footnote_reference_, reference_, and target_ elements. - - -``%section.elements;`` -====================== - -The ``%section.elements;`` parameter entity contains an OR-list of all -section_-equivalent elements. ``%section.elements;`` is itself -contained within the `%structure.model;`_ parameter entity. - -Entity definition: - -.. parsed-literal:: - - section_ - %additional.section.elements; - -The ``%additional.section.elements;`` parameter entity can be used -by wrapper DTDs to extend ``%section.elements;``. - -Via `%structure.model;`_, the ``%section.elements;`` parameter entity -is indirectly employed in the content models of the document_ and -section_ elements. - - -``%structure.model;`` -===================== - -The ``%structure.model;`` parameter entity encapsulates the -hierarchical structure of a document and of its constituent parts. -See the discussion of the `element hierarchy`_ above. - -Entity definition: - -.. parsed-literal:: - - ( ( (`%body.elements;`_ | topic_ | sidebar_)+, transition_? )*, - ( (`%section.elements;`_), (transition_?, (`%section.elements;`_) )* )? ) - -Each document_ or section_ contains zero or more body elements, -topics, and/or sidebars, optionally interspersed with single -transitions, followed by zero or more sections (whose contents are -recursively the same as this model) optionally interspersed with -transitions. - -The following restrictions are imposed by this model: - -* Transitions must be separated by other elements (body elements, - sections, etc.). In other words, a transition may not be - immediately adjacent to another transition. - -* A transition may not occur at the beginning of a document or - section. - -An additional restriction, which cannot be expressed in the language -of DTDs, is imposed by software: - -* A transition may not occur at the end of a document or section. - -The `%structure.model;`_ parameter entity is directly employed in the -content models of the document_ and section_ elements. - - -``%text.model;`` -================ - -The ``%text.model;`` parameter entity is used by many elements to -represent text data mixed with `inline elements`_. - -Entity definition: - -.. parsed-literal:: - - (#PCDATA | `%inline.elements;`_)* - -The ``%text.model;`` parameter entity is directly employed in the -content models of the following elements: abbreviation_, acronym_, -address_, author_, caption_, classifier_, contact_, copyright_, date_, -doctest_block_, emphasis_, field_name_, generated_, line_block_, -literal_block_, organization_, paragraph_, problematic_, raw_, -reference_, revision_, status_, strong_, substitution_definition_, -substitution_reference_, subtitle_, target_, term_, title_, version_ - - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/docutils.dtd b/docutils/docs/ref/docutils.dtd deleted file mode 100644 index 154566033..000000000 --- a/docutils/docs/ref/docutils.dtd +++ /dev/null @@ -1,606 +0,0 @@ -<!-- -====================================================================== - Docutils Generic DTD -====================================================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This DTD has been placed in the public domain. -:Filename: docutils.dtd - -More information about this DTD (document type definition) and the -Docutils project can be found at http://docutils.sourceforge.net/. -The latest version of this DTD is available from -http://docutils.sourceforge.net/docs/ref/docutils.dtd. - -The formal public identifier for this DTD is:: - - +//IDN docutils.sourceforge.net//DTD Docutils Generic//EN//XML ---> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Parameter Entities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Parameter entities are used to simplify the DTD (reduce duplication) -and to allow the DTD to be customized by wrapper DTDs. Parameter -entities beginning with "additional" are meant to allow easy extension -by wrapper DTDs. ---> - -<!-- Attributes -================================================================== --> - -<!-- Boolean: no if zero(s), yes if any other value. --> -<!ENTITY % yesorno "NMTOKEN"> - -<!-- Emphasize that the attribute value must be a number. --> -<!ENTITY % number "NMTOKEN"> - -<!-- A number which may be immediately followed by a unit. --> -<!ENTITY % measure "NMTOKEN"> - -<!ENTITY % additional.basic.atts ""> -<!-- -Attributes shared by all elements in this DTD: - -- `id` is a unique identifier, typically assigned by the system. -- `name` is an identifier assigned in the markup. -- `dupname` is the same as `name`, used when it's a duplicate. -- `source` is the name of the source of this document or fragment. -- `class` is used to transmit individuality information forward. ---> -<!ENTITY % basic.atts - " ids NMTOKENS #IMPLIED - names CDATA #IMPLIED - dupnames CDATA #IMPLIED - source CDATA #IMPLIED - classes NMTOKENS #IMPLIED - %additional.basic.atts; "> - -<!-- External reference to a URI/URL. --> -<!ENTITY % refuri.att - " refuri CDATA #IMPLIED "> - -<!-- Internal reference to the `id` attribute of an element. --> -<!ENTITY % refid.att - " refid IDREF #IMPLIED "> - -<!-- Space-separated list of id references, for backlinks. --> -<!ENTITY % backrefs.att - " backrefs IDREFS #IMPLIED "> - -<!-- -Internal reference to the `name` attribute of an element. On a -'target' element, 'refname' indicates an indirect target which may -resolve to either an internal or external reference. ---> -<!ENTITY % refname.att - " refname NMTOKENS #IMPLIED "> - -<!ENTITY % additional.reference.atts ""> -<!-- Collected hyperlink reference attributes. --> -<!ENTITY % reference.atts - " %refuri.att; - %refid.att; - %refname.att; - %additional.reference.atts; "> - -<!-- Unnamed hyperlink. --> -<!ENTITY % anonymous.att - " anonymous %yesorno; #IMPLIED "> - -<!-- Auto-numbered footnote or title. --> -<!ENTITY % auto.att - " auto CDATA #IMPLIED "> - -<!-- XML standard attribute for whitespace-preserving elements. --> -<!ENTITY % fixedspace.att - " xml:space (default | preserve) #FIXED 'preserve' "> - -<!ENTITY % align-h.att - " align (left | center | right) #IMPLIED "> - -<!ENTITY % align-hv.att - " align (top | middle | bottom | left | center | right) #IMPLIED "> - - -<!-- Element OR-Lists -============================================================= --> - -<!ENTITY % additional.bibliographic.elements ""> -<!ENTITY % bibliographic.elements - " author | authors | organization | address | contact - | version | revision | status | date | copyright - | field - %additional.bibliographic.elements; "> - -<!ENTITY % additional.section.elements ""> -<!ENTITY % section.elements - " section - %additional.section.elements; "> - -<!ENTITY % additional.body.elements ""> -<!ENTITY % body.elements - " paragraph | compound | container | literal_block | doctest_block - | line_block | block_quote - | table | figure | image | footnote | citation | rubric - | bullet_list | enumerated_list | definition_list | field_list - | option_list - | attention | caution | danger | error | hint | important | note - | tip | warning | admonition - | reference | target | substitution_definition | comment | pending - | system_message | raw - %additional.body.elements; "> - -<!ENTITY % additional.inline.elements ""> -<!ENTITY % inline.elements - " emphasis | strong | literal - | reference | footnote_reference | citation_reference - | substitution_reference | title_reference - | abbreviation | acronym | subscript | superscript - | inline | problematic | generated - | target | image | raw - %additional.inline.elements; "> - - -<!-- Element Content Models -================================================================== --> - -<!-- The structure model may not end with a transition. --> -<!ENTITY % structure.model - " ( ( (%body.elements; | topic | sidebar)+, transition? )*, - ( (%section.elements;), (transition?, (%section.elements;) )* )? )"> - -<!ENTITY % text.model - " (#PCDATA | %inline.elements;)* "> - - -<!-- Table Model -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This DTD uses the Exchange subset of the CALS-table model (OASIS -Technical Memorandum 9901:1999 "XML Exchange Table Model DTD", -http://www.oasis-open.org/html/tm9901.htm). ---> - -<!ENTITY % calstblx PUBLIC - "-//OASIS//DTD XML Exchange Table Model 19990315//EN" - "soextblx.dtd"> - -<!-- These parameter entities customize the table model DTD. --> -<!ENTITY % bodyatt " %basic.atts; "> <!-- table elt --> -<!ENTITY % tbl.tgroup.att " %basic.atts; "> -<!ENTITY % tbl.thead.att " %basic.atts; "> -<!ENTITY % tbl.tbody.att " %basic.atts; "> -<!ENTITY % tbl.colspec.att - " %basic.atts; - stub %yesorno; #IMPLIED "> -<!ENTITY % tbl.row.att " %basic.atts; "> -<!ENTITY % tbl.entry.mdl " (%body.elements;)* "> -<!ENTITY % tbl.entry.att - " %basic.atts; - morecols %number; #IMPLIED "> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Root Element -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!-- Optional elements may be generated by internal processing. --> -<!ELEMENT document - ( (title, subtitle?)?, - decoration?, - (docinfo, transition?)?, - %structure.model; )> -<!ATTLIST document - %basic.atts; - title CDATA #IMPLIED> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Title Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT title %text.model;> -<!ATTLIST title - %basic.atts; - %refid.att; - %auto.att;> - -<!ELEMENT subtitle %text.model;> -<!ATTLIST subtitle %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Bibliographic Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!-- Container for bibliographic elements. May not be empty. --> -<!ELEMENT docinfo (%bibliographic.elements;)+> -<!ATTLIST docinfo %basic.atts;> - -<!-- Container for bibliographic elements. May not be empty. -Eventual replacement for docinfo? --> -<!ELEMENT info (%bibliographic.elements;)+> -<!ATTLIST info %basic.atts;> - -<!ELEMENT author %text.model;> -<!ATTLIST author %basic.atts;> - -<!ELEMENT authors (author, organization?, address?, contact?)+> -<!ATTLIST authors %basic.atts;> - -<!ELEMENT organization %text.model;> -<!ATTLIST organization %basic.atts;> - -<!ELEMENT address %text.model;> -<!ATTLIST address - %basic.atts; - %fixedspace.att;> - -<!ELEMENT contact %text.model;> -<!ATTLIST contact %basic.atts;> - -<!ELEMENT version %text.model;> -<!ATTLIST version %basic.atts;> - -<!ELEMENT revision %text.model;> -<!ATTLIST revision %basic.atts;> - -<!ELEMENT status %text.model;> -<!ATTLIST status %basic.atts;> - -<!ELEMENT date %text.model;> -<!ATTLIST date %basic.atts;> - -<!ELEMENT copyright %text.model;> -<!ATTLIST copyright %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Decoration Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT decoration (header?, footer?)> -<!ATTLIST decoration %basic.atts;> - -<!ELEMENT header (%body.elements;)+> -<!ATTLIST header %basic.atts;> - -<!ELEMENT footer (%body.elements;)+> -<!ATTLIST footer %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Structural Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT section - (title, subtitle?, info?, decoration?, %structure.model;)> -<!ATTLIST section %basic.atts;> - -<!ELEMENT topic (title?, (%body.elements;)+)> -<!ATTLIST topic %basic.atts;> - -<!ELEMENT sidebar (title, subtitle?, (%body.elements; | topic)+)> -<!ATTLIST sidebar %basic.atts;> - -<!ELEMENT transition EMPTY> -<!ATTLIST transition %basic.atts;> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Body Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ---> - -<!ELEMENT paragraph %text.model;> -<!ATTLIST paragraph %basic.atts;> - -<!ELEMENT compound (%body.elements;)+> -<!ATTLIST compound %basic.atts;> - -<!ELEMENT container (%body.elements;)+> -<!ATTLIST container %basic.atts;> - -<!ELEMENT bullet_list (list_item+)> -<!ATTLIST bullet_list - %basic.atts; - bullet CDATA #IMPLIED> - -<!ELEMENT enumerated_list (list_item+)> -<!ATTLIST enumerated_list - %basic.atts; - enumtype (arabic | loweralpha | upperalpha - | lowerroman | upperroman) - #IMPLIED - prefix CDATA #IMPLIED - suffix CDATA #IMPLIED - start %number; #IMPLIED> - -<!ELEMENT list_item (%body.elements;)*> -<!ATTLIST list_item %basic.atts;> - -<!ELEMENT definition_list (definition_list_item+)> -<!ATTLIST definition_list %basic.atts;> - -<!ELEMENT definition_list_item (term, classifier*, definition)> -<!ATTLIST definition_list_item %basic.atts;> - -<!ELEMENT term %text.model;> -<!ATTLIST term %basic.atts;> - -<!ELEMENT classifier %text.model;> -<!ATTLIST classifier %basic.atts;> - -<!ELEMENT definition (%body.elements;)+> -<!ATTLIST definition %basic.atts;> - -<!ELEMENT field_list (field+)> -<!ATTLIST field_list %basic.atts;> - -<!ELEMENT field (field_name, field_body)> -<!ATTLIST field %basic.atts;> - -<!ELEMENT field_name %text.model;> -<!ATTLIST field_name %basic.atts;> - -<!-- May be empty. --> -<!ELEMENT field_body (%body.elements;)*> -<!ATTLIST field_body %basic.atts;> - -<!ELEMENT option_list (option_list_item+)> -<!ATTLIST option_list %basic.atts;> - -<!ELEMENT option_list_item (option_group, description)> -<!ATTLIST option_list_item %basic.atts;> - -<!ELEMENT option_group (option+)> -<!ATTLIST option_group %basic.atts;> - -<!ELEMENT option (option_string, option_argument*)> -<!ATTLIST option %basic.atts;> - -<!ELEMENT option_string (#PCDATA)> -<!ATTLIST option_string %basic.atts;> - -<!-- -`delimiter` contains the text preceding the `option_argument`: either -the text separating it from the `option_string` (typically either "=" -or " ") or the text between option arguments (typically either "," or -" "). ---> -<!ELEMENT option_argument (#PCDATA)> -<!ATTLIST option_argument - %basic.atts; - delimiter CDATA #IMPLIED> - -<!ELEMENT description (%body.elements;)+> -<!ATTLIST description %basic.atts;> - -<!ELEMENT literal_block %text.model;> -<!ATTLIST literal_block - %basic.atts; - %fixedspace.att;> - -<!ELEMENT line_block (line | line_block)+> -<!ATTLIST line_block %basic.atts;> - -<!ELEMENT line %text.model;> -<!ATTLIST line %basic.atts;> - -<!ELEMENT block_quote ((%body.elements;)+, attribution?)> -<!ATTLIST block_quote %basic.atts;> - -<!ELEMENT attribution %text.model;> -<!ATTLIST attribution %basic.atts;> - -<!ELEMENT doctest_block %text.model;> -<!ATTLIST doctest_block - %basic.atts; - %fixedspace.att;> - -<!ELEMENT attention (%body.elements;)+> -<!ATTLIST attention %basic.atts;> - -<!ELEMENT caution (%body.elements;)+> -<!ATTLIST caution %basic.atts;> - -<!ELEMENT danger (%body.elements;)+> -<!ATTLIST danger %basic.atts;> - -<!ELEMENT error (%body.elements;)+> -<!ATTLIST error %basic.atts;> - -<!ELEMENT hint (%body.elements;)+> -<!ATTLIST hint %basic.atts;> - -<!ELEMENT important (%body.elements;)+> -<!ATTLIST important %basic.atts;> - -<!ELEMENT note (%body.elements;)+> -<!ATTLIST note %basic.atts;> - -<!ELEMENT tip (%body.elements;)+> -<!ATTLIST tip %basic.atts;> - -<!ELEMENT warning (%body.elements;)+> -<!ATTLIST warning %basic.atts;> - -<!ELEMENT admonition (title, (%body.elements;)+)> -<!ATTLIST admonition %basic.atts;> - -<!ELEMENT footnote (label?, (%body.elements;)+)> -<!ATTLIST footnote - %basic.atts; - %backrefs.att; - %auto.att;> - -<!ELEMENT citation (label, (%body.elements;)+)> -<!ATTLIST citation - %basic.atts; - %backrefs.att;> - -<!ELEMENT label (#PCDATA)> -<!ATTLIST label %basic.atts;> - -<!ELEMENT rubric %text.model;> -<!ATTLIST rubric %basic.atts;> - -<!-- Empty except when used as an inline element. --> -<!ELEMENT target %text.model;> -<!ATTLIST target - %basic.atts; - %reference.atts; - %anonymous.att;> - -<!ELEMENT substitution_definition %text.model;> -<!ATTLIST substitution_definition - %basic.atts; - ltrim %yesorno; #IMPLIED - rtrim %yesorno; #IMPLIED> - -<!ELEMENT comment (#PCDATA)> -<!ATTLIST comment - %basic.atts; - %fixedspace.att;> - -<!ELEMENT pending EMPTY> -<!ATTLIST pending %basic.atts;> - -<!ELEMENT figure (image, ((caption, legend?) | legend)) > -<!ATTLIST figure - %basic.atts; - %align-h.att; - width %number; #IMPLIED> - -<!-- Also an inline element. --> -<!ELEMENT image EMPTY> -<!ATTLIST image - %basic.atts; - %align-hv.att; - uri CDATA #REQUIRED - alt CDATA #IMPLIED - height %measure; #IMPLIED - width %measure; #IMPLIED - scale %number; #IMPLIED> - -<!ELEMENT caption %text.model;> -<!ATTLIST caption %basic.atts;> - -<!ELEMENT legend (%body.elements;)+> -<!ATTLIST legend %basic.atts;> - -<!-- -Table elements: table, tgroup, colspec, thead, tbody, row, entry. ---> -%calstblx; - -<!-- Used to record processing information. --> -<!ELEMENT system_message (%body.elements;)+> -<!ATTLIST system_message - %basic.atts; - %backrefs.att; - level %number; #IMPLIED - line %number; #IMPLIED - type NMTOKEN #IMPLIED> - -<!-- Used to pass raw data through the system. Also inline. --> -<!ELEMENT raw %text.model;> -<!ATTLIST raw - %basic.atts; - %fixedspace.att; - format NMTOKENS #IMPLIED> - -<!-- -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Inline Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Inline elements occur within the text contents of body elements. Some -nesting of inline elements is allowed by these definitions, with the -following caveats: - -- An inline element may not contain a nested element of the same type - (e.g. <strong> may not contain another <strong>). -- Nested inline elements may or may not be supported by individual - applications using this DTD. -- The inline elements <footnote_reference>, <citation_reference>, - <literal>, and <image> do not support nesting. ---> - -<!ELEMENT emphasis %text.model;> -<!ATTLIST emphasis %basic.atts;> - -<!ELEMENT strong %text.model;> -<!ATTLIST strong %basic.atts;> - -<!ELEMENT literal (#PCDATA)> -<!ATTLIST literal %basic.atts;> - -<!-- Can also be a body element, when it contains an "image" element. --> -<!ELEMENT reference %text.model;> -<!ATTLIST reference - %basic.atts; - %reference.atts; - %anonymous.att;> - -<!ELEMENT footnote_reference (#PCDATA)> -<!ATTLIST footnote_reference - %basic.atts; - %refid.att; - %refname.att; - %auto.att;> - -<!ELEMENT citation_reference (#PCDATA)> -<!ATTLIST citation_reference - %basic.atts; - %refid.att; - %refname.att;> - -<!ELEMENT substitution_reference %text.model;> -<!ATTLIST substitution_reference - %basic.atts; - %refname.att;> - -<!ELEMENT title_reference %text.model;> -<!ATTLIST title_reference %basic.atts;> - -<!ELEMENT abbreviation %text.model;> -<!ATTLIST abbreviation %basic.atts;> - -<!ELEMENT acronym %text.model;> -<!ATTLIST acronym %basic.atts;> - -<!ELEMENT superscript %text.model;> -<!ATTLIST superscript %basic.atts;> - -<!ELEMENT subscript %text.model;> -<!ATTLIST subscript %basic.atts;> - -<!ELEMENT inline %text.model;> -<!ATTLIST inline %basic.atts;> - -<!ELEMENT problematic %text.model;> -<!ATTLIST problematic - %basic.atts; - %refid.att;> - -<!ELEMENT generated %text.model;> -<!ATTLIST generated %basic.atts;> - -<!-- -Local Variables: -mode: sgml -indent-tabs-mode: nil -fill-column: 70 -End: ---> diff --git a/docutils/docs/ref/rst/definitions.txt b/docutils/docs/ref/rst/definitions.txt deleted file mode 100644 index 78a2bf8da..000000000 --- a/docutils/docs/ref/rst/definitions.txt +++ /dev/null @@ -1,180 +0,0 @@ -============================================ - reStructuredText Standard Definition Files -============================================ -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -This document describes standard definition files, such as sets of -substitution definitions and interpreted text roles, that can be -included in reStructuredText documents. The `"include" directive`__ -has a special syntax for these standard definition files, angle -brackets around the file name:: - - .. include:: <filename.txt> - -__ directives.html#include - -The individual data files are stored with the Docutils source code in -the "docutils" package, in the ``docutils/parsers/rst/include`` -directory. - - -Substitution Definitions -======================== - -Many of the standard definition files contain sets of `substitution -definitions`__, which can be used in documents via `substitution -references`__. For example, the copyright symbol is defined in -``isonum.txt`` as "copy":: - - .. include:: <isonum.txt> - - Copyright |copy| 2003 by John Q. Public, all rights reserved. - -__ restructuredtext.html#substitution-definitions -__ restructuredtext.html#substitution-references - -Individual substitution definitions can also be copied from definition -files and pasted into documents. This has two advantages: it removes -dependencies, and it saves processing of unused definitions. However, -multiple substitution definitions add clutter to the document. - -Substitution references require separation from the surrounding text -with whitespace or punctuation. To use a substitution without -intervening whitespace, you can use the disappearing-whitespace escape -sequence, backslash-space:: - - .. include:: isonum.txt - - Copyright |copy| 2003, BogusMegaCorp\ |trade|. - -Custom substitution definitions may use the `"unicode" directive`__. -Whitespace is ignored and removed, effectively sqeezing together the -text:: - - .. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - - Copyright |copy| 2003, |BogusMegaCorp (TM)|. - -__ directives.html#unicode - -In addition, the "ltrim", "rtrim", and "trim" options may be used with -the "unicode" directive to automatically trim spaces from the left, -right, or both sides (respectively) of substitution references:: - - .. |---| unicode:: U+02014 .. em dash - :trim: - - -Character Entity Sets ---------------------- - -The following files contain substitution definitions corresponding to -XML character entity sets, from the following standards: ISO 8879 & -ISO 9573-13 (combined), MathML, and XHTML1. They were generated by -the ``tools/dev/unicode2rstsubs.py`` program from the input file -unicode.xml__, which is maintained as part of the MathML 2 -Recommentation XML source. - -__ http://www.w3.org/2003/entities/xml/ - -=================== ================================================= -Entity Set File Description -=================== ================================================= -isoamsa.txt_ Added Mathematical Symbols: Arrows -isoamsb.txt_ Added Mathematical Symbols: Binary Operators -isoamsc.txt_ Added Mathematical Symbols: Delimiters -isoamsn.txt_ Added Mathematical Symbols: Negated Relations -isoamso.txt_ Added Mathematical Symbols: Ordinary -isoamsr.txt_ Added Mathematical Symbols: Relations -isobox.txt_ Box and Line Drawing -isocyr1.txt_ Russian Cyrillic -isocyr2.txt_ Non-Russian Cyrillic -isodia.txt_ Diacritical Marks -isogrk1.txt_ Greek Letters -isogrk2.txt_ Monotoniko Greek -isogrk3.txt_ Greek Symbols -isogrk4.txt_ [1]_ Alternative Greek Symbols -isolat1.txt_ Added Latin 1 -isolat2.txt_ Added Latin 2 -isomfrk.txt_ [1]_ Mathematical Fraktur -isomopf.txt_ [1]_ Mathematical Openface (Double-struck) -isomscr.txt_ [1]_ Mathematical Script -isonum.txt_ Numeric and Special Graphic -isopub.txt_ Publishing -isotech.txt_ General Technical -mmlalias.txt_ MathML aliases for entities from other sets -mmlextra.txt_ [1]_ Extra names added by MathML -xhtml1-lat1.txt_ XHTML Latin 1 -xhtml1-special.txt_ XHTML Special Characters -xhtml1-symbol.txt_ XHTML Mathematical, Greek and Symbolic Characters -=================== ================================================= - -.. [1] There are ``*-wide.txt`` variants for each of these character - entity set files, containing characters outside of the Unicode - basic multilingual plane or BMP (wide-Unicode; code points greater - than U+FFFF). Most pre-built Python distributions are "narrow" and - do not support wide-Unicode characters. Python *can* be built with - wide-Unicode support though; consult the Python build instructions - for details. - -For example, the copyright symbol is defined as the XML character -entity ``©``. The equivalent reStructuredText substitution -reference (defined in both ``isonum.txt`` and ``xhtml1-lat1.txt``) is -``|copy|``. - -.. _isoamsa.txt: ../../../docutils/parsers/rst/include/isoamsa.txt -.. _isoamsb.txt: ../../../docutils/parsers/rst/include/isoamsb.txt -.. _isoamsc.txt: ../../../docutils/parsers/rst/include/isoamsc.txt -.. _isoamsn.txt: ../../../docutils/parsers/rst/include/isoamsn.txt -.. _isoamso.txt: ../../../docutils/parsers/rst/include/isoamso.txt -.. _isoamsr.txt: ../../../docutils/parsers/rst/include/isoamsr.txt -.. _isobox.txt: ../../../docutils/parsers/rst/include/isobox.txt -.. _isocyr1.txt: ../../../docutils/parsers/rst/include/isocyr1.txt -.. _isocyr2.txt: ../../../docutils/parsers/rst/include/isocyr2.txt -.. _isodia.txt: ../../../docutils/parsers/rst/include/isodia.txt -.. _isogrk1.txt: ../../../docutils/parsers/rst/include/isogrk1.txt -.. _isogrk2.txt: ../../../docutils/parsers/rst/include/isogrk2.txt -.. _isogrk3.txt: ../../../docutils/parsers/rst/include/isogrk3.txt -.. _isogrk4.txt: ../../../docutils/parsers/rst/include/isogrk4.txt -.. _isolat1.txt: ../../../docutils/parsers/rst/include/isolat1.txt -.. _isolat2.txt: ../../../docutils/parsers/rst/include/isolat2.txt -.. _isomfrk.txt: ../../../docutils/parsers/rst/include/isomfrk.txt -.. _isomopf.txt: ../../../docutils/parsers/rst/include/isomopf.txt -.. _isomscr.txt: ../../../docutils/parsers/rst/include/isomscr.txt -.. _isonum.txt: ../../../docutils/parsers/rst/include/isonum.txt -.. _isopub.txt: ../../../docutils/parsers/rst/include/isopub.txt -.. _isotech.txt: ../../../docutils/parsers/rst/include/isotech.txt -.. _mmlalias.txt: ../../../docutils/parsers/rst/include/mmlalias.txt -.. _mmlextra.txt: ../../../docutils/parsers/rst/include/mmlextra.txt -.. _xhtml1-lat1.txt: ../../../docutils/parsers/rst/include/xhtml1-lat1.txt -.. _xhtml1-special.txt: ../../../docutils/parsers/rst/include/xhtml1-special.txt -.. _xhtml1-symbol.txt: ../../../docutils/parsers/rst/include/xhtml1-symbol.txt - - -S5/HTML Definitions -=================== - -The "s5defs.txt_" standard definition file contains interpreted text -roles (classes) and other definitions for documents destined to become -`S5/HTML slide shows`_. - -.. _s5defs.txt: ../../../docutils/parsers/rst/include/s5defs.txt -.. _S5/HTML slide shows: ../../user/slide-shows.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt deleted file mode 100644 index af88a3d4e..000000000 --- a/docutils/docs/ref/rst/directives.txt +++ /dev/null @@ -1,1727 +0,0 @@ -============================= - reStructuredText Directives -============================= -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -This document describes the directives implemented in the reference -reStructuredText parser. - -Directives have the following syntax:: - - +-------+-------------------------------+ - | ".. " | directive type "::" directive | - +-------+ block | - | | - +-------------------------------+ - -Directives begin with an explicit markup start (two periods and a -space), followed by the directive type and two colons (collectively, -the "directive marker"). The directive block begins immediately after -the directive marker, and includes all subsequent indented lines. The -directive block is divided into arguments, options (a field list), and -content (in that order), any of which may appear. See the Directives_ -section in the `reStructuredText Markup Specification`_ for syntax -details. - -Descriptions below list "doctree elements" (document tree element -names; XML DTD generic identifiers) corresponding to individual -directives. For details on the hierarchy of elements, please see `The -Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. For directive implementation details, see `Creating -reStructuredText Directives`_. - -.. _Directives: restructuredtext.html#directives -.. _reStructuredText Markup Specification: restructuredtext.html -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Directives: - ../../howto/rst-directives.html - - -------------- - Admonitions -------------- - -.. _attention: -.. _caution: -.. _danger: -.. _error: -.. _hint: -.. _important: -.. _note: -.. _tip: -.. _warning: - -Specific Admonitions -==================== - -:Directive Types: "attention", "caution", "danger", "error", "hint", - "important", "note", "tip", "warning", "admonition" -:Doctree Elements: attention, caution, danger, error, hint, important, - note, tip, warning, admonition, title -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -Admonitions are specially marked "topics" that can appear anywhere an -ordinary body element can. They contain arbitrary body elements. -Typically, an admonition is rendered as an offset block in a document, -sometimes outlined or shaded, with a title matching the admonition -type. For example:: - - .. DANGER:: - Beware killer rabbits! - -This directive might be rendered something like this:: - - +------------------------+ - | !DANGER! | - | | - | Beware killer rabbits! | - +------------------------+ - -The following admonition directives have been implemented: - -- attention -- caution -- danger -- error -- hint -- important -- note -- tip -- warning - -Any text immediately following the directive indicator (on the same -line and/or indented on following lines) is interpreted as a directive -block and is parsed for normal body elements. For example, the -following "note" admonition directive contains one paragraph and a -bullet list consisting of two list items:: - - .. note:: This is a note admonition. - This is the second line of the first paragraph. - - - The note contains all indented body elements - following. - - It includes this bullet list. - - -.. _admonition: - -Generic Admonition -================== - -:Directive Type: "admonition" -:Doctree Elements: admonition, title -:Directive Arguments: One, required (admonition title) -:Directive Options: Possible. -:Directive Content: Interpreted as body elements. - -This is a generic, titled admonition. The title may be anything the -author desires. - -The author-supplied title is also used as a "class" attribute value -after being converted into a valid identifier form (down-cased; -non-alphanumeric characters converted to single hyphens; "admonition-" -prefixed). For example, this admonition:: - - .. admonition:: And, by the way... - - You can make up your own admonition too. - -becomes the following document tree (pseudo-XML):: - - <document source="test data"> - <admonition class="admonition-and-by-the-way"> - <title> - And, by the way... - <paragraph> - You can make up your own admonition too. - -The following option is recognized: - -``class`` : text - Override the computed "class" attribute value. See the class_ - directive below. - - --------- - Images --------- - -There are two image directives: "image" and "figure". - - -Image -===== - -:Directive Type: "image" -:Doctree Element: image -:Directive Arguments: One, required (image URI). -:Directive Options: Possible. -:Directive Content: None. - -An "image" is a simple picture:: - - .. image:: picture.png - -The URI for the image source file is specified in the directive -argument. As with hyperlink targets, the image URI may begin on the -same line as the explicit markup start and target name, or it may -begin in an indented text block immediately following, with no -intervening blank lines. If there are multiple lines in the link -block, they are stripped of leading and trailing whitespace and joined -together. - -Optionally, the image link block may contain a flat field list, the -_`image options`. For example:: - - .. image:: picture.jpeg - :height: 100 - :width: 200 - :scale: 50 - :alt: alternate text - :align: right - -The following options are recognized: - -``alt`` : text - Alternate text: a short description of the image, displayed by - applications that cannot display images, or spoken by applications - for visually impaired users. - -``height`` : integer - The desired height of the image in pixels, used to reserve space - or scale the image vertically. When the "scale" option is also - specified, they are combined. For example, a height of 200 and a - scale of 50 is equivalent to a height of 100 with no scale. - - New in Docutils 0.3.10: It is also possible to specify a `length - value`_. - -``width`` : integer - The width of the image in pixels, used to reserve space or scale - the image horizontally. As with "height" above, when the "scale" - option is also specified, they are combined. - - New in Docutils 0.3.10: It is also possible to specify a length_ - or `percentage value`_ (which is relative to the current line - width). - - .. _length: - .. _length value: restructuredtext.html#length-units - .. _percentage value: restructuredtext.html#percentage-units - -``scale`` : integer - The uniform scaling factor of the image, a percentage (but no "%" - symbol is required or allowed). "100" means full-size, and is - equivalent to omitting a "scale" option. - - If no "height" or "width" options are specified, PIL [#PIL]_ may - be used to determine them, if PIL is installed and the image file - is available. - -``align`` : "top", "middle", "bottom", "left", "center", or "right" - The alignment of the image, equivalent to the HTML ``<img>`` tag's - "align" attribute. The values "top", "middle", and "bottom" - control an image's vertical alignment (relative to the text - baseline); they are only useful for inline images (substitutions). - The values "left", "center", and "right" control an image's - horizontal alignment, allowing the image to float and have the - text flow around it. The specific behavior depends upon the - browser or rendering software used. - -``target`` : text (URI or reference name) - Makes the image into a hyperlink reference ("clickable"). The - option argument may be a URI (relative or absolute), or a - reference name with underscore suffix (e.g. ``name_``). - -``class`` : text - Set a "class" attribute value on the image element. See the - class_ directive below. - - -Figure -====== - -:Directive Type: "figure" -:Doctree Elements: figure, image, caption, legend -:Directive Arguments: One, required (image URI). -:Directive Options: Possible. -:Directive Content: Interpreted as the figure caption and an optional - legend. - -A "figure" consists of image_ data (including `image options`_), an -optional caption (a single paragraph), and an optional legend -(arbitrary body elements):: - - .. figure:: picture.png - :scale: 50 - :alt: map to buried treasure - - This is the caption of the figure (a simple paragraph). - - The legend consists of all elements after the caption. In this - case, the legend consists of this paragraph and the following - table: - - +-----------------------+-----------------------+ - | Symbol | Meaning | - +=======================+=======================+ - | .. image:: tent.png | Campground | - +-----------------------+-----------------------+ - | .. image:: waves.png | Lake | - +-----------------------+-----------------------+ - | .. image:: peak.png | Mountain | - +-----------------------+-----------------------+ - -There must be blank lines before the caption paragraph and before the -legend. To specify a legend without a caption, use an empty comment -("..") in place of the caption. - -The "figure" directive supports all of the options of the "image" -directive (see `image options`_ above). In addition, the following -options are recognized: - -``figwidth`` : integer or "image" - The width of the figure in pixels, to limit the horizontal space - used. A special value of "image" is allowed, in which case the - included image's actual width is used (requires PIL [#PIL]_). If - the image file is not found or the required software is - unavailable, this option is ignored. - - Sets the "width" attribute of the "figure" doctree element. - - This option does not scale the included image; use the "width" - `image`_ option for that. :: - - +---------------------------+ - | figure | - | | - |<------ figwidth --------->| - | | - | +---------------------+ | - | | image | | - | | | | - | |<--- width --------->| | - | +---------------------+ | - | | - |The figure's caption should| - |wrap at this width. | - +---------------------------+ - -``figclass`` : text - Set a "class" attribute value on the figure element. See the - class_ directive below. - -``align`` : "left", "center", or "right" - The horizontal alignment of the figure, allowing the image to - float and have the text flow around it. The specific behavior - depends upon the browser or rendering software used. - -.. [#PIL] `Python Imaging Library`_. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - - ---------------- - Body Elements ---------------- - -Topic -===== - -:Directive Type: "topic" -:Doctree Element: topic -:Directive Arguments: 1, required (topic title). -:Directive Options: Possible. -:Directive Content: Interpreted as the topic body. - -A topic is like a block quote with a title, or a self-contained -section with no subsections. Use the "topic" directive to indicate a -self-contained idea that is separate from the flow of the document. -Topics may occur anywhere a section or transition may occur. Body -elements and topics may not contain nested topics. - -The directive's sole argument is interpreted as the topic title; the -next line must be blank. All subsequent lines make up the topic body, -interpreted as body elements. For example:: - - .. topic:: Topic Title - - Subsequent indented lines comprise - the body of the topic, and are - interpreted as body elements. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the topic element. See the - class_ directive below. - - -Sidebar -======= - -:Directive Type: "sidebar" -:Doctree Element: sidebar -:Directive Arguments: One, required (sidebar title). -:Directive Options: Possible. -:Directive Content: Interpreted as the sidebar body. - -Sidebars are like miniature, parallel documents that occur inside -other documents, providing related or reference material. A sidebar -is typically offset by a border and "floats" to the side of the page; -the document's main text may flow around it. Sidebars can also be -likened to super-footnotes; their content is outside of the flow of -the document's main text. - -Sidebars may occur anywhere a section or transition may occur. Body -elements (including sidebars) may not contain nested sidebars. - -The directive's sole argument is interpreted as the sidebar title, -which may be followed by a subtitle option (see below); the next line -must be blank. All subsequent lines make up the sidebar body, -interpreted as body elements. For example:: - - .. sidebar:: Sidebar Title - :subtitle: Optional Sidebar Subtitle - - Subsequent indented lines comprise - the body of the sidebar, and are - interpreted as body elements. - -The following options are recognized: - -``subtitle`` : text - The sidebar's subtitle. - -``class`` : text - Set a "class" attribute value on the sidebar element. See the - class_ directive below. - - -Line Block -========== - -.. admonition:: Deprecated - - The "line-block" directive is deprecated. Use the `line block - syntax`_ instead. - - .. _line block syntax: restructuredtext.html#line-blocks - -:Directive Type: "line-block" -:Doctree Element: line_block -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Becomes the body of the line block. - -The "line-block" directive constructs an element where line breaks and -initial indentation is significant and inline markup is supported. It -is equivalent to a `parsed literal block`_ with different rendering: -typically in an ordinary serif typeface instead of a -typewriter/monospaced face, and not automatically indented. (Have the -line-block directive begin a block quote to get an indented line -block.) Line blocks are useful for address blocks and verse (poetry, -song lyrics), where the structure of lines is significant. For -example, here's a classic:: - - "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by - Ewan McTeagle (for Lassie O'Shea): - - .. line-block:: - - Lend us a couple of bob till Thursday. - I'm absolutely skint. - But I'm expecting a postal order and I can pay you back - as soon as it comes. - Love, Ewan. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the line_block element. See the - class_ directive below. - - -.. _parsed-literal: - -Parsed Literal Block -==================== - -:Directive Type: "parsed-literal" -:Doctree Element: literal_block -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Becomes the body of the literal block. - -Unlike an ordinary literal block, the "parsed-literal" directive -constructs a literal block where the text is parsed for inline markup. -It is equivalent to a `line block`_ with different rendering: -typically in a typewriter/monospaced typeface, like an ordinary -literal block. Parsed literal blocks are useful for adding hyperlinks -to code examples. - -However, care must be taken with the text, because inline markup is -recognized and there is no protection from parsing. Backslash-escapes -may be necessary to prevent unintended parsing. And because the -markup characters are removed by the parser, care must also be taken -with vertical alignment. Parsed "ASCII art" is tricky, and extra -whitespace may be necessary. - -For example, all the element names in this content model are links:: - - .. parsed-literal:: - - ( (title_, subtitle_?)?, - decoration_?, - (docinfo_, transition_?)?, - `%structure.model;`_ ) - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the literal_block element. See - the class_ directive below. - - -Rubric -====== - -:Directive Type: "rubric" -:Doctree Element: rubric -:Directive Arguments: 1, required (rubric text). -:Directive Options: Possible. -:Directive Content: None. - -.. - - rubric n. 1. a title, heading, or the like, in a manuscript, - book, statute, etc., written or printed in red or otherwise - distinguished from the rest of the text. ... - - -- Random House Webster's College Dictionary, 1991 - -The "rubric" directive inserts a "rubric" element into the document -tree. A rubric is like an informal heading that doesn't correspond to -the document's structure. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the rubric element. See the - class_ directive below. - - -Epigraph -======== - -:Directive Type: "epigraph" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -An epigraph is an apposite (suitable, apt, or pertinent) short -inscription, often a quotation or poem, at the beginning of a document -or section. - -The "epigraph" directive produces an "epigraph"-class block quote. -For example, this input:: - - .. epigraph:: - - No matter where you go, there you are. - - -- Buckaroo Banzai - -becomes this document tree fragment:: - - <block_quote class="epigraph"> - <paragraph> - No matter where you go, there you are. - <attribution> - Buckaroo Banzai - - -Highlights -========== - -:Directive Type: "highlights" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -Highlights summarize the main points of a document or section, often -consisting of a list. - -The "highlights" directive produces a "highlights"-class block quote. -See Epigraph_ above for an analogous example. - - -Pull-Quote -========== - -:Directive Type: "pull-quote" -:Doctree Element: block_quote -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as the body of the block quote. - -A pull-quote is a small selection of text "pulled out and quoted", -typically in a larger typeface. Pull-quotes are used to attract -attention, especially in long articles. - -The "pull-quote" directive produces a "pull-quote"-class block quote. -See Epigraph_ above for an analogous example. - - -.. _compound: - -Compound Paragraph -================== - -:Directive Type: "compound" -:Doctree Element: compound -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.6) - -The "compound" directive is used to create a compound paragraph, which -is a single logical paragraph containing multiple physical body -elements such as simple paragraphs, literal blocks, tables, lists, -etc., instead of directly containing text and inline elements. For -example:: - - .. compound:: - - The 'rm' command is very dangerous. If you are logged - in as root and enter :: - - cd / - rm -rf * - - you will erase the entire contents of your file system. - -In the example above, a literal block is "embedded" within a sentence -that begins in one physical paragraph and ends in another. - -.. note:: - - The "compound" directive is *not* a generic block-level container - like HTML's ``<div>`` element. Do not use it only to group a - sequence of elements, or you may get unexpected results. - - If you need a generic block-level container, please use the - container_ directive, described below. - -Compound paragraphs are typically rendered as multiple distinct text -blocks, with the possibility of variations to emphasize their logical -unity: - -* If paragraphs are rendered with a first-line indent, only the first - physical paragraph of a compound paragraph should have that indent - -- second and further physical paragraphs should omit the indents; -* vertical spacing between physical elements may be reduced; -* and so on. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the compound element. See the - class_ directive below. - - -Container -========= - -:Directive Type: "container" -:Doctree Element: container -:Directive Arguments: One or more, optional (class names). -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.10) - -The "container" directive surrounds its contents (arbitrary body -elements) with a generic block-level "container" element. Combined -with the optional "class_" attribute argument(s), this is an extension -mechanism for users & applications. For example:: - - .. container:: custom - - This paragraph might be rendered in a custom way. - -Parsing the above results in the following pseudo-XML:: - - <container classes="custom"> - <paragraph> - This paragraph might be rendered in a custom way. - -The "container" directive is the equivalent of HTML's ``<div>`` -element. It may be used to group a sequence of elements for user- or -application-specific purposes. - - --------- - Tables --------- - -Formal tables need more structure than the reStructuredText syntax -supplies. Tables may be given titles with the table_ directive. -Sometimes reStructuredText tables are inconvenient to write, or table -data in a standard format is readily available. The csv-table_ -directive supports CSV data. - - -Table -===== - -:Directive Type: "table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A normal reStructuredText table. - -(New in Docutils 0.3.1) - -The "table" directive is used to create a titled table, to associate a -title with a table:: - - .. table:: Truth table for "not" - - ===== ===== - A not A - ===== ===== - False True - True False - ===== ===== - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - - -.. _csv-table: - -CSV Table -========= - -:Directive Type: "csv-table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A CSV (comma-separated values) table. - -.. WARNING:: - - The "csv-table" directive's ":file:" and ":url:" options represent - a potential security holes. They can be disabled with the - "file_insertion_enabled_" runtime setting. - -.. Note:: - - The "csv-table" directive requires the ``csv.py`` module of the - Python standard library, which was added in Python 2.3. It will - not work with earlier versions of Python. Using the "csv-table" - directive in a document will make the document **incompatible** - with systems using Python 2.1 or 2.2. - -(New in Docutils 0.3.4) - -The "csv-table" directive is used to create a table from CSV -(comma-separated values) data. CSV is a common data format generated -by spreadsheet applications and commercial databases. The data may be -internal (an integral part of the document) or external (a separate -file). - -Example:: - - .. csv-table:: Frozen Delights! - :header: "Treat", "Quantity", "Description" - :widths: 15, 10, 30 - - "Albatross", 2.99, "On a stick!" - "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be - crunchy, now would it?" - "Gannet Ripple", 1.99, "On a stick!" - -Block markup and inline markup within cells is supported. Line ends -are recognized within cells. - -Working limitations: - -* Whitespace delimiters are supported only for external CSV files. - -* There is no support for checking that the number of columns in each - row is the same. However, this directive supports CSV generators - that do not insert "empty" entries at the end of short rows, by - automatically adding empty entries. - - .. Add "strict" option to verify input? - -The following options are recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - -``widths`` : integer [, integer...] - A comma- or space-separated list of relative column widths. The - default is equal-width columns (100%/#columns). - -``header-rows`` : integer - The number of rows of CSV data to use in the table header. - Defaults to 0. - -``stub-columns`` : integer - The number of table columns to use as stubs (row titles, on the - left). Defaults to 0. - -``header`` : CSV data - Supplemental data for the table header, added independently of and - before any ``header-rows`` from the main CSV data. Must use the - same CSV format as the main CSV data. - -``file`` : string (newlines removed) - The local filesystem path to a CSV data file. - -``url`` : string (whitespace removed) - An Internet URL reference to a CSV data file. - -``encoding`` : name of text encoding - The text encoding of the external CSV data (file or URL). - Defaults to the document's encoding (if specified). - -``delim`` : char | "tab" | "space" - A one-character string used to separate fields. Defaults to ``,`` - (comma). May be specified as a Unicode code point; see the - unicode_ directive for syntax details. - -``quote`` : char - A one-character string used to quote elements containing the - delimiter or which start with the quote character. Defaults to - ``"`` (quote). May be specified as a Unicode code point; see the - unicode_ directive for syntax details. - -``keepspace`` : flag - Treat whitespace immediately following the delimiter as - significant. The default is to ignore such whitespace. - -``escape`` : char - A one-character string used to escape the delimiter or quote - characters. May be specified as a Unicode code point; see the - unicode_ directive for syntax details. Used when the delimiter is - used in an unquoted field, or when quote characters are used - within a field. The default is to double-up the character, - e.g. "He said, ""Hi!""" - - .. Add another possible value, "double", to explicitly indicate - the default case? - - -List Table -========== - -:Directive Type: "list-table" -:Doctree Element: table -:Directive Arguments: 1, optional (table title). -:Directive Options: Possible. -:Directive Content: A uniform two-level bullet list. - -(New in Docutils 0.3.8. This is an initial implementation; `further -ideas`__ may be implemented in the future.) - -__ ../../dev/rst/alternatives.html#list-driven-tables - -The "list-table" directive is used to create a table from data in a -uniform two-level bullet list. "Uniform" means that each sublist -(second-level list) must contain the same number of list items. - -Example:: - - .. list-table:: Frozen Delights! - :widths: 15 10 30 - :header-rows: 1 - - * - Treat - - Quantity - - Description - * - Albatross - - 2.99 - - On a stick! - * - Crunchy Frog - - 1.49 - - If we took the bones out, it wouldn't be - crunchy, now would it? - * - Gannet Ripple - - 1.99 - - On a stick! - -The following options are recognized: - -``class`` : text - Set a "class" attribute value on the table element. See the - class_ directive below. - -``widths`` : integer [integer...] - A comma- or space-separated list of relative column widths. The - default is equal-width columns (100%/#columns). - -``header-rows`` : integer - The number of rows of list data to use in the table header. - Defaults to 0. - -``stub-columns`` : integer - The number of table columns to use as stubs (row titles, on the - left). Defaults to 0. - - ----------------- - Document Parts ----------------- - -.. _contents: - -Table of Contents -================= - -:Directive Type: "contents" -:Doctree Elements: pending, topic -:Directive Arguments: One, optional: title. -:Directive Options: Possible. -:Directive Content: None. - -The "contents" directive generates a table of contents (TOC) in a -topic_. Topics, and therefore tables of contents, may occur anywhere -a section or transition may occur. Body elements and topics may not -contain tables of contents. - -Here's the directive in its simplest form:: - - .. contents:: - -Language-dependent boilerplate text will be used for the title. The -English default title text is "Contents". - -An explicit title may be specified:: - - .. contents:: Table of Contents - -The title may span lines, although it is not recommended:: - - .. contents:: Here's a very long Table of - Contents title - -Options may be specified for the directive, using a field list:: - - .. contents:: Table of Contents - :depth: 2 - -If the default title is to be used, the options field list may begin -on the same line as the directive marker:: - - .. contents:: :depth: 2 - -The following options are recognized: - -``depth`` : integer - The number of section levels that are collected in the table of - contents. The default is unlimited depth. - -``local`` : flag (empty) - Generate a local table of contents. Entries will only include - subsections of the section in which the directive is given. If no - explicit title is given, the table of contents will not be titled. - -``backlinks`` : "entry" or "top" or "none" - Generate links from section headers back to the table of contents - entries, the table of contents itself, or generate no backlinks. - -``class`` : text - Set a "class" attribute value on the topic element. See the - class_ directive below. - - -.. _sectnum: -.. _section-autonumbering: - -Automatic Section Numbering -=========================== - -:Directive Type: "sectnum" or "section-autonumbering" (synonyms) -:Doctree Elements: pending, generated -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: None. - -The "sectnum" (or "section-autonumbering") directive automatically -numbers sections and subsections in a document. Section numbers are -of the "multiple enumeration" form, where each level has a number, -separated by periods. For example, the title of section 1, subsection -2, subsubsection 3 would have "1.2.3" prefixed. - -The "sectnum" directive does its work in two passes: the initial parse -and a transform. During the initial parse, a "pending" element is -generated which acts as a placeholder, storing any options internally. -At a later stage in the processing, the "pending" element triggers a -transform, which adds section numbers to titles. Section numbers are -enclosed in a "generated" element, and titles have their "auto" -attribute set to "1". - -The following options are recognized: - -``depth`` : integer - The number of section levels that are numbered by this directive. - The default is unlimited depth. - -``prefix`` : string - An arbitrary string that is prefixed to the automatically - generated section numbers. It may be something like "3.2.", which - will produce "3.2.1", "3.2.2", "3.2.2.1", and so on. Note that - any separating punctuation (in the example, a period, ".") must be - explicitly provided. The default is no prefix. - -``suffix`` : string - An arbitrary string that is appended to the automatically - generated section numbers. The default is no suffix. - -``start`` : integer - The value that will be used for the first section number. - Combined with ``prefix``, this may be used to force the right - numbering for a document split over several source files. The - default is 1. - - -.. _header: -.. _footer: - -Document Header & Footer -======================== - -:Directive Types: "header" and "footer" -:Doctree Elements: decoration, header, footer -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as body elements. - -(New in Docutils 0.3.8) - -The "header" and "footer" directives create document decorations, -useful for page navigation, notes, time/datestamp, etc. For example:: - - .. header:: This space for rent. - -This will add a paragraph to the document header, which will appear at -the top of the generated web page or at the top of every printed page. - -These directives may be used multiple times, cumulatively. There is -currently support for only one header and footer. - -.. note:: - - While it is possible to use the "header" and "footer" directives to - create navigational elements for web pages, you should be aware - that Docutils is meant to be used for *document* processing, and - that a navigation bar is not typically part of a document. - - Thus, you may soon find Docutils' abilities to be insufficient for - these purposes. At that time, you should consider using a - templating system (like ht2html_) rather than the "header" and - "footer" directives. - - .. _ht2html: http://ht2html.sourceforge.net/ - -In addition to the use of these directives to populate header and -footer content, content may also be added automatically by the -processing system. For example, if certain runtime settings are -enabled, the document footer is populated with processing information -such as a datestamp, a link to `the Docutils website`_, etc. - -.. _the Docutils website: http://docutils.sourceforge.net - - ------------- - References ------------- - -.. _target-notes: - -Target Footnotes -================ - -:Directive Type: "target-notes" -:Doctree Elements: pending, footnote, footnote_reference -:Directive Arguments: None. -:Directive Options: Possible. -:Directive Content: None. - -The "target-notes" directive creates a footnote for each external -target in the text, and corresponding footnote references after each -reference. For every explicit target (of the form, ``.. _target name: -URL``) in the text, a footnote will be generated containing the -visible URL as content. - -The following option is recognized: - -``class`` : text - Set a "class" attribute value on all footnote_reference elements. - See the class_ directive below. - - -Footnotes -========= - -**NOT IMPLEMENTED YET** - -:Directive Type: "footnotes" -:Doctree Elements: pending, topic -:Directive Arguments: None? -:Directive Options: Possible? -:Directive Content: None. - -@@@ - - -Citations -========= - -**NOT IMPLEMENTED YET** - -:Directive Type: "citations" -:Doctree Elements: pending, topic -:Directive Arguments: None? -:Directive Options: Possible? -:Directive Content: None. - -@@@ - - ---------------- - HTML-Specific ---------------- - -Meta -==== - -:Directive Type: "meta" -:Doctree Element: meta (non-standard) -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Must contain a flat field list. - -The "meta" directive is used to specify HTML metadata stored in HTML -META tags. "Metadata" is data about data, in this case data about web -pages. Metadata is used to describe and classify web pages in the -World Wide Web, in a form that is easy for search engines to extract -and collate. - -Within the directive block, a flat field list provides the syntax for -metadata. The field name becomes the contents of the "name" attribute -of the META tag, and the field body (interpreted as a single string -without inline markup) becomes the contents of the "content" -attribute. For example:: - - .. meta:: - :description: The reStructuredText plaintext markup language - :keywords: plaintext, markup language - -This would be converted to the following HTML:: - - <meta name="description" - content="The reStructuredText plaintext markup language"> - <meta name="keywords" content="plaintext, markup language"> - -Support for other META attributes ("http-equiv", "scheme", "lang", -"dir") are provided through field arguments, which must be of the form -"attr=value":: - - .. meta:: - :description lang=en: An amusing story - :description lang=fr: Un histoire amusant - -And their HTML equivalents:: - - <meta name="description" lang="en" content="An amusing story"> - <meta name="description" lang="fr" content="Un histoire amusant"> - -Some META tags use an "http-equiv" attribute instead of the "name" -attribute. To specify "http-equiv" META tags, simply omit the name:: - - .. meta:: - :http-equiv=Content-Type: text/html; charset=ISO-8859-1 - -HTML equivalent:: - - <meta http-equiv="Content-Type" - content="text/html; charset=ISO-8859-1"> - - -Imagemap -======== - -**NOT IMPLEMENTED YET** - -Non-standard element: imagemap. - - ------------------------------------------ - Directives for Substitution Definitions ------------------------------------------ - -The directives in this section may only be used in substitution -definitions. They may not be used directly, in standalone context. -The `image`_ directive may be used both in substitution definitions -and in the standalone context. - - -.. _replace: - -Replacement Text -================ - -:Directive Type: "replace" -:Doctree Element: Text & inline elements -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: A single paragraph; may contain inline markup. - -The "replace" directive is used to indicate replacement text for a -substitution reference. It may be used within substitution -definitions only. For example, this directive can be used to expand -abbreviations:: - - .. |reST| replace:: reStructuredText - - Yes, |reST| is a long word, so I can't blame anyone for wanting to - abbreviate it. - -As reStructuredText doesn't support nested inline markup, the only way -to create a reference with styled text is to use substitutions with -the "replace" directive:: - - I recommend you try |Python|_. - - .. |Python| replace:: Python, *the* best language around - .. _Python: http://www.python.org/ - - -.. _unicode: - -Unicode Character Codes -======================= - -:Directive Type: "unicode" -:Doctree Element: Text -:Directive Arguments: One or more, required (Unicode character codes, - optional text, and comments). -:Directive Options: Possible. -:Directive Content: None. - -The "unicode" directive converts Unicode character codes (numerical -values) to characters, and may be used in substitution definitions -only. - -The arguments, separated by spaces, can be: - -* **character codes** as - - - decimal numbers or - - - hexadecimal numbers, prefixed by ``0x``, ``x``, ``\x``, ``U+``, - ``u``, or ``\u`` or as XML-style hexadecimal character entities, - e.g. ``ᨫ`` - -* **text**, which is used as-is. - -Text following " .. " is a comment and is ignored. The spaces between -the arguments are ignored and thus do not appear in the output. -Hexadecimal codes are case-insensitive. - -For example, the following text:: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -results in: - - Copyright |copy| 2003, |BogusMegaCorp (TM)| |---| - all rights reserved. - - .. |copy| unicode:: 0xA9 .. copyright sign - .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 - .. with trademark sign - .. |---| unicode:: U+02014 .. em dash - :trim: - -The following options are recognized: - -``ltrim`` : flag - Whitespace to the left of the substitution reference is removed. - -``rtrim`` : flag - Whitespace to the right of the substitution reference is removed. - -``trim`` : flag - Equivalent to ``ltrim`` plus ``rtrim``; whitespace on both sides - of the substitution reference is removed. - - -Date -==== - -:Directive Type: "date" -:Doctree Element: Text -:Directive Arguments: One, optional (date format). -:Directive Options: None. -:Directive Content: None. - -The "date" directive generates the current local date and inserts it -into the document as text. This directive may be used in substitution -definitions only. - -The optional directive content is interpreted as the desired date -format, using the same codes as Python's time.strftime function. The -default format is "%Y-%m-%d" (ISO 8601 date), but time fields can also -be used. Examples:: - - .. |date| date:: - .. |time| date:: %H:%M - - Today's date is |date|. - - This document was generated on |date| at |time|. - - ---------------- - Miscellaneous ---------------- - -.. _include: - -Including an External Document Fragment -======================================= - -:Directive Type: "include" -:Doctree Elements: depend on data being included -:Directive Arguments: One, required (path to the file to include). -:Directive Options: Possible. -:Directive Content: None. - -.. WARNING:: - - The "include" directive represents a potential security hole. It - can be disabled with the "file_insertion_enabled_" runtime setting. - - .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled - -The "include" directive reads a reStructuredText-formatted text file -and parses it in the current document's context at the point of the -directive. The directive argument is the path to the file to be -included, relative to the document containing the directive. For -example:: - - This first example will be parsed at the document level, and can - thus contain any construct, including section headers. - - .. include:: inclusion.txt - - Back in the main document. - - This second example will be parsed in a block quote context. - Therefore it may only contain body elements. It may not - contain section headers. - - .. include:: inclusion.txt - -If an included document fragment contains section structure, the title -adornments must match those of the master document. - -Standard data files intended for inclusion in reStructuredText -documents are distributed with the Docutils source code, located in -the "docutils" package in the ``docutils/parsers/rst/include`` -directory. To access these files, use the special syntax for standard -"include" data files, angle brackets around the file name:: - - .. include:: <isonum.txt> - -The current set of standard "include" data files consists of sets of -substitution definitions. See `reStructuredText Standard Substitution -Definition Sets`__ for details of the available standard data files. - -__ substitutions.html - -The following options are recognized: - -``literal`` : flag (empty) - The entire included text is inserted into the document as a single - literal block (useful for program listings). - -``encoding`` : name of text encoding - The text encoding of the external data file. Defaults to the - document's encoding (if specified). - - -.. _raw: - -Raw Data Pass-Through -===================== - -:Directive Type: "raw" -:Doctree Element: raw -:Directive Arguments: One or more, required (output format types). -:Directive Options: Possible. -:Directive Content: Stored verbatim, uninterpreted. None (empty) if a - "file" or "url" option given. - -.. WARNING:: - - The "raw" directive represents a potential security hole. It can - be disabled with the "raw_enabled_" or "file_insertion_enabled_" - runtime settings. - - .. _raw_enabled: ../../user/config.html#raw-enabled - -.. Caution:: - - The "raw" directive is a stop-gap measure allowing the author to - bypass reStructuredText's markup. It is a "power-user" feature - that should not be overused or abused. The use of "raw" ties - documents to specific output formats and makes them less portable. - - If you often need to use the "raw" directive or a "raw"-derived - interpreted text role, that is a sign either of overuse/abuse or - that functionality may be missing from reStructuredText. Please - describe your situation in a message to the Docutils-users_ mailing - list. - -.. _Docutils-users: ../../user/mailing-lists.html#docutils-users - -The "raw" directive indicates non-reStructuredText data that is to be -passed untouched to the Writer. The names of the output formats are -given in the directive arguments. The interpretation of the raw data -is up to the Writer. A Writer may ignore any raw output not matching -its format. - -For example, the following input would be passed untouched by an HTML -Writer:: - - .. raw:: html - - <hr width=50 size=10> - -A LaTeX Writer could insert the following raw content into its -output stream:: - - .. raw:: latex - - \setlength{\parindent}{0pt} - -Raw data can also be read from an external file, specified in a -directive option. In this case, the content block must be empty. For -example:: - - .. raw:: html - :file: inclusion.html - -The following options are recognized: - -``file`` : string (newlines removed) - The local filesystem path of a raw data file to be included. - -``url`` : string (whitespace removed) - An Internet URL reference to a raw data file to be included. - -``encoding`` : name of text encoding - The text encoding of the external raw data (file or URL). - Defaults to the document's encoding (if specified). - - -Class -===== - -:Directive Type: "class" -:Doctree Element: pending -:Directive Arguments: One or more, required (class names / attribute - values). -:Directive Options: None. -:Directive Content: Optional. If present, it is interpreted as body - elements. - -The "class" directive sets the "class" attribute value on its content -or on the first immediately following non-comment element [#]_. For -details of the "class" attribute, see `its entry`__ in `The Docutils -Document Tree`_. The directive argument consists of one or more -space-separated class names, which are converted to lowercase and all -non-alphanumeric characters are converted to hyphens. (For the -rationale, see below.) - -__ ../doctree.html#class - -Examples:: - - .. class:: special - - This is a "special" paragraph. - - .. class:: exceptional remarkable - - An Exceptional Section - ====================== - - This is an ordinary paragraph. - - .. class:: multiple - - First paragraph. - - Second paragraph. - -The text above is parsed and transformed into this doctree fragment:: - - <paragraph class="special"> - This is a "special" paragraph. - <section class="exceptional remarkable"> - <title> - An Exceptional Section - <paragraph> - This is an ordinary paragraph. - <paragraph class="multiple"> - First paragraph. - <paragraph class="multiple"> - Second paragraph. - -.. [#] To set a "class" attribute value on a block quote, the "class" - directive must be followed by an empty comment:: - - .. class:: highlights - .. - - Block quote text. - - The directive doesn't allow content, therefore an empty comment is - required to terminate the directive. Without the empty comment, - the block quote text would be interpreted as the "class" - directive's content, and the parser would complain. - -.. topic:: Rationale for Class Attribute Value Conversion - - Docutils identifiers are converted to conform to the regular - expression ``[a-z](-?[a-z0-9]+)*``. For CSS compatibility, - identifiers (the "class" and "id" attributes) should have no - underscores, colons, or periods. Hyphens may be used. - - - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens: - - ID and NAME tokens must begin with a letter ([A-Za-z]) and - may be followed by any number of letters, digits ([0-9]), - hyphens ("-"), underscores ("_"), colons (":"), and periods - ("."). - - - However the `CSS1 spec`_ defines identifiers based on the "name" - token, a tighter interpretation ("flex" tokenizer notation - below; "latin1" and "escape" 8-bit characters have been replaced - with entities):: - - unicode \\[0-9a-f]{1,4} - latin1 [¡-ÿ] - escape {unicode}|\\[ -~¡-ÿ] - nmchar [-a-z0-9]|{latin1}|{escape} - name {nmchar}+ - - The CSS1 "nmchar" rule does not include underscores ("_"), colons - (":"), or periods ("."), therefore "class" and "id" attributes - should not contain these characters. They should be replaced with - hyphens ("-"). Combined with HTML's requirements (the first - character must be a letter; no "unicode", "latin1", or "escape" - characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern. - - .. _HTML 4.01 spec: http://www.w3.org/TR/html401/ - .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1 - - -.. _role: - -Custom Interpreted Text Roles -============================= - -:Directive Type: "role" -:Doctree Element: None; affects subsequent parsing. -:Directive Arguments: Two; one required (new role name), one optional - (base role name, in parentheses). -:Directive Options: Possible (depends on base role). -:Directive Content: depends on base role. - -(New in Docutils 0.3.2) - -The "role" directive dynamically creates a custom interpreted text -role and registers it with the parser. This means that after -declaring a role like this:: - - .. role:: custom - -the document may use the new "custom" role:: - - An example of using :custom:`interpreted text` - -This will be parsed into the following document tree fragment:: - - <paragraph> - An example of using - <inline class="custom"> - interpreted text - -The role must be declared in a document before it can be used. - -The new role may be based on an existing role, specified as a second -argument in parentheses (whitespace optional):: - - .. role:: custom(emphasis) - - :custom:`text` - -The parsed result is as follows:: - - <paragraph> - <emphasis class="custom"> - text - -If no base role is explicitly specified, a generic custom role is -automatically used. Subsequent interpreted text will produce an -"inline" element with a "class" attribute, as in the first example -above. - -With most roles, the ":class:" option can be used to set a "class" -attribute that is different from the role name. For example:: - - .. role:: custom - :class: special - - :custom:`interpreted text` - -This is the parsed result:: - - <paragraph> - <inline class="special"> - interpreted text - -.. _role class: - -The following option is recognized by the "role" directive for most -base roles: - -``class`` : text - Set a "class" attribute value on the element produced (``inline``, - or element associated with a base class) when the custom - interpreted text role is used. If no directive options are - specified, a "class" option with the directive argument (role - name) as the value is implied. See the class_ directive above. - -Specific base roles may support other options and/or directive -content. See the `reStructuredText Interpreted Text Roles`_ document -for details. - -.. _reStructuredText Interpreted Text Roles: roles.html - - -.. _default-role: - -Setting the Default Interpreted Text Role -========================================= - -:Directive Type: "default-role" -:Doctree Element: None; affects subsequent parsing. -:Directive Arguments: One, optional (new default role name). -:Directive Options: None. -:Directive Content: None. - -(New in Docutils 0.3.10) - -The "default-role" directive sets the default interpreted text role, -the role that is used for interpreted text without an explicit role. -For example, after setting the default role like this:: - - .. default-role:: subscript - -any subsequent use of implicit-role interpreted text in the document -will use the "subscript" role:: - - An example of a `default` role. - -This will be parsed into the following document tree fragment:: - - <paragraph> - An example of a - <subscript> - default - role. - -Custom roles may be used (see the "role_" directive above), but it -must have been declared in a document before it can be set as the -default role. See the `reStructuredText Interpreted Text Roles`_ -document for details of built-in roles. - -The directive may be used without an argument to restore the initial -default interpreted text role, which is application-dependent. The -initial default interpreted text role of the standard reStructuredText -parser is "title-reference". - - -.. _title: - -Metadata Document Title -======================= - -:Directive Type: "title" -:Doctree Element: None. -:Directive Arguments: 1, required (the title text). -:Directive Options: None. -:Directive Content: None. - -The "title" directive specifies the document title as metadata, which -does not become part of the document body. It overrides a -document-supplied title. For example, in HTML output the metadata -document title appears in the title bar of the browser window. - - -Restructuredtext-Test-Directive -=============================== - -:Directive Type: "restructuredtext-test-directive" -:Doctree Element: system_warning -:Directive Arguments: None. -:Directive Options: None. -:Directive Content: Interpreted as a literal block. - -This directive is provided for test purposes only. (Nobody is -expected to type in a name *that* long!) It is converted into a -level-1 (info) system message showing the directive data, possibly -followed by a literal block containing the rest of the directive -block. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/introduction.txt b/docutils/docs/ref/rst/introduction.txt deleted file mode 100644 index b7829816e..000000000 --- a/docutils/docs/ref/rst/introduction.txt +++ /dev/null @@ -1,314 +0,0 @@ -===================================== - An Introduction to reStructuredText -===================================== -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get -plaintext markup syntax and parser system. It is useful for inline -program documentation (such as Python docstrings), for quickly -creating simple web pages, and for standalone documents. -reStructuredText_ is a proposed revision and reinterpretation of the -StructuredText_ and Setext_ lightweight markup systems. - -reStructuredText is designed for extensibility for specific -application domains. Its parser is a component of Docutils_. - -This document defines the goals_ of reStructuredText and provides a -history_ of the project. It is written using the reStructuredText -markup, and therefore serves as an example of its use. For a gentle -introduction to using reStructuredText, please read `A -ReStructuredText Primer`_. The `Quick reStructuredText`_ user -reference is also useful. The `reStructuredText Markup -Specification`_ is the definitive reference. There is also an -analysis of the `Problems With StructuredText`_. - -ReStructuredText's web page is -http://docutils.sourceforge.net/rst.html. - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _StructuredText: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage -.. _Setext: http://docutils.sourceforge.net/mirror/setext.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _A ReStructuredText Primer: ../../user/rst/quickstart.html -.. _Quick reStructuredText: ../../user/rst/quickref.html -.. _reStructuredText Markup Specification: restructuredtext.html -.. _Problems with StructuredText: ../../dev/rst/problems.html - - -Goals -===== - -The primary goal of reStructuredText_ is to define a markup syntax for -use in Python docstrings and other documentation domains, that is -readable and simple, yet powerful enough for non-trivial use. The -intended purpose of the reStructuredText markup is twofold: - -- the establishment of a set of standard conventions allowing the - expression of structure within plaintext, and - -- the conversion of such documents into useful structured data - formats. - -The secondary goal of reStructuredText is to be accepted by the Python -community (by way of being blessed by PythonLabs and the BDFL [#]_) as -a standard for Python inline documentation (possibly one of several -standards, to account for taste). - -.. [#] Python's creator and "Benevolent Dictator For Life", - Guido van Rossum. - -To clarify the primary goal, here are specific design goals, in order, -beginning with the most important: - -1. Readable. The marked-up text must be easy to read without any - prior knowledge of the markup language. It should be as easily - read in raw form as in processed form. - -2. Unobtrusive. The markup that is used should be as simple and - unobtrusive as possible. The simplicity of markup constructs - should be roughly proportional to their frequency of use. The most - common constructs, with natural and obvious markup, should be the - simplest and most unobtrusive. Less common constructs, for which - there is no natural or obvious markup, should be distinctive. - -3. Unambiguous. The rules for markup must not be open for - interpretation. For any given input, there should be one and only - one possible output (including error output). - -4. Unsurprising. Markup constructs should not cause unexpected output - upon processing. As a fallback, there must be a way to prevent - unwanted markup processing when a markup construct is used in a - non-markup context (for example, when documenting the markup syntax - itself). - -5. Intuitive. Markup should be as obvious and easily remembered as - possible, for the author as well as for the reader. Constructs - should take their cues from such naturally occurring sources as - plaintext email messages, newsgroup postings, and text - documentation such as README.txt files. - -6. Easy. It should be easy to mark up text using any ordinary text - editor. - -7. Scalable. The markup should be applicable regardless of the length - of the text. - -8. Powerful. The markup should provide enough constructs to produce a - reasonably rich structured document. - -9. Language-neutral. The markup should apply to multiple natural (as - well as artificial) languages, not only English. - -10. Extensible. The markup should provide a simple syntax and - interface for adding more complex general markup, and custom - markup. - -11. Output-format-neutral. The markup will be appropriate for - processing to multiple output formats, and will not be biased - toward any particular format. - -The design goals above were used as criteria for accepting or -rejecting syntax, or selecting between alternatives. - -It is emphatically *not* the goal of reStructuredText to define -docstring semantics, such as docstring contents or docstring length. -These issues are orthogonal to the markup syntax and beyond the scope -of this specification. - -Also, it is not the goal of reStructuredText to maintain compatibility -with StructuredText_ or Setext_. reStructuredText shamelessly steals -their great ideas and ignores the not-so-great. - -Author's note: - - Due to the nature of the problem we're trying to solve (or, - perhaps, due to the nature of the proposed solution), the above - goals unavoidably conflict. I have tried to extract and distill - the wisdom accumulated over the years in the Python Doc-SIG_ - mailing list and elsewhere, to come up with a coherent and - consistent set of syntax rules, and the above goals by which to - measure them. - - There will inevitably be people who disagree with my particular - choices. Some desire finer control over their markup, others - prefer less. Some are concerned with very short docstrings, - others with full-length documents. This specification is an - effort to provide a reasonably rich set of markup constructs in a - reasonably simple form, that should satisfy a reasonably large - group of reasonable people. - - David Goodger (goodger@users.sourceforge.net), 2001-04-20 - -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - - -History -======= - -reStructuredText_, the specification, is based on StructuredText_ and -Setext_. StructuredText was developed by Jim Fulton of `Zope -Corporation`_ (formerly Digital Creations) and first released in 1996. -It is now released as a part of the open-source "Z Object Publishing -Environment" (ZOPE_). Ian Feldman's and Tony Sanders' earlier Setext_ -specification was either an influence on StructuredText or, by their -similarities, at least evidence of the correctness of this approach. - -I discovered StructuredText_ in late 1999 while searching for a way to -document the Python modules in one of my projects. Version 1.1 of -StructuredText was included in Daniel Larsson's pythondoc_. Although -I was not able to get pythondoc to work for me, I found StructuredText -to be almost ideal for my needs. I joined the Python Doc-SIG_ -(Documentation Special Interest Group) mailing list and found an -ongoing discussion of the shortcomings of the StructuredText -"standard". This discussion has been going on since the inception of -the mailing list in 1996, and possibly predates it. - -I decided to modify the original module with my own extensions and -some suggested by the Doc-SIG members. I soon realized that the -module was not written with extension in mind, so I embarked upon a -general reworking, including adapting it to the "re" regular -expression module (the original inspiration for the name of this -project). Soon after I completed the modifications, I discovered that -StructuredText.py was up to version 1.23 in the ZOPE distribution. -Implementing the new syntax extensions from version 1.23 proved to be -an exercise in frustration, as the complexity of the module had become -overwhelming. - -In 2000, development on StructuredTextNG_ ("Next Generation") began at -`Zope Corporation`_ (then Digital Creations). It seems to have many -improvements, but still suffers from many of the problems of classic -StructuredText. - -I decided that a complete rewrite was in order, and even started a -`reStructuredText SourceForge project`_ (now inactive). My -motivations (the "itches" I aim to "scratch") are as follows: - -- I need a standard format for inline documentation of the programs I - write. This inline documentation has to be convertible to other - useful formats, such as HTML. I believe many others have the same - need. - -- I believe in the Setext/StructuredText idea and want to help - formalize the standard. However, I feel the current specifications - and implementations have flaws that desperately need fixing. - -- reStructuredText could form part of the foundation for a - documentation extraction and processing system, greatly benefitting - Python. But it is only a part, not the whole. reStructuredText is - a markup language specification and a reference parser - implementation, but it does not aspire to be the entire system. I - don't want reStructuredText or a hypothetical Python documentation - processor to die stillborn because of over-ambition. - -- Most of all, I want to help ease the documentation chore, the bane - of many a programmer. - -Unfortunately I was sidetracked and stopped working on this project. -In November 2000 I made the time to enumerate the problems of -StructuredText and possible solutions, and complete the first draft of -a specification. This first draft was posted to the Doc-SIG in three -parts: - -- `A Plan for Structured Text`__ -- `Problems With StructuredText`__ -- `reStructuredText: Revised Structured Text Specification`__ - -__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001240.html -__ http://mail.python.org/pipermail/doc-sig/2000-November/001241.html - -In March 2001 a flurry of activity on the Doc-SIG spurred me to -further revise and refine my specification, the result of which you -are now reading. An offshoot of the reStructuredText project has been -the realization that a single markup scheme, no matter how well -thought out, may not be enough. In order to tame the endless debates -on Doc-SIG, a flexible `Docstring Processing System framework`_ needed -to be constructed. This framework has become the more important of -the two projects; reStructuredText_ has found its place as one -possible choice for a single component of the larger framework. - -The project web site and the first project release were rolled out in -June 2001, including posting the second draft of the spec [#spec-2]_ -and the first draft of PEPs 256, 257, and 258 [#peps-1]_ to the -Doc-SIG. These documents and the project implementation proceeded to -evolve at a rapid pace. Implementation history details can be found -in the `project history file`_. - -In November 2001, the reStructuredText parser was nearing completion. -Development of the parser continued with the addition of small -convenience features, improvements to the syntax, the filling in of -gaps, and bug fixes. After a long holiday break, in early 2002 most -development moved over to the other Docutils components, the -"Readers", "Writers", and "Transforms". A "standalone" reader -(processes standalone text file documents) was completed in February, -and a basic HTML writer (producing HTML 4.01, using CSS-1) was -completed in early March. - -`PEP 287`_, "reStructuredText Standard Docstring Format", was created -to formally propose reStructuredText as a standard format for Python -docstrings, PEPs, and other files. It was first posted to -comp.lang.python_ and the Python-dev_ mailing list on 2002-04-02. - -Version 0.4 of the reStructuredText__ and `Docstring Processing -System`_ projects were released in April 2002. The two projects were -immediately merged, renamed to "Docutils_", and a 0.1 release soon -followed. - -.. __: `reStructuredText SourceForge project`_ - -.. [#spec-2] The second draft of the spec: - - - `An Introduction to reStructuredText`__ - - `Problems With StructuredText`__ - - `reStructuredText Markup Specification`__ - - `Python Extensions to the reStructuredText Markup - Specification`__ - - __ http://mail.python.org/pipermail/doc-sig/2001-June/001858.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001859.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001860.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001861.html - -.. [#peps-1] First drafts of the PEPs: - - - `PEP 256: Docstring Processing System Framework`__ - - `PEP 258: DPS Generic Implementation Details`__ - - `PEP 257: Docstring Conventions`__ - - Current working versions of the PEPs can be found in - http://docutils.sourceforge.net/docs/peps/, and official versions - can be found in the `master PEP repository`_. - - __ http://mail.python.org/pipermail/doc-sig/2001-June/001855.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001856.html - __ http://mail.python.org/pipermail/doc-sig/2001-June/001857.html - - -.. _Zope Corporation: http://www.zope.com -.. _ZOPE: http://www.zope.org -.. _reStructuredText SourceForge project: - http://structuredtext.sourceforge.net/ -.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/ -.. _StructuredTextNG: - http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/StructuredTextNG -.. _project history file: ../../../HISTORY.html -.. _PEP 287: ../../peps/pep-0287.html -.. _Docstring Processing System framework: ../../peps/pep-0256.html -.. _comp.lang.python: news:comp.lang.python -.. _Python-dev: http://mail.python.org/pipermail/python-dev/ -.. _Docstring Processing System: http://docstring.sourceforge.net/ -.. _master PEP repository: http://www.python.org/peps/ - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt deleted file mode 100644 index 1445619b3..000000000 --- a/docutils/docs/ref/rst/restructuredtext.txt +++ /dev/null @@ -1,2879 +0,0 @@ -======================================= - reStructuredText Markup Specification -======================================= -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. Note:: - - This document is a detailed technical specification; it is not a - tutorial or a primer. If this is your first exposure to - reStructuredText, please read `A ReStructuredText Primer`_ and the - `Quick reStructuredText`_ user reference first. - -.. _A ReStructuredText Primer: ../../user/rst/quickstart.html -.. _Quick reStructuredText: ../../user/rst/quickref.html - - -reStructuredText_ is plaintext that uses simple and intuitive -constructs to indicate the structure of a document. These constructs -are equally easy to read in raw and processed forms. This document is -itself an example of reStructuredText (raw, if you are reading the -text file, or processed, if you are reading an HTML document, for -example). The reStructuredText parser is a component of Docutils_. - -Simple, implicit markup is used to indicate special constructs, such -as section headings, bullet lists, and emphasis. The markup used is -as minimal and unobtrusive as possible. Less often-used constructs -and extensions to the basic reStructuredText syntax may have more -elaborate or explicit markup. - -reStructuredText is applicable to documents of any length, from the -very small (such as inline program documentation fragments, e.g. -Python docstrings) to the quite large (this document). - -The first section gives a quick overview of the syntax of the -reStructuredText markup by example. A complete specification is given -in the `Syntax Details`_ section. - -`Literal blocks`_ (in which no markup processing is done) are used for -examples throughout this document, to illustrate the plaintext markup. - - -.. contents:: - - ------------------------ - Quick Syntax Overview ------------------------ - -A reStructuredText document is made up of body or block-level -elements, and may be structured into sections. Sections_ are -indicated through title style (underlines & optional overlines). -Sections contain body elements and/or subsections. Some body elements -contain further elements, such as lists containing list items, which -in turn may contain paragraphs and other body elements. Others, such -as paragraphs, contain text and `inline markup`_ elements. - -Here are examples of `body elements`_: - -- Paragraphs_ (and `inline markup`_):: - - Paragraphs contain text and may contain inline markup: - *emphasis*, **strong emphasis**, `interpreted text`, ``inline - literals``, standalone hyperlinks (http://www.python.org), - external hyperlinks (Python_), internal cross-references - (example_), footnote references ([1]_), citation references - ([CIT2002]_), substitution references (|example|), and _`inline - internal targets`. - - Paragraphs are separated by blank lines and are left-aligned. - -- Five types of lists: - - 1. `Bullet lists`_:: - - - This is a bullet list. - - - Bullets can be "-", "*", or "+". - - 2. `Enumerated lists`_:: - - 1. This is an enumerated list. - - 2. Enumerators may be arabic numbers, letters, or roman - numerals. - - 3. `Definition lists`_:: - - what - Definition lists associate a term with a definition. - - how - The term is a one-line phrase, and the definition is one - or more paragraphs or body elements, indented relative to - the term. - - 4. `Field lists`_:: - - :what: Field lists map field names to field bodies, like - database records. They are often part of an extension - syntax. - - :how: The field marker is a colon, the field name, and a - colon. - - The field body may contain one or more body elements, - indented relative to the field marker. - - 5. `Option lists`_, for listing command-line options:: - - -a command-line option "a" - -b file options can have arguments - and long descriptions - --long options can be long also - --input=file long options can also have - arguments - /V DOS/VMS-style options too - - There must be at least two spaces between the option and the - description. - -- `Literal blocks`_:: - - Literal blocks are either indented or line-prefix-quoted blocks, - and indicated with a double-colon ("::") at the end of the - preceding paragraph (right here -->):: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -- `Block quotes`_:: - - Block quotes consist of indented body elements: - - This theory, that is mine, is mine. - - -- Anne Elk (Miss) - -- `Doctest blocks`_:: - - >>> print 'Python-specific usage examples; begun with ">>>"' - Python-specific usage examples; begun with ">>>" - >>> print '(cut and pasted from interactive Python sessions)' - (cut and pasted from interactive Python sessions) - -- Two syntaxes for tables_: - - 1. `Grid tables`_; complete, but complex and verbose:: - - +------------------------+------------+----------+ - | Header row, column 1 | Header 2 | Header 3 | - +========================+============+==========+ - | body row 1, column 1 | column 2 | column 3 | - +------------------------+------------+----------+ - | body row 2 | Cells may span | - +------------------------+-----------------------+ - - 2. `Simple tables`_; easy and compact, but limited:: - - ==================== ========== ========== - Header row, column 1 Header 2 Header 3 - ==================== ========== ========== - body row 1, column 1 column 2 column 3 - body row 2 Cells may span columns - ==================== ====================== - -- `Explicit markup blocks`_ all begin with an explicit block marker, - two periods and a space: - - - Footnotes_:: - - .. [1] A footnote contains body elements, consistently - indented by at least 3 spaces. - - - Citations_:: - - .. [CIT2002] Just like a footnote, except the label is - textual. - - - `Hyperlink targets`_:: - - .. _Python: http://www.python.org - - .. _example: - - The "_example" target above points to this paragraph. - - - Directives_:: - - .. image:: mylogo.png - - - `Substitution definitions`_:: - - .. |symbol here| image:: symbol.png - - - Comments_:: - - .. Comments begin with two dots and a space. Anything may - follow, except for the syntax of footnotes/citations, - hyperlink targets, directives, or substitution definitions. - - ----------------- - Syntax Details ----------------- - -Descriptions below list "doctree elements" (document tree element -names; XML DTD generic identifiers) corresponding to syntax -constructs. For details on the hierarchy of elements, please see `The -Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document -type definition. - - -Whitespace -========== - -Spaces are recommended for indentation_, but tabs may also be used. -Tabs will be converted to spaces. Tab stops are at every 8th column. - -Other whitespace characters (form feeds [chr(12)] and vertical tabs -[chr(11)]) are converted to single spaces before processing. - - -Blank Lines ------------ - -Blank lines are used to separate paragraphs and other elements. -Multiple successive blank lines are equivalent to a single blank line, -except within literal blocks (where all whitespace is preserved). -Blank lines may be omitted when the markup makes element separation -unambiguous, in conjunction with indentation. The first line of a -document is treated as if it is preceded by a blank line, and the last -line of a document is treated as if it is followed by a blank line. - - -Indentation ------------ - -Indentation is used to indicate -- and is only significant in -indicating -- block quotes, definitions (in definition list items), -and local nested content: - -- list item content (multi-line contents of list items, and multiple - body elements within a list item, including nested lists), -- the content of literal blocks, and -- the content of explicit markup blocks. - -Any text whose indentation is less than that of the current level -(i.e., unindented text or "dedents") ends the current level of -indentation. - -Since all indentation is significant, the level of indentation must be -consistent. For example, indentation is the sole markup indicator for -`block quotes`_:: - - This is a top-level paragraph. - - This paragraph belongs to a first-level block quote. - - Paragraph 2 of the first-level block quote. - -Multiple levels of indentation within a block quote will result in -more complex structures:: - - This is a top-level paragraph. - - This paragraph belongs to a first-level block quote. - - This paragraph belongs to a second-level block quote. - - Another top-level paragraph. - - This paragraph belongs to a second-level block quote. - - This paragraph belongs to a first-level block quote. The - second-level block quote above is inside this first-level - block quote. - -When a paragraph or other construct consists of more than one line of -text, the lines must be left-aligned:: - - This is a paragraph. The lines of - this paragraph are aligned at the left. - - This paragraph has problems. The - lines are not left-aligned. In addition - to potential misinterpretation, warning - and/or error messages will be generated - by the parser. - -Several constructs begin with a marker, and the body of the construct -must be indented relative to the marker. For constructs using simple -markers (`bullet lists`_, `enumerated lists`_, footnotes_, citations_, -`hyperlink targets`_, directives_, and comments_), the level of -indentation of the body is determined by the position of the first -line of text, which begins on the same line as the marker. For -example, bullet list bodies must be indented by at least two columns -relative to the left edge of the bullet:: - - - This is the first line of a bullet list - item's paragraph. All lines must align - relative to the first line. [1]_ - - This indented paragraph is interpreted - as a block quote. - - Because it is not sufficiently indented, - this paragraph does not belong to the list - item. - - .. [1] Here's a footnote. The second line is aligned - with the beginning of the footnote label. The ".." - marker is what determines the indentation. - -For constructs using complex markers (`field lists`_ and `option -lists`_), where the marker may contain arbitrary text, the indentation -of the first line *after* the marker determines the left edge of the -body. For example, field lists may have very long markers (containing -the field names):: - - :Hello: This field has a short field name, so aligning the field - body with the first line is feasible. - - :Number-of-African-swallows-required-to-carry-a-coconut: It would - be very difficult to align the field body with the left edge - of the first line. It may even be preferable not to begin the - body on the same line as the marker. - - -Escaping Mechanism -================== - -The character set universally available to plaintext documents, 7-bit -ASCII, is limited. No matter what characters are used for markup, -they will already have multiple meanings in written text. Therefore -markup characters *will* sometimes appear in text **without being -intended as markup**. Any serious markup system requires an escaping -mechanism to override the default meaning of the characters used for -the markup. In reStructuredText we use the backslash, commonly used -as an escaping character in other domains. - -A backslash followed by any character (except whitespace characters) -escapes that character. The escaped character represents the -character itself, and is prevented from playing a role in any markup -interpretation. The backslash is removed from the output. A literal -backslash is represented by two backslashes in a row (the first -backslash "escapes" the second, preventing it being interpreted in an -"escaping" role). - -Backslash-escaped whitespace characters are removed from the document. -This allows for character-level `inline markup`_. - -There are two contexts in which backslashes have no special meaning: -literal blocks and inline literals. In these contexts, a single -backslash represents a literal backslash, without having to double up. - -Please note that the reStructuredText specification and parser do not -address the issue of the representation or extraction of text input -(how and in what form the text actually *reaches* the parser). -Backslashes and other characters may serve a character-escaping -purpose in certain contexts and must be dealt with appropriately. For -example, Python uses backslashes in strings to escape certain -characters, but not others. The simplest solution when backslashes -appear in Python docstrings is to use raw docstrings:: - - r"""This is a raw docstring. Backslashes (\) are not touched.""" - - -Reference Names -=============== - -Simple reference names are single words consisting of alphanumerics -plus isolated (no two adjacent) internal hyphens, underscores, and -periods; no whitespace or other characters are allowed. Footnote -labels (Footnotes_ & `Footnote References`_), citation labels -(Citations_ & `Citation References`_), `interpreted text`_ roles, and -some `hyperlink references`_ use the simple reference name syntax. - -Reference names using punctuation or whose names are phrases (two or -more space-separated words) are called "phrase-references". -Phrase-references are expressed by enclosing the phrase in backquotes -and treating the backquoted text as a reference name:: - - Want to learn about `my favorite programming language`_? - - .. _my favorite programming language: http://www.python.org - -Simple reference names may also optionally use backquotes. - -Reference names are whitespace-neutral and case-insensitive. When -resolving reference names internally: - -- whitespace is normalized (one or more spaces, horizontal or vertical - tabs, newlines, carriage returns, or form feeds, are interpreted as - a single space), and - -- case is normalized (all alphabetic characters are converted to - lowercase). - -For example, the following `hyperlink references`_ are equivalent:: - - - `A HYPERLINK`_ - - `a hyperlink`_ - - `A - Hyperlink`_ - -Hyperlinks_, footnotes_, and citations_ all share the same namespace -for reference names. The labels of citations (simple reference names) -and manually-numbered footnotes (numbers) are entered into the same -database as other hyperlink names. This means that a footnote -(defined as "``.. [1]``") which can be referred to by a footnote -reference (``[1]_``), can also be referred to by a plain hyperlink -reference (1_). Of course, each type of reference (hyperlink, -footnote, citation) may be processed and rendered differently. Some -care should be taken to avoid reference name conflicts. - - -Document Structure -================== - -Document --------- - -Doctree element: document. - -The top-level element of a parsed reStructuredText document is the -"document" element. After initial parsing, the document element is a -simple container for a document fragment, consisting of `body -elements`_, transitions_, and sections_, but lacking a document title -or other bibliographic elements. The code that calls the parser may -choose to run one or more optional post-parse transforms_, -rearranging the document fragment into a complete document with a -title and possibly other metadata elements (author, date, etc.; see -`Bibliographic Fields`_). - -Specifically, there is no way to indicate a document title and -subtitle explicitly in reStructuredText. Instead, a lone top-level -section title (see Sections_ below) can be treated as the document -title. Similarly, a lone second-level section title immediately after -the "document title" can become the document subtitle. The rest of -the sections are then lifted up a level or two. See the `DocTitle -transform`_ for details. - - -Sections --------- - -Doctree elements: section, title. - -Sections are identified through their titles, which are marked up with -adornment: "underlines" below the title text, or underlines and -matching "overlines" above the title. An underline/overline is a -single repeated punctuation character that begins in column 1 and -forms a line extending at least as far as the right edge of the title -text. Specifically, an underline/overline character may be any -non-alphanumeric printable 7-bit ASCII character [#]_. When an -overline is used, the length and character used must match the -underline. Underline-only adornment styles are distinct from -overline-and-underline styles that use the same character. There may -be any number of levels of section titles, although some output -formats may have limits (HTML has 6 levels). - -.. [#] The following are all valid section title adornment - characters:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - Some characters are more suitable than others. The following are - recommended:: - - = - ` : . ' " ~ ^ _ * + # - -Rather than imposing a fixed number and order of section title -adornment styles, the order enforced will be the order as encountered. -The first style encountered will be an outermost title (like HTML H1), -the second style will be a subtitle, the third will be a subsubtitle, -and so on. - -Below are examples of section title styles:: - - =============== - Section Title - =============== - - --------------- - Section Title - --------------- - - Section Title - ============= - - Section Title - ------------- - - Section Title - ````````````` - - Section Title - ''''''''''''' - - Section Title - ............. - - Section Title - ~~~~~~~~~~~~~ - - Section Title - ************* - - Section Title - +++++++++++++ - - Section Title - ^^^^^^^^^^^^^ - -When a title has both an underline and an overline, the title text may -be inset, as in the first two examples above. This is merely -aesthetic and not significant. Underline-only title text may *not* be -inset. - -A blank line after a title is optional. All text blocks up to the -next title of the same or higher level are included in a section (or -subsection, etc.). - -All section title styles need not be used, nor need any specific -section title style be used. However, a document must be consistent -in its use of section titles: once a hierarchy of title styles is -established, sections must use that hierarchy. - -Each section title automatically generates a hyperlink target pointing -to the section. The text of the hyperlink target (the "reference -name") is the same as that of the section title. See `Implicit -Hyperlink Targets`_ for a complete description. - -Sections may contain `body elements`_, transitions_, and nested -sections. - - -Transitions ------------ - -Doctree element: transition. - - Instead of subheads, extra space or a type ornament between - paragraphs may be used to mark text divisions or to signal - changes in subject or emphasis. - - (The Chicago Manual of Style, 14th edition, section 1.80) - -Transitions are commonly seen in novels and short fiction, as a gap -spanning one or more lines, with or without a type ornament such as a -row of asterisks. Transitions separate other body elements. A -transition should not begin or end a section or document, nor should -two transitions be immediately adjacent. - -The syntax for a transition marker is a horizontal line of 4 or more -repeated punctuation characters. The syntax is the same as section -title underlines without title text. Transition markers require blank -lines before and after:: - - Para. - - ---------- - - Para. - -Unlike section title underlines, no hierarchy of transition markers is -enforced, nor do differences in transition markers accomplish -anything. It is recommended that a single consistent style be used. - -The processing system is free to render transitions in output in any -way it likes. For example, horizontal rules (``<hr>``) in HTML output -would be an obvious choice. - - -Body Elements -============= - -Paragraphs ----------- - -Doctree element: paragraph. - -Paragraphs consist of blocks of left-aligned text with no markup -indicating any other body element. Blank lines separate paragraphs -from each other and from other body elements. Paragraphs may contain -`inline markup`_. - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | | - +------------------------------+ - - +------------------------------+ - | paragraph | - | | - +------------------------------+ - - -Bullet Lists ------------- - -Doctree elements: bullet_list, list_item. - -A text block which begins with a "-", "*", or "+", followed by -whitespace, is a bullet list item (a.k.a. "unordered" list item). -List item bodies must be left-aligned and indented relative to the -bullet; the text immediately after the bullet determines the -indentation. For example:: - - - This is the first bullet list item. The blank line above the - first list item is required; blank lines between list items - (such as below this paragraph) are optional. - - - This is the first paragraph in the second item in the list. - - This is the second paragraph in the second item in the list. - The blank line above this paragraph is required. The left edge - of this paragraph lines up with the paragraph above, both - indented relative to the bullet. - - - This is a sublist. The bullet lines up with the left edge of - the text blocks above. A sublist is a new list so requires a - blank line above and below. - - - This is the third item of the main list. - - This paragraph is not part of the list. - -Here are examples of **incorrectly** formatted bullet lists:: - - - This first line is fine. - A blank line is required between list items and paragraphs. - (Warning) - - - The following line appears to be a new sublist, but it is not: - - This is a paragraph continuation, not a sublist (since there's - no blank line). This line is also incorrectly indented. - - Warnings may be issued by the implementation. - -Syntax diagram:: - - +------+-----------------------+ - | "- " | list item | - +------| (body elements)+ | - +-----------------------+ - - -Enumerated Lists ----------------- - -Doctree elements: enumerated_list, list_item. - -Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists, -but use enumerators instead of bullets. An enumerator consists of an -enumeration sequence member and formatting, followed by whitespace. -The following enumeration sequences are recognized: - -- arabic numerals: 1, 2, 3, ... (no upper limit). -- uppercase alphabet characters: A, B, C, ..., Z. -- lower-case alphabet characters: a, b, c, ..., z. -- uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999). -- lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999). - -In addition, the auto-enumerator, "#", may be used to automatically -enumerate a list. Auto-enumerated lists may begin with explicit -enumeration, which sets the sequence. Fully auto-enumerated lists use -arabic numerals and begin with 1. (Auto-enumerated lists are new in -Docutils 0.3.8.) - -The following formatting types are recognized: - -- suffixed with a period: "1.", "A.", "a.", "I.", "i.". -- surrounded by parentheses: "(1)", "(A)", "(a)", "(I)", "(i)". -- suffixed with a right-parenthesis: "1)", "A)", "a)", "I)", "i)". - -While parsing an enumerated list, a new list will be started whenever: - -- An enumerator is encountered which does not have the same format and - sequence type as the current list (e.g. "1.", "(a)" produces two - separate lists). - -- The enumerators are not in sequence (e.g., "1.", "3." produces two - separate lists). - -It is recommended that the enumerator of the first list item be -ordinal-1 ("1", "A", "a", "I", or "i"). Although other start-values -will be recognized, they may not be supported by the output format. A -level-1 [info] system message will be generated for any list beginning -with a non-ordinal-1 enumerator. - -Lists using Roman numerals must begin with "I"/"i" or a -multi-character value, such as "II" or "XV". Any other -single-character Roman numeral ("V", "X", "L", "C", "D", "M") will be -interpreted as a letter of the alphabet, not as a Roman numeral. -Likewise, lists using letters of the alphabet may not begin with -"I"/"i", since these are recognized as Roman numeral 1. - -The second line of each enumerated list item is checked for validity. -This is to prevent ordinary paragraphs from being mistakenly -interpreted as list items, when they happen to begin with text -identical to enumerators. For example, this text is parsed as an -ordinary paragraph:: - - A. Einstein was a really - smart dude. - -However, ambiguity cannot be avoided if the paragraph consists of only -one line. This text is parsed as an enumerated list item:: - - A. Einstein was a really smart dude. - -If a single-line paragraph begins with text identical to an enumerator -("A.", "1.", "(b)", "I)", etc.), the first character will have to be -escaped in order to have the line parsed as an ordinary paragraph:: - - \A. Einstein was a really smart dude. - -Examples of nested enumerated lists:: - - 1. Item 1 initial text. - - a) Item 1a. - b) Item 1b. - - 2. a) Item 2a. - b) Item 2b. - -Example syntax diagram:: - - +-------+----------------------+ - | "1. " | list item | - +-------| (body elements)+ | - +----------------------+ - - -Definition Lists ----------------- - -Doctree elements: definition_list, definition_list_item, term, -classifier, definition. - -Each definition list item contains a term, optional classifiers, and a -definition. A term is a simple one-line word or phrase. Optional -classifiers may follow the term on the same line, each after an inline -" : " (space, colon, space). A definition is a block indented -relative to the term, and may contain multiple paragraphs and other -body elements. There may be no blank line between a term line and a -definition block (this distinguishes definition lists from `block -quotes`_). Blank lines are required before the first and after the -last definition list item, but are optional in-between. For example:: - - term 1 - Definition 1. - - term 2 - Definition 2, paragraph 1. - - Definition 2, paragraph 2. - - term 3 : classifier - Definition 3. - - term 4 : classifier one : classifier two - Definition 4. - -Inline markup is parsed in the term line before the classifier -delimiter (" : ") is recognized. The delimiter will only be -recognized if it appears outside of any inline markup. - -A definition list may be used in various ways, including: - -- As a dictionary or glossary. The term is the word itself, a - classifier may be used to indicate the usage of the term (noun, - verb, etc.), and the definition follows. - -- To describe program variables. The term is the variable name, a - classifier may be used to indicate the type of the variable (string, - integer, etc.), and the definition describes the variable's use in - the program. This usage of definition lists supports the classifier - syntax of Grouch_, a system for describing and enforcing a Python - object schema. - -Syntax diagram:: - - +----------------------------+ - | term [ " : " classifier ]* | - +--+-------------------------+--+ - | definition | - | (body elements)+ | - +----------------------------+ - - -Field Lists ------------ - -Doctree elements: field_list, field, field_name, field_body. - -Field lists are used as part of an extension syntax, such as options -for directives_, or database-like records meant for further -processing. They may also be used for two-column table-like -structures resembling database records (label & data pairs). -Applications of reStructuredText may recognize field names and -transform fields or field bodies in certain contexts. For examples, -see `Bibliographic Fields`_ below, or the "image_" and "meta_" -directives in `reStructuredText Directives`_. - -Field lists are mappings from field names to field bodies, modeled on -RFC822_ headers. A field name may consist of any characters, but -colons (":") inside of field names must be escaped with a backslash. -Inline markup is parsed in field names. Field names are -case-insensitive when further processed or transformed. The field -name, along with a single colon prefix and suffix, together form the -field marker. The field marker is followed by whitespace and the -field body. The field body may contain multiple body elements, -indented relative to the field marker. The first line after the field -name marker determines the indentation of the field body. For -example:: - - :Date: 2001-08-16 - :Version: 1 - :Authors: - Me - - Myself - - I - :Indentation: Since the field marker may be quite long, the second - and subsequent lines of the field body do not have to line up - with the first line, but they must be indented relative to the - field name marker, and they must line up with each other. - :Parameter i: integer - -The interpretation of individual words in a multi-word field name is -up to the application. The application may specify a syntax for the -field name. For example, second and subsequent words may be treated -as "arguments", quoted phrases may be treated as a single argument, -and direct support for the "name=value" syntax may be added. - -Standard RFC822_ headers cannot be used for this construct because -they are ambiguous. A word followed by a colon at the beginning of a -line is common in written text. However, in well-defined contexts -such as when a field list invariably occurs at the beginning of a -document (PEPs and email messages), standard RFC822 headers could be -used. - -Syntax diagram (simplified):: - - +--------------------+----------------------+ - | ":" field name ":" | field body | - +-------+------------+ | - | (body elements)+ | - +-----------------------------------+ - - -Bibliographic Fields -```````````````````` - -Doctree elements: docinfo, author, authors, organization, contact, -version, status, date, copyright, field, topic. - -When a field list is the first non-comment element in a document -(after the document title, if there is one), it may have its fields -transformed to document bibliographic data. This bibliographic data -corresponds to the front matter of a book, such as the title page and -copyright page. - -Certain registered field names (listed below) are recognized and -transformed to the corresponding doctree elements, most becoming child -elements of the "docinfo" element. No ordering is required of these -fields, although they may be rearranged to fit the document structure, -as noted. Unless otherwise indicated below, each of the bibliographic -elements' field bodies may contain a single paragraph only. Field -bodies may be checked for `RCS keywords`_ and cleaned up. Any -unrecognized fields will remain as generic fields in the docinfo -element. - -The registered bibliographic field names and their corresponding -doctree elements are as follows: - -- Field name "Author": author element. -- "Authors": authors. -- "Organization": organization. -- "Contact": contact. -- "Address": address. -- "Version": version. -- "Status": status. -- "Date": date. -- "Copyright": copyright. -- "Dedication": topic. -- "Abstract": topic. - -The "Authors" field may contain either: a single paragraph consisting -of a list of authors, separated by ";" or ","; or a bullet list whose -elements each contain a single paragraph per author. ";" is checked -first, so "Doe, Jane; Doe, John" will work. In some languages -(e.g. Swedish), there is no singular/plural distinction between -"Author" and "Authors", so only an "Authors" field is provided, and a -single name is interpreted as an "Author". If a single name contains -a comma, end it with a semicolon to disambiguate: ":Authors: Doe, -Jane;". - -The "Address" field is for a multi-line surface mailing address. -Newlines and whitespace will be preserved. - -The "Dedication" and "Abstract" fields may contain arbitrary body -elements. Only one of each is allowed. They become topic elements -with "Dedication" or "Abstract" titles (or language equivalents) -immediately following the docinfo element. - -This field-name-to-element mapping can be replaced for other -languages. See the `DocInfo transform`_ implementation documentation -for details. - -Unregistered/generic fields may contain one or more paragraphs or -arbitrary body elements. - - -RCS Keywords -```````````` - -`Bibliographic fields`_ recognized by the parser are normally checked -for RCS [#]_ keywords and cleaned up [#]_. RCS keywords may be -entered into source files as "$keyword$", and once stored under RCS or -CVS [#]_, they are expanded to "$keyword: expansion text $". For -example, a "Status" field will be transformed to a "status" element:: - - :Status: $keyword: expansion text $ - -.. [#] Revision Control System. -.. [#] RCS keyword processing can be turned off (unimplemented). -.. [#] Concurrent Versions System. CVS uses the same keywords as RCS. - -Processed, the "status" element's text will become simply "expansion -text". The dollar sign delimiters and leading RCS keyword name are -removed. - -The RCS keyword processing only kicks in when the field list is in -bibliographic context (first non-comment construct in the document, -after a document title if there is one). - - -Option Lists ------------- - -Doctree elements: option_list, option_list_item, option_group, option, -option_string, option_argument, description. - -Option lists are two-column lists of command-line options and -descriptions, documenting a program's options. For example:: - - -a Output all. - -b Output both (this description is - quite long). - -c arg Output just arg. - --long Output all day long. - - -p This option has two paragraphs in the description. - This is the first. - - This is the second. Blank lines may be omitted between - options (as above) or left in (as here and below). - - --very-long-option A VMS-style option. Note the adjustment for - the required two spaces. - - --an-even-longer-option - The description can also start on the next line. - - -2, --two This option has two variants. - - -f FILE, --file=FILE These two options are synonyms; both have - arguments. - - /V A VMS/DOS-style option. - -There are several types of options recognized by reStructuredText: - -- Short POSIX options consist of one dash and an option letter. -- Long POSIX options consist of two dashes and an option word; some - systems use a single dash. -- Old GNU-style "plus" options consist of one plus and an option - letter ("plus" options are deprecated now, their use discouraged). -- DOS/VMS options consist of a slash and an option letter or word. - -Please note that both POSIX-style and DOS/VMS-style options may be -used by DOS or Windows software. These and other variations are -sometimes used mixed together. The names above have been chosen for -convenience only. - -The syntax for short and long POSIX options is based on the syntax -supported by Python's getopt.py_ module, which implements an option -parser similar to the `GNU libc getopt_long()`_ function but with some -restrictions. There are many variant option systems, and -reStructuredText option lists do not support all of them. - -Although long POSIX and DOS/VMS option words may be allowed to be -truncated by the operating system or the application when used on the -command line, reStructuredText option lists do not show or support -this with any special syntax. The complete option word should be -given, supported by notes about truncation if and when applicable. - -Options may be followed by an argument placeholder, whose role and -syntax should be explained in the description text. Either a space or -an equals sign may be used as a delimiter between options and option -argument placeholders; short options ("-" or "+" prefix only) may omit -the delimiter. Option arguments may take one of two forms: - -- Begins with a letter (``[a-zA-Z]``) and subsequently consists of - letters, numbers, underscores and hyphens (``[a-zA-Z0-9_-]``). -- Begins with an open-angle-bracket (``<``) and ends with a - close-angle-bracket (``>``); any characters except angle brackets - are allowed internally. - -Multiple option "synonyms" may be listed, sharing a single -description. They must be separated by comma-space. - -There must be at least two spaces between the option(s) and the -description. The description may contain multiple body elements. The -first line after the option marker determines the indentation of the -description. As with other types of lists, blank lines are required -before the first option list item and after the last, but are optional -between option entries. - -Syntax diagram (simplified):: - - +----------------------------+-------------+ - | option [" " argument] " " | description | - +-------+--------------------+ | - | (body elements)+ | - +----------------------------------+ - - -Literal Blocks --------------- - -Doctree element: literal_block. - -A paragraph consisting of two colons ("::") signifies that the -following text block(s) comprise a literal block. The literal block -must either be indented or quoted (see below). No markup processing -is done within a literal block. It is left as-is, and is typically -rendered in a monospaced typeface:: - - This is a typical paragraph. An indented literal block follows. - - :: - - for a in [5,4,3,2,1]: # this is program code, shown as-is - print a - print "it's..." - # a literal block continues until the indentation ends - - This text has returned to the indentation of the first paragraph, - is outside of the literal block, and is therefore treated as an - ordinary paragraph. - -The paragraph containing only "::" will be completely removed from the -output; no empty paragraph will remain. - -As a convenience, the "::" is recognized at the end of any paragraph. -If immediately preceded by whitespace, both colons will be removed -from the output (this is the "partially minimized" form). When text -immediately precedes the "::", *one* colon will be removed from the -output, leaving only one colon visible (i.e., "::" will be replaced by -":"; this is the "fully minimized" form). - -In other words, these are all equivalent (please pay attention to the -colons after "Paragraph"): - -1. Expanded form:: - - Paragraph: - - :: - - Literal block - -2. Partially minimized form:: - - Paragraph: :: - - Literal block - -3. Fully minimized form:: - - Paragraph:: - - Literal block - -All whitespace (including line breaks, but excluding minimum -indentation for indented literal blocks) is preserved. Blank lines -are required before and after a literal block, but these blank lines -are not included as part of the literal block. - - -Indented Literal Blocks -``````````````````````` - -Indented literal blocks are indicated by indentation relative to the -surrounding text (leading whitespace on each line). The minimum -indentation will be removed from each line of an indented literal -block. The literal block need not be contiguous; blank lines are -allowed between sections of indented text. The literal block ends -with the end of the indentation. - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | (ends with "::") | - +------------------------------+ - +---------------------------+ - | indented literal block | - +---------------------------+ - - -Quoted Literal Blocks -````````````````````` - -Quoted literal blocks are unindented contiguous blocks of text where -each line begins with the same non-alphanumeric printable 7-bit ASCII -character [#]_. A blank line ends a quoted literal block. The -quoting characters are preserved in the processed document. - -.. [#] - The following are all valid quoting characters:: - - ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ - - Note that these are the same characters as are valid for title - adornment of sections_. - -Possible uses include literate programming in Haskell and email -quoting:: - - John Doe wrote:: - - >> Great idea! - > - > Why didn't I think of that? - - You just did! ;-) - -Syntax diagram:: - - +------------------------------+ - | paragraph | - | (ends with "::") | - +------------------------------+ - +------------------------------+ - | ">" per-line-quoted | - | ">" contiguous literal block | - +------------------------------+ - - -Line Blocks ------------ - -Doctree elements: line_block, line. (New in Docutils 0.3.5.) - -Line blocks are useful for address blocks, verse (poetry, song -lyrics), and unadorned lists, where the structure of lines is -significant. Line blocks are groups of lines beginning with vertical -bar ("|") prefixes. Each vertical bar prefix indicates a new line, so -line breaks are preserved. Initial indents are also significant, -resulting in a nested structure. Inline markup is supported. -Continuation lines are wrapped portions of long lines; they begin with -a space in place of the vertical bar. The left edge of a continuation -line must be indented, but need not be aligned with the left edge of -the text above it. A line block ends with a blank line. - -This example illustrates continuation lines:: - - | Lend us a couple of bob till Thursday. - | I'm absolutely skint. - | But I'm expecting a postal order and I can pay you back - as soon as it comes. - | Love, Ewan. - -This example illustrates the nesting of line blocks, indicated by the -initial indentation of new lines:: - - Take it away, Eric the Orchestra Leader! - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -Syntax diagram:: - - +------+-----------------------+ - | "| " | line | - +------| continuation line | - +-----------------------+ - - -Block Quotes ------------- - -Doctree element: block_quote, attribution. - -A text block that is indented relative to the preceding text, without -markup indicating it to be a literal block, is a block quote. All -markup processing (for body elements and inline markup) continues -within the block quote:: - - This is an ordinary paragraph, introducing a block quote. - - "It is my business to know things. That is my trade." - - -- Sherlock Holmes - -If the final block of a block quote begins with "--", "---", or a true -em-dash (flush left within the block quote), it is interpreted as an -attribution. If the attribution consists of multiple lines, the left -edges of the second and subsequent lines must align. - -Blank lines are required before and after a block quote, but these -blank lines are not included as part of the block quote. - -Syntax diagram:: - - +------------------------------+ - | (current level of | - | indentation) | - +------------------------------+ - +---------------------------+ - | block quote | - | (body elements)+ | - | | - | -- attribution text | - | (optional) | - +---------------------------+ - - -Doctest Blocks --------------- - -Doctree element: doctest_block. - -Doctest blocks are interactive Python sessions cut-and-pasted into -docstrings. They are meant to illustrate usage by example, and -provide an elegant and powerful testing environment via the `doctest -module`_ in the Python standard library. - -Doctest blocks are text blocks which begin with ``">>> "``, the Python -interactive interpreter main prompt, and end with a blank line. -Doctest blocks are treated as a special case of literal blocks, -without requiring the literal block syntax. If both are present, the -literal block syntax takes priority over Doctest block syntax:: - - This is an ordinary paragraph. - - >>> print 'this is a Doctest block' - this is a Doctest block - - The following is a literal block:: - - >>> This is not recognized as a doctest block by - reStructuredText. It *will* be recognized by the doctest - module, though! - -Indentation is not required for doctest blocks. - - -Tables ------- - -Doctree elements: table, tgroup, colspec, thead, tbody, row, entry. - -ReStructuredText provides two syntaxes for delineating table cells: -`Grid Tables`_ and `Simple Tables`_. - -As with other body elements, blank lines are required before and after -tables. Tables' left edges should align with the left edge of -preceding text blocks; if indented, the table is considered to be part -of a block quote. - -Once isolated, each table cell is treated as a miniature document; the -top and bottom cell boundaries act as delimiting blank lines. Each -cell contains zero or more body elements. Cell contents may include -left and/or right margins, which are removed before processing. - - -Grid Tables -``````````` - -Grid tables provide a complete table representation via grid-like -"ASCII art". Grid tables allow arbitrary cell contents (body -elements), and both row and column spans. However, grid tables can be -cumbersome to produce, especially for simple data sets. The `Emacs -table mode`_ is a tool that allows easy editing of grid tables, in -Emacs. See `Simple Tables`_ for a simpler (but limited) -representation. - -Grid tables are described with a visual grid made up of the characters -"-", "=", "|", and "+". The hyphen ("-") is used for horizontal lines -(row separators). The equals sign ("=") may be used to separate -optional header rows from the table body (not supported by the `Emacs -table mode`_). The vertical bar ("|") is used for vertical lines -(column separators). The plus sign ("+") is used for intersections of -horizontal and vertical lines. Example:: - - +------------------------+------------+----------+----------+ - | Header row, column 1 | Header 2 | Header 3 | Header 4 | - | (header rows optional) | | | | - +========================+============+==========+==========+ - | body row 1, column 1 | column 2 | column 3 | column 4 | - +------------------------+------------+----------+----------+ - | body row 2 | Cells may span columns. | - +------------------------+------------+---------------------+ - | body row 3 | Cells may | - Table cells | - +------------------------+ span rows. | - contain | - | body row 4 | | - body elements. | - +------------------------+------------+---------------------+ - -Some care must be taken with grid tables to avoid undesired -interactions with cell text in rare cases. For example, the following -table contains a cell in row 2 spanning from column 2 to column 4:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -If a vertical bar is used in the text of that cell, it could have -unintended effects if accidentally aligned with column boundaries:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -Several solutions are possible. All that is needed is to break the -continuity of the cell outline rectangle. One possibility is to shift -the text by adding an extra space before:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - -Another possibility is to add an extra line to row 2:: - - +--------------+----------+-----------+-----------+ - | row 1, col 1 | column 2 | column 3 | column 4 | - +--------------+----------+-----------+-----------+ - | row 2 | Use the command ``ls | more``. | - | | | - +--------------+----------+-----------+-----------+ - | row 3 | | | | - +--------------+----------+-----------+-----------+ - - -Simple Tables -````````````` - -Simple tables provide a compact and easy to type but limited -row-oriented table representation for simple data sets. Cell contents -are typically single paragraphs, although arbitrary body elements may -be represented in most cells. Simple tables allow multi-line rows (in -all but the first column) and column spans, but not row spans. See -`Grid Tables`_ above for a complete table representation. - -Simple tables are described with horizontal borders made up of "=" and -"-" characters. The equals sign ("=") is used for top and bottom -table borders, and to separate optional header rows from the table -body. The hyphen ("-") is used to indicate column spans in a single -row by underlining the joined columns, and may optionally be used to -explicitly and/or visually separate rows. - -A simple table begins with a top border of equals signs with one or -more spaces at each column boundary (two or more spaces recommended). -Regardless of spans, the top border *must* fully describe all table -columns. There must be at least two columns in the table (to -differentiate it from section headers). The last of the optional -header rows is underlined with '=', again with spaces at column -boundaries. There may not be a blank line below the header row -separator; it would be interpreted as the bottom border of the table. -The bottom boundary of the table consists of '=' underlines, also with -spaces at column boundaries. For example, here is a truth table, a -three-column table with one header row and four body rows:: - - ===== ===== ======= - A B A and B - ===== ===== ======= - False False False - True False False - False True False - True True True - ===== ===== ======= - -Underlines of '-' may be used to indicate column spans by "filling in" -column margins to join adjacent columns. Column span underlines must -be complete (they must cover all columns) and align with established -column boundaries. Text lines containing column span underlines may -not contain any other text. A column span underline applies only to -one row immediately above it. For example, here is a table with a -column span in the header:: - - ===== ===== ====== - Inputs Output - ------------ ------ - A B A or B - ===== ===== ====== - False False False - True False True - False True True - True True True - ===== ===== ====== - -Each line of text must contain spaces at column boundaries, except -where cells have been joined by column spans. Each line of text -starts a new row, except when there is a blank cell in the first -column. In that case, that line of text is parsed as a continuation -line. For this reason, cells in the first column of new rows (*not* -continuation lines) *must* contain some text; blank cells would lead -to a misinterpretation. An empty comment ("..") is sufficient and -will be omitted from the processed output (see Comments_ below). -Also, this mechanism limits cells in the first column to only one line -of text. Use `grid tables`_ if this limitation is unacceptable. - -Underlines of '-' may also be used to visually separate rows, even if -there are no column spans. This is especially useful in long tables, -where rows are many lines long. - -Blank lines are permitted within simple tables. Their interpretation -depends on the context. Blank lines *between* rows are ignored. -Blank lines *within* multi-line rows may separate paragraphs or other -body elements within cells. - -The rightmost column is unbounded; text may continue past the edge of -the table (as indicated by the table borders). However, it is -recommended that borders be made long enough to contain the entire -text. - -The following example illustrates continuation lines (row 2 consists -of two lines of text, and four lines for row 3), a blank line -separating paragraphs (row 3, column 2), and text extending past the -right edge of the table:: - - ===== ===== - col 1 col 2 - ===== ===== - 1 Second column of row 1. - 2 Second column of row 2. - Second line of paragraph. - 3 - Second column of row 3. - - - Second item in bullet - list (row 3, column 2). - ===== ===== - - -Explicit Markup Blocks ----------------------- - -An explicit markup block is a text block: - -- whose first line begins with ".." followed by whitespace (the - "explicit markup start"), -- whose second and subsequent lines (if any) are indented relative to - the first, and -- which ends before an unindented line. - -Explicit markup blocks are analogous to bullet list items, with ".." -as the bullet. The text on the lines immediately after the explicit -markup start determines the indentation of the block body. The -maximum common indentation is always removed from the second and -subsequent lines of the block body. Therefore if the first construct -fits in one line, and the indentation of the first and second -constructs should differ, the first construct should not begin on the -same line as the explicit markup start. - -Blank lines are required between explicit markup blocks and other -elements, but are optional between explicit markup blocks where -unambiguous. - -The explicit markup syntax is used for footnotes, citations, hyperlink -targets, directives, substitution definitions, and comments. - - -Footnotes -````````` - -Doctree elements: footnote, label. - -Each footnote consists of an explicit markup start (".. "), a left -square bracket, the footnote label, a right square bracket, and -whitespace, followed by indented body elements. A footnote label can -be: - -- a whole decimal number consisting of one or more digits, - -- a single "#" (denoting `auto-numbered footnotes`_), - -- a "#" followed by a simple reference name (an `autonumber label`_), - or - -- a single "*" (denoting `auto-symbol footnotes`_). - -The footnote content (body elements) must be consistently indented (by -at least 3 spaces) and left-aligned. The first body element within a -footnote may often begin on the same line as the footnote label. -However, if the first element fits on one line and the indentation of -the remaining elements differ, the first element must begin on the -line after the footnote label. Otherwise, the difference in -indentation will not be detected. - -Footnotes may occur anywhere in the document, not only at the end. -Where and how they appear in the processed output depends on the -processing system. - -Here is a manually numbered footnote:: - - .. [1] Body elements go here. - -Each footnote automatically generates a hyperlink target pointing to -itself. The text of the hyperlink target name is the same as that of -the footnote label. `Auto-numbered footnotes`_ generate a number as -their footnote label and reference name. See `Implicit Hyperlink -Targets`_ for a complete description of the mechanism. - -Syntax diagram:: - - +-------+-------------------------+ - | ".. " | "[" label "]" footnote | - +-------+ | - | (body elements)+ | - +-------------------------+ - - -Auto-Numbered Footnotes -....................... - -A number sign ("#") may be used as the first character of a footnote -label to request automatic numbering of the footnote or footnote -reference. - -The first footnote to request automatic numbering is assigned the -label "1", the second is assigned the label "2", and so on (assuming -there are no manually numbered footnotes present; see `Mixed Manual -and Auto-Numbered Footnotes`_ below). A footnote which has -automatically received a label "1" generates an implicit hyperlink -target with name "1", just as if the label was explicitly specified. - -.. _autonumber label: `autonumber labels`_ - -A footnote may specify a label explicitly while at the same time -requesting automatic numbering: ``[#label]``. These labels are called -_`autonumber labels`. Autonumber labels do two things: - -- On the footnote itself, they generate a hyperlink target whose name - is the autonumber label (doesn't include the "#"). - -- They allow an automatically numbered footnote to be referred to more - than once, as a footnote reference or hyperlink reference. For - example:: - - If [#note]_ is the first footnote reference, it will show up as - "[1]". We can refer to it again as [#note]_ and again see - "[1]". We can also refer to it as note_ (an ordinary internal - hyperlink reference). - - .. [#note] This is the footnote labeled "note". - -The numbering is determined by the order of the footnotes, not by the -order of the references. For footnote references without autonumber -labels (``[#]_``), the footnotes and footnote references must be in -the same relative order but need not alternate in lock-step. For -example:: - - [#]_ is a reference to footnote 1, and [#]_ is a reference to - footnote 2. - - .. [#] This is footnote 1. - .. [#] This is footnote 2. - .. [#] This is footnote 3. - - [#]_ is a reference to footnote 3. - -Special care must be taken if footnotes themselves contain -auto-numbered footnote references, or if multiple references are made -in close proximity. Footnotes and references are noted in the order -they are encountered in the document, which is not necessarily the -same as the order in which a person would read them. - - -Auto-Symbol Footnotes -..................... - -An asterisk ("*") may be used for footnote labels to request automatic -symbol generation for footnotes and footnote references. The asterisk -may be the only character in the label. For example:: - - Here is a symbolic footnote reference: [*]_. - - .. [*] This is the footnote. - -A transform will insert symbols as labels into corresponding footnotes -and footnote references. The number of references must be equal to -the number of footnotes. One symbol footnote cannot have multiple -references. - -The standard Docutils system uses the following symbols for footnote -marks [#]_: - -- asterisk/star ("*") -- dagger (HTML character entity "†", Unicode U+02020) -- double dagger ("‡"/U+02021) -- section mark ("§"/U+000A7) -- pilcrow or paragraph mark ("¶"/U+000B6) -- number sign ("#") -- spade suit ("♠"/U+02660) -- heart suit ("♥"/U+02665) -- diamond suit ("♦"/U+02666) -- club suit ("♣"/U+02663) - -.. [#] This list was inspired by the list of symbols for "Note - Reference Marks" in The Chicago Manual of Style, 14th edition, - section 12.51. "Parallels" ("||") were given in CMoS instead of - the pilcrow. The last four symbols (the card suits) were added - arbitrarily. - -If more than ten symbols are required, the same sequence will be -reused, doubled and then tripled, and so on ("**" etc.). - -.. Note:: When using auto-symbol footnotes, the choice of output - encoding is important. Many of the symbols used are not encodable - in certain common text encodings such as Latin-1 (ISO 8859-1). The - use of UTF-8 for the output encoding is recommended. An - alternative for HTML and XML output is to use the - "xmlcharrefreplace" `output encoding error handler`__. - -__ ../../user/config.html#output-encoding-error-handler - - -Mixed Manual and Auto-Numbered Footnotes -........................................ - -Manual and automatic footnote numbering may both be used within a -single document, although the results may not be expected. Manual -numbering takes priority. Only unused footnote numbers are assigned -to auto-numbered footnotes. The following example should be -illustrative:: - - [2]_ will be "2" (manually numbered), - [#]_ will be "3" (anonymous auto-numbered), and - [#label]_ will be "1" (labeled auto-numbered). - - .. [2] This footnote is labeled manually, so its number is fixed. - - .. [#label] This autonumber-labeled footnote will be labeled "1". - It is the first auto-numbered footnote and no other footnote - with label "1" exists. The order of the footnotes is used to - determine numbering, not the order of the footnote references. - - .. [#] This footnote will be labeled "3". It is the second - auto-numbered footnote, but footnote label "2" is already used. - - -Citations -````````` - -Citations are identical to footnotes except that they use only -non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation -labels are simple `reference names`_ (case-insensitive single words -consisting of alphanumerics plus internal hyphens, underscores, and -periods; no whitespace). Citations may be rendered separately and -differently from footnotes. For example:: - - Here is a citation reference: [CIT2002]_. - - .. [CIT2002] This is the citation. It's just like a footnote, - except the label is textual. - - -.. _hyperlinks: - -Hyperlink Targets -````````````````` - -Doctree element: target. - -These are also called _`explicit hyperlink targets`, to differentiate -them from `implicit hyperlink targets`_ defined below. - -Hyperlink targets identify a location within or outside of a document, -which may be linked to by `hyperlink references`_. - -Hyperlink targets may be named or anonymous. Named hyperlink targets -consist of an explicit markup start (".. "), an underscore, the -reference name (no trailing underscore), a colon, whitespace, and a -link block:: - - .. _hyperlink-name: link-block - -Reference names are whitespace-neutral and case-insensitive. See -`Reference Names`_ for details and examples. - -Anonymous hyperlink targets consist of an explicit markup start -(".. "), two underscores, a colon, whitespace, and a link block; there -is no reference name:: - - .. __: anonymous-hyperlink-target-link-block - -An alternate syntax for anonymous hyperlinks consists of two -underscores, a space, and a link block:: - - __ anonymous-hyperlink-target-link-block - -See `Anonymous Hyperlinks`_ below. - -There are three types of hyperlink targets: internal, external, and -indirect. - -1. _`Internal hyperlink targets` have empty link blocks. They provide - an end point allowing a hyperlink to connect one place to another - within a document. An internal hyperlink target points to the - element following the target. For example:: - - Clicking on this internal hyperlink will take us to the target_ - below. - - .. _target: - - The hyperlink target above points to this paragraph. - - Internal hyperlink targets may be "chained". Multiple adjacent - internal hyperlink targets all point to the same element:: - - .. _target1: - .. _target2: - - The targets "target1" and "target2" are synonyms; they both - point to this paragraph. - - If the element "pointed to" is an external hyperlink target (with a - URI in its link block; see #2 below) the URI from the external - hyperlink target is propagated to the internal hyperlink targets; - they will all "point to" the same URI. There is no need to - duplicate a URI. For example, all three of the following hyperlink - targets refer to the same URI:: - - .. _Python DOC-SIG mailing list archive: - .. _archive: - .. _Doc-SIG: http://mail.python.org/pipermail/doc-sig/ - - An inline form of internal hyperlink target is available; see - `Inline Internal Targets`_. - -2. _`External hyperlink targets` have an absolute or relative URI or - email address in their link blocks. For example, take the - following input:: - - See the Python_ home page for info. - - `Write to me`_ with your questions. - - .. _Python: http://www.python.org - .. _Write to me: jdoe@example.com - - After processing into HTML, the hyperlinks might be expressed as:: - - See the <a href="http://www.python.org">Python</a> home page - for info. - - <a href="mailto:jdoe@example.com">Write to me</a> with your - questions. - - An external hyperlink's URI may begin on the same line as the - explicit markup start and target name, or it may begin in an - indented text block immediately following, with no intervening - blank lines. If there are multiple lines in the link block, they - are concatenated. Any whitespace is removed (whitespace is - permitted to allow for line wrapping). The following external - hyperlink targets are equivalent:: - - .. _one-liner: http://docutils.sourceforge.net/rst.html - - .. _starts-on-this-line: http:// - docutils.sourceforge.net/rst.html - - .. _entirely-below: - http://docutils. - sourceforge.net/rst.html - - If an external hyperlink target's URI contains an underscore as its - last character, it must be escaped to avoid being mistaken for an - indirect hyperlink target:: - - This link_ refers to a file called ``underscore_``. - - .. _link: underscore\_ - - It is possible (although not generally recommended) to include URIs - directly within hyperlink references. See `Embedded URIs`_ below. - -3. _`Indirect hyperlink targets` have a hyperlink reference in their - link blocks. In the following example, target "one" indirectly - references whatever target "two" references, and target "two" - references target "three", an internal hyperlink target. In - effect, all three reference the same thing:: - - .. _one: two_ - .. _two: three_ - .. _three: - - Just as with `hyperlink references`_ anywhere else in a document, - if a phrase-reference is used in the link block it must be enclosed - in backquotes. As with `external hyperlink targets`_, the link - block of an indirect hyperlink target may begin on the same line as - the explicit markup start or the next line. It may also be split - over multiple lines, in which case the lines are joined with - whitespace before being normalized. - - For example, the following indirect hyperlink targets are - equivalent:: - - .. _one-liner: `A HYPERLINK`_ - .. _entirely-below: - `a hyperlink`_ - .. _split: `A - Hyperlink`_ - -If the reference name contains any colons, either: - -- the phrase must be enclosed in backquotes:: - - .. _`FAQTS: Computers: Programming: Languages: Python`: - http://python.faqts.com/ - -- or the colon(s) must be backslash-escaped in the link target:: - - .. _Chapter One\: "Tadpole Days": - - It's not easy being green... - -See `Implicit Hyperlink Targets`_ below for the resolution of -duplicate reference names. - -Syntax diagram:: - - +-------+----------------------+ - | ".. " | "_" name ":" link | - +-------+ block | - | | - +----------------------+ - - -Anonymous Hyperlinks -.................... - -The `World Wide Web Consortium`_ recommends in its `HTML Techniques -for Web Content Accessibility Guidelines`_ that authors should -"clearly identify the target of each link." Hyperlink references -should be as verbose as possible, but duplicating a verbose hyperlink -name in the target is onerous and error-prone. Anonymous hyperlinks -are designed to allow convenient verbose hyperlink references, and are -analogous to `Auto-Numbered Footnotes`_. They are particularly useful -in short or one-off documents. However, this feature is easily abused -and can result in unreadable plaintext and/or unmaintainable -documents. Caution is advised. - -Anonymous `hyperlink references`_ are specified with two underscores -instead of one:: - - See `the web site of my favorite programming language`__. - -Anonymous targets begin with ".. __:"; no reference name is required -or allowed:: - - .. __: http://www.python.org - -As a convenient alternative, anonymous targets may begin with "__" -only:: - - __ http://www.python.org - -The reference name of the reference is not used to match the reference -to its target. Instead, the order of anonymous hyperlink references -and targets within the document is significant: the first anonymous -reference will link to the first anonymous target. The number of -anonymous hyperlink references in a document must match the number of -anonymous targets. For readability, it is recommended that targets be -kept close to references. Take care when editing text containing -anonymous references; adding, removing, and rearranging references -require attention to the order of corresponding targets. - - -Directives -`````````` - -Doctree elements: depend on the directive. - -Directives are an extension mechanism for reStructuredText, a way of -adding support for new constructs without adding new primary syntax -(directives may support additional syntax locally). All standard -directives (those implemented and registered in the reference -reStructuredText parser) are described in the `reStructuredText -Directives`_ document, and are always available. Any other directives -are domain-specific, and may require special action to make them -available when processing the document. - -For example, here's how an image_ may be placed:: - - .. image:: mylogo.jpeg - -A figure_ (a graphic with a caption) may placed like this:: - - .. figure:: larch.png - - The larch. - -An admonition_ (note, caution, etc.) contains other body elements:: - - .. note:: This is a paragraph - - - Here is a bullet list. - -Directives are indicated by an explicit markup start (".. ") followed -by the directive type, two colons, and whitespace (together called the -"directive marker"). Directive types are case-insensitive single -words (alphanumerics plus internal hyphens, underscores, and periods; -no whitespace). Two colons are used after the directive type for -these reasons: - -- Two colons are distinctive, and unlikely to be used in common text. - -- Two colons avoids clashes with common comment text like:: - - .. Danger: modify at your own risk! - -- If an implementation of reStructuredText does not recognize a - directive (i.e., the directive-handler is not installed), a level-3 - (error) system message is generated, and the entire directive block - (including the directive itself) will be included as a literal - block. Thus "::" is a natural choice. - -The directive block is consists of any text on the first line of the -directive after the directive marker, and any subsequent indented -text. The interpretation of the directive block is up to the -directive code. There are three logical parts to the directive block: - -1. Directive arguments. -2. Directive options. -3. Directive content. - -Individual directives can employ any combination of these parts. -Directive arguments can be filesystem paths, URLs, title text, etc. -Directive options are indicated using `field lists`_; the field names -and contents are directive-specific. Arguments and options must form -a contiguous block beginning on the first or second line of the -directive; a blank line indicates the beginning of the directive -content block. If either arguments and/or options are employed by the -directive, a blank line must separate them from the directive content. -The "figure" directive employs all three parts:: - - .. figure:: larch.png - :scale: 50 - - The larch. - -Simple directives may not require any content. If a directive that -does not employ a content block is followed by indented text anyway, -it is an error. If a block quote should immediately follow a -directive, use an empty comment in-between (see Comments_ below). - -Actions taken in response to directives and the interpretation of text -in the directive content block or subsequent text block(s) are -directive-dependent. See `reStructuredText Directives`_ for details. - -Directives are meant for the arbitrary processing of their contents, -which can be transformed into something possibly unrelated to the -original text. It may also be possible for directives to be used as -pragmas, to modify the behavior of the parser, such as to experiment -with alternate syntax. There is no parser support for this -functionality at present; if a reasonable need for pragma directives -is found, they may be supported. - -Directives do not generate "directive" elements; they are a *parser -construct* only, and have no intrinsic meaning outside of -reStructuredText. Instead, the parser will transform recognized -directives into (possibly specialized) document elements. Unknown -directives will trigger level-3 (error) system messages. - -Syntax diagram:: - - +-------+-------------------------------+ - | ".. " | directive type "::" directive | - +-------+ block | - | | - +-------------------------------+ - - -Substitution Definitions -```````````````````````` - -Doctree element: substitution_definition. - -Substitution definitions are indicated by an explicit markup start -(".. ") followed by a vertical bar, the substitution text, another -vertical bar, whitespace, and the definition block. Substitution text -may not begin or end with whitespace. A substitution definition block -contains an embedded inline-compatible directive (without the leading -".. "), such as "image_" or "replace_". For example:: - - The |biohazard| symbol must be used on containers used to - dispose of medical waste. - - .. |biohazard| image:: biohazard.png - -It is an error for a substitution definition block to directly or -indirectly contain a circular substitution reference. - -`Substitution references`_ are replaced in-line by the processed -contents of the corresponding definition (linked by matching -substitution text). Matches are case-sensitive but forgiving; if no -exact match is found, a case-insensitive comparison is attempted. - -Substitution definitions allow the power and flexibility of -block-level directives_ to be shared by inline text. They are a way -to include arbitrarily complex inline structures within text, while -keeping the details out of the flow of text. They are the equivalent -of SGML/XML's named entities or programming language macros. - -Without the substitution mechanism, every time someone wants an -application-specific new inline structure, they would have to petition -for a syntax change. In combination with existing directive syntax, -any inline structure can be coded without new syntax (except possibly -a new directive). - -Syntax diagram:: - - +-------+-----------------------------------------------------+ - | ".. " | "|" substitution text "| " directive type "::" data | - +-------+ directive block | - | | - +-----------------------------------------------------+ - -Following are some use cases for the substitution mechanism. Please -note that most of the embedded directives shown are examples only and -have not been implemented. - -Objects - Substitution references may be used to associate ambiguous text - with a unique object identifier. - - For example, many sites may wish to implement an inline "user" - directive:: - - |Michael| and |Jon| are our widget-wranglers. - - .. |Michael| user:: mjones - .. |Jon| user:: jhl - - Depending on the needs of the site, this may be used to index the - document for later searching, to hyperlink the inline text in - various ways (mailto, homepage, mouseover Javascript with profile - and contact information, etc.), or to customize presentation of - the text (include username in the inline text, include an icon - image with a link next to the text, make the text bold or a - different color, etc.). - - The same approach can be used in documents which frequently refer - to a particular type of objects with unique identifiers but - ambiguous common names. Movies, albums, books, photos, court - cases, and laws are possible. For example:: - - |The Transparent Society| offers a fascinating alternate view - on privacy issues. - - .. |The Transparent Society| book:: isbn=0738201448 - - Classes or functions, in contexts where the module or class names - are unclear and/or interpreted text cannot be used, are another - possibility:: - - 4XSLT has the convenience method |runString|, so you don't - have to mess with DOM objects if all you want is the - transformed output. - - .. |runString| function:: module=xml.xslt class=Processor - -Images - Images are a common use for substitution references:: - - West led the |H| 3, covered by dummy's |H| Q, East's |H| K, - and trumped in hand with the |S| 2. - - .. |H| image:: /images/heart.png - :height: 11 - :width: 11 - .. |S| image:: /images/spade.png - :height: 11 - :width: 11 - - * |Red light| means stop. - * |Green light| means go. - * |Yellow light| means go really fast. - - .. |Red light| image:: red_light.png - .. |Green light| image:: green_light.png - .. |Yellow light| image:: yellow_light.png - - |-><-| is the official symbol of POEE_. - - .. |-><-| image:: discord.png - .. _POEE: http://www.poee.org/ - - The "image_" directive has been implemented. - -Styles [#]_ - Substitution references may be used to associate inline text with - an externally defined presentation style:: - - Even |the text in Texas| is big. - - .. |the text in Texas| style:: big - - The style name may be meaningful in the context of some particular - output format (CSS class name for HTML output, LaTeX style name - for LaTeX, etc), or may be ignored for other output formats (such - as plaintext). - - .. @@@ This needs to be rethought & rewritten or removed: - - Interpreted text is unsuitable for this purpose because the set - of style names cannot be predefined - it is the domain of the - content author, not the author of the parser and output - formatter - and there is no way to associate a style name - argument with an interpreted text style role. Also, it may be - desirable to use the same mechanism for styling blocks:: - - .. style:: motto - At Bob's Underwear Shop, we'll do anything to get in - your pants. - - .. style:: disclaimer - All rights reversed. Reprint what you like. - - .. [#] There may be sufficient need for a "style" mechanism to - warrant simpler syntax such as an extension to the interpreted - text role syntax. The substitution mechanism is cumbersome for - simple text styling. - -Templates - Inline markup may be used for later processing by a template - engine. For example, a Zope_ author might write:: - - Welcome back, |name|! - - .. |name| tal:: replace user/getUserName - - After processing, this ZPT output would result:: - - Welcome back, - <span tal:replace="user/getUserName">name</span>! - - Zope would then transform this to something like "Welcome back, - David!" during a session with an actual user. - -Replacement text - The substitution mechanism may be used for simple macro - substitution. This may be appropriate when the replacement text - is repeated many times throughout one or more documents, - especially if it may need to change later. A short example is - unavoidably contrived:: - - |RST| is a little annoying to type over and over, especially - when writing about |RST| itself, and spelling out the - bicapitalized word |RST| every time isn't really necessary for - |RST| source readability. - - .. |RST| replace:: reStructuredText_ - .. _reStructuredText: http://docutils.sourceforge.net/rst.html - - Substitution is also appropriate when the replacement text cannot - be represented using other inline constructs, or is obtrusively - long:: - - But still, that's nothing compared to a name like - |j2ee-cas|__. - - .. |j2ee-cas| replace:: - the Java `TM`:super: 2 Platform, Enterprise Edition Client - Access Services - __ http://developer.java.sun.com/developer/earlyAccess/ - j2eecas/ - - The "replace_" directive has been implemented. - - -Comments -```````` - -Doctree element: comment. - -Arbitrary indented text may follow the explicit markup start and will -be processed as a comment element. No further processing is done on -the comment block text; a comment contains a single "text blob". -Depending on the output formatter, comments may be removed from the -processed output. The only restriction on comments is that they not -use the same syntax as any of the other explicit markup constructs: -substitution definitions, directives, footnotes, citations, or -hyperlink targets. To ensure that none of the other explicit markup -constructs is recognized, leave the ".." on a line by itself:: - - .. This is a comment - .. - _so: is this! - .. - [and] this! - .. - this:: too! - .. - |even| this:: ! - -An explicit markup start followed by a blank line and nothing else -(apart from whitespace) is an "empty comment". It serves to terminate -a preceding construct, and does **not** consume any indented text -following. To have a block quote follow a list or any indented -construct, insert an unindented empty comment in-between. - -Syntax diagram:: - - +-------+----------------------+ - | ".. " | comment | - +-------+ block | - | | - +----------------------+ - - -Implicit Hyperlink Targets -========================== - -Implicit hyperlink targets are generated by section titles, footnotes, -and citations, and may also be generated by extension constructs. -Implicit hyperlink targets otherwise behave identically to explicit -`hyperlink targets`_. - -Problems of ambiguity due to conflicting duplicate implicit and -explicit reference names are avoided by following this procedure: - -1. `Explicit hyperlink targets`_ override any implicit targets having - the same reference name. The implicit hyperlink targets are - removed, and level-1 (info) system messages are inserted. - -2. Duplicate implicit hyperlink targets are removed, and level-1 - (info) system messages inserted. For example, if two or more - sections have the same title (such as "Introduction" subsections of - a rigidly-structured document), there will be duplicate implicit - hyperlink targets. - -3. Duplicate explicit hyperlink targets are removed, and level-2 - (warning) system messages are inserted. Exception: duplicate - `external hyperlink targets`_ (identical hyperlink names and - referenced URIs) do not conflict, and are not removed. - -System messages are inserted where target links have been removed. -See "Error Handling" in `PEP 258`_. - -The parser must return a set of *unique* hyperlink targets. The -calling software (such as the Docutils_) can warn of unresolvable -links, giving reasons for the messages. - - -Inline Markup -============= - -In reStructuredText, inline markup applies to words or phrases within -a text block. The same whitespace and punctuation that serves to -delimit words in written text is used to delimit the inline markup -syntax constructs. The text within inline markup may not begin or end -with whitespace. Arbitrary `character-level inline markup`_ is -supported although not encouraged. Inline markup cannot be nested. - -There are nine inline markup constructs. Five of the constructs use -identical start-strings and end-strings to indicate the markup: - -- emphasis_: "*" -- `strong emphasis`_: "**" -- `interpreted text`_: "`" -- `inline literals`_: "``" -- `substitution references`_: "|" - -Three constructs use different start-strings and end-strings: - -- `inline internal targets`_: "_`" and "`" -- `footnote references`_: "[" and "]_" -- `hyperlink references`_: "`" and "\`_" (phrases), or just a - trailing "_" (single words) - -`Standalone hyperlinks`_ are recognized implicitly, and use no extra -markup. - -The inline markup start-string and end-string recognition rules are as -follows. If any of the conditions are not met, the start-string or -end-string will not be recognized or processed. - -1. Inline markup start-strings must start a text block or be - immediately preceded by whitespace or one of:: - - ' " ( [ { < - / : - -2. Inline markup start-strings must be immediately followed by - non-whitespace. - -3. Inline markup end-strings must be immediately preceded by - non-whitespace. - -4. Inline markup end-strings must end a text block or be immediately - followed by whitespace or one of:: - - ' " ) ] } > - / : . , ; ! ? \ - -5. If an inline markup start-string is immediately preceded by a - single or double quote, "(", "[", "{", or "<", it must not be - immediately followed by the corresponding single or double quote, - ")", "]", "}", or ">". - -6. An inline markup end-string must be separated by at least one - character from the start-string. - -7. An unescaped backslash preceding a start-string or end-string will - disable markup recognition, except for the end-string of `inline - literals`_. See `Escaping Mechanism`_ above for details. - -For example, none of the following are recognized as containing inline -markup start-strings: - -- asterisks: * "*" '*' (*) (* [*] {*} 1*x BOM32_* -- double asterisks: ** a**b O(N**2) etc. -- backquotes: ` `` etc. -- underscores: _ __ __init__ __init__() etc. -- vertical bars: | || etc. - -It may be desirable to use inline literals for some of these anyhow, -especially if they represent code snippets. It's a judgment call. - -These cases *do* require either literal-quoting or escaping to avoid -misinterpretation:: - - *4, class_, *args, **kwargs, `TeX-quoted', *ML, *.txt - -The inline markup recognition rules were devised intentionally to -allow 90% of non-markup uses of "*", "`", "_", and "|" *without* -resorting to backslashes. For 9 of the remaining 10%, use inline -literals or literal blocks:: - - "``\*``" -> "\*" (possibly in another font or quoted) - -Only those who understand the escaping and inline markup rules should -attempt the remaining 1%. ;-) - -Inline markup delimiter characters are used for multiple constructs, -so to avoid ambiguity there must be a specific recognition order for -each character. The inline markup recognition order is as follows: - -- Asterisks: `Strong emphasis`_ ("**") is recognized before emphasis_ - ("*"). - -- Backquotes: `Inline literals`_ ("``"), `inline internal targets`_ - (leading "_`", trailing "`"), are mutually independent, and are - recognized before phrase `hyperlink references`_ (leading "`", - trailing "\`_") and `interpreted text`_ ("`"). - -- Trailing underscores: Footnote references ("[" + label + "]_") and - simple `hyperlink references`_ (name + trailing "_") are mutually - independent. - -- Vertical bars: `Substitution references`_ ("|") are independently - recognized. - -- `Standalone hyperlinks`_ are the last to be recognized. - - -Character-Level Inline Markup ------------------------------ - -It is possible to mark up individual characters within a word with -backslash escapes (see `Escaping Mechanism`_ above). Backslash -escapes can be used to allow arbitrary text to immediately follow -inline markup:: - - Python ``list``\s use square bracket syntax. - -The backslash will disappear from the processed document. The word -"list" will appear as inline literal text, and the letter "s" will -immediately follow it as normal text, with no space in-between. - -Arbitrary text may immediately precede inline markup using -backslash-escaped whitespace:: - - Possible in *re*\ ``Structured``\ *Text*, though not encouraged. - -The backslashes and spaces separating "re", "Structured", and "Text" -above will disappear from the processed document. - -.. CAUTION:: - - The use of backslash-escapes for character-level inline markup is - not encouraged. Such use is ugly and detrimental to the - unprocessed document's readability. Please use this feature - sparingly and only where absolutely necessary. - - -Emphasis --------- - -Doctree element: emphasis. - -Start-string = end-string = "*". - -Text enclosed by single asterisk characters is emphasized:: - - This is *emphasized text*. - -Emphasized text is typically displayed in italics. - - -Strong Emphasis ---------------- - -Doctree element: strong. - -Start-string = end-string = "**". - -Text enclosed by double-asterisks is emphasized strongly:: - - This is **strong text**. - -Strongly emphasized text is typically displayed in boldface. - - -Interpreted Text ----------------- - -Doctree element: depends on the explicit or implicit role and -processing. - -Start-string = end-string = "`". - -Interpreted text is text that is meant to be related, indexed, linked, -summarized, or otherwise processed, but the text itself is typically -left alone. Interpreted text is enclosed by single backquote -characters:: - - This is `interpreted text`. - -The "role" of the interpreted text determines how the text is -interpreted. The role may be inferred implicitly (as above; the -"default role" is used) or indicated explicitly, using a role marker. -A role marker consists of a colon, the role name, and another colon. -A role name is a single word consisting of alphanumerics plus internal -hyphens, underscores, and periods; no whitespace or other characters -are allowed. A role marker is either a prefix or a suffix to the -interpreted text, whichever reads better; it's up to the author:: - - :role:`interpreted text` - - `interpreted text`:role: - -Interpreted text allows extensions to the available inline descriptive -markup constructs. To emphasis_, `strong emphasis`_, `inline -literals`_, and `hyperlink references`_, we can add "title reference", -"index entry", "acronym", "class", "red", "blinking" or anything else -we want. Only pre-determined roles are recognized; unknown roles will -generate errors. A core set of standard roles is implemented in the -reference parser; see `reStructuredText Interpreted Text Roles`_ for -individual descriptions. In addition, applications may support -specialized roles. - - -Inline Literals ---------------- - -Doctree element: literal. - -Start-string = end-string = "``". - -Text enclosed by double-backquotes is treated as inline literals:: - - This text is an example of ``inline literals``. - -Inline literals may contain any characters except two adjacent -backquotes in an end-string context (according to the recognition -rules above). No markup interpretation (including backslash-escape -interpretation) is done within inline literals. - -Line breaks are *not* preserved in inline literals. Although a -reStructuredText parser will preserve runs of spaces in its output, -the final representation of the processed document is dependent on the -output formatter, thus the preservation of whitespace cannot be -guaranteed. If the preservation of line breaks and/or other -whitespace is important, `literal blocks`_ should be used. - -Inline literals are useful for short code snippets. For example:: - - The regular expression ``[+-]?(\d+(\.\d*)?|\.\d+)`` matches - floating-point numbers (without exponents). - - -Hyperlink References --------------------- - -Doctree element: reference. - -- Named hyperlink references: - - - Start-string = "" (empty string), end-string = "_". - - Start-string = "`", end-string = "\`_". (Phrase references.) - -- Anonymous hyperlink references: - - - Start-string = "" (empty string), end-string = "__". - - Start-string = "`", end-string = "\`__". (Phrase references.) - -Hyperlink references are indicated by a trailing underscore, "_", -except for `standalone hyperlinks`_ which are recognized -independently. The underscore can be thought of as a right-pointing -arrow. The trailing underscores point away from hyperlink references, -and the leading underscores point toward `hyperlink targets`_. - -Hyperlinks consist of two parts. In the text body, there is a source -link, a reference name with a trailing underscore (or two underscores -for `anonymous hyperlinks`_):: - - See the Python_ home page for info. - -A target link with a matching reference name must exist somewhere else -in the document. See `Hyperlink Targets`_ for a full description). - -`Anonymous hyperlinks`_ (which see) do not use reference names to -match references to targets, but otherwise behave similarly to named -hyperlinks. - - -Embedded URIs -````````````` - -A hyperlink reference may directly embed a target URI inline, within -angle brackets ("<...>") as follows:: - - See the `Python home page <http://www.python.org>`_ for info. - -This is exactly equivalent to:: - - See the `Python home page`_ for info. - - .. _Python home page: http://www.python.org - -The bracketed URI must be preceded by whitespace and be the last text -before the end string. With a single trailing underscore, the -reference is named and the same target URI may be referred to again. - -With two trailing underscores, the reference and target are both -anonymous, and the target cannot be referred to again. These are -"one-off" hyperlinks. For example:: - - `RFC 2396 <http://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC - 2732 <http://www.rfc-editor.org/rfc/rfc2732.txt>`__ together - define the syntax of URIs. - -Equivalent to:: - - `RFC 2396`__ and `RFC 2732`__ together define the syntax of URIs. - - __ http://www.rfc-editor.org/rfc/rfc2396.txt - __ http://www.rfc-editor.org/rfc/rfc2732.txt - -If reference text happens to end with angle-bracketed text that is -*not* a URI, the open-angle-bracket needs to be backslash-escaped. -For example, here is a reference to a title describing a tag:: - - See `HTML Element: \<a>`_ below. - -The reference text may also be omitted, in which case the URI will be -duplicated for use as the reference text. This is useful for relative -URIs where the address or file name is also the desired reference -text:: - - See `<a_named_relative_link>`_ or `<an_anonymous_relative_link>`__ - for details. - -.. CAUTION:: - - This construct offers easy authoring and maintenance of hyperlinks - at the expense of general readability. Inline URIs, especially - long ones, inevitably interrupt the natural flow of text. For - documents meant to be read in source form, the use of independent - block-level `hyperlink targets`_ is **strongly recommended**. The - embedded URI construct is most suited to documents intended *only* - to be read in processed form. - - -Inline Internal Targets ------------------------- - -Doctree element: target. - -Start-string = "_`", end-string = "`". - -Inline internal targets are the equivalent of explicit `internal -hyperlink targets`_, but may appear within running text. The syntax -begins with an underscore and a backquote, is followed by a hyperlink -name or phrase, and ends with a backquote. Inline internal targets -may not be anonymous. - -For example, the following paragraph contains a hyperlink target named -"Norwegian Blue":: - - Oh yes, the _`Norwegian Blue`. What's, um, what's wrong with it? - -See `Implicit Hyperlink Targets`_ for the resolution of duplicate -reference names. - - -Footnote References -------------------- - -Doctree element: footnote_reference. - -Start-string = "[", end-string = "]_". - -Each footnote reference consists of a square-bracketed label followed -by a trailing underscore. Footnote labels are one of: - -- one or more digits (i.e., a number), - -- a single "#" (denoting `auto-numbered footnotes`_), - -- a "#" followed by a simple reference name (an `autonumber label`_), - or - -- a single "*" (denoting `auto-symbol footnotes`_). - -For example:: - - Please RTFM [1]_. - - .. [1] Read The Fine Manual - - -Citation References -------------------- - -Doctree element: citation_reference. - -Start-string = "[", end-string = "]_". - -Each citation reference consists of a square-bracketed label followed -by a trailing underscore. Citation labels are simple `reference -names`_ (case-insensitive single words, consisting of alphanumerics -plus internal hyphens, underscores, and periods; no whitespace). - -For example:: - - Here is a citation reference: [CIT2002]_. - -See Citations_ for the citation itself. - - -Substitution References ------------------------ - -Doctree element: substitution_reference, reference. - -Start-string = "|", end-string = "|" (optionally followed by "_" or -"__"). - -Vertical bars are used to bracket the substitution reference text. A -substitution reference may also be a hyperlink reference by appending -a "_" (named) or "__" (anonymous) suffix; the substitution text is -used for the reference text in the named case. - -The processing system replaces substitution references with the -processed contents of the corresponding `substitution definitions`_ -(which see for the definition of "correspond"). Substitution -definitions produce inline-compatible elements. - -Examples:: - - This is a simple |substitution reference|. It will be replaced by - the processing system. - - This is a combination |substitution and hyperlink reference|_. In - addition to being replaced, the replacement text or element will - refer to the "substitution and hyperlink reference" target. - - -Standalone Hyperlinks ---------------------- - -Doctree element: reference. - -Start-string = end-string = "" (empty string). - -A URI (absolute URI [#URI]_ or standalone email address) within a text -block is treated as a general external hyperlink with the URI itself -as the link's text. For example:: - - See http://www.python.org for info. - -would be marked up in HTML as:: - - See <a href="http://www.python.org">http://www.python.org</a> for - info. - -Two forms of URI are recognized: - -1. Absolute URIs. These consist of a scheme, a colon (":"), and a - scheme-specific part whose interpretation depends on the scheme. - - The scheme is the name of the protocol, such as "http", "ftp", - "mailto", or "telnet". The scheme consists of an initial letter, - followed by letters, numbers, and/or "+", "-", ".". Recognition is - limited to known schemes, per the `Official IANA Registry of URI - Schemes`_ and the W3C's `Retired Index of WWW Addressing Schemes`_. - - The scheme-specific part of the resource identifier may be either - hierarchical or opaque: - - - Hierarchical identifiers begin with one or two slashes and may - use slashes to separate hierarchical components of the path. - Examples are web pages and FTP sites:: - - http://www.python.org - - ftp://ftp.python.org/pub/python - - - Opaque identifiers do not begin with slashes. Examples are - email addresses and newsgroups:: - - mailto:someone@somewhere.com - - news:comp.lang.python - - With queries, fragments, and %-escape sequences, URIs can become - quite complicated. A reStructuredText parser must be able to - recognize any absolute URI, as defined in RFC2396_ and RFC2732_. - -2. Standalone email addresses, which are treated as if they were - absolute URIs with a "mailto:" scheme. Example:: - - someone@somewhere.com - -Punctuation at the end of a URI is not considered part of the URI, -unless the URI is terminated by a closing angle bracket (">"). -Backslashes may be used in URIs to escape markup characters, -specifically asterisks ("*") and underscores ("_") which are vaid URI -characters (see `Escaping Mechanism`_ above). - -.. [#URI] Uniform Resource Identifier. URIs are a general form of - URLs (Uniform Resource Locators). For the syntax of URIs see - RFC2396_ and RFC2732_. - - -Units -===== - -(New in Docutils 0.3.10.) - -All measures consist of a positive floating point number in standard -(non-scientific) notation and a unit, possibly separated by one or -more spaces. - -Units are only supported where explicitly mentioned in the reference -manuals. - - -Length Units ------------- - -The following length units are supported by the reStructuredText -parser: - -* em (ems, the height of the element's font) -* ex (x-height, the height of the letter "x") -* px (pixels, relative to the canvas resolution) -* in (inches; 1in=2.54cm) -* cm (centimeters; 1cm=10mm) -* mm (millimeters) -* pt (points; 1pt=1/72in) -* pc (picas; 1pc=12pt) - -(List and explanations taken from -http://www.htmlhelp.com/reference/css/units.html#length.) - -The following are all valid length values: "1.5em", "20 mm", ".5in". - - -Percentage Units ----------------- - -Percentage values have a percent sign ("%") as unit. Percentage -values are relative to other values, depending on the context in which -they occur. - - ----------------- - Error Handling ----------------- - -Doctree element: system_message, problematic. - -Markup errors are handled according to the specification in `PEP -258`_. - - -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _transforms: - http://docutils.sourceforge.net/docutils/transforms/ -.. _Grouch: http://www.mems-exchange.org/software/grouch/ -.. _RFC822: http://www.rfc-editor.org/rfc/rfc822.txt -.. _DocTitle transform: -.. _DocInfo transform: - http://docutils.sourceforge.net/docutils/transforms/frontmatter.py -.. _getopt.py: - http://www.python.org/doc/current/lib/module-getopt.html -.. _GNU libc getopt_long(): - http://www.gnu.org/software/libc/manual/html_node/Getopt-Long-Options.html -.. _doctest module: - http://www.python.org/doc/current/lib/module-doctest.html -.. _Emacs table mode: http://table.sourceforge.net/ -.. _Official IANA Registry of URI Schemes: - http://www.iana.org/assignments/uri-schemes -.. _Retired Index of WWW Addressing Schemes: - http://www.w3.org/Addressing/schemes.html -.. _World Wide Web Consortium: http://www.w3.org/ -.. _HTML Techniques for Web Content Accessibility Guidelines: - http://www.w3.org/TR/WCAG10-HTML-TECHS/#link-text -.. _image: directives.html#image -.. _replace: directives.html#replace -.. _meta: directives.html#meta -.. _figure: directives.html#figure -.. _admonition: directives.html#admonitions -.. _reStructuredText Directives: directives.html -.. _reStructuredText Interpreted Text Roles: roles.html -.. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt -.. _RFC2732: http://www.rfc-editor.org/rfc/rfc2732.txt -.. _Zope: http://www.zope.com/ -.. _PEP 258: ../../peps/pep-0258.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/ref/rst/roles.txt b/docutils/docs/ref/rst/roles.txt deleted file mode 100644 index 3b8b114bc..000000000 --- a/docutils/docs/ref/rst/roles.txt +++ /dev/null @@ -1,318 +0,0 @@ -========================================= - reStructuredText Interpreted Text Roles -========================================= - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -This document describes the interpreted text roles implemented in the -reference reStructuredText parser. - -Interpreted text uses backquotes (`) around the text. An explicit -role marker may optionally appear before or after the text, delimited -with colons. For example:: - - This is `interpreted text` using the default role. - - This is :title:`interpreted text` using an explicit role. - -A default role may be defined by applications of reStructuredText; it -is used if no explicit ``:role:`` prefix or suffix is given. The -"default default role" is `:title-reference:`_. It can be changed -using the default-role_ directive. - -See the `Interpreted Text`_ section in the `reStructuredText Markup -Specification`_ for syntax details. For details on the hierarchy of -elements, please see `The Docutils Document Tree`_ and the `Docutils -Generic DTD`_ XML document type definition. For interpreted text role -implementation details, see `Creating reStructuredText Interpreted -Text Roles`_. - -.. _"role" directive: directives.html#role -.. _default-role: directives.html#default-role -.. _Interpreted Text: restructuredtext.html#interpreted-text -.. _reStructuredText Markup Specification: restructuredtext.html -.. _The Docutils Document Tree: ../doctree.html -.. _Docutils Generic DTD: ../docutils.dtd -.. _Creating reStructuredText Interpreted Text Roles: - ../../howto/rst-roles.html - - -.. contents:: - - ---------------- - Customization ---------------- - -Custom interpreted text roles may be defined in a document with the -`"role" directive`_. Customization details are listed with each role. - -.. _class: - -A ``class`` option is recognized by the "role" directive for most -interpreted text roles. A description__ is provided in the `"role" -directive`_ documentation. - -__ directives.html#role-class - - ----------------- - Standard Roles ----------------- - -``:emphasis:`` -============== - -:Aliases: None -:DTD Element: emphasis -:Customization: - :Options: class_. - :Content: None. - -Implements emphasis. These are equivalent:: - - *text* - :emphasis:`text` - - -``:literal:`` -============== - -:Aliases: None -:DTD Element: literal -:Customization: - :Options: class_. - :Content: None. - -Implements inline literal text. These are equivalent:: - - ``text`` - :literal:`text` - -Care must be taken with backslash-escapes though. These are *not* -equivalent:: - - ``text \ and \ backslashes`` - :literal:`text \ and \ backslashes` - -The backslashes in the first line are preserved (and do nothing), -whereas the backslashes in the second line escape the following -spaces. - - -``:pep-reference:`` -=================== - -:Aliases: ``:PEP:`` -:DTD Element: reference -:Customization: - :Options: class_. - :Content: None. - -The ``:pep-reference:`` role is used to create an HTTP reference to a -PEP (Python Enhancement Proposal). The ``:PEP:`` alias is usually -used. For example:: - - See :PEP:`287` for more information about reStructuredText. - -This is equivalent to:: - - See `PEP 287`__ for more information about reStructuredText. - - __ http://www.python.org/peps/pep-0287.html - - -``:rfc-reference:`` -=================== - -:Aliases: ``:RFC:`` -:DTD Element: reference -:Customization: - :Options: class_. - :Content: None. - -The ``:rfc-reference:`` role is used to create an HTTP reference to an -RFC (Internet Request for Comments). The ``:RFC:`` alias is usually -used. For example:: - - See :RFC:`2822` for information about email headers. - -This is equivalent to:: - - See `RFC 2822`__ for information about email headers. - - __ http://www.faqs.org/rfcs/rfc2822.html - - -``:strong:`` -============ - -:Aliases: None -:DTD Element: strong -:Customization: - :Options: class_. - :Content: None. - -Implements strong emphasis. These are equivalent:: - - **text** - :strong:`text` - - -``:subscript:`` -=============== - -:Aliases: ``:sub:`` -:DTD Element: subscript -:Customization: - :Options: class_. - :Content: None. - -Implements subscripts. - -.. Tip:: - - Whitespace or punctuation is required around interpreted text, but - often not desired with subscripts & superscripts. - Backslash-escaped whitespace can be used; the whitespace will be - removed from the processed document:: - - H\ :sub:`2`\ O - E = mc\ :sup:`2` - - In such cases, readability of the plain text can be greatly - improved with substitutions:: - - The chemical formula for pure water is |H2O|. - - .. |H2O| replace:: H\ :sub:`2`\ O - - See `the reStructuredText spec`__ for further information on - `character-level markup`__ and `the substitution mechanism`__. - - __ restructuredtext.html - __ restructuredtext.html#character-level-inline-markup - __ restructuredtext.html#substitution-references - - -``:superscript:`` -================= - -:Aliases: ``:sup:`` -:DTD Element: superscript -:Customization: - :Options: class_. - :Content: None. - -Implements superscripts. See the tip in `:subscript:`_ above. - - -``:title-reference:`` -===================== - -:Aliases: ``:title:``, ``:t:``. -:DTD Element: title_reference -:Customization: - :Options: class_. - :Content: None. - -The ``:title-reference:`` role is used to describe the titles of -books, periodicals, and other materials. It is the equivalent of the -HTML "cite" element, and it is expected that HTML writers will -typically render "title_reference" elements using "cite". - -Since title references are typically rendered with italics, they are -often marked up using ``*emphasis*``, which is misleading and vague. -The "title_reference" element provides accurate and unambiguous -descriptive markup. - -Let's assume ``:title-reference:`` is the default interpreted text -role (see below) for this example:: - - `Design Patterns` [GoF95]_ is an excellent read. - -The following document fragment (pseudo-XML_) will result from -processing:: - - <paragraph> - <title_reference> - Design Patterns - - <citation_reference refname="gof95"> - GoF95 - is an excellent read. - -``:title-reference:`` is the default interpreted text role in the -standard reStructuredText parser. This means that no explicit role is -required. Applications of reStructuredText may designate a different -default role, in which case the explicit ``:title-reference:`` role -must be used to obtain a ``title_reference`` element. - - -.. _pseudo-XML: ../doctree.html#pseudo-xml - - -------------------- - Specialized Roles -------------------- - -``raw`` -======= - -:Aliases: None -:DTD Element: raw -:Customization: - :Options: class_, format - :Content: None - -.. WARNING:: - - The "raw" role is a stop-gap measure allowing the author to bypass - reStructuredText's markup. It is a "power-user" feature that - should not be overused or abused. The use of "raw" ties documents - to specific output formats and makes them less portable. - - If you often need to use "raw"-derived interpreted text roles or - the "raw" directive, that is a sign either of overuse/abuse or that - functionality may be missing from reStructuredText. Please - describe your situation in a message to the Docutils-users_ mailing - list. - - .. _Docutils-users: ../../user/mailing-lists.html#docutils-user - -The "raw" role indicates non-reStructuredText data that is to be -passed untouched to the Writer. It is the inline equivalent of the -`"raw" directive`_; see its documentation for details on the -semantics. - -.. _"raw" directive: directives.html#raw - -The "raw" role cannot be used directly. The `"role" directive`_ must -first be used to build custom roles based on the "raw" role. One or -more formats (Writer names) must be provided in a "format" option. - -For example, the following creates an HTML-specific "raw-html" role:: - - .. role:: raw-html(raw) - :format: html - -This role can now be used directly to pass data untouched to the HTML -Writer. For example:: - - If there just *has* to be a line break here, - :raw-html:`<br />` - it can be accomplished with a "raw"-derived role. - But the line block syntax should be considered first. - -.. Tip:: Roles based on "raw" should clearly indicate their origin, so - they are not mistaken for reStructuredText markup. Using a "raw-" - prefix for role names is recommended. - -In addition to "class_", the following option is recognized: - -``format`` : text - One or more space-separated output format names (Writer names). diff --git a/docutils/docs/ref/soextblx.dtd b/docutils/docs/ref/soextblx.dtd deleted file mode 100644 index 56ba311ba..000000000 --- a/docutils/docs/ref/soextblx.dtd +++ /dev/null @@ -1,312 +0,0 @@ -<!-- -=========================================================================== - OASIS XML Exchange Table Model Declaration Module -=========================================================================== -:Date: 1999-03-15 ---> - -<!-- This set of declarations defines the XML version of the Exchange - Table Model as of the date shown in the Formal Public Identifier - (FPI) for this entity. - - This set of declarations may be referred to using a public external - entity declaration and reference as shown in the following three - lines: - - <!ENTITY % calstblx - PUBLIC "-//OASIS//DTD XML Exchange Table Model 19990315//EN"> - %calstblx; - - If various parameter entities used within this set of declarations - are to be given non-default values, the appropriate declarations - should be given before calling in this package (i.e., before the - "%calstblx;" reference). ---> - -<!-- The motivation for this XML version of the Exchange Table Model - is simply to create an XML version of the SGML Exchange Table - Model. By design, no effort has been made to "improve" the model. - - This XML version incorporates the logical bare minimum changes - necessary to make the Exchange Table Model a valid XML DTD. ---> - -<!-- The XML version of the Exchange Table Model differs from - the SGML version in the following ways: - - The following parameter entities have been removed: - - - tbl.table.excep, tbl.hdft.excep, tbl.row.excep, tbl.entry.excep - There are no exceptions in XML. The following normative statement - is made in lieu of exceptions: the exchange table model explicitly - forbids a table from occurring within another table. If the - content model of an entry includes a table element, then this - cannot be enforced by the DTD, but it is a deviation from the - exchange table model to include a table within a table. - - - tbl.hdft.name, tbl.hdft.mdl, tbl.hdft.excep, tbl.hdft.att - The motivation for these elements was to change the table - header/footer elements. Since XML does not allow element declarations - to contain name groups, and the exchange table model does not - allow a table to contain footers, the continued presence of these - attributes seems unnecessary. - - The following parameter entity has been added: - - - tbl.thead.att - This entity parameterizes the attributes on thead. It replaces - the tbl.hdft.att parameter entity. - - Other miscellaneous changes: - - - Tag ommission indicators have been removed - - Comments have been removed from declarations - - NUMBER attributes have been changed to NMTOKEN - - NUTOKEN attributes have been to changed to NMTOKEN - - Removed the grouping characters around the content model - parameter entry for the 'entry' element. This is necessary - so that an entry can contain #PCDATA and be defined as an - optional, repeatable OR group beginning with #PCDATA. ---> - -<!-- This entity includes a set of element and attribute declarations - that partially defines the Exchange table model. However, the model - is not well-defined without the accompanying natural language - description of the semantics (meanings) of these various elements, - attributes, and attribute values. The semantic writeup, also available - from SGML Open, should be used in conjunction with this entity. ---> - -<!-- In order to use the Exchange table model, various parameter entity - declarations are required. A brief description is as follows: - - ENTITY NAME WHERE USED WHAT IT IS - - %yesorno In ATTLIST of: An attribute declared value - almost all elements for a "boolean" attribute - - %paracon In content model of: The "text" (logical content) - <entry> of the model group for <entry> - - %titles In content model of: The "title" part of the model - table element group for the table element - - %tbl.table.name In declaration of: The name of the "table" - table element element - - %tbl.table-titles.mdl In content model of: The model group for the title - table elements part of the content model for - table element - - %tbl.table.mdl In content model of: The model group for the content - table elements model for table element, - often (and by default) defined - in terms of %tbl.table-titles.mdl - and tgroup - - %tbl.table.att In ATTLIST of: Additional attributes on the - table element table element - - %bodyatt In ATTLIST of: Additional attributes on the - table element table element (for backward - compatibility with the SGML - model) - - %tbl.tgroup.mdl In content model of: The model group for the content - <tgroup> model for <tgroup> - - %tbl.tgroup.att In ATTLIST of: Additional attributes on the -4 <tgroup> <tgroup> element - - %tbl.thead.att In ATTLIST of: Additional attributes on the - <thead> <thead> element - - %tbl.tbody.att In ATTLIST of: Additional attributes on the - <tbody> <tbody> element - - %tbl.colspec.att In ATTLIST of: Additional attributes on the - <colspec> <colspec> element - - %tbl.row.mdl In content model of: The model group for the content - <row> model for <row> - - %tbl.row.att In ATTLIST of: Additional attributes on the - <row> <row> element - - %tbl.entry.mdl In content model of: The model group for the content - <entry> model for <entry> - - %tbl.entry.att In ATTLIST of: Additional attributes on the - <entry> <entry> element - - This set of declarations will use the default definitions shown below - for any of these parameter entities that are not declared before this - set of declarations is referenced. ---> - -<!-- These definitions are not directly related to the table model, but are - used in the default CALS table model and may be defined elsewhere (and - prior to the inclusion of this table module) in the referencing DTD. --> - -<!ENTITY % yesorno 'NMTOKEN'> <!-- no if zero(s), yes if any other value --> -<!ENTITY % titles 'title?'> -<!ENTITY % paracon '#PCDATA'> <!-- default for use in entry content --> - -<!-- -The parameter entities as defined below change and simplify the CALS table -model as published (as part of the Example DTD) in MIL-HDBK-28001. The -resulting simplified DTD has support from the SGML Open vendors and is -therefore more interoperable among different systems. - -These following declarations provide the Exchange default definitions -for these entities. However, these entities can be redefined (by giving -the appropriate parameter entity declaration(s) prior to the reference -to this Table Model declaration set entity) to fit the needs of the -current application. - -Note, however, that changes may have significant effect on the ability to -interchange table information. These changes may manifest themselves -in useability, presentation, and possible structure information degradation. ---> - -<!ENTITY % tbl.table.name "table"> -<!ENTITY % tbl.table-titles.mdl "%titles;,"> -<!ENTITY % tbl.table-main.mdl "tgroup+"> -<!ENTITY % tbl.table.mdl "%tbl.table-titles.mdl; %tbl.table-main.mdl;"> -<!ENTITY % tbl.table.att " - pgwide %yesorno; #IMPLIED "> -<!ENTITY % bodyatt ""> -<!ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody"> -<!ENTITY % tbl.tgroup.att ""> -<!ENTITY % tbl.thead.att ""> -<!ENTITY % tbl.tbody.att ""> -<!ENTITY % tbl.colspec.att ""> -<!ENTITY % tbl.row.mdl "entry+"> -<!ENTITY % tbl.row.att ""> -<!ENTITY % tbl.entry.mdl "(%paracon;)*"> -<!ENTITY % tbl.entry.att ""> - -<!-- ===== Element and attribute declarations follow. ===== --> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.table.name "table" - ENTITY % tbl.table-titles.mdl "%titles;," - ENTITY % tbl.table.mdl "%tbl.table-titles; tgroup+" - ENTITY % tbl.table.att " - pgwide %yesorno; #IMPLIED " ---> - -<!ELEMENT %tbl.table.name; (%tbl.table.mdl;)> - -<!ATTLIST %tbl.table.name; - frame (top|bottom|topbot|all|sides|none) #IMPLIED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - %tbl.table.att; - %bodyatt; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.tgroup.mdl "colspec*,thead?,tbody" - ENTITY % tbl.tgroup.att "" ---> - -<!ELEMENT tgroup (%tbl.tgroup.mdl;) > - -<!ATTLIST tgroup - cols NMTOKEN #REQUIRED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - align (left|right|center|justify|char) #IMPLIED - %tbl.tgroup.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.colspec.att "" ---> - -<!ELEMENT colspec EMPTY > - -<!ATTLIST colspec - colnum NMTOKEN #IMPLIED - colname NMTOKEN #IMPLIED - colwidth CDATA #IMPLIED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - align (left|right|center|justify|char) #IMPLIED - char CDATA #IMPLIED - charoff NMTOKEN #IMPLIED - %tbl.colspec.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.thead.att "" ---> - -<!ELEMENT thead (row+)> - -<!ATTLIST thead - valign (top|middle|bottom) #IMPLIED - %tbl.thead.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.tbody.att "" ---> - -<!ELEMENT tbody (row+)> - -<!ATTLIST tbody - valign (top|middle|bottom) #IMPLIED - %tbl.tbody.att; -> - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % tbl.row.mdl "entry+" - ENTITY % tbl.row.att "" ---> - -<!ELEMENT row (%tbl.row.mdl;)> - -<!ATTLIST row - rowsep %yesorno; #IMPLIED - valign (top|middle|bottom) #IMPLIED - %tbl.row.att; -> - - -<!-- - Default declarations previously defined in this entity and - referenced below include: - ENTITY % paracon "#PCDATA" - ENTITY % tbl.entry.mdl "(%paracon;)*" - ENTITY % tbl.entry.att "" ---> - -<!ELEMENT entry %tbl.entry.mdl;> - -<!ATTLIST entry - colname NMTOKEN #IMPLIED - namest NMTOKEN #IMPLIED - nameend NMTOKEN #IMPLIED - morerows NMTOKEN #IMPLIED - colsep %yesorno; #IMPLIED - rowsep %yesorno; #IMPLIED - align (left|right|center|justify|char) #IMPLIED - char CDATA #IMPLIED - charoff NMTOKEN #IMPLIED - valign (top|middle|bottom) #IMPLIED - %tbl.entry.att; -> diff --git a/docutils/docs/ref/transforms.txt b/docutils/docs/ref/transforms.txt deleted file mode 100644 index 54446f8dd..000000000 --- a/docutils/docs/ref/transforms.txt +++ /dev/null @@ -1,116 +0,0 @@ -===================== - Docutils Transforms -===================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - - -.. contents:: - - -For background about transforms and the Transformer object, see `PEP -258`_. - -.. _PEP 258: ../peps/pep-0258.html#transformer - - -Transforms Listed in Priority Order -=================================== - -============================== ============================ ======== -Transform: module.Class Added By Priority -============================== ============================ ======== -misc.class "class" (d/p) 210 - -references.Substitutions standalone (r), pep (r) 220 - -references.PropagateTargets standalone (r), pep (r) 260 - -frontmatter.DocTitle standalone (r) 320 - -frontmatter.DocInfo standalone (r) 340 - -frontmatter.SectSubTitle standalone (r) 350 - -peps.Headers pep (r) 360 - -peps.Contents pep (r) 380 - -references.AnonymousHyperlinks standalone (r), pep (r) 440 - -references.IndirectHyperlinks standalone (r), pep (r) 460 - -peps.TargetNotes pep (r) 520 - -references.TargetNotes peps.TargetNotes (t/p) 0 - -misc.CallBack peps.TargetNotes (t/p) 1 - -references.TargetNotes "target-notes" (d/p) 540 - -references.Footnotes standalone (r), pep (r) 620 - -references.ExternalTargets standalone (r), pep (r) 640 - -references.InternalTargets standalone (r), pep (r) 660 - -parts.SectNum "sectnum" (d/p) 710 - -parts.Contents "contents" (d/p), 720 - peps.Contents (t/p) - -universal.StripComments Reader (r) 740 - -peps.PEPZero peps.Headers (t/p) 760 - -components.Filter "meta" (d/p) 780 - -writer_aux.Compound newlatex2e (w) 810 - -universal.Decorations Reader (r) 820 - -misc.Transitions standalone (r), pep (r) 830 - -universal.ExposeInternals Reader (r) 840 - -references.DanglingReferences standalone (r), pep (r) 850 - -universal.Messages Writer (w) 860 - -universal.FilterMessages Writer (w) 870 - -universal.TestMessages DocutilsTestSupport 880 - -misc.CallBack n/a 990 -============================== ============================ ======== - -Key: - -* (r): Reader -* (w): Writer -* (d): Directive -* (t): Transform -* (/p): Via a "pending" node - - -Transform Priority Range Categories -=================================== - -==== ==== ================================================ - Priority ----------- ------------------------------------------------ -From To Category -==== ==== ================================================ - 0 99 immediate execution (added by another transform) - 100 199 very early (non-standard) - 200 299 very early - 300 399 early - 400 699 main - 700 799 late - 800 899 very late - 900 999 very late (non-standard) -==== ==== ================================================ diff --git a/docutils/docs/user/Makefile.docutils-update b/docutils/docs/user/Makefile.docutils-update deleted file mode 100644 index 89097b5ff..000000000 --- a/docutils/docs/user/Makefile.docutils-update +++ /dev/null @@ -1,6 +0,0 @@ -slide-shows.s5.html: slide-shows.txt - rst2s5.py slide-shows.txt slide-shows.s5.html \ - --config ../../tools/docutils.conf \ - --overwrite-theme-files \ - --link-stylesheet \ - --no-generator --no-datestamp --no-source-link diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt deleted file mode 100644 index 0413dd5be..000000000 --- a/docutils/docs/user/config.txt +++ /dev/null @@ -1,1041 +0,0 @@ -============================== - Docutils Configuration Files -============================== - -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - -.. Cross-reference command-line options with configuration file - settings? Make alphabetical indexes of both. - -Configuration files are used for persistent customization; they can be -set once and take effect every time you use a front-end tool. -Configuration file settings override the built-in defaults, and -command-line options override all. - -By default, Docutils checks the following places for configuration -files, in the following order: - -1. ``/etc/docutils.conf``: This is a system-wide configuration file, - applicable to all Docutils processing on the system. - -2. ``./docutils.conf``: This is a project-specific configuration file, - located in the current directory. The Docutils front end has to be - executed from the directory containing this configuration file for - it to take effect (note that this may have nothing to do with the - location of the source files). Settings in the project-specific - configuration file will override corresponding settings in the - system-wide file. - -3. ``~/.docutils``: This is a user-specific configuration file, - located in the user's home directory. Settings in this file will - override corresponding settings in both the system-wide and - project-specific configuration files. - -If more than one configuration file is found, all will be read but -later entries will override earlier ones. For example, a "stylesheet" -entry in a user-specific configuration file will override a -"stylesheet" entry in the system-wide file. - -The default implicit config file paths can be overridden by the -``DOCUTILSCONFIG`` environment variable. ``DOCUTILSCONFIG`` should -contain a colon-separated (semicolon-separated on Windows) sequence of -config file paths to search for; leave it empty to disable implicit -config files altogether. Tilde-expansion is performed on paths. -Paths are interpreted relative to the current working directory. -Empty path items are ignored. - -In addition, a configuration file may be explicitly specified with the -"--config" command-line option. This configuration file is read after -the three implicit ones listed above (or the ones defined by the -``DOCUTILSCONFIG`` environment variable), and its entries will have -priority. - - -------------------------- -Configuration File Syntax -------------------------- - -Configuration files use the standard ConfigParser.py_ Python_ module. -From its documentation: - - The configuration file consists of sections, lead by a "[section]" - header and followed by "name: value" entries, with continuations - in the style of `RFC 822`_; "name=value" is also accepted. Note - that leading whitespace is removed from values. ... Lines - beginning with "#" or ";" are ignored and may be used to provide - comments. - -.. Note:: No format string interpolation is done. - -Configuration file entry names correspond to internal runtime -settings. Underscores ("_") and hyphens ("-") can be used -interchangably in entry names; hyphens are automatically converted to -underscores. - -For on/off switch settings (booleans), the following values are -recognized: - -* On: "true", "yes", "on", "1" -* Off: "false", "no", "off", "0", "" (no value) - - -------------------------------------- -Configuration File Sections & Entries -------------------------------------- - -Below are the Docutils runtime settings, listed by config file -section. Any setting may be specified in any section, but only -settings from active sections will be used. Sections correspond to -Docutils components (module name or alias; section names are always in -lowercase letters). Each `Docutils application`_ uses a specific set -of components; corresponding configuration file sections are applied -when the application is used. Configuration sections are applied in -general-to-specific order, as follows: - -1. `[general]`_ - -2. `[parsers]`_, parser dependencies, and the section specific to the - Parser used ("[... parser]"). Currently, only `[restructuredtext - parser]`_ is applicable. - -3. `[readers]`_, reader dependencies, and the section specific to the - Reader used ("[... reader]"). For example, `[pep reader]`_ depends - on `[standalone reader]`_. - -4. `[writers]`_, writer dependencies, and the section specific to the - Writer used ("[... writer]"). For example, `[pep_html writer]`_ - depends on `[html4css1 writer]`_. - -5. `[applications]`_, application dependencies, and the section - specific to the Application (front-end tool) in use - ("[... application]"). - -Since any setting may be specified in any section, this ordering -allows component- or application-specific overrides of earlier -settings. For example, there may be Reader-specific overrides of -general settings; Writer-specific overrides of Parser settings; -Application-specific overrides of Writer settings; and so on. - -If multiple configuration files are applicable, the process is -completed (all sections are applied in the order given) for each one -before going on to the next. For example, a "[pep_html writer] -stylesheet" setting in an earlier configuration file would be -overridden by an "[html4css1 writer] stylesheet" setting in a later -file. - -Some knowledge of Python_ is assumed for some attributes. - -.. _ConfigParser.py: - http://www.python.org/doc/current/lib/module-ConfigParser.html -.. _Python: http://www.python.org/ -.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt -.. _Docutils application: tools.html - - -[general] -========= - -Settings in the "[general]" section are always applied. - -_`auto_id_prefix` - Prefix prepended to all auto-generated IDs generated within the - document, after id_prefix_. - - Default: "id". Options: ``--auto-id-prefix`` (hidden, intended - mainly for programmatic use). - -_`datestamp` - Include a time/datestamp in the document footer. Contains a - format string for Python's ``time.strftime``. See the `time - module documentation`__. - - Default: None. Options: ``--date, -d, --time, -t, - --no-datestamp``. - - Configuration file entry examples:: - - # Equivalent to --date command-line option, results in - # ISO 8601 extended format datestamp, e.g. "2001-12-21": - datestamp: %Y-%m-%d - - # Equivalent to --time command-line option, results in - # date/timestamp like "2001-12-21 18:43 UTC": - datestamp: %Y-%m-%d %H:%M UTC - - # Disables datestamp; equivalent to --no-datestamp: - datestamp: - - __ http://www.python.org/doc/current/lib/module-time.html - -_`debug` - Report debug-level system messages. - - Default: don't (None). Options: ``--debug, --no-debug``. - -_`dump_internals` - At the end of processing, write all internal attributes of the - document (``document.__dict__``) to stderr. - - Default: don't (None). Options: ``--dump-internals`` (hidden, for - development use only). - -_`dump_pseudo_xml` - At the end of processing, write the pseudo-XML representation of - the document to stderr. - - Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden, - for development use only). - -_`dump_settings` - At the end of processing, write all Docutils settings to stderr. - - Default: don't (None). Options: ``--dump-settings`` (hidden, for - development use only). - -_`dump_transforms` - At the end of processing, write a list of all transforms applied - to the document to stderr. - - Default: don't (None). Options: ``--dump-transforms`` (hidden, - for development use only). - -_`error_encoding` - The text encoding for error output. - - Default: "ascii". Options: ``--error-encoding, -e``. - -_`error_encoding_error_handler` - The error handler for unencodable characters in error output. See - output_encoding_error_handler_ for acceptable values. - - Default: "backslashreplace" for Python 2.3 and later; "replace" - otherwise. Options: ``--error-encoding-error-handler, - --error-encoding, -e``. - -_`exit_status_level` - A system message level threshold; non-halting system messages at - or above this level will produce a non-zero exit status at normal - exit. Exit status is the maximum system message level plus 10 (11 - for INFO, etc.). - - Default: disabled (5). Options: ``--exit-status``. - -_`expose_internals` - List of internal attribues to expose as external attributes (with - "internal:" namespace prefix). To specify multiple attributes in - configuration files, use colons to separate names; on the command - line, the option may be used more than once. - - Default: don't (None). Options: ``--expose-internal-attribute`` - (hidden, for development use only). - -_`footnote_backlinks` - Enable or disable backlinks from footnotes and citations to their - references. - - Default: enabled (1). Options: ``--footnote-backlinks, - --no-footnote-backlinks``. - -_`generator` - Include a "Generated by Docutils" credit and link in the document - footer. - - Default: off (None). Options: ``--generator, -g, - --no-generator``. - -_`halt_level` - The threshold at or above which system messages are converted to - exceptions, halting execution immediately. If `traceback`_ is - set, the exception will propagate; otherwise, Docutils will exit. - - Default: severe (4). Options: ``--halt, --strict``. - -_`id_prefix` - Prefix prepended to all IDs generated within the document. See - also auto_id_prefix_. - - Default: "" (empty). Options: ``--id-prefix`` (hidden, intended - mainly for programmatic use). - -_`input_encoding` - The text encoding for input. - - Default: auto-detect (None). Options: ``--input-encoding, -i``. - -_`input_encoding_error_handler` - The error handler for undecodable characters in the input. - Acceptable values include: - - strict - Raise an exception in case of an encoding error. - replace - Replace malformed data with the official Unicode replacement - character, U+FFFD. - ignore - Ignore malformed data and continue without further notice. - - Acceptable values are the same as for the "error" parameter of - Python's ``unicode`` function; other values may be defined in - applications or in future versions of Python. - - Default: "strict". Options: ``--input-encoding-error-handler, - --input-encoding, -i``. - -_`language_code` - `ISO 639`_ 2-letter language code (3-letter codes used only if no - 2-letter code exists). - - Default: English ("en"). Options: ``--language, -l``. - -_`output_encoding` - The text encoding for output. - - Default: "UTF-8". Options: ``--output-encoding, -o``. - -_`output_encoding_error_handler` - The error handler for unencodable characters in the output. - Acceptable values include: - - strict - Raise an exception in case of an encoding error. - replace - Replace malformed data with a suitable replacement marker, - such as "?". - ignore - Ignore malformed data and continue without further notice. - xmlcharrefreplace - Replace with the appropriate XML character reference, such as - "``†``". - backslashreplace - (Python 2.3+) Replace with backslashed escape sequences, such - as "``\u2020``". - - Acceptable values are the same as for the "error" parameter of - Python's ``encode`` string method; other values may be defined in - applications or in future versions of Python. - - Default: "strict". Options: ``--output-encoding-error-handler, - --output-encoding, -o``. - -_`record_dependencies` - Path to a file where Docutils will write a list of files that the - input and output depend on [#dependencies]_, e.g. due to file - inclusion. [#pwd]_ The format is one filename per line. This - option is particularly useful in conjunction with programs like - ``make``. - - Set to ``-`` in order to write dependencies to stdout. - - Default: None. Option: ``--record-dependencies``. - -_`report_level` - Verbosity threshold at or above which system messages are - reported. - - Default: warning (2). Options: ``--report, -r, --verbose, -v, - --quiet, -q``. - -_`sectnum_xform` - Enable or disable the section numbering transform - (docutils.transforms.parts.SectNum). - - Default: enabled (1). Options: ``--section-numbering``, - ``--no-section-numbering``. - -_`source_link` - Include a "View document source" link in the document footer. URL - will be relative to the destination. - - Default: don't (None). Options: ``--source-link, -s, - --no-source-link``. - -_`source_url` - An explicit URL for a "View document source" link, used verbatim. - - Default: compute if source_link (None). Options: ``--source-url, - --no-source-link``. - -_`strict_visitor` - When processing a document tree with the Visitor pattern, raise an - error if a writer does not support a node type listed as optional. - For transitional development use. - - Default: disabled (None). Option: ``--strict-visitor`` (hidden, - for development use only). - -_`strip_comments` - Enable the removal of comment elements from the document tree. - - Default: disabled (None). Options: ``--strip-comment``, - ``--leave-comments``. - -_`title` - The document title as metadata, which does not become part of the - document body. It overrides a document-supplied title. For - example, in HTML output the metadata document title appears in the - title bar of the browser window. - - Default: none. Option: ``--title``. - -_`toc_backlinks` - Enable backlinks from section titles to table of contents entries - ("entry"), to the top of the TOC ("top"), or disable ("none"). - - Default: "entry". Options: ``--toc-entry-backlinks, - --toc-top-backlinks, --no-toc-backlinks``. - -_`traceback` - Enable Python tracebacks when halt-level system messages and other - exceptions occur. Useful for debugging, and essential for issue - reports. Exceptions are allowed to propagate, instead of being - caught and reported (in a user-friendly way) by Docutils. - - Default: disabled (None) unless Docutils is run programmatically - using the `Publisher Interface`_. Options: ``--traceback, - --no-traceback``. - - .. _Publisher Interface: ../api/publisher.html - -_`warning_stream` - Path to a file for the output of system messages (warnings) - [#pwd]_. - - Default: stderr (None). Options: ``--warnings``. - - -[parsers] ---------- - -Docutils currently supports only one parser, for reStructuredText. - - -[restructuredtext parser] -````````````````````````` - -_`file_insertion_enabled` - Enable or disable directives that insert the contents of external - files, such as the "include_" & "raw_". A "warning" system - message (including the directive text) is inserted instead. (See - also raw_enabled_ for another security-relevant setting.) - - Default: enabled (1). Options: ``--file-insertion-enabled, - --no-file-insertion``. - - .. _include: ../ref/rst/directives.html#include - .. _raw: ../ref/rst/directives.html#raw - -_`pep_references` - Recognize and link to standalone PEP references (like "PEP 258"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--pep-references``. - -_`pep_base_url` - Base URL for PEP references. - - Default: "http://www.python.org/peps/". Option: - ``--pep-base-url``. - -_`raw_enabled` - Enable or disable the "raw_" directive. A "warning" system - message (including the directive text) is inserted instead. (See - also file_insertion_enabled_ for another security-relevant - setting.) - - Default: enabled (1). Options: ``--raw-enabled, --no-raw``. - -_`rfc_references` - Recognize and link to standalone RFC references (like "RFC 822"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--rfc-references``. - -_`rfc_base_url` - Base URL for RFC references. - - Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``. - -_`tab_width` - Number of spaces for hard tab expansion. - - Default: 8. Options: ``--tab-width``. - -_`trim_footnote_reference_space` - Remove spaces before footnote references. - - Default: don't (None); may be overriden by a writer-specific - footnote_references__ default though. Options: - ``--trim-footnote-reference-space, - --leave-footnote-reference-space``. - -__ `footnote_references [latex2e writer]`_ - - -[readers] ---------- - - -[standalone reader] -``````````````````` - -_`docinfo_xform` - Enable or disable the bibliographic field list transform - (docutils.transforms.frontmatter.DocInfo). - - Default: enabled (1). Options: ``--no-doc-info``. - -_`doctitle_xform` - Enable or disable the promotion of a lone top-level section title - to document title (and subsequent section title to document - subtitle promotion; docutils.transforms.frontmatter.DocTitle). - - Default: enabled (1). Options: ``--no-doc-title``. - -_`sectsubtitle_xform` - - Enable or disable the promotion of the title of a lone subsection - to a subtitle (docutils.transforms.frontmatter.SectSubTitle). - - Default: disabled (0). Options: ``--section-subtitles, - --no-section-subtitles``. - - -[pep reader] -```````````` - -The `pep_references`_ and `rfc_references`_ options -(`[restructuredtext parser]`_) are set on by default. - - -[python reader] -``````````````` - -Under construction. - - -[writers] ---------- - -[docutils_xml writer] -````````````````````` - -_`doctype_declaration` - Generate XML with a DOCTYPE declaration. - - Default: do (1). Options: ``--no-doctype``. - -_`indents` - Generate XML with indents and newlines. - - Default: don't (None). Options: ``--indents``. - -_`newlines` - Generate XML with newlines before and after tags. - - Default: don't (None). Options: ``--newlines``. - -.. _xml_declaration [docutils_xml writer]: - -xml_declaration - Generate XML with an XML declaration. Also defined for the - `HTML Writer`__. - - .. Caution:: The XML declaration carries text encoding - information, without which standard tools may be unable to read - the generated XML. - - Default: do (1). Options: ``--no-xml-declaration``. - - __ `xml_declaration [html4css1 writer]`_ - - -[html4css1 writer] -`````````````````` - -.. _attribution [html4css1 writer]: - -attribution - Format for block quote attributions: one of "dash" (em-dash - prefix), "parentheses"/"parens", or "none". Also defined for the - `LaTeX Writer`__. - - Default: "dash". Options: ``--attribution``. - - __ `attribution [latex2e writer]`_ - -_`cloak_email_addresses` - Scramble email addresses to confuse harvesters. In the reference - URI, the "@" will be replaced by %-escapes (as of RFC 1738). In - the visible text (link text) of an email reference, the "@" and - all periods (".") will be surrounded by ``<span>`` tags. - Furthermore, HTML entities are used to encode these characters in - order to further complicate decoding the email address. For - example, "abc@example.org" will be output as:: - - <a class="reference" href="mailto:abc%40example.org"> - abc<span>@</span>example<span>.</span>org</a> - - .. Note:: While cloaking email addresses will have little to no - impact on the rendering and usability of email links in most - browsers, some browsers (e.g. the ``links`` browser) may decode - cloaked email addresses incorrectly. - - Default: don't cloak (None). Option: ``--cloak-email-addresses``. - -_`compact_lists` - Remove extra vertical whitespace between items of bullet lists and - enumerated lists, when list items are all "simple" (i.e., items - each contain one paragraph and/or one "simple" sublist only). The - behaviour can be specified directly via "class" attributes (values - "compact" and "open") in the document. - - Default: enabled (1). Options: ``--compact-lists, - --no-compact-lists``. - -_`compact_field_lists` - Remove extra vertical whitespace between items of field lists that - are "simple" (i.e., all field bodies each contain at most one - paragraph). The behaviour can be specified directly via "class" - attributes (values "compact" and "open") in the document. - - Default: enabled (1). Options: ``--compact-field-lists, - --no-compact-field-lists``. - -_`embed_stylesheet` - Embed the stylesheet in the output HTML file. The stylesheet file - must be accessible during processing. - - Default: enabled. Options: ``--embed-stylesheet, - --link-stylesheet``. - -_`field_name_limit` - The maximum width (in characters) for one-column field names. - Longer field names will span an entire row of the table used to - render the field list. 0 indicates "no limit". See also - option_limit_. - - Default: 14 characters. Option: ``--field-name-limit``. - -.. _footnote_references [html4css1 writer]: - -footnote_references - Format for footnote references, one of "superscript" or - "brackets". Also defined for the `LaTeX Writer`__. - - Overrides [#override]_ trim_footnote_reference_space_, if - applicable. [#footnote_space]_ - - Default: "brackets". Option: ``--footnote-references``. - - __ `footnote_references [latex2e writer]`_ - -_`initial_header_level` - The initial level for header elements. This does not affect the - document title & subtitle; see doctitle_xform_. - - Default: 1 (for "<h1>"). Option: ``--initial-header-level``. - -_`option_limit` - The maximum width (in characters) for options in option lists. - Longer options will span an entire row of the table used to render - the option list. 0 indicates "no limit". See also - field_name_limit_. - - Default: 14 characters. Option: ``--option-limit``. - -.. _stylesheet [html4css1 writer]: - -stylesheet - CSS stylesheet URL, used verbatim. Overrides the - "stylesheet_path" setting [#override]_. Pass an empty string to - deactivate stylesheet inclusion. - - Default: None. Options: ``--stylesheet``. - - (Setting also defined for the `LaTeX Writer`__.) - - __ `stylesheet [latex2e writer]`_ - -.. _stylesheet_path [html4css1 writer]: - -stylesheet_path - Path to CSS stylesheet [#pwd]_. Overrides the "stylesheet" URL - setting [#override]_. Path is adjusted relative to the output - HTML file. Also defined for the `LaTeX Writer`__. - - Default: "html4css1.css" in the docutils/writers/html4css1/ - directory (installed automatically; for the exact machine-specific - path, use the ``--help`` option). Options: ``--stylesheet-path``. - - __ `stylesheet_path [latex2e writer]`_ - -.. _xml_declaration [html4css1 writer]: - -xml_declaration - Generate XML with an XML declaration. Also defined for the - `Docutils XML Writer`__. - - .. Caution:: The XML declaration carries text encoding - information, without which standard tools may be unable to read - the generated XML. - - Default: do (1). Options: ``--no-xml-declaration``. - - __ `xml_declaration [docutils_xml writer]`_ - - -[pep_html writer] -................. - -The PEP/HTML Writer derives from the standard HTML Writer, and shares -all settings defined in the `[html4css1 writer]`_ section. The -"[html4css1 writer]" section of configuration files is processed -before the "[pep_html writer]" section. - -The PEP/HTML Writer's default for the ``stylesheet_path`` setting -differs from that of the standard HTML Writer: -``docutils/writers/pep_html/pep.css`` in the installation directory is -used. For the exact machine-specific path, use the ``--help`` option. - -_`no_random` - Do not use a random banner image. Mainly used to get predictable - results when testing. - - Default: random enabled (None). Options: ``--no-random`` - (hidden). - -_`pep_home` - Home URL prefix for PEPs. - - Default: current directory ("."). Options: ``--pep-home``. - -_`template` - Path to PEP template file [#pwd]_. - - Default: "pep-html-template" (in current directory). Options: - ``--template``. - -_`python_home` - Python's home URL. - - Default: parent directory (".."). Options: ``--python-home``. - - -[s5_html writer] -................. - -The S5/HTML Writer derives from the standard HTML Writer, and shares -all settings defined in the `[html4css1 writer]`_ section. The -"[html4css1 writer]" section of configuration files is processed -before the "[s5_html writer]" section. - -The S5/HTML Writer's default for the ``compact_lists`` setting differs -from that of the standard HTML Writer: the default here is to disable -compact lists. - -_`current_slide` - - Enable or disable the current slide indicator ("1/15"). - - Default: disabled (None). Options: ``--current-slide``, - ``--no-current-slide``. - -_`overwrite_theme_files` - Allow or prevent the overwriting of existing theme files in the - ``ui/<theme>`` directory. This has no effect if "theme_url_" is - used. - - Default: keep existing theme files (None). Options: - ``--keep-theme-files``, ``--overwrite-theme-files``. - -_`theme` - Name of an installed S5 theme, to be copied into a ``ui/<theme>`` - subdirectory, beside the destination file (output HTML). Note - that existing theme files will not be overwritten; the existing - theme directory you must be deleted manually. Overrides the - "theme_url_" setting [#override]_. - - Default: "default". Option: ``--theme``. - -_`theme_url` - The URL of an S5 theme directory. The destination file (output - HTML) will link to this theme; nothing will be copied. Overrides - the "theme_" setting [#override]_. - - Default: None. Option: ``--theme-url``. - - -[latex2e writer] -```````````````` - -_`use_latex_toc` - To get pagenumbers in the table of contents the table of contents - must be generated by latex. Usually latex must be run twice to get - numbers correct. - - *Note:* LaTeX will number the sections, which might be a bug in - this case. - - Default: off. Option: ``--use-latex-toc``. - -.. XXX Missing: use_latex_docinfo - -_`use_latex_footnotes` - Use LaTeX-footnotes not a figure simulation. This might give no - Hyperrefs on /to footnotes, but should be able to handle an - unlimited number of footnotes. - - Default: off. Option: ``--use-latex-footnotes``. - -_`hyperlink_color` - Color of any hyperlinks embedded in text. Use "0" to disable - coloring of links. - - Default: "blue". Option: ``--hyperlink-color``. - -_`documentclass` - Specify latex documentclass, *but* beaware that books have chapters - articles not. - - Default: "article". Option: ``--documentclass``. - -_`documentoptions` - Specify document options. Multiple options can be given, separated by - commas. - - Default: "10pt,a4paper". Option: ``--documentoptions``. - -.. _stylesheet [latex2e writer]: - -stylesheet - Specify a stylesheet file. Overrides stylesheet_path - [#override]_. The file will be ``\input`` by latex in the - document header. Also defined for the `HTML Writer`__. - - Default: no stylesheet (""). Option: ``--stylesheet``. - - __ `stylesheet [html4css1 writer]`_ - -.. _stylesheet_path [latex2e writer]: - -stylesheet_path - Path to stylesheet [#pwd]_. Overrides "stylesheet" setting - (``--stylesheet``) [#override]_. - - Please note that you will have to run ``latex`` from the directory - containing the output file; otherwise the stylesheet reference - will be invalid. - - This setting is also defined for the `HTML Writer`__. - - Default: None. Option: ``--stylesheet-path``. - - __ `stylesheet_path [html4css1 writer]`_ - -.. XXX Missing: embed_stylesheet - -.. _footnote_references [latex2e writer]: - -footnote_references - Format for footnote references: one of "superscript" or - "brackets". Also defined for the `HTML Writer`__. - - Overrides [#override]_ trim_footnote_reference_space_, if - applicable. [#footnote_space]_ - - Default: "superscript". Option: ``--footnote-references``. - - __ `footnote_references [html4css1 writer]`_ - -.. _attribution [latex2e writer]: - -attribution - Format for block quote attributions, the same as for the - html-writer: one of "dash" (em-dash prefix), - "parentheses"/"parens" or "none". Also defined for the `HTML - Writer`__. - - Default: "dash". Option: ``--attribution``. - - __ `attribution [html4css1 writer]`_ - -_`compound_enumerators` - Enable or disable compound enumerators for nested enumerated lists - (e.g. "1.2.a.ii"). - - Default: disabled (None). Options: ``--compound-enumerators``, - ``--no-compound-enumerators``. - -_`section_prefix_for_enumerators` - Enable or disable section ("." subsection ...) prefixes for - compound enumerators. This has no effect unless - `compound_enumerators`_ are enabled. - - Default: disabled (None). Options: - ``--section-prefix-for-enumerators``, - ``--no-section-prefix-for-enumerators``. - -_`section_enumerator_separator` - The separator between section number prefix and enumerator for - compound enumerated lists (see `compound_enumerators`_). - - Generally it isn't recommended to use both sub-sections and nested - enumerated lists with compound enumerators. This setting avoids - ambiguity in the situation where a section "1" has a list item - enumerated "1.1", and subsection "1.1" has list item "1". With a - separator of ".", these both would translate into a final compound - enumerator of "1.1.1". With a separator of "-", we get the - unambiguous "1-1.1" and "1.1-1". - - Default: "-". Option: ``--section-enumerator-separator``. - -_`table_style` - Specify the drawing of separation lines. - - - "standard" lines around and between cells. - - "booktabs" a line above and below the table and one after the - head. - - "nolines". - - Default: "standard". Option: ``--table-style``. - - -[pseudoxml writer] -`````````````````` - -No settings are defined for this Writer. - - -[applications] --------------- - -[buildhtml application] -``````````````````````` - -_`prune` - List of directories not to process. To specify multiple - directories in configuration files, use colon-separated paths; on - the command line, the option may be used more than once. - - Default: none ([]). Options: ``--prune``. - -_`recurse` - Recursively scan subdirectories, or ignore subdirectories. - - Default: recurse (1). Options: ``--recurse, --local``. - -_`silent` - Work silently (no progress messages). Independent of - "report_level". - - Default: show progress (None). Options: ``--silent``. - - -[docfactory application] -```````````````````````` - -(To be completed.) - - -Other Settings -============== - -These settings are only effective as command-line options, positional -arguments, or for internal use; setting them in configuration files -has no effect. - -_`config` - Path to a configuration file to read (if it exists) [#pwd]_. - Settings may override defaults and earlier settings. The config - file is processed immediately. Multiple ``--config`` options may - be specified; each will be processed in turn. - - Filesystem path settings contained within the config file will be - interpreted relative to the config file's location (*not* relative - to the current working directory). - - Default: None. Options: ``--config``. - -_`_directories` - (``buildhtml.py`` front end.) List of paths to source - directories, set from positional arguments. - - Default: current working directory (None). No command-line - options. - -_`_disable_config` - Prevent standard configuration files from being read. For - programmatic use only. - - Default: config files enabled (None). No command-line options. - -_`_destination` - Path to output destination, set from positional arguments. - - Default: stdout (None). No command-line options. - -_`_source` - Path to input source, set from positional arguments. - - Default: stdin (None). No command-line options. - -.. _ISO 639: http://www.loc.gov/standards/iso639-2/englangn.html - -.. [#pwd] Path relative to the working directory of the process at - launch. - -.. [#override] The overridden setting will automatically be set to - ``None`` for command-line options and config file settings. Client - programs which specify defaults that override other settings must - do the overriding explicitly, by assigning ``None`` to the other - settings. - -.. [#dependencies] Some notes on the dependency recorder: - - * Images are only added to the dependency list if the - reStructuredText parser extracted image dimensions from the file. - - * Stylesheets are only added if they are embedded. - - * For practical reasons, the output of the LaTeX writer is - considered merely an *intermediate* processing stage. The - dependency recorder records all files the *rendered* file - (e.g. in PDF or DVI format) depends on. Thus, images and - stylesheets are both unconditionally recorded as dependencies - when using the LaTeX writer. - -.. [#footnote_space] The footnote space is trimmed if the reference - style is "superscript", and it is left if the reference style is - "brackets". - - The overriding only happens if the parser supports the - trim_footnote_reference_space option. - - ------------------------------- -Old-Format Configuration Files ------------------------------- - -Formerly, Docutils configuration files contained a single "[options]" -section only. This was found to be inflexible, and in August 2003 -Docutils adopted the current component-based configuration file -sections as described above. Docutils will still recognize the old -"[options]" section, but complains with a deprecation warning. - -To convert existing config files, the easiest way is to change the -section title: change "[options]" to "[general]". Most settings -haven't changed. The only ones to watch out for are these: - -===================== ===================================== -Old-Format Setting New Section & Setting -===================== ===================================== -pep_stylesheet [pep_html writer] stylesheet -pep_stylesheet_path [pep_html writer] stylesheet_path -pep_template [pep_html writer] template -===================== ===================================== diff --git a/docutils/docs/user/emacs.txt b/docutils/docs/user/emacs.txt deleted file mode 100644 index 49687f599..000000000 --- a/docutils/docs/user/emacs.txt +++ /dev/null @@ -1,497 +0,0 @@ -.. -*- coding: utf-8 -*- - -======================================== - Emacs Support for reStructuredText -======================================== - -:Author: Martin Blais <blais@furius.ca> -:Date: $Date$ -:Abstract: - - High-level description of the existing emacs support for editing - reStructuredText text documents. Suggested setup code and usage - instructions are provided. - -.. contents:: - - -Introduction -============ - -reStructuredText_ is a series of conventions that allows a -toolset--docutils--to extract generic document structure from simple -text files. For people who use Emacs_, there is a package that adds -some support for the conventions that reStructuredText_ specifies: -``rst.el``. - -This document describes the most important features that it provides, -how to setup your emacs to use them and how to invoke them. - - -Basic Setup -=========== - -The emacs support is completely provided by the ``rst.el`` emacs -package. In order to use these features, you need to put the file in -your emacs load-path, and to load it with:: - - (require 'rst) ;; or (load "rst") - -Additional configuration variables can be customized and can be found -by browsing the source code for ``rst.el``. - -Then you will want to bind keys to the most common commands it -provides. A standard text-mode hook function is maintained and -provided by the package for this use, set it up like this:: - - (add-hook 'text-mode-hook 'rst-text-mode-bindings) - -A prefix map is defined for all the ``rst.el`` commands. By default, -it is bound to the mode-specific-map and ``p``, e.g. ``C-c p ...``. - - -Section Decoration Adjustment -============================= - -The rst package does not completely parse all the reStructuredText_ -constructs, but it contains the ability to recognize the section -decorations and to build the hierarchy of the document. What we call -section decorations or adornments are the underlines or under- and -overlines used to mark a section title. - -There is a function that helps a great deal to maintain these -decorations: ``rst-adjust`` (bound on ``C-c p a``, ``C-c p =`` or -``C-=`` by default). This function is a Swiss army knife that can be -invoked repeatedly and whose behaviour depends on context: - -#. If there is an incomplete underline, e.g.:: - - My Section Title - ^^ - - Invocation will complete the section title. You can simply enter a - few characters of the title and invoke the function to complete it. - It can also be used to adjust the length of the existing decoration - when you need to edit the title. - -#. If there is no section decoration, a decoration one level under the - last encountered section level is added; - -#. If there is already a section decoration, it is promoted to the - next level. You can invoke it like this repeatedly to cycle the - title through the hierarchy of existing decorations. - -Invoking the function with a negative prefix argument, e.g. ``C-- -C-=``, will effectively reverse the direction of decoration cycling. -To alternate between underline-only and over-and-under styles, you can -use a regular prefix argument, e.g. ``C-u C-=``. See the -documentation of ``rst-adjust`` for more description of the prefix -arguments to alter the behaviour of the function. - - -Promoting and Demoting Many Sections ------------------------------------- - -When you are re-organizing the structure of a document, it can be -useful to change the level of a number of section titles. The same -key binding can be used to do that: if the region is active when the -binding is invoked, all the section titles that are within the region -are promoted accordingly (or demoted, with negative prefix arg). - - -Customizations --------------- - -You can set the variable ``rst-preferred-decorations`` to a list of -the decorations that you like to use for documents. Everyone has -their preference. ``rst-default-indent`` can be set to the number of -indent spaces preferred for the over-and-under decoration style. - - -Viewing the Hierarchy of Section Decorations -============================================ - -You can visualize the hierarchy of the section decorations in the -current buffer by invoking ``rst-display-decorations-hierarchy``, -bound on ``C-c p h``. A temporary buffer will appear with fake -section titles rendered in the style of the current document. This -can be useful when editing other people's documents to find out which -section decorations correspond to which levels. - - -Table of Contents -================= - -When you are editing long documents, it can be a bit difficult to -orient yourself in the structure of your text. To that effect, a -function is provided that quickly parses the document and presents a -hierarchically indented table of contents of the document in a -temporary buffer, in which you can navigate and press ``Return`` to go -to a specific section. - -Invoke this function (``rst-toc``) with ``C-c p t``. It should -present a temporary buffer that looks something like this:: - - Table of Contents: - Debugging Meta-Techniques - Introduction - Debugging Solution Patterns - Recognize That a Bug Exists - Subdivide and Isolate - Identify and Verify Assumptions - Use a Tool for Introspection - Change one thing at a time - Learn about the System - Understanding a bug - The Basic Steps in Debugging - Attitude - Bad Feelings - Good Feelings - References - -When you select a section title, the temporary buffer disappears and -you are left with the cursor positioned at the chosen section. - - -Inserting a Table of Contents ------------------------------ - -Oftentimes in long text documents that are meant to be read directly, -a Table of Contents is inserted at the beginning of the text. This is -the case for most internet FAQs, for example. In reStructuredText_ -documents, since the table of contents is automatically generated by -the parser with the ``.. contents::`` directive, people generally have -not been adding a text table of contents to their source documents, -and partly because it is too much trouble to edit and maintain. - -The emacs support for reStructuredText_ provides a function to insert -such a table of contents in your document. Since it is not meant to -be part of the document text, you should place such a table of -contents within a comment, so that it is ignored by the parser. This -is the favoured usage:: - - .. contents:: - .. - 1 Introduction - 2 Debugging Solution Patterns - 2.1 Recognize That a Bug Exists - 2.2 Subdivide and Isolate - 2.3 Identify and Verify Assumptions - 2.4 Use a Tool for Introspection - 2.5 Change one thing at a time - 2.6 Learn about the System - 3 Understanding a bug - 4 The Basic Steps in Debugging - 5 Attitude - 5.1 Bad Feelings - 5.2 Good Feelings - 6 References - -Just place the cursor at the top-left corner where you want to insert -the TOC and invoke the function with ``C-c p i``. The table of -contents will display all the section titles that are under the -location where the insertion occurs. This way you can insert local -table of contents by placing them in the appropriate location. - -If you have deep nesting of sections, you can use a numeric prefix -argument to limit the depth of rendering of the TOC. - -You can also customize the look of the TOC by setting the values of -the following variables:: ``rst-toc-indent``, -``rst-toc-insert-style``, ``rst-toc-insert-max-level``. - - -Maintaining the Table of Contents Up-to-date --------------------------------------------- - -One issue is that you will probably want to maintain the inserted -table of contents up-to-date. There is a function that will -automatically look for the inserted TOC (``rst-toc-insert-update``) -and it can be added to a hook on the section decoration adjustment -function, so that every time you adjust a section title, the TOC is -updated. Add this functionality with the following emacs -configuration:: - - (add-hook 'rst-adjust-hook 'rst-toc-insert-update) - -You can invoke the update on the current buffer with ``C-c p u``. - - -Navigating Between the Section Titles -===================================== - -You can move the cursor between the different sections by using the -``rst-backward-section`` and ``rst-forward-section`` functions, by -default bound to the ``C-c p p`` and ``C-c p n`` keys (also ``C-c -C-p`` and ``C-c C-n``). - - -Shifting Bullet List Levels -=========================== - -Due to the nature of reStructuredText_, bullet lists are always -indented by two characters (unless they are part of a blockquote), -e.g. :: - - - Fruits - - - Bananas - - Apples - - Oranges - - - Veggies - - - Zucchini - - Chick Peas - -To this effect, when re-organizing bullet lists, it can be useful to -shift regions of text by indents of two characters. You can use the -``C-c C-r`` and ``C-c C-l`` to shift the current region. These -bindings are similar to the ones provided by python-mode for editing -python code and behave similarly. - - -Major Mode for Editing reStructuredText Documents -================================================= - -There is a major mode available for editing and syntax highlighting -reStructuredText_ constructs. This mode was written by Stefan Merten -[#]_. It mostly provides lazy syntax coloring for many of the -constructs that reStructuredText_ prescribes. - -To enable this mode, type ``M-x rst-mode`` or you can set up an -``auto-mode-alist`` to automatically turn it on whenever you visit -reStructuredText_ documents:: - - (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) ) - -If have local variables enabled (see ``enable-local-variables`` in the -Emacs manual), you can also add the following at the top of your -documents to trigger rst-mode:: - - .. -*- mode: rst -*- - -Or add this at the end of your documents:: - - .. - Local Variables: - mode: rst - End: - -By default, the font-lock colouring is performed lazily. If you don't -like this, you can turn this off by setting the value of -``rst-mode-lazy``. You can also change the various colours (see the -source file for the whole list of customizable faces). - -.. [#] This mode used to be provided by the file ``rst-mode.el`` and - has now been integrated with the rest of the emacs code. - - -Converting Documents from Emacs -=============================== - -At the moment there is minimal support for calling the conversion -tools from within Emacs. You can add a key binding like this to -invoke it:: - - (local-set-key [(control c)(?9)] 'rst-compile) - -This function basically creates a compilation command with the correct -output name for the current buffer and then invokes Emacs' compile -function. It also looks for the presence of a ``docutils.conf`` -configuration file in the parent directories and adds it to the -cmdline options. You can customize which tool is used to perform the -conversion and some standard options to always be added as well. - -Invocation uses the toolset indicated by -``rst-compile-primary-toolset`` (default is ``'html``). Invocation -with a prefix argument uses ``rst-compile-secondary-toolset`` (default -is ``'latex``). - -.. note:: - - In general it is preferred to use a Makefile to automate the - conversion of many documents or a hierarchy of documents. The - functionality presented above is meant to be convenient for use on - single files. - - -Other / External Useful Emacs Settings -====================================== - -This section covers general emacs text-mode settings that are useful -in the context of reStructuredText_ conventions. These are not -provided by ``rst.el`` but you may find them useful specifically for -reStructuredText_ documents. - - -Settings for Filling Lists --------------------------- - -One problem with the default text-mode settings is that *filling* long -lines in bullet and enumerated lists that do not have an empty line -between them merges them together, e.g.:: - - - Bananas; - - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay; - - Oranges; - -Becomes:: - - - Bananas; One Apple a day keeps the doctor away, and eating more - - keeps the pirates at bay; Oranges; - -This is usually not what you want. What you want is this:: - - - Bananas; - - One Apple a day keeps the doctor away, and eating more keeps - the pirates at bay; - - Oranges; - -The problem is that emacs does not recognize the various consecutive -items as forming paragraph boundaries. You can fix this easily by -changing the global value of the parapraph boundary detection to -recognize such lists, using the ``rst-set-paragraph-separation`` -function:: - - (add-hook 'text-mode-hook 'rst-set-paragraph-separation) - - -``text-mode`` Settings ----------------------- - -Consult the Emacs manual for more text-mode customizations. In -particular, you may be interested in setting the following variables, -functions and modes that pertain somewhat to text-mode: - -- indent-tabs-mode -- colon-double-space -- auto-fill-mode -- auto-mode-alist -- fill-region - - -Editing Tables: Emacs table mode --------------------------------- - -You may want to check out `Emacs table mode`_ to create an edit -tables, it allows creating ascii tables compatible with -reStructuredText_. - -.. _Emacs table mode: http://table.sourceforge.net/ - - -Character Processing --------------------- - -Since reStructuredText punts on the issue of character processing, -here are some useful resources for Emacs users in the Unicode world: - -* `xmlunicode.el and unichars.el from Norman Walsh - <http://nwalsh.com/emacs/xmlchars/index.html>`__ - -* `An essay by Tim Bray, with example code - <http://www.tbray.org/ongoing/When/200x/2003/09/27/UniEmacs>`__ - -* For Emacs users on Mac OS X, here are some useful useful additions - to your .emacs file. - - - To get direct keyboard input of non-ASCII characters (like - "option-e e" resulting in "é" [eacute]), first enable the option - key by setting the command key as your meta key:: - - (setq mac-command-key-is-meta t) ;; nil for option key - - Next, use one of these lines:: - - (set-keyboard-coding-system 'mac-roman) - (setq mac-keyboard-text-encoding kTextEncodingISOLatin1) - - I prefer the first line, because it enables non-Latin-1 characters - as well (em-dash, curly quotes, etc.). - - - To enable the display of all characters in the Mac-Roman charset, - first create a fontset listing the fonts to use for each range of - characters using charsets that Emacs understands:: - - (create-fontset-from-fontset-spec - "-apple-monaco-medium-r-normal--10-*-*-*-*-*-fontset-monaco, - ascii:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman, - latin-iso8859-1:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman, - mule-unicode-0100-24ff:-apple-monaco-medium-r-normal--10-100-75-75-m-100-mac-roman") - - Latin-1 doesn't cover characters like em-dash and curly quotes, so - "mule-unicode-0100-24ff" is needed. - - Next, use that fontset:: - - (set-frame-font "fontset-monaco") - - - To enable cooperation between the system clipboard and the Emacs - kill ring, add this line:: - - (set-clipboard-coding-system 'mac-roman) - - Other useful resources are in `Andrew Choi's Emacs 21 for Mac OS X - FAQ <http://members.shaw.ca/akochoi-emacs/stories/faq.html>`__. - -No matter what platform (or editor) you're using, I recommend the -ProFont__ programmer's font. It's monospaced, small but readable, -similar characters are visually distinctive (like "I1l|", "0O", "ao", -and ".,:;"), and free. - -__ http://www.tobias-jung.de/seekingprofont/ - - -Credits -======= - -- The automatic section adjustment and table of contents features were - written by Martin Blais; -- ``rst-mode`` and its syntax highlighting was implemented by Stefan - Merten; -- Various other functions were implemented by David Goodger. - - -Obsolete Files -============== - -On 2005-10-30, ``restructuredtext.el``, ``rst-html.el`` and -``rst-mode.el`` were merged to form the new ``rst.el``. You can -consider the old files obsolete and remove them. - - -Future Work -=========== - -Here are some features and ideas that will be worked on in the future, -in those frenzied mornings of excitement over the virtues of the -one-true-way kitchen sink of editors: - -- It would be nice to differentiate between text files using - reStructuredText_ and other general text files. If we had a - function to automatically guess whether a .txt file is following the - reStructuredText_ conventions, we could trigger rst-mode without - having to hard-code this in every text file, nor forcing the user to - add a local mode variable at the top of the file. - - We could perform this guessing by searching for a valid decoration - at the top of the document or searching for reStructuredText_ - directives further on. - -- The suggested decorations when adjusting should not have to cycle - below one below the last section decoration level preceding the - cursor. We need to fix that. - - -.. _Emacs: http://www.gnu.org/software/emacs/emacs.html -.. _reStructuredText: http://docutils.sf.net/rst.html - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/docutils/docs/user/images/big-black.png b/docutils/docs/user/images/big-black.png Binary files differdeleted file mode 100644 index 869a0cf9f..000000000 --- a/docutils/docs/user/images/big-black.png +++ /dev/null diff --git a/docutils/docs/user/images/big-white.png b/docutils/docs/user/images/big-white.png Binary files differdeleted file mode 100644 index 1ce6d7d7d..000000000 --- a/docutils/docs/user/images/big-white.png +++ /dev/null diff --git a/docutils/docs/user/images/default.png b/docutils/docs/user/images/default.png Binary files differdeleted file mode 100644 index 509eeddad..000000000 --- a/docutils/docs/user/images/default.png +++ /dev/null diff --git a/docutils/docs/user/images/happy_monkey.png b/docutils/docs/user/images/happy_monkey.png Binary files differdeleted file mode 100644 index 2164c06dd..000000000 --- a/docutils/docs/user/images/happy_monkey.png +++ /dev/null diff --git a/docutils/docs/user/images/medium-black.png b/docutils/docs/user/images/medium-black.png Binary files differdeleted file mode 100644 index f851e679e..000000000 --- a/docutils/docs/user/images/medium-black.png +++ /dev/null diff --git a/docutils/docs/user/images/medium-white.png b/docutils/docs/user/images/medium-white.png Binary files differdeleted file mode 100644 index e5a465a56..000000000 --- a/docutils/docs/user/images/medium-white.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-all.png b/docutils/docs/user/images/rsp-all.png Binary files differdeleted file mode 100644 index 3e5f5ede3..000000000 --- a/docutils/docs/user/images/rsp-all.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-breaks.png b/docutils/docs/user/images/rsp-breaks.png Binary files differdeleted file mode 100644 index f2a31b098..000000000 --- a/docutils/docs/user/images/rsp-breaks.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-covers.png b/docutils/docs/user/images/rsp-covers.png Binary files differdeleted file mode 100644 index 597c2c2a8..000000000 --- a/docutils/docs/user/images/rsp-covers.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-cuts.png b/docutils/docs/user/images/rsp-cuts.png Binary files differdeleted file mode 100644 index aa46b3876..000000000 --- a/docutils/docs/user/images/rsp-cuts.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-empty.png b/docutils/docs/user/images/rsp-empty.png Binary files differdeleted file mode 100644 index f6b93c38b..000000000 --- a/docutils/docs/user/images/rsp-empty.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp-objects.png b/docutils/docs/user/images/rsp-objects.png Binary files differdeleted file mode 100644 index 43ce276f1..000000000 --- a/docutils/docs/user/images/rsp-objects.png +++ /dev/null diff --git a/docutils/docs/user/images/rsp.svg b/docutils/docs/user/images/rsp.svg deleted file mode 100644 index 03445d3bc..000000000 --- a/docutils/docs/user/images/rsp.svg +++ /dev/null @@ -1,636 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="1224.0000pt" - height="792.00000pt" - id="svg16130" - sodipodi:version="0.32" - inkscape:version="0.42" - sodipodi:docbase="/Users/david/projects/docutils/s5-branch/docs/user/images" - sodipodi:docname="rsp.svg" - inkscape:export-filename="/Users/david/projects/docutils/s5-branch/docs/user/images/rsp-empty.png" - inkscape:export-xdpi="90.000000" - inkscape:export-ydpi="90.000000"> - <defs - id="defs16132"> - <radialGradient - cx="64.960804" - cy="86.732626" - fx="64.394720" - fy="89.843742" - id="radialGradient1157" - r="4.6795605" - xlink:href="#linearGradient1125" - gradientTransform="scale(1.232968,0.811051)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1147" - x1="30.807715" - x2="9.1659926" - xlink:href="#linearGradient1129" - y1="134.41771" - y2="128.61883" - gradientTransform="scale(2.035443,0.491293)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1146" - x1="23.109005" - x2="23.655650" - xlink:href="#linearGradient1129" - y1="86.372661" - y2="75.530011" - gradientTransform="scale(1.564854,0.639037)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1150" - x1="7.1055503" - x2="37.417715" - xlink:href="#linearGradient1152" - y1="148.97907" - y2="149.31015" - gradientTransform="scale(1.328405,0.752782)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1152"> - <stop - id="stop1153" - offset="0.00000000" - style="stop-color:#ffffff;stop-opacity:0.00000000;" /> - <stop - id="stop1155" - offset="0.44302326" - style="stop-color:#ffffff;stop-opacity:0.46274510;" /> - <stop - id="stop1154" - offset="1.0000000" - style="stop-color:#ffffff;stop-opacity:0.00000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1151" - x1="29.180973" - x2="12.077421" - xlink:href="#linearGradient1152" - y1="176.88234" - y2="176.49016" - gradientTransform="scale(1.503932,0.664924)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1135" - x1="5.6004575" - x2="57.337623" - xlink:href="#linearGradient1136" - y1="125.70108" - y2="125.70108" - gradientTransform="scale(1.240748,0.805966)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1129"> - <stop - id="stop1130" - offset="0.00000000" - style="stop-color:#ffffff;stop-opacity:0.00000000;" /> - <stop - id="stop1131" - offset="1.0000000" - style="stop-color:#ffffff;stop-opacity:0.64583331;" /> - </linearGradient> - <linearGradient - id="linearGradient1128" - x1="76.620649" - x2="89.927438" - xlink:href="#linearGradient1129" - y1="79.202017" - y2="132.51965" - gradientTransform="scale(1.342210,0.745040)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1133" - x1="95.959445" - x2="95.959445" - xlink:href="#linearGradient1125" - y1="96.280971" - y2="6.0312801" - gradientTransform="scale(1.356086,0.737416)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1136"> - <stop - id="stop1137" - offset="0.00000000" - style="stop-color:#000000;stop-opacity:1.0000000;" /> - <stop - id="stop1138" - offset="1.0000000" - style="stop-color:#454545;stop-opacity:1.0000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1145" - x1="26.716417" - x2="57.535761" - xlink:href="#linearGradient1136" - y1="72.512797" - y2="104.12337" - gradientTransform="scale(1.435519,0.696612)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1125"> - <stop - id="stop1126" - offset="0.00000000" - style="stop-color:#979797;stop-opacity:1.0000000;" /> - <stop - id="stop1163" - offset="0.35050300" - style="stop-color:#fafafa;stop-opacity:1.0000000;" /> - <stop - id="stop1164" - offset="0.36050299" - style="stop-color:#9f9f9f;stop-opacity:1.0000000;" /> - <stop - id="stop1127" - offset="1.0000000" - style="stop-color:#ffffff;stop-opacity:1.0000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1134" - x1="66.560545" - x2="26.091148" - xlink:href="#linearGradient1125" - y1="135.98955" - y2="85.436682" - gradientTransform="scale(1.892867,0.528299)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - id="linearGradient1243"> - <stop - id="stop1244" - offset="0.00000000" - style="stop-color:#000000;stop-opacity:0.19791667;" /> - <stop - id="stop1245" - offset="1.0000000" - style="stop-color:#000000;stop-opacity:0.00000000;" /> - </linearGradient> - <linearGradient - id="linearGradient1149" - x1="508.22840" - x2="505.28565" - xlink:href="#linearGradient1243" - y1="556.37391" - y2="107.87502" - gradientTransform="scale(1.347706,0.742001)" - gradientUnits="userSpaceOnUse" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16217" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16219" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16221" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - <linearGradient - inkscape:collect="always" - xlink:href="#linearGradient1243" - id="linearGradient16223" - gradientUnits="userSpaceOnUse" - gradientTransform="scale(1.347706,0.742001)" - x1="508.22840" - y1="556.37391" - x2="505.28565" - y2="107.87502" /> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="0.52132701" - inkscape:cx="650.00000" - inkscape:cy="497.00000" - inkscape:document-units="px" - inkscape:current-layer="layer7" - showgrid="true" - inkscape:grid-bbox="false" - inkscape:grid-points="false" - gridspacingx="5.0000000px" - gridspacingy="5.0000000px" - gridtolerance="2.5000000px" - inkscape:window-width="920" - inkscape:window-height="603" - inkscape:window-x="20" - inkscape:window-y="73" /> - <metadata - id="metadata16135"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="base" - inkscape:groupmode="layer" - id="layer1" - style="display:inline"> - <g - id="g17404" - transform="translate(100.0000,-75.00000)" - style="stroke:none;stroke-opacity:1.0000000"> - <rect - ry="38.000000" - rx="38.000000" - style="fill:#ffffff;fill-opacity:0.14999999;stroke:none;stroke-opacity:1.0000000" - id="rrect19" - width="1100.0000" - height="844.00000" - x="0.0000000" - y="146.00000" /> - <rect - ry="36.000000" - rx="36.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect18" - width="1096.0000" - height="840.00000" - x="2.0000000" - y="148.00000" /> - <rect - ry="34.000000" - rx="34.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect17" - width="1092.0000" - height="836.00000" - x="4.0000000" - y="150.00000" /> - <rect - ry="32.000000" - rx="32.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect16" - width="1088.0000" - height="832.00000" - x="6.0000000" - y="152.00000" /> - <rect - ry="30.000000" - rx="30.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect15" - width="1084.0000" - height="828.00000" - x="8.0000000" - y="154.00000" /> - <rect - ry="28.000000" - rx="28.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect14" - width="1080.0000" - height="824.00000" - x="10.000000" - y="156.00000" /> - <rect - ry="26.000000" - rx="26.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect13" - width="1076.0000" - height="820.00000" - x="12.000000" - y="158.00000" /> - <rect - ry="24.000000" - rx="24.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect12" - width="1072.0000" - height="816.00000" - x="14.000000" - y="160.00000" /> - <rect - ry="22.000000" - rx="22.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect11" - width="1068.0000" - height="812.00000" - x="16.000000" - y="162.00000" /> - <rect - ry="20.000000" - rx="20.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect10" - width="1064.0000" - height="808.00000" - x="18.000000" - y="164.00000" /> - <rect - ry="18.000000" - rx="18.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect9" - width="1060.0000" - height="804.00000" - x="20.000000" - y="166.00000" /> - <rect - ry="16.000000" - rx="16.000000" - style="fill:#ffffff;fill-opacity:0.099999972;stroke:none;stroke-opacity:1.0000000" - id="rrect8" - width="1056.0000" - height="800.00000" - x="22.000000" - y="168.00000" /> - <rect - ry="14.000000" - rx="14.000000" - style="fill:#ffffff;fill-opacity:0.11999995;stroke:none;stroke-opacity:1.0000000" - id="rrect7" - width="1052.0000" - height="796.00000" - x="24.000000" - y="170.00000" /> - <rect - ry="12.000000" - rx="12.000000" - style="fill:#ffffff;fill-opacity:0.14000000;stroke:none;stroke-opacity:1.0000000" - id="rrect6" - width="1048.0000" - height="792.00000" - x="26.000000" - y="172.00000" /> - <rect - ry="10.000000" - rx="10.000000" - style="fill:#ffffff;fill-opacity:0.15999998;stroke:none;stroke-opacity:1.0000000" - id="rrect5" - width="1044.0000" - height="788.00000" - x="28.000000" - y="174.00000" /> - <rect - ry="8.0000000" - rx="8.0000000" - style="fill:#ffffff;fill-opacity:0.17999996;stroke:none;stroke-opacity:1.0000000" - id="rrect4" - width="1040.0000" - height="784.00000" - x="30.000000" - y="176.00000" /> - <rect - ry="6.0000000" - rx="6.0000000" - style="fill:#ffffff;fill-opacity:0.20000000;stroke:none;stroke-opacity:1.0000000" - id="rrect3" - width="1036.0000" - height="780.00000" - x="32.000000" - y="178.00000" /> - <rect - ry="4.0000000" - rx="4.0000000" - style="fill:#ffffff;fill-opacity:0.21999998;stroke:none;stroke-opacity:1.0000000" - id="rrect2" - width="1032.0000" - height="776.00000" - x="34.000000" - y="180.00000" /> - <rect - ry="2.0000000" - rx="2.0000000" - style="fill:#ffffff;fill-opacity:0.49999997;stroke:none;stroke-opacity:1.0000000" - id="rrect1" - width="1028.0000" - height="772.00000" - x="36.000000" - y="182.00000" /> - <rect - style="fill:#ffffff;fill-opacity:1.0000000;stroke:none;stroke-width:2.0000000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="rect7529" - width="1024.0000" - height="768.00000" - x="38.000000" - y="184.00000" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer6" - inkscape:label="cuts" - style="display:inline"> - <g - style="display:inline" - id="g17268" - transform="matrix(3.955288,0.000000,0.000000,3.955288,-1133.851,-788.5280)"> - <g - transform="matrix(-1.028194e-2,1.033891e-2,-1.033891e-2,-1.028194e-2,587.3686,366.0048)" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - id="g17126"> - <path - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - sodipodi:nodetypes="ccccc" - id="path17128" - d="M 7602.2995,10592.638 L 6351.2995,11841.638 L 7603.2995,9842.6385 L 8851.2995,11843.638 L 7602.2995,10592.638 z " /> - </g> - <path - id="text17130" - d="M 346.56856,325.28003 C 346.01656,325.52003 345.34456,325.66403 344.48056,325.66403 C 342.70456,325.66403 341.26456,324.51203 341.26456,322.35203 C 341.24056,320.43204 342.48856,319.06403 344.40856,319.06403 C 345.36856,319.06403 346.01656,319.23203 346.44856,319.42403 L 347.02456,316.71203 C 346.25656,316.42403 345.20056,316.25603 344.24056,316.25603 C 339.87256,316.25603 337.52056,319.06404 337.52056,322.49603 C 337.52056,326.19203 339.94456,328.52003 343.73656,328.52003 C 345.12856,328.52003 346.35256,328.28003 347.00056,327.96803 L 346.56856,325.28003 M 360.08468,316.52003 L 356.43668,316.52003 L 356.43668,323.50403 C 356.43668,323.81603 356.38868,324.08003 356.29268,324.29603 C 356.07668,324.87203 355.47668,325.56803 354.46868,325.56803 C 353.17269,325.56803 352.62068,324.53603 352.62068,322.83203 L 352.62068,316.52003 L 348.97268,316.52003 L 348.97268,323.40803 C 348.97268,327.03203 350.70069,328.52003 353.10068,328.52003 C 355.21268,328.52003 356.31669,327.32003 356.77268,326.60003 L 356.84468,326.60003 L 357.01268,328.25603 L 360.18068,328.25603 C 360.13268,327.27204 360.08468,326.02403 360.08468,324.48803 L 360.08468,316.52003 M 363.54031,314.31203 L 363.54031,316.52003 L 361.98031,316.52003 L 361.98031,319.20803 L 363.54031,319.20803 L 363.54031,324.03203 C 363.54031,325.68803 363.87631,326.81603 364.54831,327.51203 C 365.14831,328.11203 366.13231,328.52003 367.30831,328.52003 C 368.31631,328.52003 369.20431,328.37603 369.66031,328.20803 L 369.63631,325.44803 C 369.30031,325.52003 369.06031,325.54403 368.55631,325.54403 C 367.47631,325.54403 367.11631,324.89603 367.11631,323.48003 L 367.11631,319.20803 L 369.73231,319.20803 L 369.73231,316.52003 L 367.11631,316.52003 L 367.11631,313.32803 L 363.54031,314.31203 M 371.17681,327.68003 C 372.06481,328.16003 373.43281,328.52003 374.96881,328.52003 C 378.32881,328.52003 380.03281,326.91203 380.03281,324.70403 C 380.00881,323.00004 379.09681,321.84803 376.86481,321.10403 C 375.42481,320.60003 374.96881,320.31203 374.96881,319.73603 C 374.96881,319.16003 375.47281,318.80003 376.36081,318.80003 C 377.34481,318.80003 378.37681,319.18403 378.90481,319.44803 L 379.52881,316.95203 C 378.80881,316.59203 377.60881,316.25603 376.24081,316.25603 C 373.33681,316.25603 371.46481,317.91204 371.46481,320.12003 C 371.44081,321.48803 372.37681,322.83203 374.82481,323.62403 C 376.16881,324.08003 376.52881,324.36803 376.52881,324.99203 C 376.52881,325.59203 376.07281,325.95203 374.96881,325.95203 C 373.88881,325.95203 372.49681,325.49603 371.82481,325.08803 L 371.17681,327.68003" - style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer5" - inkscape:label="scissors" - style="display:inline"> - <g - style="display:inline" - transform="matrix(-0.261242,0.531875,-0.531875,-0.261243,609.4123,269.4384)" - id="g834"> - <path - transform="matrix(-0.974540,0.224211,0.224211,0.974540,434.7533,-39.90828)" - style="font-size:12.000000px;fill:#dadadb;fill-rule:evenodd;stroke:#000000;stroke-width:10.000006;stroke-linejoin:round;stroke-dasharray:none" - id="path693" - d="M 130.58000,19.228100 C 131.42800,19.228100 283.20600,268.51700 283.20600,268.51700 C 283.20600,268.51700 237.41800,294.80300 238.26600,294.80300 C 239.11400,294.80300 112.77400,100.62900 130.58000,19.228100 z " /> - <path - style="font-size:12.000000px;fill:#1f1f61;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:10.000000;stroke-linejoin:bevel;stroke-dasharray:none" - id="path596" - d="M 267.36640,300.28500 C 267.36640,300.28500 221.96450,419.33820 230.36720,437.01870 C 230.00410,447.80450 196.57070,496.47240 174.95750,496.94460 C 156.32120,498.11630 95.023300,483.45520 104.85110,423.19450 C 116.53670,361.19710 166.80670,382.68650 186.68190,380.35660 C 206.55780,378.02600 240.34010,301.17560 216.89540,284.78780 C 243.06010,291.66780 266.70660,302.06270 267.36640,300.28500 z M 178.01080,388.46270 C 110.22310,370.58330 97.043850,476.92290 157.42350,483.15570 C 225.11850,486.03500 224.54920,396.02940 178.01080,388.46270 z " /> - <path - transform="matrix(0.984591,0.174877,-0.174877,0.984591,41.27270,-35.37063)" - style="font-size:12.000000px;fill:#dadadb;fill-rule:evenodd;stroke:#000000;stroke-width:9.9999933;stroke-linejoin:bevel;stroke-dasharray:none" - id="path674" - d="M 130.58000,19.228100 C 131.42800,19.228100 283.20600,268.51700 283.20600,268.51700 C 283.20600,268.51700 237.41800,294.80300 238.26600,294.80300 C 239.11400,294.80300 112.77400,100.62900 130.58000,19.228100 z " /> - <path - transform="translate(161.5948,57.16911)" - style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none" - sodipodi:nodetypes="ccc" - id="path710" - d="M 81.400500,200.68300 C 66.137900,201.53100 63.594200,225.27300 81.400500,226.12100 C 98.359000,225.27300 98.359200,200.68300 81.400500,200.68300 z " /> - <path - transform="translate(161.5948,57.16911)" - style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none" - id="path711" - d="M 69.529600,209.16300 C 71.225500,209.16300 86.488100,224.42500 86.488100,224.42500" /> - <path - transform="translate(161.5948,57.16911)" - style="font-size:12.000000px;fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:6.2500000;stroke-dasharray:none" - sodipodi:nodetypes="cc" - id="path712" - d="M 76.313000,203.22700 C 77.160900,203.22700 92.423500,218.49000 92.423500,218.49000" /> - <path - style="font-size:12.000000px;fill:#e6ffff;fill-opacity:0.75000000;fill-rule:evenodd;stroke-width:1.0000000pt" - sodipodi:nodetypes="cccc" - id="path717" - d="M 311.59912,21.282200 C 312.44712,21.282200 250.54912,207.82500 250.54912,207.82500 C 250.54912,207.82500 257.17737,220.62188 259.72037,219.77388 C 262.26437,218.92588 318.38312,30.609400 311.59912,21.282200 z " /> - <path - transform="translate(-3.750000,3.750000)" - style="font-size:12.000000px;fill-opacity:0.31851897;fill-rule:evenodd;stroke-width:1.0000000pt" - sodipodi:nodetypes="ccccc" - id="path718" - d="M 236.85900,262.03100 L 240.39000,257.08300 L 256.63200,272.60800 L 252.68100,276.70800 L 236.85900,262.03100 z " /> - <path - style="font-size:12.000000px;fill:#1f1f61;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:10.000000;stroke-linejoin:bevel;stroke-dasharray:none" - id="path590" - d="M 319.25070,379.53570 C 386.05280,358.26700 404.56760,463.80860 344.57810,473.07250 C 277.11370,479.35530 273.15220,389.43500 319.25070,379.53570 z M 225.57020,295.96700 C 225.57020,295.96700 276.90680,412.58430 269.40450,430.66530 C 270.31010,441.41910 306.15060,488.34270 327.76030,487.72650 C 346.43190,487.95870 406.91430,470.23100 394.06590,410.54120 C 379.27480,349.21050 330.15000,373.20280 310.18270,371.87620 C 290.21460,370.54890 252.60710,295.49620 275.19730,277.94910 C 249.41200,286.13730 226.31860,297.70920 225.57020,295.96700 z " /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer4" - inkscape:label="breaks" - style="display:inline"> - <g - style="display:inline" - id="g17263" - transform="matrix(3.955288,0.000000,0.000000,3.955288,-654.3060,-855.6644)"> - <g - transform="matrix(0.000000,1.458120e-2,1.458120e-2,0.000000,167.9907,189.6206)" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - id="g2604"> - <path - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - sodipodi:nodetypes="ccccc" - id="path2606" - d="M 7601.0000,11063.000 L 6350.0000,12312.000 L 7602.0000,10313.000 L 8850.0000,12314.000 L 7601.0000,11063.000 z " /> - </g> - <path - id="text17114" - d="M 299.55643,273.07213 C 299.55643,274.39213 299.50843,275.80813 299.46043,276.57613 L 302.55643,276.57613 L 302.70043,274.94413 L 302.74843,274.94413 C 303.56443,276.33613 304.90843,276.84013 306.27643,276.84013 C 308.96443,276.84013 311.62843,274.72813 311.62843,270.50413 C 311.65243,266.90413 309.61243,264.57613 306.80443,264.57613 C 305.17243,264.57613 303.94843,265.22413 303.25243,266.23213 L 303.20443,266.23213 L 303.20443,259.53613 L 299.55643,259.53613 L 299.55643,273.07213 M 303.20443,269.85613 C 303.20443,269.61613 303.22843,269.40013 303.27643,269.18413 C 303.51643,268.12813 304.42843,267.38413 305.41243,267.38413 C 307.11643,267.38413 307.93243,268.82413 307.93243,270.64813 C 307.93243,272.76013 306.97243,273.96013 305.41243,273.96013 C 304.35643,273.96013 303.51643,273.19213 303.27643,272.23213 C 303.22843,272.04013 303.20443,271.82413 303.20443,271.58413 L 303.20443,269.85613 M 313.90018,276.57613 L 317.54818,276.57613 L 317.54818,270.64813 C 317.54818,270.33613 317.57218,270.07213 317.62018,269.83213 C 317.86018,268.68013 318.77218,267.98413 320.11618,267.98413 C 320.52418,267.98413 320.81218,268.03213 321.12418,268.08013 L 321.12418,264.64813 C 320.86018,264.60013 320.69218,264.57613 320.35618,264.57613 C 319.20418,264.57613 317.78818,265.29613 317.18818,267.02413 L 317.09218,267.02413 L 316.94818,264.84013 L 313.82818,264.84013 C 313.90018,265.84813 313.92418,266.97613 313.92418,268.70413 L 313.90018,276.57613 M 333.40881,271.87213 C 333.45681,271.58413 333.52881,271.03213 333.52881,270.40813 C 333.52881,267.50413 332.08880,264.55213 328.29681,264.55213 C 324.24081,264.55213 322.36881,267.84013 322.36881,270.81613 C 322.36881,274.51213 324.64881,276.81613 328.63281,276.81613 C 330.21681,276.81613 331.68081,276.57613 332.88081,276.07213 L 332.40081,273.60013 C 331.41681,273.93613 330.40881,274.10413 329.16081,274.10413 C 327.45681,274.10413 325.96881,273.38413 325.84881,271.84813 L 333.40881,271.87213 M 325.82481,269.35213 C 325.92081,268.39213 326.54481,266.97613 328.10481,266.97613 C 329.76081,266.97613 330.14481,268.48813 330.14481,269.35213 L 325.82481,269.35213 M 345.46506,269.64013 C 345.46506,266.88013 344.24105,264.57613 340.32906,264.57613 C 338.19306,264.57613 336.58506,265.17613 335.76906,265.63213 L 336.44106,267.96013 C 337.20906,267.50413 338.48106,267.09613 339.68106,267.09613 C 341.48106,267.09613 341.81706,267.98413 341.81706,268.60813 L 341.81706,268.75213 C 337.66506,268.75213 334.92906,270.19213 334.92906,273.24013 C 334.92906,275.11213 336.34506,276.84013 338.72106,276.84013 C 340.11306,276.84013 341.31306,276.33613 342.08106,275.40013 L 342.15306,275.40013 L 342.36906,276.57613 L 345.65706,276.57613 C 345.51306,275.92813 345.46506,274.84813 345.46506,273.74413 L 345.46506,269.64013 M 341.93706,272.30413 C 341.93706,272.52013 341.91306,272.73613 341.86506,272.92813 C 341.62506,273.67213 340.85706,274.27213 339.96906,274.27213 C 339.15306,274.27213 338.52906,273.81613 338.52906,272.88013 C 338.52906,271.48813 340.01706,271.03213 341.93706,271.03213 L 341.93706,272.30413 M 352.00131,259.53613 L 348.35331,259.53613 L 348.35331,276.57613 L 352.00131,276.57613 L 352.00131,272.92813 L 352.91331,271.75213 L 355.76931,276.57613 L 360.25731,276.57613 L 355.45731,269.59213 L 359.65731,264.84013 L 355.26531,264.84013 L 352.88931,268.39213 C 352.60131,268.82413 352.31331,269.30413 352.04931,269.80813 L 352.00131,269.80813 L 352.00131,259.53613 M 360.71256,276.00013 C 361.60056,276.48013 362.96856,276.84013 364.50456,276.84013 C 367.86455,276.84013 369.56856,275.23213 369.56856,273.02413 C 369.54456,271.32013 368.63256,270.16813 366.40056,269.42413 C 364.96056,268.92013 364.50456,268.63213 364.50456,268.05613 C 364.50456,267.48013 365.00856,267.12013 365.89656,267.12013 C 366.88056,267.12013 367.91256,267.50413 368.44056,267.76813 L 369.06456,265.27213 C 368.34456,264.91213 367.14456,264.57613 365.77656,264.57613 C 362.87256,264.57613 361.00056,266.23213 361.00056,268.44013 C 360.97656,269.80813 361.91256,271.15213 364.36056,271.94413 C 365.70456,272.40013 366.06456,272.68813 366.06456,273.31213 C 366.06456,273.91213 365.60856,274.27213 364.50456,274.27213 C 363.42456,274.27213 362.03256,273.81613 361.36056,273.40813 L 360.71256,276.00013" - style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer3" - inkscape:label="rock" - style="display:inline"> - <g - style="display:inline" - transform="matrix(0.708388,0.000000,0.000000,0.708388,768.4189,171.0555)" - id="g2067"> - <path - sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" - id="path10" - d="M 149.15160,130.25073 L 138.01458,125.99417 L 132.85423,131.15452 L 127.69388,137.17493 L 120.81341,144.91545 L 113.07289,154.37609 L 105.33236,163.83673 L 97.591837,173.29738 L 89.851312,183.61808 L 82.970845,194.79883 L 76.090379,205.11953 L 70.069971,215.44023 L 64.909621,224.04082 L 61.469388,232.64140 L 58.889213,240.38192 L 58.889213,246.40233 L 60.609329,250.70262 L 66.629738,257.58309 L 73.510204,263.60350 L 82.110787,269.62391 L 90.711370,275.64431 L 100.17201,280.80466 L 108.77259,285.96501 L 117.37318,291.98542 L 124.25364,296.28571 L 129.41399,300.58601 L 132.85423,304.02624 L 135.43440,306.60641 L 138.01458,308.32653 L 140.59475,310.04665 L 144.03499,311.76676 L 150.05539,314.34694 L 156.93586,316.92711 L 165.53644,319.50729 L 195.63848,318.64723 L 201.65889,318.64723 L 208.53936,318.64723 L 216.27988,319.50729 L 224.02041,320.36735 L 230.90087,321.22741 L 236.06122,323.80758 L 241.22157,325.52770 L 248.10204,325.52770 L 254.98251,325.52770 L 261.86297,324.66764 L 268.74344,322.94752 L 275.62391,321.22741 L 281.64431,318.64723 L 286.80466,316.92711 L 291.10496,314.34694 L 295.40525,310.90671 L 298.84548,306.60641 L 303.14577,302.30612 L 306.58601,298.00583 L 310.02624,293.70554 L 312.60641,291.12536 L 315.18659,290.26531 L 318.62682,290.26531 L 322.92711,289.40525 L 328.94752,287.68513 L 334.96793,285.10496 L 340.98834,283.38484 L 346.14869,280.80466 L 349.58892,279.08455 L 351.30904,277.36443 L 356.78718,268.76385 L 364.48397,254.32361 L 363.12536,245.36152 L 359.04956,237.80175 L 362.48980,236.94169 L 365.93003,234.36152 L 368.51020,230.92128 L 371.09038,225.76093 L 373.67055,221.46064 L 375.39067,218.02041 L 376.25073,215.44023 L 377.11079,214.58017 L 365.93003,182.75802 L 364.20991,181.03790 L 361.62974,176.73761 L 357.32945,171.57726 L 352.16910,164.69679 L 347.00875,158.67638 L 342.70845,153.51603 L 333.79008,153.06414 L 329.62682,149.89505 L 322.92711,148.35569 L 320.03207,145.27697 L 315.64140,143.64723 L 312.97085,142.01749 L 308.94169,139.52769 L 304.14285,137.62682 L 299.34403,135.63557 L 295.22449,130.56560 L 290.24490,127.71429 L 286.80466,123.41399 L 284.22449,119.97376 L 282.50437,117.39359 L 281.64431,116.53353 L 239.50146,101.91254 L 238.64140,101.91254 L 236.06122,101.05248 L 231.76093,100.19242 L 227.46064,99.332362 L 222.30029,98.472303 L 218.00000,98.472303 L 213.69971,98.472303 L 211.11953,98.472303 L 181.51020,124.82216 L 149.15160,130.25073 z " - style="fill:#b5abab;fill-opacity:1.0000000" /> - <path - sodipodi:nodetypes="cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" - id="path1333" - d="M 272.27930,110.03646 L 278.00000,110.00000 L 281.00000,109.00000 L 285.00000,109.00000 L 288.00000,109.00000 L 290.00000,113.00000 L 293.00000,116.00000 L 295.00000,119.00000 L 298.00000,123.00000 L 300.00000,126.00000 L 302.00000,130.00000 L 303.00000,134.00000 L 303.00000,138.00000 L 302.00000,139.00000 L 302.00000,139.00000 L 301.00000,140.00000 L 301.00000,140.00000 L 297.00000,137.00000 L 293.00000,135.00000 L 290.00000,132.00000 L 287.00000,129.00000 L 284.00000,128.00000 L 280.00000,127.00000 L 277.00000,126.00000 L 273.00000,126.00000 L 270.00000,125.00000 L 266.00000,125.00000 L 262.00000,125.00000 L 259.00000,125.00000 L 254.00000,122.00000 L 249.00000,119.00000 L 245.00000,116.00000 L 240.00000,112.00000 L 235.00000,110.00000 L 230.00000,108.00000 L 225.00000,109.00000 L 219.00000,111.00000 L 214.00000,113.00000 L 209.00000,116.00000 L 204.00000,119.00000 L 199.00000,122.00000 L 194.00000,125.00000 L 190.00000,129.00000 L 186.00000,134.00000 L 183.00000,139.00000 L 177.00000,141.00000 L 171.00000,143.00000 L 164.00000,143.00000 L 157.00000,143.00000 L 150.00000,144.00000 L 143.00000,145.00000 L 137.00000,147.00000 L 131.00000,151.00000 L 129.00000,153.00000 L 127.00000,155.00000 L 125.00000,158.00000 L 124.00000,161.00000 L 117.00000,167.00000 L 111.00000,174.00000 L 106.00000,181.00000 L 101.00000,188.00000 L 96.000000,195.00000 L 92.000000,203.00000 L 87.000000,211.00000 L 81.000000,218.00000 L 78.000000,225.00000 L 74.000000,231.00000 L 70.000000,238.00000 L 69.000000,246.00000 L 74.000000,250.00000 L 79.000000,254.00000 L 83.000000,259.00000 L 88.000000,263.00000 L 93.000000,267.00000 L 97.000000,272.00000 L 102.00000,276.00000 L 107.00000,280.00000 L 111.00000,284.00000 L 116.00000,287.00000 L 121.00000,291.00000 L 126.00000,294.00000 L 132.00000,296.00000 L 138.00000,299.00000 L 144.00000,301.00000 L 150.00000,302.00000 L 155.00000,302.00000 L 159.00000,302.00000 L 164.00000,302.00000 L 168.00000,302.00000 L 172.00000,302.00000 L 176.00000,301.00000 L 180.00000,300.00000 L 184.00000,297.00000 L 188.00000,296.00000 L 191.00000,296.00000 L 193.00000,297.00000 L 196.00000,300.00000 L 198.00000,302.00000 L 201.00000,304.00000 L 204.00000,306.00000 L 207.00000,306.00000 L 211.00000,308.00000 L 214.00000,309.00000 L 218.00000,310.00000 L 222.00000,311.00000 L 226.00000,312.00000 L 230.00000,312.00000 L 233.00000,313.00000 L 237.00000,314.00000 L 240.00000,314.00000 L 244.00000,314.00000 L 246.00000,314.00000 L 249.00000,313.00000 L 252.00000,312.00000 L 255.00000,311.00000 L 258.00000,311.00000 L 261.00000,311.00000 L 267.00000,308.00000 L 273.00000,305.00000 L 279.00000,301.00000 L 285.00000,296.00000 L 290.00000,291.00000 L 296.00000,287.00000 L 302.00000,282.00000 L 308.00000,278.00000 L 312.00000,277.00000 L 316.00000,276.00000 L 321.00000,276.00000 L 325.00000,275.00000 L 329.00000,275.00000 L 334.00000,275.00000 L 338.00000,274.00000 L 343.00000,274.00000 L 344.00000,272.00000 L 346.00000,270.00000 L 349.00000,268.00000 L 351.00000,265.00000 L 354.00000,263.00000 L 356.00000,259.00000 L 357.00000,256.00000 L 359.00000,253.00000 L 357.00000,248.00000 L 355.00000,244.00000 L 353.00000,239.00000 L 352.00000,234.00000 L 355.00000,231.00000 L 359.00000,228.00000 L 363.00000,226.00000 L 366.00000,222.00000 L 363.00000,217.00000 L 359.00000,212.00000 L 355.00000,206.00000 L 354.00000,200.00000 L 356.00000,192.00000 L 358.00000,183.00000 L 358.00000,175.00000 L 354.00000,167.00000 L 352.00000,165.00000 L 349.00000,163.00000 L 347.00000,161.00000 L 344.00000,160.00000 L 341.00000,159.00000 L 338.00000,158.00000 L 335.00000,158.00000 L 332.00000,158.00000 L 330.00000,156.00000 L 328.00000,154.00000 L 327.00000,153.00000 L 327.00000,150.00000 L 329.00000,149.00000 L 335.00000,150.00000 L 342.00000,151.00000 L 349.00000,152.00000 L 355.00000,154.00000 L 361.00000,156.00000 L 367.00000,160.00000 L 371.00000,164.00000 L 374.00000,171.00000 L 374.00000,178.00000 L 373.00000,186.00000 L 372.00000,193.00000 L 375.00000,200.00000 L 379.00000,204.00000 L 382.00000,208.00000 L 386.00000,212.00000 L 388.00000,216.00000 L 389.00000,216.00000 L 389.00000,217.00000 L 389.00000,218.00000 L 389.00000,219.00000 L 389.00000,219.00000 L 391.00000,219.00000 L 391.00000,224.00000 L 390.00000,227.00000 L 388.00000,230.00000 L 385.00000,233.00000 L 382.00000,235.00000 L 378.00000,238.00000 L 375.00000,240.00000 L 373.00000,243.00000 L 372.00000,249.00000 L 372.00000,254.00000 L 370.00000,259.00000 L 367.00000,264.00000 L 365.00000,269.00000 L 362.00000,274.00000 L 358.00000,279.00000 L 353.00000,283.00000 L 348.00000,286.00000 L 343.00000,289.00000 L 338.00000,292.00000 L 332.00000,293.00000 L 328.00000,293.00000 L 325.00000,294.00000 L 321.00000,296.00000 L 319.00000,298.00000 L 317.00000,302.00000 L 315.00000,305.00000 L 313.00000,308.00000 L 311.00000,312.00000 L 308.00000,315.00000 L 306.00000,318.00000 L 302.00000,321.00000 L 299.00000,322.00000 L 295.00000,324.00000 L 291.00000,325.00000 L 288.00000,327.00000 L 284.00000,329.00000 L 276.00000,330.00000 L 267.00000,332.00000 L 259.00000,333.00000 L 250.00000,333.00000 L 242.00000,333.00000 L 233.00000,333.00000 L 225.00000,332.00000 L 217.00000,329.00000 L 212.00000,328.00000 L 207.00000,327.00000 L 202.00000,325.00000 L 197.00000,324.00000 L 192.00000,323.00000 L 187.00000,323.00000 L 182.00000,324.00000 L 178.00000,326.00000 L 168.00000,325.00000 L 158.00000,322.00000 L 149.00000,317.00000 L 140.00000,312.00000 L 131.00000,306.00000 L 123.00000,301.00000 L 115.00000,295.00000 L 108.00000,291.00000 L 105.00000,289.00000 L 102.00000,286.00000 L 98.000000,284.00000 L 94.000000,283.00000 L 90.000000,281.00000 L 86.000000,279.00000 L 83.000000,277.00000 L 79.000000,275.00000 L 75.000000,272.00000 L 71.000000,269.00000 L 66.000000,266.00000 L 62.000000,263.00000 L 58.000000,260.00000 L 54.000000,256.00000 L 51.000000,251.00000 L 49.000000,247.00000 L 51.000000,238.00000 L 54.000000,229.00000 L 58.000000,221.00000 L 63.000000,213.00000 L 85.000000,179.00000 L 89.000000,173.00000 L 94.000000,167.00000 L 99.000000,162.00000 L 104.00000,156.00000 L 108.00000,151.00000 L 113.00000,146.00000 L 117.00000,141.00000 L 121.00000,135.00000 L 125.00000,132.00000 L 128.00000,129.00000 L 132.00000,126.00000 L 135.00000,123.00000 L 139.00000,121.00000 L 143.00000,119.00000 L 148.00000,118.00000 L 152.00000,117.00000 L 157.00000,117.00000 L 162.00000,117.00000 L 167.00000,117.00000 L 172.00000,117.00000 L 176.00000,117.00000 L 181.00000,115.00000 L 185.00000,113.00000 L 189.00000,110.00000 L 192.00000,107.00000 L 196.00000,105.00000 L 200.00000,102.00000 L 203.00000,99.000000 L 207.00000,96.000000 L 210.00000,94.000000 L 214.00000,92.000000 L 219.00000,91.000000 L 221.00000,89.000000 L 223.00000,88.000000 L 227.00000,89.000000 L 230.00000,89.000000 L 234.00000,89.000000 L 237.00000,91.000000 L 241.00000,92.000000 L 244.00000,95.000000 L 247.00000,97.000000 L 250.00000,100.00000 L 253.00000,103.00000 L 257.03646,105.51823 L 262.08918,108.23892" - style="fill:#000000" /> - <path - sodipodi:nodetypes="ccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" - style="fill:#645858;fill-opacity:1.0000000" - d="M 289.76968,176.61808 L 294.76968,177.61808 L 298.76968,178.61808 L 303.76968,179.61808 L 308.76968,180.61808 L 312.76968,182.61808 L 316.76968,184.61808 L 320.76968,186.61808 L 322.88387,187.07485 L 323.76968,189.55120 L 325.24603,192.02754 L 322.76968,193.61808 L 320.88387,193.01571 L 319.76968,193.61808 L 316.76968,193.61808 L 313.58860,194.38970 L 311.00000,195.69680 L 307.54519,197.77551 L 303.00583,200.85423 L 298.46647,201.08455 L 293.92711,197.23616 L 287.84840,196.69680 L 283.30904,197.46648 L 279.53936,196.46648 L 275.76968,193.69680 L 269.32070,193.78135 L 264.55102,194.01167 L 259.78134,194.70263 L 256.55102,193.85423 L 252.62974,193.46648 L 245.24198,195.69680 L 240.70262,196.38776 L 235.62391,196.84840 L 230.31487,199.61808 L 225.77551,203.69680 L 218.92711,207.23616 L 213.16327,211.85423 L 206.31487,213.16327 L 201.23615,211.93295 L 193.84840,210.70263 L 187.99806,205.86607 L 181.57290,203.02154 L 174.66149,202.84239 L 166.45481,204.08455 L 159.37609,206.62391 L 151.06495,208.38970 L 147.76968,206.79916 L 144.29333,204.91335 L 142.58860,202.02754 L 141.58860,199.14173 L 142.47441,196.07485 L 146.76968,196.61808 L 151.76968,194.61808 L 156.76968,191.61808 L 161.76968,189.61808 L 165.76968,187.61808 L 170.76968,185.61808 L 175.76968,182.61808 L 180.76968,180.61808 L 183.76968,180.61808 L 187.76968,179.61808 L 190.76968,180.61808 L 193.76968,181.61808 L 196.76968,182.61808 L 198.76968,183.61808 L 201.76968,185.61808 L 204.76968,188.61808 L 208.76968,187.61808 L 212.76968,184.61808 L 215.76968,180.61808 L 217.76968,176.61808 L 221.76968,174.61808 L 225.76968,172.61808 L 229.76968,169.61808 L 233.76968,167.61808 L 237.76968,165.61808 L 242.76968,163.61808 L 246.76968,161.61808 L 250.76968,159.61808 L 256.76968,160.61808 L 261.76968,162.61808 L 265.76968,165.61808 L 269.76968,169.61808 L 274.76968,173.61808 L 278.76968,175.61808 L 283.76968,177.61808 L 289.76968,176.61808 z " - id="path2065" /> - <path - id="path16" - d="M 289.00000,172.00000 L 294.00000,173.00000 L 298.00000,174.00000 L 303.00000,175.00000 L 308.00000,176.00000 L 312.00000,178.00000 L 316.00000,180.00000 L 320.00000,182.00000 L 323.00000,186.00000 L 323.00000,187.00000 L 323.00000,188.00000 L 322.00000,189.00000 L 321.00000,190.00000 L 319.00000,189.00000 L 316.00000,189.00000 L 314.00000,188.00000 L 311.00000,188.00000 L 308.00000,188.00000 L 305.00000,188.00000 L 303.00000,188.00000 L 300.00000,188.00000 L 296.00000,187.00000 L 293.00000,187.00000 L 290.00000,188.00000 L 287.00000,188.00000 L 284.00000,189.00000 L 281.00000,189.00000 L 278.00000,188.00000 L 275.00000,186.00000 L 272.00000,184.00000 L 268.00000,181.00000 L 264.00000,178.00000 L 260.00000,176.00000 L 256.00000,174.00000 L 252.00000,173.00000 L 247.00000,173.00000 L 243.00000,174.00000 L 239.00000,177.00000 L 235.00000,180.00000 L 232.00000,183.00000 L 229.00000,186.00000 L 228.00000,185.00000 L 226.00000,188.00000 L 223.00000,191.00000 L 221.00000,193.00000 L 218.00000,195.00000 L 215.00000,196.00000 L 212.00000,198.00000 L 210.00000,200.00000 L 207.00000,202.00000 L 204.00000,201.00000 L 202.00000,200.00000 L 199.00000,200.00000 L 197.00000,198.00000 L 194.00000,197.00000 L 192.00000,195.00000 L 190.00000,193.00000 L 189.00000,191.00000 L 185.00000,190.00000 L 182.00000,190.00000 L 178.00000,191.00000 L 174.00000,192.00000 L 150.00000,202.00000 L 147.00000,201.00000 L 145.00000,200.00000 L 143.00000,198.00000 L 142.00000,196.00000 L 142.00000,195.00000 L 146.00000,192.00000 L 151.00000,190.00000 L 156.00000,187.00000 L 161.00000,185.00000 L 165.00000,183.00000 L 170.00000,181.00000 L 175.00000,178.00000 L 180.00000,176.00000 L 183.00000,176.00000 L 187.00000,175.00000 L 190.00000,176.00000 L 193.00000,177.00000 L 196.00000,178.00000 L 198.00000,179.00000 L 201.00000,181.00000 L 204.00000,184.00000 L 208.00000,183.00000 L 212.00000,180.00000 L 215.00000,176.00000 L 217.00000,172.00000 L 221.00000,170.00000 L 225.00000,168.00000 L 229.00000,165.00000 L 233.00000,163.00000 L 237.00000,161.00000 L 242.00000,159.00000 L 246.00000,157.00000 L 250.00000,155.00000 L 256.00000,156.00000 L 261.00000,158.00000 L 265.00000,161.00000 L 269.00000,165.00000 L 274.00000,169.00000 L 278.00000,171.00000 L 283.00000,173.00000 L 289.00000,172.00000 z " - style="fill:#000000" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer8" - inkscape:label="covers" - style="display:inline"> - <g - id="g17273" - transform="matrix(3.955288,0.000000,0.000000,3.955288,155.1671,-915.1278)"> - <g - id="g17118" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" - transform="matrix(1.274278e-2,7.087528e-3,-7.087528e-3,1.274278e-2,147.7444,148.5166)"> - <path - d="M 7601.0000,11063.000 L 6350.0000,12312.000 L 7602.0000,10313.000 L 8850.0000,12314.000 L 7601.0000,11063.000 z " - id="path17120" - sodipodi:nodetypes="ccccc" - style="fill:#00ff00;fill-opacity:1.0000000;stroke:#000000;stroke-width:47.034168;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000" /> - </g> - <path - id="text17122" - d="M 187.95573,356.23294 C 187.40374,356.47294 186.73173,356.61694 185.86773,356.61694 C 184.09174,356.61694 182.65173,355.46494 182.65173,353.30494 C 182.62773,351.38494 183.87574,350.01694 185.79573,350.01694 C 186.75573,350.01694 187.40374,350.18494 187.83573,350.37694 L 188.41173,347.66494 C 187.64374,347.37694 186.58773,347.20894 185.62773,347.20894 C 181.25974,347.20894 178.90773,350.01694 178.90773,353.44894 C 178.90773,357.14493 181.33174,359.47294 185.12373,359.47294 C 186.51573,359.47294 187.73974,359.23294 188.38773,358.92094 L 187.95573,356.23294 M 195.83186,359.47294 C 198.95186,359.47294 201.99986,357.50493 201.99986,353.23294 C 201.99986,349.68094 199.59986,347.20894 196.02386,347.20894 C 192.23186,347.20894 189.73586,349.63294 189.73586,353.42494 C 189.73586,357.21693 192.37586,359.47294 195.80786,359.47294 L 195.83186,359.47294 M 195.85586,356.85694 C 194.31986,356.85694 193.47986,355.34494 193.47986,353.35294 C 193.47986,351.60094 194.15186,349.82494 195.87986,349.82494 C 197.53586,349.82494 198.20786,351.60094 198.20786,353.32894 C 198.20786,355.44094 197.31986,356.85694 195.87986,356.85694 L 195.85586,356.85694 M 202.98798,347.47294 L 207.25998,359.20894 L 210.90798,359.20894 L 215.27598,347.47294 L 211.43598,347.47294 L 209.92398,352.92094 C 209.65999,353.92894 209.46798,354.81694 209.27598,355.77694 L 209.20398,355.77694 C 209.01199,354.84094 208.81998,353.90494 208.53198,352.92094 L 206.94798,347.47294 L 202.98798,347.47294 M 227.30711,354.50494 C 227.35511,354.21694 227.42711,353.66494 227.42711,353.04094 C 227.42711,350.13694 225.98711,347.18494 222.19511,347.18494 C 218.13911,347.18494 216.26711,350.47294 216.26711,353.44894 C 216.26711,357.14493 218.54711,359.44894 222.53111,359.44894 C 224.11511,359.44894 225.57911,359.20894 226.77911,358.70494 L 226.29911,356.23294 C 225.31511,356.56894 224.30711,356.73694 223.05911,356.73694 C 221.35511,356.73694 219.86711,356.01694 219.74711,354.48094 L 227.30711,354.50494 M 219.72311,351.98494 C 219.81911,351.02494 220.44311,349.60894 222.00311,349.60894 C 223.65911,349.60894 224.04311,351.12094 224.04311,351.98494 L 219.72311,351.98494 M 229.59536,359.20894 L 233.24336,359.20894 L 233.24336,353.28094 C 233.24336,352.96894 233.26736,352.70494 233.31536,352.46494 C 233.55536,351.31294 234.46736,350.61694 235.81136,350.61694 C 236.21936,350.61694 236.50736,350.66494 236.81936,350.71294 L 236.81936,347.28094 C 236.55536,347.23294 236.38736,347.20894 236.05136,347.20894 C 234.89936,347.20894 233.48336,347.92894 232.88336,349.65694 L 232.78736,349.65694 L 232.64336,347.47294 L 229.52336,347.47294 C 229.59536,348.48094 229.61936,349.60894 229.61936,351.33694 L 229.59536,359.20894 M 238.06398,358.63294 C 238.95198,359.11294 240.31999,359.47294 241.85598,359.47294 C 245.21598,359.47294 246.91998,357.86494 246.91998,355.65694 C 246.89598,353.95294 245.98398,352.80094 243.75198,352.05694 C 242.31199,351.55294 241.85598,351.26494 241.85598,350.68894 C 241.85598,350.11294 242.35999,349.75294 243.24798,349.75294 C 244.23198,349.75294 245.26399,350.13694 245.79198,350.40094 L 246.41598,347.90494 C 245.69599,347.54494 244.49598,347.20894 243.12798,347.20894 C 240.22399,347.20894 238.35198,348.86494 238.35198,351.07294 C 238.32798,352.44094 239.26399,353.78494 241.71198,354.57694 C 243.05598,355.03294 243.41598,355.32094 243.41598,355.94494 C 243.41598,356.54494 242.95998,356.90494 241.85598,356.90494 C 240.77599,356.90494 239.38398,356.44894 238.71198,356.04094 L 238.06398,358.63294" - style="font-size:24.000000px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:125.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#007f00;fill-opacity:1.0000000;stroke:none;stroke-width:1.0000000pt;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000;font-family:Myriad" /> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer7" - inkscape:label="paper" - style="display:inline"> - <g - style="display:inline" - id="g17136" - transform="matrix(3.955288,0.000000,0.000000,3.955288,-708.3488,-857.6103)"> - <path - sodipodi:nodetypes="cccccccc" - d="M 390.34708,372.49332 L 332.34539,427.86139 L 272.20460,392.33038 L 341.37790,339.74173 L 378.06120,351.10999 C 379.20468,351.78631 380.06344,352.64698 380.62363,353.61296 L 390.84522,371.30530 C 391.02046,371.60027 390.83244,372.00903 390.34708,372.49332 z " - style="fill:#ffff19;fill-opacity:1.0000000;stroke:#000000;stroke-width:1.6000000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12105" /> - <path - id="path12107" - style="fill:#bebe12;fill-opacity:1.0000000;stroke:#000000;stroke-width:1.6000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 390.84798,371.31968 C 390.67230,371.01421 390.16897,370.87309 389.44281,370.86931 L 380.40026,370.92353 L 380.40026,370.92353 L 381.40039,356.76032 C 381.45531,355.66353 381.19370,354.58394 380.62363,353.61296 L 390.84798,371.31968 z " - sodipodi:nodetypes="ccccccc" /> - </g> - </g> -</svg> diff --git a/docutils/docs/user/images/s5-files.png b/docutils/docs/user/images/s5-files.png Binary files differdeleted file mode 100644 index 53cbbf250..000000000 --- a/docutils/docs/user/images/s5-files.png +++ /dev/null diff --git a/docutils/docs/user/images/s5-files.svg b/docutils/docs/user/images/s5-files.svg deleted file mode 100644 index a3e644a22..000000000 --- a/docutils/docs/user/images/s5-files.svg +++ /dev/null @@ -1,639 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="595.27559pt" - height="841.88976pt" - id="svg5904" - sodipodi:version="0.32" - inkscape:version="0.42" - sodipodi:docbase="/Users/david/projects/docutils/s5-branch/docs/user/images" - sodipodi:docname="s5-files.svg" - inkscape:export-filename="/Users/david/projects/docutils/s5-branch/docs/user/images/s5-files.png" - inkscape:export-xdpi="100.00000" - inkscape:export-ydpi="100.00000"> - <defs - id="defs5906"> - <marker - inkscape:stockid="Arrow1Mstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="ccccc" - id="path10526" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.4)" /> - </marker> - <marker - inkscape:stockid="Arrow1Lstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Lstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="ccccc" - id="path10529" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" - transform="scale(0.8)" /> - </marker> - <marker - inkscape:stockid="Arrow2Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Mend" - style="overflow:visible;"> - <path - sodipodi:nodetypes="cccc" - id="path10518" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(0.6) rotate(180) translate(-5,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Mstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Mstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="cccc" - id="path10509" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(0.6) translate(-5,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Lend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Lend" - style="overflow:visible;"> - <path - sodipodi:nodetypes="cccc" - id="path10521" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(1.1) rotate(180) translate(-5,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Lstart" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Lstart" - style="overflow:visible"> - <path - sodipodi:nodetypes="cccc" - id="path10512" - style="font-size:12.0;fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(1.1) translate(-5,0)" /> - </marker> - </defs> - <sodipodi:namedview - id="base" - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1.0" - inkscape:pageopacity="0.0" - inkscape:pageshadow="2" - inkscape:zoom="1.0050485" - inkscape:cx="359.99999" - inkscape:cy="345.00000" - inkscape:document-units="px" - inkscape:current-layer="layer1" - inkscape:window-width="1161" - inkscape:window-height="810" - inkscape:window-x="51" - inkscape:window-y="22" - showgrid="true" - inkscape:grid-bbox="true" - inkscape:grid-points="true" - gridspacingx="5.0000000px" - gridspacingy="5.0000000px" - gridtolerance="2.0000000px" /> - <metadata - id="metadata5909"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - </cc:Work> - </rdf:RDF> - </metadata> - <g - inkscape:label="Layer 1" - inkscape:groupmode="layer" - id="layer1" - style="display:inline"> - <g - id="g15792"> - <g - transform="translate(-5.000000,-55.00000)" - id="g13828" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <g - id="g13761" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <path - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" - d="M 451.84175,542.36220 L 490.47866,542.36220" - id="path13719" /> - <path - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" - d="M 515.00000,597.36220 L 491.83836,597.36220" - id="path13721" /> - <path - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" - d="M 515.00000,487.36218 L 491.83836,487.36218" - id="path13723" /> - <path - id="path13725" - d="M 491.83836,487.36218 L 491.83836,597.36220 L 491.83836,707.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13757" - d="M 515.00000,707.36218 L 491.83836,707.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - </g> - <g - id="g13695" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <path - id="path10755" - d="M 451.84175,982.36220 L 490.47866,982.36220" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13691" - d="M 515.00000,1037.3622 L 491.83836,1037.3622" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13689" - d="M 515.00000,927.36218 L 491.83836,927.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13687" - d="M 491.83836,1037.3622 L 491.83836,927.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - </g> - <g - id="g13174" - style="stroke:#000000;stroke-opacity:1.0000000;stroke-linejoin:round;stroke-linecap:round"> - <path - id="path9672" - d="M 205.00000,762.36217 L 275.47323,762.36217" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13150" - d="M 325.12023,762.36218 L 276.91055,762.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13148" - d="M 325.12023,872.36218 L 276.91055,872.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13146" - d="M 325.12023,982.36218 L 276.91055,982.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13156" - d="M 325.12023,542.36218 L 276.91055,542.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13154" - d="M 276.91055,982.36218 L 276.91055,542.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:none;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - <path - id="path13144" - d="M 325.12023,652.36218 L 276.91055,652.36218" - style="fill:none;fill-opacity:0.75000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4.0000000;stroke-opacity:1.0000000" /> - </g> - </g> - <g - transform="translate(-5.000000,-55.00000)" - id="g13805" - style="stroke:#000000;stroke-opacity:1.0000000"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13533" - transform="translate(-160.0000,215.0000)"> - <g - id="g13262" - transform="translate(522.7639,-102.4046)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path13264" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path13266" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9098" - y="266.27817" - x="748.73212" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="266.27817" - x="748.73212" - id="tspan9100" - sodipodi:role="line">s5-core</tspan><tspan - id="tspan9102" - y="290.27818" - x="748.73212" - sodipodi:role="line">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13541" - transform="translate(-160.0000,215.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(522.7639,7.595400)" - id="g13276"> - <path - id="path13278" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path13280" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9104" - y="377.05817" - x="749.49524" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="377.05817" - x="749.49524" - id="tspan9106" - sodipodi:role="line">framing</tspan><tspan - id="tspan9108" - y="401.05818" - x="749.49524" - sodipodi:role="line">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13549" - transform="translate(-160.0000,215.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(522.7639,117.5954)" - id="g13290"> - <path - id="path13292" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path13294" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - transform="scale(1.075185,0.930073)" - sodipodi:linespacing="100.00000%" - id="text9110" - y="522.89044" - x="696.86365" - style="font-size:25.804459px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="522.89044" - x="696.86365" - id="tspan9112" - sodipodi:role="line">pretty</tspan><tspan - id="tspan9114" - y="548.69490" - x="696.86365" - sodipodi:role="line">.css</tspan></text> - </g> - </g> - <g - transform="translate(-5.000000,-55.00000)" - id="g13701" - style="stroke:#000000;stroke-opacity:1.0000000"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13617" - transform="translate(-150.0000,240.0000)"> - <g - id="g13322" - transform="translate(512.7639,312.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path13324" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path13326" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9122" - y="682.05817" - x="740.27032" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="682.05817" - x="740.27033" - id="tspan9124" - sodipodi:role="line">iepngfix</tspan><tspan - id="tspan9126" - y="706.05818" - x="740.27032" - sodipodi:role="line">.htc</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13609" - transform="translate(-150.0000,240.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(512.7639,422.5954)" - id="g13336"> - <path - id="path13338" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path13340" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9116" - y="790.57019" - x="739.14758" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="790.57019" - x="739.14758" - id="tspan9118" - sodipodi:role="line">blank</tspan><tspan - id="tspan9120" - y="814.57020" - x="739.14758" - sodipodi:role="line">.gif</tspan></text> - </g> - </g> - <g - transform="translate(-5.000000,-55.00000)" - id="g13768" - style="stroke:#000000;stroke-opacity:1.0000000"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g12998" - transform="translate(140.0000,160.0000)"> - <g - id="g12960" - transform="translate(32.76392,117.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12962" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path12964" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9080" - y="486.96219" - x="259.42813" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="486.96219" - x="259.42813" - id="tspan9082" - sodipodi:role="line">outline</tspan><tspan - id="tspan9084" - y="510.96220" - x="259.42813" - sodipodi:role="line">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13006" - transform="translate(140.0000,160.0000)"> - <g - id="g12972" - transform="translate(32.76392,227.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12974" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path12976" /> - </g> - <text - xml:space="preserve" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - x="259.34225" - y="596.96216" - id="text9284" - sodipodi:linespacing="100.00000%"><tspan - sodipodi:role="line" - id="tspan9290" - x="259.34226" - y="596.96216">print</tspan><tspan - sodipodi:role="line" - id="tspan9292" - x="259.34225" - y="620.96217">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13014" - transform="translate(140.0000,160.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(32.76392,337.5954)" - id="g12978"> - <path - id="path12980" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path12982" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - xml:space="preserve" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - x="259.56012" - y="706.32617" - id="text12043" - sodipodi:linespacing="100.00000%"><tspan - sodipodi:role="line" - id="tspan12045" - x="259.56012" - y="706.32617">opera</tspan><tspan - sodipodi:role="line" - x="259.56012" - y="730.32618" - id="tspan12047">.css</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13022" - transform="translate(140.0000,160.0000)"> - <g - id="g12984" - transform="translate(32.76392,447.5954)" - style="stroke:#000000;stroke-opacity:1.0000000"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12986" /> - <path - sodipodi:nodetypes="ccccccc" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - id="path12988" /> - </g> - <text - sodipodi:linespacing="100.00000%" - id="text9092" - y="816.30219" - x="259.32312" - style="font-size:24.000011px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="816.30219" - x="259.32312" - id="tspan9094" - sodipodi:role="line">slides</tspan><tspan - id="tspan9096" - y="840.30220" - x="259.32312" - sodipodi:role="line">.js</tspan></text> - </g> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g12990" - transform="translate(140.0000,160.0000)"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - transform="translate(32.76392,7.595403)" - id="g12886"> - <path - id="path2125" - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - d="M 286.53987,344.38881 L 259.95853,330.91154 C 258.50529,330.17714 256.87802,329.76853 255.16608,329.76765 L 167.23608,329.76678 L 167.23608,329.76678 L 167.23608,419.76678 L 287.23608,419.76678 L 287.22985,346.10313 C 287.20953,345.21142 286.98750,344.61022 286.53987,344.38881 z " - sodipodi:nodetypes="ccccccccc" /> - <path - id="path2168" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 286.55635,344.40356 C 286.09815,344.17032 285.49622,344.35102 284.82132,344.84280 L 276.51509,351.08392 L 276.51509,351.08392 L 263.72436,334.02075 C 262.71303,332.71478 261.42576,331.64498 259.95853,330.91154 L 286.55635,344.40356 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - transform="scale(1.003177,0.996833)" - sodipodi:linespacing="100.00000%" - id="text9074" - y="378.15045" - x="258.4964" - style="font-size:24.117754px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - xml:space="preserve"><tspan - y="378.15045" - x="258.49640" - id="tspan9076" - sodipodi:role="line">slides</tspan><tspan - id="tspan9078" - y="402.26821" - x="258.49640" - sodipodi:role="line">.css</tspan></text> - </g> - </g> - <g - id="g14176"> - <g - style="stroke:#000000;stroke-opacity:1.0000000" - id="g13130" - transform="translate(0.000000,-54.99999)"> - <path - sodipodi:nodetypes="ccccccccc" - d="M 209.99815,696.86669 L 210.00000,852.36217 L 75.000000,852.36217 L 75.000000,672.36217 L 75.000000,672.36217 L 161.90250,672.36347 C 164.47041,672.36479 166.91132,672.97771 169.09117,674.07931 L 208.96319,694.29521 C 209.63463,694.62733 209.96767,695.52913 209.99815,696.86669 z " - style="fill:#ffffff;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000" - id="path12105" /> - <path - id="path12107" - style="fill:#a6a6a6;fill-opacity:1.0000000;stroke:#000000;stroke-width:3.7500000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;display:inline" - d="M 208.98791,694.31734 C 208.30060,693.96748 207.39771,694.23853 206.38536,694.97620 L 193.92602,704.33788 L 193.92602,704.33788 L 174.73992,678.74312 C 173.22293,676.78417 171.29202,675.17947 169.09117,674.07931 L 208.98791,694.31734 z " - sodipodi:nodetypes="ccccccc" /> - </g> - <text - xml:space="preserve" - style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:100.00000%;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1.0000000;stroke:#000000;stroke-width:0.0000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4.0000000;stroke-dasharray:none;stroke-opacity:1.0000000;font-family:Myriad" - x="146.13911" - y="695.62231" - id="text9058" - sodipodi:linespacing="100.00000%" - transform="scale(0.997872,1.002133)"><tspan - sodipodi:role="line" - x="146.13911" - y="695.62231" - id="tspan9128"><tspan - id="tspan14172" - style="font-size:36.814487px;font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;text-align:center;line-height:99.999976%;writing-mode:lr-tb;text-anchor:middle;stroke:#000000;stroke-width:0.0000000;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000;font-family:Myriad" />*.html</tspan><tspan - sodipodi:role="line" - x="146.13912" - y="732.43680" - id="tspan14174">output</tspan></text> - </g> - </g> - </g> - <g - inkscape:groupmode="layer" - id="layer2" - inkscape:label="2" - style="display:inline" /> -</svg> diff --git a/docutils/docs/user/images/small-black.png b/docutils/docs/user/images/small-black.png Binary files differdeleted file mode 100644 index f8d80d387..000000000 --- a/docutils/docs/user/images/small-black.png +++ /dev/null diff --git a/docutils/docs/user/images/small-white.png b/docutils/docs/user/images/small-white.png Binary files differdeleted file mode 100644 index 65f96895d..000000000 --- a/docutils/docs/user/images/small-white.png +++ /dev/null diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt deleted file mode 100644 index ce8447692..000000000 --- a/docutils/docs/user/latex.txt +++ /dev/null @@ -1,388 +0,0 @@ -================================ - Generating LaTeX with Docutils -================================ - -:Author: Engelbert Gruber -:Contact: grubert@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Introduction -============ - -Producing LaTeX code from reST input could be done in at least two ways: - -a. Transform the internal markup into corresponding LaTeX markup e.g. - a section title would be written as ```\section{this section ...}``. -b. Using LaTeX as a typesetting system to produce desired paperwork - without caring about loosing document structure information. - -The former might be preferable, but limits to LaTeXs capabilities, so -in reality it is a mix. The reality is that LaTeX has a titlepage with -title, author and date, by default only title is used. Author and date -are shown in the docutils docinfo table and set to blank for LaTeX. -To get author and date set by LaTeX specify option "use-LaTeX-docinfo". - -Options -======= - -Configuration can be done in two ways (again): - -1. Options to the docutils tool: e.g. language selection. -2. Options to LaTeX via the stylesheet file. - -The generated LaTeX documents should be kept processable by a standard -LaTeX installation (if such a thing exists), therefore the document -contains default settings. To allow *overwriting defaults* the stylesheet -is included at last. - -Run ``rst2latex.py --help`` to see the command-line options, or have look in -config documentytion. - - -===================== ================================================ -Configuration Issue Description -===================== ================================================ -papersize Default: a4paper. Paper geometry can be changed - using ``\geometry{xxx}`` entries. - - Some possibilities: - - * a4paper, b3paper, letterpaper, executivepaper, - legalpaper - * landscape, portrait, twoside. - - and a ton of other option setting margins. - - An example:: - - \geometry{a5paper,landscape} ---------------------- ------------------------------------------------ -paragraph indent By default LaTeX indents the forst line in a - paragraph. The following lines set indentation - to zero but add a vertical space between - paragraphs.:: - - \setlength{\parindent}{0pt} - \setlength{\parskip}{6pt plus 2pt minus 1pt} ---------------------- ------------------------------------------------ -admonitionwidth The width for admonitions. - Default: 0.9*textwidth, this can be changed - e.g.:: - - \setlength{\admonitionwidth}{0.7\textwidth} ---------------------- ------------------------------------------------ -docinfowidth The width for the docinfo table. - Default: 0.9*textwidth, changed to e.g.:: - - \setlength{\docinfowidth}{0.7\textwidth} ---------------------- ------------------------------------------------ -rubric style The header contains the definition of a new - LaTeX command rubric. Inserting:: - - \renewcommand{\rubric}[1]{\subsection*{ - ~\hfill {\color{red} #1} \hfill ~}} - - sets rubric to subsection style in red. - - Default: subsection style italic. ---------------------- ------------------------------------------------ -line spacing Is done with package *setspace*, which gives - singlespace, onehalfspace and doublespace - commands. To get documentwide double spacing, - add this to your stylesheet :: - - \usepackage{setspace} - \doublespacing - - Another way :: - - \linespread{1.55} - - And yet another, add ``doublesp`` to the - documentoptions and e.g. :: - - \setstretch{1.7} - - for bigger linespacing. ---------------------- ------------------------------------------------ -font selection see below -===================== ================================================ - - -Font selection --------------- - -When generating pdf-files from LaTeX, use the pdflatex command, the files -are a lot smaller if postscript fonts are used. This *was* fixed by putting -``\usepackage{times}`` into the stylesheet. - -It is said that the typewriter font in computer modern font, the default -LaTeX font package, is too heavy compared to the others. There is a package -or some commands too fix this, which i currently cannot find. - -Some people diagnose a similar unbalance for the postscript fonts, the -package to fix this is ``\usepackage{pslatex}``. -pslatex in contrast to the standard LaTeX fonts has a bold typewriter font. - -As ``times`` does not use the appropriate mathematical fonts and ``pslatex`` -does not work with T1 encodings one should use:: - - \usepackage{mathptmx} - \usepackage[scaled=.90]{helvet} - \usepackage{courier} - -*font encoding* can be selected with option "font-encoding". Default -uses package "ae" for old style font encoding use "OT1". - -Hyphenation ------------ - -The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to -10000 almost prevents hyphenation. As this produces lines with more spcea -between words one should increase LaTeX's ``\tolerance`` for this. - -E.g. try :: - - \hyphenpenalty=5000 - \tolerance=1000 - -Unicode -------- - -The generated LaTeX documents are in latin1 encoding per default, if unicode -characters are required one must set ``--output-encoding=utf-8`` install -`LaTeX unicode`_ support and add:: - - \usepackage{ucs} - \usepackage[utf8]{inputenc} - -to the stylesheet. If LaTeX issues a Warning about unloaded/known characters -adding :: - - \PreloadUnicodePage{n} - -where *n* is the unicode pagenumber, might help. - -.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/ - -Table of figures ----------------- - -A table of figures can be generated by a command directly to LaTeX:: - - .. raw:: LaTeX - - \listoffigures - -LaTeX also has a command ``\listoftables``. - -Section numbering ------------------ - -If section numbering and LaTeX table of contents is used LaTeX and -docutils will number sections. To switch off displaying of LaTeX's -numbers one has to add following lines to the stylesheet :: - - % no section number display - \makeatletter - \def\@seccntformat#1{} - \makeatother - % no numbers in toc - \renewcommand{\numberline}[1]{} - - -Number pages by chapter ------------------------ - -This can be accomplished with :: - - \usepackage{chappg} - -From the documentation - - Basic operation of the package is to redefine ``\thepage`` to be - ``\thechapter-\arabic{page}``, and to cause the page number to be reset - (to 1) at the start of each chapter. So the pages of chapter 3 will - be numbered 3-1, 3-2, ..., and the pages of appendix B will be - numbered B-1, B-2, ... - -See documentation for details and other possibilities. - -Images ------- - -Images are included in LaTeX by the graphicx package. The supported -image formats depend on the used driver (dvi, dvips, pdftex, ...). - -If pdf-image inclusion in pdf files fails, specify -``--graphicx-option=pdftex`` or ``--graphicx-option=auto``. - - -Commands directly to LaTeX -========================== - -By means of the reST-raw directive one can give commands directly to -LaTeX, e.g. forcing a page break:: - - .. raw:: LaTeX - - \newpage - - -Or setting formulas in LaTeX:: - - .. raw:: LaTeX - - $$x^3 + 3x^2a + 3xa^2 + a^3,$$ - - -Or making a colorbox: If someone wants to get a red background for a textblock, -she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in -reStructuredText do something like this:: - - |begincolorbox| - Nobody expects the spanish inquisition. - |endcolorbox| - - .. |begincolorbox| raw:: LaTeX - - \\begin{center} - \\colorbox{bg}{ - \\parbox{0.985\\linewidth}{ - - .. |endcolorbox| raw:: LaTeX - - }} - \\end{center} - - -Custom title page ------------------ - -Currently maketitle only shows the title and subtitle, date and author are shown -in the docinfo table. - -To change the titlepage layout, e.g. see fancyhdr, one must redefine the -maketitle command in the stylesheet:: - - \renewcommand{\maketitle}{ - \begin{titlepage} - \begin{center} - \textsf{TITLE \@title} \\ - Date: \today - \end{center} - \end{titlepage} - } - -``\@title`` contains the title. - -Problems -======== - -Open to be fixed or open to discussion. - -footnotes and citations ------------------------ - -Initially both were implemented using figures, because hyperlinking back -and forth seemed to be impossible. Later images were put into figures. - -This results in footnotes images and figures possibly being mixed at page -foot. - -* Use LaTeX footnotes and citations for printing or more complex layout. -* Footnotes and citations done with figures might excell in hyperlink - support. - -If ``use-latex-citations`` is used a bibliography is inserted right at -the end of the document. *This should be customizable*. - -Tables ------- - -:Tablewidth: reST-documents line length is assumed to be 80 characters. The - tablewidth is set relative to this value. If someone produces - documents with line length of 132 this will fail. - - Table width is tried to fit in page even if it is wider than - the assumed linewidth, still assumed linewidth is a hook. - -* In tools.txt the option tables right column, there should be some more spacing - between the description and the next paragraph "Default:". - - Paragraph separation in tables is hairy. - see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab - - - The strut solution did not work. - - setting extrarowheight added ad top of row not between paragraphs in - a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline. - - baselineskip/stretch does not help. -* Should there be two hlines after table head and on table end ? -* Table: multicol cells are always {l}. -* The contents of a rowspan cell do not influence table height. - (Maybe if we put a tabular inside ?) -* Table heads and footer for longtable (firstpage lastpage ..). -* Table cells with multirow and multicolumn -* literal-blocks in table cells: - - - If verbatim or flushleft is used one gets vertical space above and below. - - This is bad for the topmost paragraph in a cell, therefore the writer - uses raggedright. - - Ragged right fails on followup paragraphs as the vertical space would be - missing. - -Notes -~~~~~ - -* table-style booktabs: booktabs.sty 1.00 does not work with longtable. - -Miscellaneous -------------- - -* Selection of LaTeX fontsize configurable. -* Assumed reST linelength for table width setting configurable. -* literal-block indentation configurable. -* recongize LaTeX and replace by ``\LaTeX``. -* Support embed-stylesheet. -* Sidebar handling. -* Maybe add end of line after term in definition list. see - http://roundup.sf.net/doc-0.5/features.pdf -* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH). -* center subsection{Abstract} gives a LaTeX error here. - ``! LaTeX Error: Something's wrong--perhaps a missing \item.`` - Committed a HACK: centering by hfill. -* Document errors are also too silent. -* Use optionlist for docinfo, the table does only work for single page. -* Consider peter funk's hooks for TeXpert: - - * Define his own document preamble (including the choice to - choose his own documentclass. That would make the ``--documentclass`` - option superfluous). I suggest to call this option ``--preamble`` - * Use two additional hooks to put additional stuff just behind the - ``\begin{document}`` and just before the ``\end{document}`` macros. - Typical uses would be ``\tableofcontents``, ``\listoffigures`` and - ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such - for larger documents. - -* The indentional problematic error in docs/user/rst/demo.txt is not - referring anywhere. -* Footnotes are not all on the same page (as in - docs/user/rst/demo.txt) and do not link back and forth. -* No link to system errors. -* Hyperlinks are not hyphenated; this leads to bad spacing. See - docs/user/rst/demo.txt 2.14 directives. -* Meta keywords into pdf ? -* Pagestyle headings does not work, when sections are starred. -* For additional docinfo items: the field_body is inserted as text, i.e. no - markup is done. -* Multiple author entries in docinfo (same thing as in html). -* keep literal-blocks together on a page, avoid pagebreaks. - - failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before - the block. - diff --git a/docutils/docs/user/links.txt b/docutils/docs/user/links.txt deleted file mode 100644 index 3bb2aaa70..000000000 --- a/docutils/docs/user/links.txt +++ /dev/null @@ -1,137 +0,0 @@ -===================== - Docutils_ Link List -===================== - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. title:: Docutils Links - -.. contents:: - -This document contains links users of Docutils and reStructuredText -may find useful, listed in no particular order. Many of the project -listed here are hosted in the `Docutils Sandbox`_. If you have -something to publish, you can get write access, too! - -The most current version of this link list can always be found at -http://docutils.sourceforge.net/docs/user/links.html. - - -Users ------ - -This section contains links which are interesting for all users of -Docutils. All projects listed here are usable by end users in some -way, however please do not expect all of them to run straight out of -the box. - -* For Wikis, please see the `FAQ entry about Wikis`_. - -* For Blogs (Weblogs), please see the `FAQ entry about Blogs`_. - -* Alberto Berti is developing an `OpenDocument writer`_. - -* xml2rst_, an XSLT stylesheet written by Stefan Merten, converts XML - dumps of the document tree (e.g. created with rst2xml.py) back to - reStructuredText. - -* xhtml2rest_, written by Antonios Christofides, is a simple utility - to convert XHTML to reStructuredText. - -* rst2ht_, by Oliver Rutherfurd, converts reStructuredText to an .ht - template, for use with ht2html_. - -* htmlnav_, by Gunnar Schwant, is an HTML writer which supports - navigation bars. - -* rst2chm_, written by Oliver Rutherfurd, generates Microsoft HTML - Help files from reStructuredText files. - -* rest2web_, by Michael Foord, is a tool for creating web sites with - reStructuredText. - -* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope" - application that is complete and ready to install. - -* The Docutils interface to PythonPoint_, also by Richard Jones, - produces PDF presentations using ReportLabs. - -* Engelbert Gruber has begun a `ManPage Writer`_. - -* Oliver Rutherfurd has begun a `DocBook Writer`_. - -* Gunnar Schwant's DocFactory_ is a wxPython GUI application for - Docutils. - -* Patrick O'Brien has taken over the `OpenOffice.org Writer`_. - -* Bill Bumgarner has written a `simple HTML writer`_ that doesn't rely - on CSS (stylesheets). - -* Beni Cherniavsky has written a generic `preprocessing module`_ for - roles and/or directives and built preprocessors for TeX math for - both LaTeX and HTML output on top of it. - -* Beni Cherniavsky maintains a Makefile_ for driving Docutils, hoping - to handle everything one might do with Docutils. - - -API Developers --------------- - -This section contains links which are primarily interesting for -developers who use the Docutils API from within their own -applications. - -* Nabu_, written by Martin Blais, is a publishing system which - extracts information from reStructuredText documents and stores it - in a database. Python knowledge is required to write extractor - functions (see `Writing an Extractor`_) and to retrieve the data - from the database again. - -* There is a `pickle writer`_, written by Martin Blais. - - -Core Developers ---------------- - -Links primarily interesting for developers who work with the Docutils -code base. - -* PySource_, by Tony Ibbs, is an experimental Python source Reader. - There is some related code in David Goodger's sandbox - (pysource_reader_) and a `Python Source Reader`_ document. - - -.. _Docutils: http://docutils.sourceforge.net/ -.. _FAQ entry about Wikis: http://docutils.sf.net/FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax -.. _FAQ entry about Blogs: http://docutils.sf.net/FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax -.. _OpenDocument writer: http://thread.gmane.org/gmane.text.docutils.devel/3388 -.. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/index.html -.. _rst2ht: http://www.rutherfurd.net/articles/rst-ht2html.html -.. _ht2html: http://ht2html.sourceforge.net/ -.. _htmlnav: http://docutils.sf.net/sandbox/gschwant/htmlnav/ -.. _xhtml2rest: http://docutils.sf.net/sandbox/fwiemann/xhtml2rest/ -.. _rst2chm: http://www.rutherfurd.net/software/rst2chm/ -.. _rest2web: http://www.voidspace.org.uk/python/rest2web/ -.. _Docutils Sandbox: http://docutils.sf.net/sandbox/README.html -.. _ZReST: http://docutils.sf.net/sandbox/richard/ZReST/ -.. _PySource: http://docutils.sf.net/sandbox/tibs/pysource/ -.. _pysource_reader: http://docutils.sf.net/sandbox/davidg/pysource_reader/ -.. _Python Source Reader: http://docutils.sf.net/docs/dev/pysource.html -.. _PythonPoint: http://docutils.sf.net/sandbox/richard/pythonpoint/ -.. _Manpage Writer: http://docutils.sf.net/sandbox/grubert/man/ -.. _ReportLabs/PDF Writer: http://docutils.sf.net/sandbox/dreamcatcher/rlpdf/ -.. _DocBook Writer: http://docutils.sf.net/sandbox/oliverr/docbook/ -.. _DocFactory: http://docutils.sf.net/sandbox/gschwant/docfactory/doc/ -.. _OpenOffice.org Writer: http://docutils.sf.net/sandbox/pobrien/OpenOffice/ -.. _simple HTML writer: http://docutils.sf.net/sandbox/bbum/DocArticle/ -.. _preprocessing module: http://docutils.sf.net/sandbox/cben/rolehack/ -.. _Makefile: http://docutils.sf.net/sandbox/cben/make/ -.. _Nabu: http://furius.ca/nabu/ -.. _Writing an Extractor: http://furius.ca/nabu/doc/nabu-extractor.html -.. _pickle writer: http://docutils.sf.net/sandbox/blais/pickle_writer/ diff --git a/docutils/docs/user/mailing-lists.txt b/docutils/docs/user/mailing-lists.txt deleted file mode 100644 index 8137e29e7..000000000 --- a/docutils/docs/user/mailing-lists.txt +++ /dev/null @@ -1,111 +0,0 @@ -========================= - Docutils_ Mailing Lists -========================= - -:Author: Felix Wiemann -:Contact: Felix.Wiemann@ososo.de -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - - -All discussion about Docutils takes place on mailing lists. - -There are four different lists with traffic related to Docutils. If -unsure, use the **Docutils-users** mailing list: - - -Docutils-users --------------- - -The Docutils-users mailing list is a place to discuss any issues -related to the usage of Docutils and reStructuredText. (Please be -sure to check the FAQ_ first.) - -There are three possibilities to **read and post** messages on the -mailing lists; use the one you feel most comfortable with. - -* Using an `email subscription`__. This is the traditional way; you - will receive all messages sent to the mailing list via email. - - __ http://lists.sourceforge.net/lists/listinfo/docutils-users - -* Using Gmane's `web interface`__. To post a message, click "post" or - "followup" in the drop-down menu on the right. - - __ http://news.gmane.org/gmane.text.docutils.user - -* If you prefer using a newsreader, you can also use Gmane's `NNTP - interface`__ (gmane.text.docutils.user on news.gmane.org). - - __ nntp://news.gmane.org/gmane.text.docutils.user. - -**If you do not wish to subscribe,** you can also just send an email -message to Docutils-users@lists.sourceforge.net. Please note in your -message that you are not subscribed (to make sure that you receive -copies [CCs] of any replies). - -The first time you post a message without being subscribed (also when -posting via Gmane), you will receive an automatic response with the -subject "Your message to Docutils-users awaits moderator approval"; -this is done to prevent spam to the mailing lists. Your message will -usually be approved within a few hours. To avoid duplicates, please -do not resend your message using a different email address. After -your first message has been approved, your email address will be added -to the whitelist and future messages will be posted to the mailing -list without moderation. - - -Doc-SIG -------- - -The "Python Documentation Special Interest Group" (Doc-SIG) mailing -list is occasionally used to discuss the usage of Docutils for Python -documentation. - -This mailing list can be accessed via `email subscription`__, web__ or -news__ (gmane.comp.python.documentation) as well. You must be -subscribed in order to post messages to this mailing list. - -__ http://mail.python.org/mailman/listinfo/doc-sig -__ http://news.gmane.org/gmane.comp.python.documentation -__ nntp://news.gmane.org/gmane.comp.python.documentation - - -Docutils-develop ----------------- - -Discussions about developing and extending Docutils take place on the -Docutils-develop mailing list. - -You can access this list via `email subscription`__, web__ or news__ -(gmane.text.docutils.devel); the posting address is -Docutils-develop@lists.sourceforge.net. - -__ http://lists.sourceforge.net/lists/listinfo/docutils-develop -__ http://news.gmane.org/gmane.text.docutils.devel -__ nntp://news.gmane.org/gmane.text.docutils.devel - - -Docutils-checkins ------------------ - -All check-ins to the `Subversion repository`_ cause a "check-in email" -to the Docutils-checkins list. In order to stay informed about -current development, developers are advised to monitor this mailing -list. - -This mailing list is for reading only; please direct any discussion -about the check-ins to Docutils-develop. (For your convenience, the -Reply-To header of all check-in emails points to Docutils-develop.) - -This mailing list is accessible via `email subscription`__, web__ or -news__ (gmane.text.docutils.cvs) as well. - -__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins -__ http://news.gmane.org/gmane.text.docutils.cvs -__ nntp://news.gmane.org/gmane.text.docutils.cvs - -.. _Subversion repository: http://docutils.sf.net/docs/dev/repository.html -.. _Docutils: http://docutils.sourceforge.net/ -.. _FAQ: http://docutils.sourceforge.net/FAQ.html diff --git a/docutils/docs/user/rst/cheatsheet.txt b/docutils/docs/user/rst/cheatsheet.txt deleted file mode 100644 index dfea5bcb7..000000000 --- a/docutils/docs/user/rst/cheatsheet.txt +++ /dev/null @@ -1,125 +0,0 @@ -===================================================== - The reStructuredText_ Cheat Sheet: Syntax Reminders -===================================================== -:Info: See <http://docutils.sf.net/rst.html> for introductory docs. -:Author: David Goodger <goodger@python.org> -:Date: $Date$ -:Revision: $Revision$ -:Description: This is a "docinfo block", or bibliographic field list - -Section Structure -================= -Section titles are underlined or overlined & underlined. - -Body Elements -============= -Grid table: - -+--------------------------------+-----------------------------------+ -| Paragraphs are flush-left, | Literal block, preceded by "::":: | -| separated by blank lines. | | -| | Indented | -| Block quotes are indented. | | -+--------------------------------+ or:: | -| >>> print 'Doctest block' | | -| Doctest block | > Quoted | -+--------------------------------+-----------------------------------+ -| | Line blocks preserve line breaks & indents. [new in 0.3.6] | -| | Useful for addresses, verse, and adornment-free lists; long | -| lines can be wrapped with continuation lines. | -+--------------------------------------------------------------------+ - -Simple tables: - -================ ============================================================ -List Type Examples -================ ============================================================ -Bullet list * items begin with "-", "+", or "*" -Enumerated list 1. items use any variation of "1.", "A)", and "(i)" - #. also auto-enumerated -Definition list Term is flush-left : optional classifier - Definition is indented, no blank line between -Field list :field name: field body -Option list -o at least 2 spaces between option & description -================ ============================================================ - -================ ============================================================ -Explicit Markup Examples (visible in the `text source <cheatsheet.txt>`_) -================ ============================================================ -Footnote .. [1] Manually numbered or [#] auto-numbered - (even [#labelled]) or [*] auto-symbol -Citation .. [CIT2002] A citation. -Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html - .. _indirect target: reStructuredText_ - .. _internal target: -Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html -Directive ("::") .. image:: images/biohazard.png -Substitution Def .. |substitution| replace:: like an inline directive -Comment .. is anything else -================ ============================================================ - -Inline Markup -============= -*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text -with role`:emphasis:; ``inline literal text``; standalone hyperlink, -http://docutils.sourceforge.net; named reference, reStructuredText_; -`anonymous reference`__; footnote reference, [1]_; citation reference, -[CIT2002]_; |substitution|; _`inline internal target`. - -Directive Quick Reference -========================= -See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info. - -================ ============================================================ -Directive Name Description (Docutils version added to, in [brackets]) -================ ============================================================ -attention Specific admonition; also "caution", "danger", - "error", "hint", "important", "note", "tip", "warning" -admonition Generic titled admonition: ``.. admonition:: By The Way`` -image ``.. image:: picture.png``; many options possible -figure Like "image", but with optional caption and legend -topic ``.. topic:: Title``; like a mini section -sidebar ``.. sidebar:: Title``; like a mini parallel document -parsed-literal A literal block with parsed inline markup -rubric ``.. rubric:: Informal Heading`` -epigraph Block quote with class="epigraph" -highlights Block quote with class="highlights" -pull-quote Block quote with class="pull-quote" -compound Compound paragraphs [0.3.6] -container Generic block-level container element [0.3.10] -table Create a titled table [0.3.1] -list-table Create a table from a uniform two-level bullet list [0.3.8] -csv-table Create a table from CSV data (requires Python 2.3+) [0.3.4] -contents Generate a table of contents -sectnum Automatically number sections, subsections, etc. -header, footer Create document decorations [0.3.8] -target-notes Create an explicit footnote for each external target -meta HTML-specific metadata -include Read an external reST file as if it were inline -raw Non-reST data passed untouched to the Writer -replace Replacement text for substitution definitions -unicode Unicode character code conversion for substitution defs -date Generates today's date; for substitution defs -class Set a "class" attribute on the next element -role Create a custom interpreted text role [0.3.2] -default-role Set the default interpreted text role [0.3.10] -title Set the metadata document title [0.3.10] -================ ============================================================ - -Interpreted Text Role Quick Reference -===================================== -See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info. - -================ ============================================================ -Role Name Description -================ ============================================================ -emphasis Equivalent to *emphasis* -literal Equivalent to ``literal`` but processes backslash escapes -PEP Reference to a numbered Python Enhancement Proposal -RFC Reference to a numbered Internet Request For Comments -raw For non-reST data; cannot be used directly (see docs) [0.3.6] -strong Equivalent to **strong** -sub Subscript -sup Superscript -title Title reference (book, etc.); standard default role -================ ============================================================ diff --git a/docutils/docs/user/rst/demo.txt b/docutils/docs/user/rst/demo.txt deleted file mode 100644 index 7a0abd033..000000000 --- a/docutils/docs/user/rst/demo.txt +++ /dev/null @@ -1,552 +0,0 @@ -.. This is a comment. Note how any initial comments are moved by - transforms to after the document title, subtitle, and docinfo. - -================================ - reStructuredText Demonstration -================================ - -.. Above is the document title, and below is the subtitle. - They are transformed from section titles after parsing. - --------------------------------- - Examples of Syntax Constructs --------------------------------- - -.. bibliographic fields (which also require a transform): - -:Author: David Goodger -:Address: 123 Example Street - Example, EX Canada - A1B 2C3 -:Contact: goodger@users.sourceforge.net -:Authors: Me; Myself; I -:organization: humankind -:date: $Date$ -:status: This is a "work in progress" -:revision: $Revision$ -:version: 1 -:copyright: This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. -:field name: This is a generic bibliographic field. -:field name 2: - Generic bibliographic fields may contain multiple body elements. - - Like this. - -:Dedication: - - For Docutils users & co-developers. - -:abstract: - - This document is a demonstration of the reStructuredText markup - language, containing examples of all basic reStructuredText - constructs and many advanced constructs. - -.. meta:: - :keywords: reStructuredText, demonstration, demo, parser - :description lang=en: A demonstration of the reStructuredText - markup language, containing examples of all basic - constructs and many advanced constructs. - -.. contents:: Table of Contents -.. section-numbering:: - - -Structural Elements -=================== - -Section Title -------------- - -That's it, the text just above this line. - -Transitions ------------ - -Here's a transition: - ---------- - -It divides the section. - -Body Elements -============= - -Paragraphs ----------- - -A paragraph. - -Inline Markup -````````````` - -Paragraphs contain text and may contain inline markup: *emphasis*, -**strong emphasis**, ``inline literals``, standalone hyperlinks -(http://www.python.org), external hyperlinks (Python_), internal -cross-references (example_), external hyperlinks with embedded URIs -(`Python web site <http://www.python.org>`__), footnote references -(manually numbered [1]_, anonymous auto-numbered [#]_, labeled -auto-numbered [#label]_, or symbolic [*]_), citation references -([CIT2002]_), substitution references (|example|), and _`inline -hyperlink targets` (see Targets_ below for a reference back to here). -Character-level inline markup is also possible (although exceedingly -ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by -|problematic| text (generated by processing errors; this one is -intentional). - -The default role for interpreted text is `Title Reference`. Here are -some explicit interpreted text roles: a PEP reference (:PEP:`287`); an -RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; -and explicit roles for :emphasis:`standard` :strong:`inline` -:literal:`markup`. - -.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! - -Let's test wrapping and whitespace significance in inline literals: -``This is an example of --inline-literal --text, --including some-- -strangely--hyphenated-words. Adjust-the-width-of-your-browser-window -to see how the text is wrapped. -- ---- -------- Now note the -spacing between the words of this sentence (words -should be grouped in pairs).`` - -If the ``--pep-references`` option was supplied, there should be a -live link to PEP 258 here. - -Bullet Lists ------------- - -- A bullet list - - + Nested bullet list. - + Nested item 2. - -- Item 2. - - Paragraph 2 of item 2. - - * Nested bullet list. - * Nested item 2. - - - Third level. - - Item 2. - - * Nested item 3. - -Enumerated Lists ----------------- - -1. Arabic numerals. - - a) lower alpha) - - (i) (lower roman) - - A. upper alpha. - - I) upper roman) - -2. Lists that don't start at 1: - - 3. Three - - 4. Four - - C. C - - D. D - - iii. iii - - iv. iv - -#. List items may also be auto-enumerated. - -Definition Lists ----------------- - -Term - Definition -Term : classifier - Definition paragraph 1. - - Definition paragraph 2. -Term - Definition - -Field Lists ------------ - -:what: Field lists map field names to field bodies, like database - records. They are often part of an extension syntax. They are - an unambiguous variant of RFC 2822 fields. - -:how arg1 arg2: - - The field marker is a colon, the field name, and a colon. - - The field body may contain one or more body elements, indented - relative to the field marker. - -Option Lists ------------- - -For listing command-line options: - --a command-line option "a" --b file options can have arguments - and long descriptions ---long options can be long also ---input=file long options can also have - arguments - ---very-long-option - The description can also start on the next line. - - The description may contain multiple body elements, - regardless of where it starts. - --x, -y, -z Multiple options are an "option group". --v, --verbose Commonly-seen: short & long options. --1 file, --one=file, --two file - Multiple options with arguments. -/V DOS/VMS-style options too - -There must be at least two spaces between the option and the -description. - -Literal Blocks --------------- - -Literal blocks are indicated with a double-colon ("::") at the end of -the preceding paragraph (over there ``-->``). They can be indented:: - - if literal_block: - text = 'is left as-is' - spaces_and_linebreaks = 'are preserved' - markup_processing = None - -Or they can be quoted without indentation:: - ->> Great idea! -> -> Why didn't I think of that? - -Line Blocks ------------ - -| This is a line block. It ends with a blank line. -| Each new line begins with a vertical bar ("|"). -| Line breaks and initial indents are preserved. -| Continuation lines are wrapped portions of long lines; - they begin with a space in place of the vertical bar. -| The left edge of a continuation line need not be aligned with - the left edge of the text above it. - -| This is a second line block. -| -| Blank lines are permitted internally, but they must begin with a "|". - -Take it away, Eric the Orchestra Leader! - - | A one, two, a one two three four - | - | Half a bee, philosophically, - | must, *ipso facto*, half not be. - | But half the bee has got to be, - | *vis a vis* its entity. D'you see? - | - | But can a bee be said to be - | or not to be an entire bee, - | when half the bee is not a bee, - | due to some ancient injury? - | - | Singing... - -Block Quotes ------------- - -Block quotes consist of indented body elements: - - My theory by A. Elk. Brackets Miss, brackets. This theory goes - as follows and begins now. All brontosauruses are thin at one - end, much much thicker in the middle and then thin again at the - far end. That is my theory, it is mine, and belongs to me and I - own it, and what it is too. - - -- Anne Elk (Miss) - -Doctest Blocks --------------- - ->>> print 'Python-specific usage examples; begun with ">>>"' -Python-specific usage examples; begun with ">>>" ->>> print '(cut and pasted from interactive Python sessions)' -(cut and pasted from interactive Python sessions) - -Tables ------- - -Here's a grid table followed by a simple table: - -+------------------------+------------+----------+----------+ -| Header row, column 1 | Header 2 | Header 3 | Header 4 | -| (header rows optional) | | | | -+========================+============+==========+==========+ -| body row 1, column 1 | column 2 | column 3 | column 4 | -+------------------------+------------+----------+----------+ -| body row 2 | Cells may span columns. | -+------------------------+------------+---------------------+ -| body row 3 | Cells may | - Table cells | -+------------------------+ span rows. | - contain | -| body row 4 | | - body elements. | -+------------------------+------------+----------+----------+ -| body row 5 | Cells may also be | | -| | empty: ``-->`` | | -+------------------------+-----------------------+----------+ - -===== ===== ====== - Inputs Output ------------- ------ - A B A or B -===== ===== ====== -False False False -True False True -False True True -True True True -===== ===== ====== - -Footnotes ---------- - -.. [1] A footnote contains body elements, consistently indented by at - least 3 spaces. - - This is the footnote's second paragraph. - -.. [#label] Footnotes may be numbered, either manually (as in [1]_) or - automatically using a "#"-prefixed label. This footnote has a - label so it can be referred to from multiple places, both as a - footnote reference ([#label]_) and as a hyperlink reference - (label_). - -.. [#] This footnote is numbered automatically and anonymously using a - label of "#" only. - -.. [*] Footnotes may also use symbols, specified with a "*" label. - Here's a reference to the next footnote: [*]_. - -.. [*] This footnote shows the next symbol in the sequence. - -.. [4] Here's an unreferenced footnote, with a reference to a - nonexistent footnote: [5]_. - -Citations ---------- - -.. [CIT2002] Citations are text-labeled footnotes. They may be - rendered separately and differently from footnotes. - -Here's a reference to the above, [CIT2002]_, and a [nonexistent]_ -citation. - -Targets -------- - -.. _example: - -This paragraph is pointed to by the explicit "example" target. A -reference can be found under `Inline Markup`_, above. `Inline -hyperlink targets`_ are also possible. - -Section headers are implicit targets, referred to by name. See -Targets_, which is a subsection of `Body Elements`_. - -Explicit external targets are interpolated into references such as -"Python_". - -.. _Python: http://www.python.org/ - -Targets may be indirect and anonymous. Thus `this phrase`__ may also -refer to the Targets_ section. - -__ Targets_ - -Here's a `hyperlink reference without a target`_, which generates an -error. - -Duplicate Target Names -`````````````````````` - -Duplicate names in section headers or other implicit targets will -generate "info" (level-1) system messages. Duplicate names in -explicit targets will generate "warning" (level-2) system messages. - -Duplicate Target Names -`````````````````````` - -Since there are two "Duplicate Target Names" section headers, we -cannot uniquely refer to either of them by name. If we try to (like -this: `Duplicate Target Names`_), an error is generated. - -Directives ----------- - -.. contents:: :local: - -These are just a sample of the many reStructuredText Directives. For -others, please see -http://docutils.sourceforge.net/docs/ref/rst/directives.html. - -Document Parts -`````````````` - -An example of the "contents" directive can be seen above this section -(a local, untitled table of contents_) and at the beginning of the -document (a document-wide `table of contents`_). - -Images -`````` - -An image directive (also clickable -- a hyperlink reference): - -.. image:: images/title.png - :target: directives_ - -A figure directive: - -.. figure:: images/title.png - :alt: reStructuredText, the markup syntax - - A figure is an image with a caption and/or a legend: - - +------------+-----------------------------------------------+ - | re | Revised, revisited, based on 're' module. | - +------------+-----------------------------------------------+ - | Structured | Structure-enhanced text, structuredtext. | - +------------+-----------------------------------------------+ - | Text | Well it is, isn't it? | - +------------+-----------------------------------------------+ - - This paragraph is also part of the legend. - -Admonitions -``````````` - -.. Attention:: Directives at large. - -.. Caution:: - - Don't take any wooden nickels. - -.. DANGER:: Mad scientist at work! - -.. Error:: Does not compute. - -.. Hint:: It's bigger than a bread box. - -.. Important:: - - Wash behind your ears. - - Clean up your room. - - Call your mother. - - Back up your data. - -.. Note:: This is a note. - -.. Tip:: 15% if the service is good. - -.. WARNING:: Strong prose may provoke extreme mental exertion. - Reader discretion is strongly advised. - -.. admonition:: And, by the way... - - You can make up your own admonition too. - -Topics, Sidebars, and Rubrics -````````````````````````````` - -.. sidebar:: Sidebar Title - :subtitle: Optional Subtitle - - This is a sidebar. It is for text outside the flow of the main - text. - - .. rubric:: This is a rubric inside a sidebar - - Sidebars often appears beside the main text with a border and - background color. - -.. topic:: Topic Title - - This is a topic. - -.. rubric:: This is a rubric - -Target Footnotes -```````````````` - -.. target-notes:: - -Replacement Text -```````````````` - -I recommend you try |Python|_. - -.. |Python| replace:: Python, *the* best language around - -Compound Paragraph -`````````````````` - -.. compound:: - - This paragraph contains a literal block:: - - Connecting... OK - Transmitting data... OK - Disconnecting... OK - - and thus consists of a simple paragraph, a literal block, and - another simple paragraph. Nonetheless it is semantically *one* - paragraph. - -This construct is called a *compound paragraph* and can be produced -with the "compound" directive. - -Substitution Definitions ------------------------- - -An inline image (|example|) example: - -.. |EXAMPLE| image:: images/biohazard.png - -(Substitution definitions are not visible in the HTML source.) - -Comments --------- - -Here's one: - -.. Comments begin with two dots and a space. Anything may - follow, except for the syntax of footnotes, hyperlink - targets, directives, or substitution definitions. - - Double-dashes -- "--" -- must be escaped somehow in HTML output. - -(View the HTML source to see the comment.) - -Error Handling -============== - -Any errors caught during processing will generate system messages. - -|*** Expect 6 errors (including this one). ***| - -There should be six messages in the following, auto-generated -section, "Docutils System Messages": - -.. section should be added by Docutils automatically diff --git a/docutils/docs/user/rst/images/ball1.gif b/docutils/docs/user/rst/images/ball1.gif Binary files differdeleted file mode 100644 index 3e14441d9..000000000 --- a/docutils/docs/user/rst/images/ball1.gif +++ /dev/null diff --git a/docutils/docs/user/rst/images/biohazard.png b/docutils/docs/user/rst/images/biohazard.png Binary files differdeleted file mode 100644 index ae4629d8b..000000000 --- a/docutils/docs/user/rst/images/biohazard.png +++ /dev/null diff --git a/docutils/docs/user/rst/images/title.png b/docutils/docs/user/rst/images/title.png Binary files differdeleted file mode 100644 index cc6218efe..000000000 --- a/docutils/docs/user/rst/images/title.png +++ /dev/null diff --git a/docutils/docs/user/rst/quickref.html b/docutils/docs/user/rst/quickref.html deleted file mode 100644 index 604cfe6bc..000000000 --- a/docutils/docs/user/rst/quickref.html +++ /dev/null @@ -1,1352 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" - "http://www.w3.org/TR/html4/loose.dtd"> - -<html> - <head> - <title>Quick reStructuredText</title> - <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> - - <style type="text/css"><!-- - a.backref { text-decoration: none ; color: black } - div.line-block { display: block } - div.line-block div.line-block { margin-left: 1.5em } - --></style> - - </head> - - <body> - <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1> - - <!-- Caveat: if you're reading the HTML for the examples, --> - <!-- beware that it was hand-generated, not by Docutils/ReST. --> - - <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" - >http://docutils.sourceforge.net/docs/user/rst/quickref.html</a></em> - <br><em>Being a cheat-sheet for reStructuredText</em> - <br><em>Updated $Date$</em> - - <blockquote> - <p>Copyright: This document has been placed in the public domain. - </blockquote> - - - <p>The full details of the markup may be found on the - <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> - page. This document is just intended as a reminder. - - <p>Links that look like "(<a href="#details">details</a>)" point - into the HTML version of the full <a - href="../../ref/rst/restructuredtext.html">reStructuredText - specification</a> document. These are relative links; if they - don't work, please use the <a - href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" - >master "Quick reStructuredText"</a> document. - - <h2><a name="contents">Contents</a></h2> - - <ul> - <li><a href="#inline-markup">Inline Markup</a></li> - <li><a href="#escaping">Escaping with Backslashes</a></li> - <li><a href="#section-structure">Section Structure</a></li> - <li><a href="#paragraphs">Paragraphs</a></li> - <li><a href="#bullet-lists">Bullet Lists</a></li> - <li><a href="#enumerated-lists">Enumerated Lists</a></li> - <li><a href="#definition-lists">Definition Lists</a></li> - <li><a href="#field-lists">Field Lists</a></li> - <li><a href="#option-lists">Option Lists</a></li> - <li><a href="#literal-blocks">Literal Blocks</a></li> - <li><a href="#line-blocks">Line Blocks</a></li> - <li><a href="#block-quotes">Block Quotes</a></li> - <li><a href="#doctest-blocks">Doctest Blocks</a></li> - <li><a href="#tables">Tables</a></li> - <li><a href="#transitions">Transitions</a></li> - <li><a href="#explicit-markup">Explicit Markup</a> - <ul> - <li><a href="#footnotes">Footnotes</a></li> - <li><a href="#citations">Citations</a></li> - <li><a href="#hyperlink-targets">Hyperlink Targets</a> - <ul> - <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li> - <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li> - <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li> - <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li> - </ul></li> - <li><a href="#directives">Directives</a></li> - <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> - <li><a href="#comments">Comments</a></li> - </ul></li> - <li><a href="#getting-help">Getting Help</a></li> - </ul> - - <h2><a href="#contents" name="inline-markup" class="backref" - >Inline Markup</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#inline-markup">details</a>) - - <p>Inline markup allows words and phrases within text to have - character styles (like italics and boldface) and functionality - (like hyperlinks). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th>Plain text - <th>Typical result - <th>Notes - </thead> - <tbody> - <tr valign="top"> - <td nowrap><samp>*emphasis*</samp> - <td><em>emphasis</em> - <td>Normally rendered as italics. - - <tr valign="top"> - <td nowrap><samp>**strong emphasis**</samp> - <td><strong>strong emphasis</strong> - <td>Normally rendered as boldface. - - <tr valign="top"> - <td nowrap><samp>`interpreted text`</samp> - <td>(see note at right) - <td>The rendering and <em>meaning</em> of interpreted text is - domain- or application-dependent. It can be used for things - like index entries or explicit descriptive markup (like program - identifiers). - - <tr valign="top"> - <td nowrap><samp>``inline literal``</samp> - <td><code>inline literal</code> - <td>Normally rendered as monospaced text. Spaces should be - preserved, but line breaks will not be. - - <tr valign="top"> - <td nowrap><samp>reference_</samp> - <td><a href="#hyperlink-targets">reference</a> - <td>A simple, one-word hyperlink reference. See <a - href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>`phrase reference`_</samp> - <td><a href="#hyperlink-targets">phrase reference</a> - <td>A hyperlink reference with spaces or punctuation needs to be - quoted with backquotes. See <a - href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>anonymous__</samp> - <td><a href="#hyperlink-targets">anonymous</a> - <td>With two underscores instead of one, both simple and phrase - references may be anonymous (the reference text is not repeated - at the target). See <a - href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>_`inline internal target`</samp> - <td><a name="inline-internal-target">inline internal target</a> - <td>A crossreference target within text. - See <a href="#hyperlink-targets">Hyperlink Targets</a>. - - <tr valign="top"> - <td nowrap><samp>|substitution reference|</samp> - <td>(see note at right) - <td>The result is substituted in from the <a - href="#substitution-references-and-definitions">substitution - definition</a>. It could be text, an image, a hyperlink, or a - combination of these and others. - - <tr valign="top"> - <td nowrap><samp>footnote reference [1]_</samp> - <td>footnote reference <sup><a href="#footnotes">1</a></sup> - <td>See <a href="#footnotes">Footnotes</a>. - - <tr valign="top"> - <td nowrap><samp>citation reference [CIT2002]_</samp> - <td>citation reference <a href="#citations">[CIT2002]</a> - <td>See <a href="#citations">Citations</a>. - - <tr valign="top"> - <td nowrap><samp>http://docutils.sf.net/</samp> - <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> - <td>A standalone hyperlink. - - </table> - - <p>Asterisk, backquote, vertical bar, and underscore are inline - delimiter characters. Asterisk, backquote, and vertical bar act - like quote marks; matching characters surround the marked-up word - or phrase, whitespace or other quoting is required outside them, - and there can't be whitespace just inside them. If you want to use - inline delimiter characters literally, <a href="#escaping">escape - (with backslash)</a> or quote them (with double backquotes; i.e. - use inline literals). - - <p>In detail, the reStructuredText specification says that in - inline markup, the following rules apply to start-strings and - end-strings (inline markup delimiters): - - <ol> - <li>The start-string must start a text block or be - immediately preceded by whitespace or any of - <samp>' " ( [ {</samp> or <samp><</samp>. - <li>The start-string must be immediately followed by non-whitespace. - <li>The end-string must be immediately preceded by non-whitespace. - <li>The end-string must end a text block (end of document or - followed by a blank line) or be immediately followed by whitespace - or any of <samp>' " . , : ; ! ? - ) ] } / \</samp> - or <samp>></samp>. - <li>If a start-string is immediately preceded by one of - <samp>' " ( [ {</samp> or <samp><</samp>, it must not be - immediately followed by the corresponding character from - <samp>' " ) ] }</samp> or <samp>></samp>. - <li>An end-string must be separated by at least one - character from the start-string. - <li>An <a href="#escaping">unescaped</a> backslash preceding a - start-string or end-string will disable markup recognition, except - for the end-string of inline literals. - </ol> - - <p>Also remember that inline markup may not be nested (well, - except that inline literals can contain any of the other inline - markup delimiter characters, but that doesn't count because - nothing is processed). - - <h2><a href="#contents" name="escaping" class="backref" - >Escaping with Backslashes</a></h2> - - <p>(<a - href="../../ref/rst/restructuredtext.html#escaping-mechanism">details</a>) - - <p>reStructuredText uses backslashes ("\") to override the special - meaning given to markup characters and get the literal characters - themselves. To get a literal backslash, use an escaped backslash - ("\\"). For example: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Raw reStructuredText - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"><td> - <samp>*escape* ``with`` "\"</samp> - <td><em>escape</em> <samp>with</samp> "" - <tr valign="top"><td> - <samp>\*escape* \``with`` "\\"</samp> - <td>*escape* ``with`` "\" - </table> - - <p>In Python strings it will, of course, be necessary - to escape any backslash characters so that they actually - <em>reach</em> reStructuredText. - The simplest way to do this is to use raw strings: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Python string - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"><td> - <samp>r"""\*escape* \`with` "\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\\*escape* \\`with` "\\\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\*escape* \`with` "\\""""</samp> - <td><em>escape</em> with "" - </table> - - <h2><a href="#contents" name="section-structure" class="backref" - >Section Structure</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#sections">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>=====</samp> -<br><samp>Title</samp> -<br><samp>=====</samp> -<br><samp>Subtitle</samp> -<br><samp>--------</samp> -<br><samp>Titles are underlined (or over-</samp> -<br><samp>and underlined) with a printing</samp> -<br><samp>nonalphanumeric 7-bit ASCII</samp> -<br><samp>character. Recommended choices</samp> -<br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> -<br><samp>The underline/overline must be at</samp> -<br><samp>least as long as the title text.</samp> -<br><samp></samp> -<br><samp>A lone top-level (sub)section</samp> -<br><samp>is lifted up to be the document's</samp> -<br><samp>(sub)title.</samp> - - <td> - <font size="+2"><strong>Title</strong></font> - <p><font size="+1"><strong>Subtitle</strong></font> - <p>Titles are underlined (or over- - and underlined) with a printing - nonalphanumeric 7-bit ASCII - character. Recommended choices - are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". - The underline/overline must be at - least as long as the title text. - <p>A lone top-level (sub)section is - lifted up to be the document's - (sub)title. - </table> - - <h2><a href="#contents" name="paragraphs" class="backref" - >Paragraphs</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#paragraphs">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>This is a paragraph.</samp> - -<p><samp>Paragraphs line up at their left</samp> -<br><samp>edges, and are normally separated</samp> -<br><samp>by blank lines.</samp> - - <td> - <p>This is a paragraph. - - <p>Paragraphs line up at their left edges, and are normally - separated by blank lines. - - </table> - - <h2><a href="#contents" name="bullet-lists" class="backref" - >Bullet Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#bullet-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Bullet lists:</samp> - -<p><samp>- This is item 1</samp> -<br><samp>- This is item 2</samp> - -<p><samp>- Bullets are "-", "*" or "+".</samp> -<br><samp> Continuing text must be aligned</samp> -<br><samp> after the bullet and whitespace.</samp> - -<p><samp>Note that a blank line is required</samp> -<br><samp>before the first item and after the</samp> -<br><samp>last, but is optional between items.</samp> - <td>Bullet lists: - <ul> - <li>This is item 1 - <li>This is item 2 - <li>Bullets are "-", "*" or "+". - Continuing text must be aligned - after the bullet and whitespace. - </ul> - <p>Note that a blank line is required before the first - item and after the last, but is optional between items. - </table> - - <h2><a href="#contents" name="enumerated-lists" class="backref" - >Enumerated Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#enumerated-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Enumerated lists:</samp> - -<p><samp>3. This is the first item</samp> -<br><samp>4. This is the second item</samp> -<br><samp>5. Enumerators are arabic numbers,</samp> -<br><samp> single letters, or roman numerals</samp> -<br><samp>6. List items should be sequentially</samp> -<br><samp> numbered, but need not start at 1</samp> -<br><samp> (although not all formatters will</samp> -<br><samp> honour the first index).</samp> -<br><samp>#. This item is auto-enumerated</samp> - <td>Enumerated lists: - <ol type="1"> - <li value="3">This is the first item - <li>This is the second item - <li>Enumerators are arabic numbers, single letters, - or roman numerals - <li>List items should be sequentially numbered, - but need not start at 1 (although not all - formatters will honour the first index). - <li>This item is auto-enumerated - </ol> - </table> - - <h2><a href="#contents" name="definition-lists" class="backref" - >Definition Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#definition-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Definition lists:</samp> -<br> -<br><samp>what</samp> -<br><samp> Definition lists associate a term with</samp> -<br><samp> a definition.</samp> -<br> -<br><samp>how</samp> -<br><samp> The term is a one-line phrase, and the</samp> -<br><samp> definition is one or more paragraphs or</samp> -<br><samp> body elements, indented relative to the</samp> -<br><samp> term. Blank lines are not allowed</samp> -<br><samp> between term and definition.</samp> - <td>Definition lists: - <dl> - <dt><strong>what</strong> - <dd>Definition lists associate a term with - a definition. - - <dt><strong>how</strong> - <dd>The term is a one-line phrase, and the - definition is one or more paragraphs or - body elements, indented relative to the - term. Blank lines are not allowed - between term and definition. - </dl> - </table> - - <h2><a href="#contents" name="field-lists" class="backref" - >Field Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#field-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>:Authors:</samp> -<br><samp> Tony J. (Tibs) Ibbs,</samp> -<br><samp> David Goodger</samp> - -<p><samp> (and sundry other good-natured folks)</samp> - -<p><samp>:Version: 1.0 of 2001/08/08</samp> -<br><samp>:Dedication: To my father.</samp> - <td> - <table> - <tr valign="top"> - <td><strong>Authors:</strong> - <td>Tony J. (Tibs) Ibbs, - David Goodger - <tr><td><td>(and sundry other good-natured folks) - <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 - <tr><td><strong>Dedication:</strong><td>To my father. - </table> - </table> - - <p>Field lists are used as part of an extension syntax, such as - options for <a href="#directives">directives</a>, or database-like - records meant for further processing. Field lists may also be - used as generic two-column table constructs in documents. - - <h2><a href="#contents" name="option-lists" class="backref" - >Option Lists</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#option-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> --a command-line option "a" -<br>-b file options can have arguments -<br> and long descriptions -<br>--long options can be long also -<br>--input=file long options can also have -<br> arguments -<br>/V DOS/VMS-style options too -</samp> - - <td> - <table border="0" width="100%"> - <tbody valign="top"> - <tr> - <td width="30%"><samp>-a</samp> - <td>command-line option "a" - <tr> - <td><samp>-b <i>file</i></samp> - <td>options can have arguments and long descriptions - <tr> - <td><samp>--long</samp> - <td>options can be long also - <tr> - <td><samp>--input=<i>file</i></samp> - <td>long options can also have arguments - <tr> - <td><samp>/V</samp> - <td>DOS/VMS-style options too - </table> - </table> - - <p>There must be at least two spaces between the option and the - description. - - <h2><a href="#contents" name="literal-blocks" class="backref" - >Literal Blocks</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#literal-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>A paragraph containing only two colons</samp> -<br><samp>indicates that the following indented</samp> -<br><samp>or quoted text is a literal block.</samp> -<br> -<br><samp>::</samp> -<br> -<br><samp> Whitespace, newlines, blank lines, and</samp> -<br><samp> all kinds of markup (like *this* or</samp> -<br><samp> \this) is preserved by literal blocks.</samp> -<br> -<br><samp> The paragraph containing only '::'</samp> -<br><samp> will be omitted from the result.</samp> -<br> -<br><samp>The ``::`` may be tacked onto the very</samp> -<br><samp>end of any paragraph. The ``::`` will be</samp> -<br><samp>omitted if it is preceded by whitespace.</samp> -<br><samp>The ``::`` will be converted to a single</samp> -<br><samp>colon if preceded by text, like this::</samp> -<br> -<br><samp> It's very convenient to use this form.</samp> -<br> -<br><samp>Literal blocks end when text returns to</samp> -<br><samp>the preceding paragraph's indentation.</samp> -<br><samp>This means that something like this</samp> -<br><samp>is possible::</samp> -<br> -<br><samp> We start here</samp> -<br><samp> and continue here</samp> -<br><samp> and end here.</samp> -<br> -<br><samp>Per-line quoting can also be used on</samp> -<br><samp>unindented literal blocks:</samp> -<br> -<br><samp>> Useful for quotes from email and</samp> -<br><samp>> for Haskell literate programming.</samp> - - <td> - <p>A paragraph containing only two colons -indicates that the following indented or quoted -text is a literal block. - - <pre> - Whitespace, newlines, blank lines, and - all kinds of markup (like *this* or - \this) is preserved by literal blocks. - - The paragraph containing only '::' - will be omitted from the result.</pre> - - <p>The <samp>::</samp> may be tacked onto the very -end of any paragraph. The <samp>::</samp> will be -omitted if it is preceded by whitespace. -The <samp>::</samp> will be converted to a single -colon if preceded by text, like this: - - <pre> - It's very convenient to use this form.</pre> - - <p>Literal blocks end when text returns to -the preceding paragraph's indentation. -This means that something like this is possible: - - <pre> - We start here - and continue here - and end here.</pre> - - <p>Per-line quoting can also be used on -unindented literal blocks: - - <pre> - > Useful for quotes from email and - > for Haskell literate programming.</pre> - </table> - - <h2><a href="#contents" name="line-blocks" class="backref" - >Line Blocks</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#line-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>| Line blocks are useful for addresses,</samp> -<br><samp>| verse, and adornment-free lists.</samp> -<br><samp>|</samp> -<br><samp>| Each new line begins with a</samp> -<br><samp>| vertical bar ("|").</samp> -<br><samp>| Line breaks and initial indents</samp> -<br><samp>| are preserved.</samp> -<br><samp>| Continuation lines are wrapped</samp> -<br><samp> portions of long lines; they begin</samp> -<br><samp> with spaces in place of vertical bars.</samp> - - <td> - <div class="line-block"> - <div class="line">Line blocks are useful for addresses,</div> - <div class="line">verse, and adornment-free lists.</div> - <div class="line"><br /></div> - <div class="line">Each new line begins with a</div> - <div class="line">vertical bar ("|").</div> - <div class="line-block"> - <div class="line">Line breaks and initial indents</div> - <div class="line">are preserved.</div> - </div> - <div class="line">Continuation lines are wrapped portions - of long lines; they begin - with spaces in place of vertical bars.</div> - </div> - </table> - - <h2><a href="#contents" name="block-quotes" class="backref" - >Block Quotes</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#block-quotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Block quotes are just:</samp> - -<p><samp> Indented paragraphs,</samp> - -<p><samp> and they may nest.</samp> - <td> - Block quotes are just: - <blockquote> - <p>Indented paragraphs, - <blockquote> - <p>and they may nest. - </blockquote> - </blockquote> - </table> - - <h2><a href="#contents" name="doctest-blocks" class="backref" - >Doctest Blocks</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp>Doctest blocks are interactive -<br>Python sessions. They begin with -<br>"``>>>``" and end with a blank line.</samp> - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> - - <td> - <p>Doctest blocks are interactive - Python sessions. They begin with - "<samp>>>></samp>" and end with a blank line. - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> - </table> - - <p>"The <a - href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a> - module searches a module's docstrings for text that looks like an - interactive Python session, then executes all such sessions to - verify they still work exactly as shown." (From the doctest docs.) - - <h2><a href="#contents" name="tables" class="backref" - >Tables</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>) - - <p>There are two syntaxes for tables in reStructuredText. Grid - tables are complete but cumbersome to create. Simple tables are - easy to create but limited (no row spans, etc.).</p> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>Grid table:</samp></p> - -<p><samp>+------------+------------+-----------+</samp> -<br><samp>| Header 1 | Header 2 | Header 3 |</samp> -<br><samp>+============+============+===========+</samp> -<br><samp>| body row 1 | column 2 | column 3 |</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 2 | Cells may span columns.|</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 3 | Cells may | - Cells |</samp> -<br><samp>+------------+ span rows. | - contain |</samp> -<br><samp>| body row 4 | | - blocks. |</samp> -<br><samp>+------------+------------+-----------+</samp></p> - <td> - <p>Grid table:</p> - <table border="1"> - <thead valign="bottom"> - <tr> - <th>Header 1 - <th>Header 2 - <th>Header 3 - </tr> - </thead> - <tbody valign="top"> - <tr> - <td>body row 1 - <td>column 2 - <td>column 3 - </tr> - <tr> - <td>body row 2 - <td colspan="2">Cells may span columns. - </tr> - <tr> - <td>body row 3 - <td rowspan="2">Cells may<br>span rows. - <td rowspan="2"> - <ul> - <li>Cells - <li>contain - <li>blocks. - </ul> - </tr> - <tr> - <td>body row 4 - </tr> - </table> - <tr valign="top"> - <td> -<p><samp>Simple table:</samp></p> - -<p><samp>===== ===== ======</samp> -<br><samp> Inputs Output</samp> -<br><samp>------------ ------</samp> -<br><samp> A B A or B</samp> -<br><samp>===== ===== ======</samp> -<br><samp>False False False</samp> -<br><samp>True False True</samp> -<br><samp>False True True</samp> -<br><samp>True True True</samp> -<br><samp>===== ===== ======</samp></p> - - <td> - <p>Simple table:</p> - <table border="1"> - <colgroup> - <col width="31%"> - <col width="31%"> - <col width="38%"> - </colgroup> - <thead valign="bottom"> - <tr> - <th colspan="2">Inputs - <th>Output - <tr> - <th>A - <th>B - <th>A or B - <tbody valign="top"> - <tr> - <td>False - <td>False - <td>False - <tr> - <td>True - <td>False - <td>True - <tr> - <td>False - <td>True - <td>True - <tr> - <td>True - <td>True - <td>True - </table> - - </table> - - <h2><a href="#contents" name="transitions" class="backref" - >Transitions</a></h2> - - <p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> -A transition marker is a horizontal line -<br>of 4 or more repeated punctuation -<br>characters.</samp> - - <p><samp>------------</samp> - - <p><samp>A transition should not begin or end a -<br>section or document, nor should two -<br>transitions be immediately adjacent.</samp> - - <td> - <p>A transition marker is a horizontal line - of 4 or more repeated punctuation - characters.</p> - - <hr> - - <p>A transition should not begin or end a - section or document, nor should two - transitions be immediately adjacent. - </table> - - <p>Transitions are commonly seen in novels and short fiction, as a - gap spanning one or more lines, marking text divisions or - signaling changes in subject, time, point of view, or emphasis. - - <h2><a href="#contents" name="explicit-markup" class="backref" - >Explicit Markup</a></h2> - - <p>Explicit markup blocks are used for constructs which float - (footnotes), have no direct paper-document representation - (hyperlink targets, comments), or require specialized processing - (directives). They all begin with two periods and whitespace, the - "explicit markup start". - - <h3><a href="#contents" name="footnotes" class="backref" - >Footnotes</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Footnote references, like [5]_.</samp> - <br><samp>Note that footnotes may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [5] A numerical footnote. Note</samp> - <br><samp> there's no colon after the ``]``.</samp> - - <td> - Footnote references, like <sup><a href="#5">5</a></sup>. - Note that footnotes may get rearranged, e.g., to the bottom of - the "page". - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. - Note there's no colon after the <samp>]</samp>. - </table> - - <tr valign="top"> - <td> - <samp>Autonumbered footnotes are</samp> - <br><samp>possible, like using [#]_ and [#]_.</samp> - <p><samp>.. [#] This is the first one.</samp> - <br><samp>.. [#] This is the second one.</samp> - - <p><samp>They may be assigned 'autonumber</samp> - <br><samp>labels' - for instance, - <br>[#fourth]_ and [#third]_.</samp> - - <p><samp>.. [#third] a.k.a. third_</samp> - <p><samp>.. [#fourth] a.k.a. fourth_</samp> - <td> - Autonumbered footnotes are possible, like using <sup><a - href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. - - <p>They may be assigned 'autonumber labels' - for instance, - <sup><a href="#fourth">4</a></sup> and <sup><a - href="#third">3</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. - <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. - <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> - <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> - </table> - - <tr valign="top"> - <td> - <samp>Auto-symbol footnotes are also</samp> - <br><samp>possible, like this: [*]_ and [*]_.</samp> - <p><samp>.. [*] This is the first one.</samp> - <br><samp>.. [*] This is the second one.</samp> - - <td> - Auto-symbol footnotes are also - possible, like this: <sup><a href="#symbol1">*</a></sup> - and <sup><a href="#symbol2">†</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote - <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. - </table> - - </table> - - <p>The numbering of auto-numbered footnotes is determined by the - order of the footnotes, not of the references. For auto-numbered - footnote references without autonumber labels - ("<samp>[#]_</samp>"), the references and footnotes must be in the - same relative order. Similarly for auto-symbol footnotes - ("<samp>[*]_</samp>"). - - <h3><a href="#contents" name="citations" class="backref" - >Citations</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Citation references, like [CIT2002]_.</samp> - <br><samp>Note that citations may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [CIT2002] A citation</samp> - <br><samp> (as often used in journals).</samp> - - <p><samp>Citation labels contain alphanumerics,</samp> - <br><samp>underlines, hyphens and fullstops.</samp> - <br><samp>Case is not significant.</samp> - - <p><samp>Given a citation like [this]_, one</samp> - <br><samp>can also refer to it like this_.</samp> - - <p><samp>.. [this] here.</samp> - - <td> - Citation references, like <a href="#cit2002">[CIT2002]</a>. - Note that citations may get rearranged, e.g., to the bottom of - the "page". - - <p>Citation labels contain alphanumerics, underlines, hyphens - and fullstops. Case is not significant. - - <p>Given a citation like <a href="#this">[this]</a>, one - can also refer to it like <a href="#this">this</a>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Citations: --> - <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation - (as often used in journals). - <tr><td><a name="this"><strong>[this]</strong></a><td> here. - </table> - - </table> - - <h3><a href="#contents" name="hyperlink-targets" class="backref" - >Hyperlink Targets</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>) - - <h4><a href="#contents" name="external-hyperlink-targets" class="backref" - >External Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td rowspan="2"> - <samp>External hyperlinks, like Python_.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <tr><td>External hyperlinks, like - <a href="http://www.python.org/">Python</a>. - </table> - <tr valign="top"> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Call-out form</em> - <tr><td>External hyperlinks, like - <a href="#labPython"><i>Python</i></a>. - - <p><table> - <tr><td colspan="2"><hr> - <tr><td><a name="labPython"><i>Python:</i></a> - <td> <a href="http://www.python.org/">http://www.python.org/</a> - </table> - </table> - </table> - - <p>"<em>Fold-in</em>" is the representation typically used in HTML - documents (think of the indirect hyperlink being "folded in" like - ingredients into a cake), and "<em>call-out</em>" is more suitable for - printed documents, where the link needs to be presented explicitly, for - example as a footnote. You can force usage of the call-out form by - using the - "<a href="../../ref/rst/directives.html#target-notes">target-notes</a>" - directive. - - <p>reStructuredText also provides for <b>embedded URIs</b> (<a - href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>), - a convenience at the expense of readability. A hyperlink - reference may directly embed a target URI inline, within angle - brackets. The following is exactly equivalent to the example above: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td rowspan="2"> - <samp>External hyperlinks, like `Python -<br><http://www.python.org/>`_.</samp> - <td>External hyperlinks, like - <a href="http://www.python.org/">Python</a>. - </table> - - <h4><a href="#contents" name="internal-hyperlink-targets" class="backref" - >Internal Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td rowspan="2"><samp>Internal crossreferences, like example_.</samp> - - <p><samp>.. _example:</samp> - - <p><samp>This is an example crossreference target.</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <!-- Note that some browsers may not like an "a" tag that --> - <!-- does not have any content, so we could arbitrarily --> - <!-- use the first word as content - *or* just trust to --> - <!-- luck! --> - <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> - <p><a name="example-foldin">This</a> is an example - crossreference target. - </table> - <tr valign="top"> - <td> - <table width="100%"> - <tr><td bgcolor="#99CCFF"><em>Call-out form</em> - <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> - - <p><a name="example-callout"><i>example:</i></a> - <br>This is an example crossreference target. - </table> - - </table> - - <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" - >Indirect Hyperlink Targets</a></h4> - - <p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Python_ is `my favourite -<br>programming language`__.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - - <p><samp>__ Python_</samp> - - <td> - <p><a href="http://www.python.org/">Python</a> is - <a href="http://www.python.org/">my favourite - programming language</a>. - - </table> - - <p>The second hyperlink target (the line beginning with - "<samp>__</samp>") is both an indirect hyperlink target - (<i>indirectly</i> pointing at the Python website via the - "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink - target</b>. In the text, a double-underscore suffix is used to - indicate an <b>anonymous hyperlink reference</b>. In an anonymous - hyperlink target, the reference text is not repeated. This is - useful for references with long text or throw-away references, but - the target should be kept close to the reference to prevent them - going out of sync. - - <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" - >Implicit Hyperlink Targets</a></h4> - - <p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>) - - <p>Section titles, footnotes, and citations automatically generate - hyperlink targets (the title text or footnote/citation label is - used as the hyperlink name). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead><tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Titles are targets, too</samp> - <br><samp>=======================</samp> - <br><samp>Implict references, like `Titles are</samp> - <br><samp>targets, too`_.</samp> - <td> - <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> - <p>Implict references, like <a href="#title">Titles are - targets, too</a>. - </table> - - <h3><a href="#contents" name="directives" class="backref" - >Directives</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>) - - <p>Directives are a general-purpose extension mechanism, a way of - adding support for new constructs without adding new syntax. For - a description of all standard directives, see <a - href="../../ref/rst/directives.html" >reStructuredText - Directives</a>. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp>For instance:</samp> - - <p><samp>.. image:: images/ball1.gif</samp> - - <td> - For instance: - <p><img src="images/ball1.gif" alt="ball1"> - </table> - - <h3><a href="#contents" name="substitution-references-and-definitions" - class="backref" >Substitution References and Definitions</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>) - - <p>Substitutions are like inline directives, allowing graphics and - arbitrary constructs within text. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp> -The |biohazard| symbol must be -used on containers used to -dispose of medical waste.</samp> - - <p><samp> -.. |biohazard| image:: biohazard.png</samp> - - <td> - - <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol - must be used on containers used to dispose of medical waste. - - </table> - - <h3><a href="#contents" name="comments" class="backref" - >Comments</a></h3> - - <p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>) - - <p>Any text which begins with an explicit markup start but doesn't - use the syntax of any of the constructs above, is a comment. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp>.. This text will not be shown</samp> - <br><samp> (but, for instance, in HTML might be</samp> - <br><samp> rendered as an HTML comment)</samp> - - <td> - <!-- This text will not be shown --> - <!-- (but, for instance in HTML might be --> - <!-- rendered as an HTML comment) --> - - <tr valign="top"> - <td> - <samp>An empty "comment" does not</samp> - <br><samp>"consume" following blocks.</samp> - <p><samp>..</samp> - <p><samp> So this block is not "lost",</samp> - <br><samp> despite its indentation.</samp> - <td> - An empty "comment" does not - "consume" following blocks. - <blockquote> - So this block is not "lost", - despite its indentation. - </blockquote> - </table> - - <h2><a href="#contents" name="getting-help" class="backref" - >Getting Help</a></h2> - - <p>Users who have questions or need assistance with Docutils or - reStructuredText should <a - href="mailto:docutils-users@lists.sourceforge.net" >post a - message</a> to the <a - href="http://lists.sourceforge.net/lists/listinfo/docutils-users" - >Docutils-Users mailing list</a>. The <a - href="http://docutils.sourceforge.net/" >Docutils project web - site</a> has more information. - - <p><hr> - <address> - <p>Authors: - <a href="http://www.tibsnjoan.co.uk/">Tibs</a> - (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) - and David Goodger - (<a href="mailto:goodger@python.org">goodger@python.org</a>) - </address> - <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> - </body> -</html> diff --git a/docutils/docs/user/rst/quickstart.txt b/docutils/docs/user/rst/quickstart.txt deleted file mode 100644 index 735dcf512..000000000 --- a/docutils/docs/user/rst/quickstart.txt +++ /dev/null @@ -1,387 +0,0 @@ -A ReStructuredText Primer -========================= - -:Author: Richard Jones -:Version: $Revision$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -The text below contains links that look like "(quickref__)". These -are relative links that point to the `Quick reStructuredText`_ user -reference. If these links don't work, please refer to the `master -quick reference`_ document. - -__ -.. _Quick reStructuredText: quickref.html -.. _master quick reference: - http://docutils.sourceforge.net/docs/user/rst/quickref.html - - -Structure ---------- - -From the outset, let me say that "Structured Text" is probably a bit -of a misnomer. It's more like "Relaxed Text" that uses certain -consistent patterns. These patterns are interpreted by a HTML -converter to produce "Very Structured Text" that can be used by a web -browser. - -The most basic pattern recognised is a **paragraph** (quickref__). -That's a chunk of text that is separated by blank lines (one is -enough). Paragraphs must have the same indentation -- that is, line -up at their left edge. Paragraphs that start indented will result in -indented quote paragraphs. For example:: - - This is a paragraph. It's quite - short. - - This paragraph will result in an indented block of - text, typically used for quoting other text. - - This is another one. - -Results in: - - This is a paragraph. It's quite - short. - - This paragraph will result in an indented block of - text, typically used for quoting other text. - - This is another one. - -__ quickref.html#paragraphs - -Text styles ------------ - -(quickref__) - -__ quickref.html#inline-markup - -Inside paragraphs and other bodies of text, you may additionally mark -text for *italics* with "``*italics*``" or **bold** with -"``**bold**``". - -If you want something to appear as a fixed-space literal, use -"````double back-quotes````". Note that no further fiddling is done -inside the double back-quotes -- so asterisks "``*``" etc. are left -alone. - -If you find that you want to use one of the "special" characters in -text, it will generally be OK -- reStructuredText is pretty smart. -For example, this * asterisk is handled just fine. If you actually -want text \*surrounded by asterisks* to **not** be italicised, then -you need to indicate that the asterisk is not special. You do this by -placing a backslash just before it, like so "``\*``" (quickref__), or -by enclosing it in double back-quotes (inline literals), like this:: - - ``\*`` - -__ quickref.html#escaping - -Lists ------ - -Lists of items come in three main flavours: **enumerated**, -**bulleted** and **definitions**. In all list cases, you may have as -many paragraphs, sublists, etc. as you want, as long as the left-hand -side of the paragraph or whatever aligns with the first line of text -in the list item. - -Lists must always start a new paragraph -- that is, they must appear -after a blank line. - -**enumerated** lists (numbers, letters or roman numerals; quickref__) - __ quickref.html#enumerated-lists - - Start a line off with a number or letter followed by a period ".", - right bracket ")" or surrounded by brackets "( )" -- whatever you're - comfortable with. All of the following forms are recognised:: - - 1. numbers - - A. upper-case letters - and it goes over many lines - - with two paragraphs and all! - - a. lower-case letters - - 3. with a sub-list starting at a different number - 4. make sure the numbers are in the correct sequence though! - - I. upper-case roman numerals - - i. lower-case roman numerals - - (1) numbers again - - 1) and again - - Results in (note: the different enumerated list styles are not - always supported by every web browser, so you may not get the full - effect here): - - 1. numbers - - A. upper-case letters - and it goes over many lines - - with two paragraphs and all! - - a. lower-case letters - - 3. with a sub-list starting at a different number - 4. make sure the numbers are in the correct sequence though! - - I. upper-case roman numerals - - i. lower-case roman numerals - - (1) numbers again - - 1) and again - -**bulleted** lists (quickref__) - __ quickref.html#bullet-lists - - Just like enumerated lists, start the line off with a bullet point - character - either "-", "+" or "*":: - - * a bullet point using "*" - - - a sub-list using "-" - - + yet another sub-list - - - another item - - Results in: - - * a bullet point using "*" - - - a sub-list using "-" - - + yet another sub-list - - - another item - -**definition** lists (quickref__) - __ quickref.html#definition-lists - - Unlike the other two, the definition lists consist of a term, and - the definition of that term. The format of a definition list is:: - - what - Definition lists associate a term with a definition. - - *how* - The term is a one-line phrase, and the definition is one or more - paragraphs or body elements, indented relative to the term. - Blank lines are not allowed between term and definition. - - Results in: - - what - Definition lists associate a term with a definition. - - *how* - The term is a one-line phrase, and the definition is one or more - paragraphs or body elements, indented relative to the term. - Blank lines are not allowed between term and definition. - -Preformatting (code samples) ----------------------------- -(quickref__) - -__ quickref.html#literal-blocks - -To just include a chunk of preformatted, never-to-be-fiddled-with -text, finish the prior paragraph with "``::``". The preformatted -block is finished when the text falls back to the same indentation -level as a paragraph prior to the preformatted block. For example:: - - An example:: - - Whitespace, newlines, blank lines, and all kinds of markup - (like *this* or \this) is preserved by literal blocks. - Lookie here, I've dropped an indentation level - (but not far enough) - - no more example - -Results in: - - An example:: - - Whitespace, newlines, blank lines, and all kinds of markup - (like *this* or \this) is preserved by literal blocks. - Lookie here, I've dropped an indentation level - (but not far enough) - - no more example - -Note that if a paragraph consists only of "``::``", then it's removed -from the output:: - - :: - - This is preformatted text, and the - last "::" paragraph is removed - -Results in: - -:: - - This is preformatted text, and the - last "::" paragraph is removed - -Sections --------- - -(quickref__) - -__ quickref.html#section-structure - -To break longer text up into sections, you use **section headers**. -These are a single line of text (one or more words) with adornment: an -underline alone, or an underline and an overline together, in dashes -"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the -non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you -feel comfortable with. An underline-only adornment is distinct from -an overline-and-underline adornment using the same character. The -underline/overline must be at least as long as the title text. Be -consistent, since all sections marked with the same adornment style -are deemed to be at the same level:: - - Chapter 1 Title - =============== - - Section 1.1 Title - ----------------- - - Subsection 1.1.1 Title - ~~~~~~~~~~~~~~~~~~~~~~ - - Section 1.2 Title - ----------------- - - Chapter 2 Title - =============== - -This results in the following structure, illustrated by simplified -pseudo-XML:: - - <section> - <title> - Chapter 1 Title - <section> - <title> - Section 1.1 Title - <section> - <title> - Subsection 1.1.1 Title - <section> - <title> - Section 1.2 Title - <section> - <title> - Chapter 2 Title - -(Pseudo-XML uses indentation for nesting and has no end-tags. It's -not possible to show actual processed output, as in the other -examples, because sections cannot exist inside block quotes. For a -concrete example, compare the section structure of this document's -source text and processed output.) - -Note that section headers are available as link targets, just using -their name. To link to the Lists_ heading, I write "``Lists_``". If -the heading has a space in it like `text styles`_, we need to quote -the heading "```text styles`_``". - - -Document Title / Subtitle -````````````````````````` - -The title of the whole document is distinct from section titles and -may be formatted somewhat differently (e.g. the HTML writer by default -shows it as a centered heading). - -To indicate the document title in reStructuredText, use a unique adornment -style at the beginning of the document. To indicate the document subtitle, -use another unique adornment style immediately after the document title. For -example:: - - ================ - Document Title - ================ - ---------- - Subtitle - ---------- - - Section Title - ============= - - ... - -Note that "Document Title" and "Section Title" above both use equals -signs, but are distict and unrelated styles. The text of -overline-and-underlined titles (but not underlined-only) may be inset -for aesthetics. - - -Images ------- - -(quickref__) - -__ quickref.html#directives - -To include an image in your document, you use the the ``image`` directive__. -For example:: - - .. image:: images/biohazard.png - -results in: - -.. image:: images/biohazard.png - -The ``images/biohazard.png`` part indicates the filename of the image -you wish to appear in the document. There's no restriction placed on -the image (format, size etc). If the image is to appear in HTML and -you wish to supply additional information, you may:: - - .. image:: images/biohazard.png - :height: 100 - :width: 200 - :scale: 50 - :alt: alternate text - -See the full `image directive documentation`__ for more info. - -__ ../../ref/rst/directives.html -__ ../../ref/rst/directives.html#images - - -What Next? ----------- - -This primer introduces the most common features of reStructuredText, -but there are a lot more to explore. The `Quick reStructuredText`_ -user reference is a good place to go next. For complete details, the -`reStructuredText Markup Specification`_ is the place to go [#]_. - -Users who have questions or need assistance with Docutils or -reStructuredText should post a message to the Docutils-users_ mailing -list. - -.. [#] If that relative link doesn't work, try the master document: - http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. - -.. _reStructuredText Markup Specification: - ../../ref/rst/restructuredtext.html -.. _Docutils-users: ../mailing-lists.html#docutils-users -.. _Docutils project web site: http://docutils.sourceforge.net/ diff --git a/docutils/docs/user/slide-shows.txt b/docutils/docs/user/slide-shows.txt deleted file mode 100644 index 6732f4f44..000000000 --- a/docutils/docs/user/slide-shows.txt +++ /dev/null @@ -1,1004 +0,0 @@ -.. include:: <s5defs.txt> - -================================= - Easy Slide Shows With reST & S5 -================================= - -:Authors: David Goodger & Chris Liechti -:Date: $Date$ - -.. This document has been placed in the public domain. - -.. container:: handout - - How to create quick, good-looking presentation slide shows with - Docutils_/reStructuredText_ and S5_. - - This document serves both as a user manual and as a usage example - of the s5_html.py writer and the rst2s5.py front end. - - To view this document as a slide show see - http://docutils.sf.net/docs/user/slide-shows.s5.html (or `your - local copy <slide-shows.s5.html>`__). - -.. contents:: - :class: handout - -.. class:: tiny - -* S5 themes are designed for full-screen display areas with a 4:3 - aspect ratio. If the slide text doesn't fit in your browser window, - try decreasing the text size. - -* Use the space bar to advance, Page Up/Down & arrow keys to navigate. - -* Best viewed in Firefox_, Safari, and Konqueror. Click the "|mode|" - button to switch between presentation & handout/outline modes. Hit - the "C" key to display the navigation controls, or mouse over the - lower right-hand corner. - -* Functionality is limited in Opera. Switch to full-screen mode (F11 - key) to activate Opera Show. - -* S5 works in Internet Explorer, but it may look ugly. - -.. container:: handout - - The first slide of a presentation consists of all visible text up - to the first section title. The document title is also added to - the footer of all slides. - - The "footer" directive is used to specify part of the slide footer - text. It is currently limited to one short line (one paragraph). - - There is no support for the "header" directive in the themes - included with Docutils. - -.. _Docutils: http://docutils.sourceforge.net/ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _S5: http://meyerweb.com/eric/tools/s5/ -.. _Firefox: http://www.mozilla.com/firefox/ -.. |bullet| unicode:: U+02022 -.. |mode| unicode:: U+00D8 .. capital o with stroke - -.. footer:: Location |bullet| Date - - -Introduction -============ - -.. class:: handout - - ``rst2s5.py`` is a Docutils_ front end that outputs HTML for use - with S5_, a "Simple Standards-based Slide Show System" by Eric - Meyer. - -.. topic:: Installation - :class: handout - - Prerequisites: Python and the Docutils_ package have to be - installed. See the `Docutils README`__ file for installation - instructions. - - __ http://docutils.sourceforge.net/README.html - -* reStructuredText - - .. class:: handout - - Uses normal reStructuredText as input. - -* One section per slide - - .. class:: handout - - Each first-level section is converted into a single slide. - -* XHTML output - - .. container:: handout - - Presentations can be viewed using most modern graphical web - browsers. The browser must support CSS, JavaScript, and XHTML. - S5 even works with IE! - - S5 was designed to add the functionality of the `Opera Show`_ - standard (without Opera Show's limitations) to non-Opera - browsers. Unfortunately, most of S5's CSS and JavaScript - extensions don't function in the Opera browser. - - .. _Opera Show: http://www.opera.com/support/tutorials/operashow/ - -* Themes - - .. class:: handout - - A variety of themes are available. See `Example Themes`_, below. - -* ``rst2s5.py`` - - .. class:: handout - - The front-end tool to generate S5 slide shows. - -.. topic:: Keyboard Controls - :class: handout - - The following apply in any supporting browser besides Opera, which - uses the default Opera Show controls instead. - - .. list-table:: - :header-rows: 1 - - * - Action - - Key(s) - * - Go to the next slide - - * [Space bar] - * [Return] - * [Enter] - * [Right arrow] - * [Down arrow] - * [Page down] - * Click the left mouse button outside of the control area, - Flash object, or movie - * - Go to the previous slide - - * [Left arrow] - * [Up arrow] - * [Page up] - * - Go to the title (first) slide - - [Home] - * - Go to the last slide - - [End] - * - Jump directly to a slide - - Type the slide number, then hit [Return] or [Enter] - * - Skip forward *n* slides - - Type the number of slides to skip, then hit any "go to next" - key (except [Return] or [Enter]) - * - Skip backward *n* slides - - Type the number of slides to skip, then hit any "go to - previous" key - * - Switch between slideshow and outline view - - * [T] - * Click the |mode| button - * - Show/hide slide controls - - * [C] - * Move the mouse pointer over the control area - - Further details of the S5 user interface can be found at `Eric - Meyer's S5 page`__. - - __ S5_ - - -Features (1) -============ - -.. container:: handout - - The S5/HTML Writer supports all the standard Docutils HTML - features. S5 has been released to the Public Domain. - -S5-specific features: - -.. class:: incremental - -* The document title is duplicated on each slide in the S5 footer. - -* The ``footer`` directive may be used to define additional text in - the S5 footer. - - .. container:: handout - - But it is limited to one line of text. - - This is useful for information such as the date of the - presentation and/or the location. The field in the footer is - left blank if no ``footer`` directive is used. - - Example:: - - .. footer:: Location - Date - - There is also a progress indicator (slide counter) in the footer - that can be enabled. It's disabled by default. - -* Incremental display. - - .. class:: handout - - An "incremental" class can be assigned to lists and other elements - to get one-item-at-a-time behavior (like this list). Incremental - display does not work in the Opera browser. - -* Text auto-scaling. - - .. class:: handout - - The text size adjusts relative to the size of your browser window - automatically. You may need to reload the document after resizing - the window. The browser and platform affect the font used; be sure - to test the slide show on the presentation system. - - -Features (2): Handouts -====================== - -.. container:: handout - - The contents of any element with a "class" attribute value of - "handout" are hidden in the slide presentation, and are only - visible when the presentation is printed, or viewed in outline - mode. "Handout"-class elements can appear anywhere in the text, as - often as needed. - - This means that the slides and extra handout material can be - combined in one document. The handout can be printed directly from - the browser, and it will contain more than just silly framed - slides. This can be used to provide more detailed information, or - for speaker's notes. - -.. class:: incremental - -* Use the "class" directive:: - - .. class:: handout - - .. container:: handout - - The ``.. class:: handout`` directive can be used to tag - individual paragraphs and other elements. The "class" directive - applies to the first element immediately following:: - - .. class:: handout - - This paragraph will get a - ``class="handout"`` attribute. - - This paragraph will not be affected. - - It also applies to multiple elements in the directive content:: - - .. class:: handout - - These paragraphs are the content - of the "class" directive. And as such... - - Both paragraphs will *individually* receive - ``class="handout"`` attributes. - -* Use the "container" directive:: - - .. container:: handout - - .. container:: handout - - Arbitrary handout blocks can be created using the ``container`` - directive. The content is treated as one. - -* Use the "class" option of directives that support it:: - - .. topic:: Extra Material For Handouts - :class: handout - -.. container:: handout - - The following directives support "class" options: - - * all admonition directives ("admonition", "note", "hint", etc.) - * "image" & "figure" - * "topic" - * "sidebar" - * "line-block" - * "parsed-literal" - * "rubric" - * "compound" - * "table", "csv-table", & "list-table" - * "target-notes" (more about that below) - * "role" (pre-defined; more below) - - Handout contents are also visible on the screen if the S5 view mode - is toggled from "slide show" to "outline" mode. - - -Caveats -======= - -.. class:: incremental - -1. Some Docutils features are not supported by some themes. - - .. container:: handout - - For example, header rendering is not supported by the themes - supplied with Docutils. - - The "header" directive is used to set header text. S5 - automatically inserts section/slide titles into the "header" - area of a slide. If both Docutils headers and S5 headers (slide - titles) exist simultaneously, they interfere with each other. - -2. Care must be taken with the "contents" directive. - - .. container:: handout - - The ``--no-toc-backlinks`` option is the default for the S5/HTML - writer (``toc_backlinks=0`` setting). Other values for this - setting will change the CSS class of headings such that they - won't show up correctly in the slide show. - - Use the ``:class: handout`` option on the "contents" directive - to limit the table of contents to the handout/outline mode - only:: - - .. contents:: - :class: handout - - -.. class:: incremental - -3. Subsections ... ------------------- - -... may be used, sparingly. - -.. container:: handout - - Only first-level sections become slides. Not many levels of - subsections can fit on a slide. - - Subsections (of any level) work normally in handouts though. Add - "``.. class:: handout``" before a subsection (or sub-subsection, or - ...), and the entire subsection will only appear in the handout. - - -Generating a Slide Show (1) -=========================== - -.. class:: incremental - -1. Open a console (terminal, command shell) and go to the folder - containing your file, ``slides.txt``. - -2. Run the command:: - - rst2s5.py slides.txt slides.html - -3. Specify an S5 theme with the ``--theme`` option. - - .. class:: handout - - Docutils will copy the S5 theme files into a ``ui/<theme>`` folder - beside the output HTML file. A slide show can also link to an - existing theme using the ``--theme-url`` option. - - -Generating a Slide Show (2) -=========================== - -.. class:: incremental - -4. Include a copy of any linked stylesheet. - - .. class:: handout - - The default Docutils stylesheet, ``html4css1.css``, will normally - be embedded in the output HTML. If you choose to link to a - stylesheet instead of embedding, you must include a copy (suggested - location: in the ``ui/`` directory). - -5. Open ``slides.html`` in a web browser. - -6. Expand the browser window to full-screen mode, and speak. - - .. class:: handout - - The `Web Developer`__ extension for Firefox is very useful. With - it, you can resize your browser window to the exact dimensions of - the projector you'll be using, so you can test beforehand. There - are many other useful features as well. - - __ http://chrispederick.com/work/webdeveloper/ - -7. Profit! - - -Examples (1) -============ - -.. sidebar:: Hint - - Admonitions, tables, sidebars, and other elements can be used in - on-screen presentations in handouts. Images too! - - .. image:: images/happy_monkey.png - :alt: sample image - -===== ===== ====== - A B A or B -===== ===== ====== -False False False -True False True -False True True -True True True -===== ===== ====== - - -Examples (2): Incremental Text -============================== - -.. class:: incremental - - Paragraphs can be displayed one at a time... - - .. container:: - - ... or a bunch at a time. - - This second paragraph is displayed together with the previous - one by grouping them with the "container" directive. - -`We can also display` `one` `word` `at` `a` `time,` -`or a phrase` `at a time,` -`or even` `o`\ `n`\ `e` `l`\ `e`\ `t`\ `t`\ `e`\ `r` `at a time!` - -`(But the markup ain't pretty.)` - - -Examples (3): Incr. Graphics -============================ - -Let's play... Rock, Scissors, Paper - -.. container:: animation - - .. image:: images/rsp-empty.png - :class: hidden slide-display - - .. class:: incremental hidden slide-display - - .. image:: images/rsp-objects.png - .. image:: images/rsp-cuts.png - .. image:: images/rsp-covers.png - .. image:: images/rsp-breaks.png - - .. image:: images/rsp-all.png - :class: incremental - - -Themes -====== - -.. class:: incremental - -* Several themes are available, and they're easy to adapt. - - .. container:: handout - - Themes from the `S5 tutorial`__ can be used. These themes are in - the public domain and may be redistributed freely. - - __ http://meyerweb.com/eric/tools/s5/s5blank.zip - - Sites with other S5 themes: - - * http://meyerweb.com/eric/tools/s5/themes/ - * http://mozilla.wikicities.com/wiki/Firefox_S5:Designs - * http://lachy.id.au/dev/mozilla/firefox/s5/ - - S5 is becoming more popular every day. Do a web search for "S5 - theme" and you're bound to find plenty of choices. - -* "``--theme``" option. - - .. container:: handout - - The theme can be specified with the "``--theme``" command-line - option. - - Example:: - - rst2s5 --theme big-black slides.txt slides.html - - The default theme is "default". - -* "``theme``" setting. - - .. class:: handout - - You can set the theme with the "``theme``" configuration file - setting. - -* Copied to ``./ui/<theme>/``. - - .. class:: handout - - Themes are copied into a ``ui/<theme>`` folder inside the folder - containing the presentation. - -* Link with "``--theme-url``" option. - - .. class:: handout - - Link to a theme on the same or another web site, using the - "``--theme-url``" option or "``theme_url``" configuration file - setting. - - -Example Themes -============== - -.. class:: handout - - The default theme, "default", is a simplified version of S5's - default theme. It accommodates up to 13 lines of text. - -.. class:: center - - "default" - - .. image:: images/default.png - :align: center - - -Example Themes: Small Text -========================== - -.. class:: handout - - The "small-white" and "small-black" themes are simplifications of - the default theme (**small** black text on a **white** background, - and **small** black text on a **white** background, respectively). - They each accommodate up to 15 lines of text. - -.. list-table:: - :class: borderless - - * - "small-white" - - .. image:: images/small-white.png - - - "small-black" - - .. image:: images/small-black.png - - -Example Themes: Large Text -========================== - -.. class:: handout - - The "big-white" and "big-black" themes feature very large, bold - text, with no footers. Only five short lines fit in a slide. - -.. list-table:: - :class: borderless - - * - "big-white" - - .. image:: images/big-white.png - - - "big-black" - - .. image:: images/big-black.png - - -Example Themes: Medium Text -=========================== - -.. class:: handout - - The "medium-white" and "medium-black" themes feature medium-sized - text. Up to 8 lines of text are accommodated. - -.. list-table:: - :class: borderless - - * - "medium-white" - - .. image:: images/medium-white.png - - - "medium-black" - - .. image:: images/medium-black.png - - -S5 Theme Files -============== - -An S5 theme consists of a directory containing several files -- -stylesheets, JavaScript, and graphics: - -.. image:: images/s5-files.png - :align: center - -.. container:: handout - - The generated HTML contains the entire slide show text. It also - contains links to the following files: - - * slides.css simply contains import links to: - - - s5-core.css: Default styles critical to the proper functioning - of the slide show; don't touch this! - - - framing.css: Sets the basic layout of slide components (header, - footer, controls, etc. This file is the often edited. - - - pretty.css: Presentation styles that give the slide show a - unique look and feel. This is the file that you're most likely - to edit for a custom theme. You can make a whole new theme - just by editing this file, and not touching the others. - - * outline.css: Styles for outline mode. - - * print.css: Styles for printing; hides most layout elements, and - may display others. - - * opera.css: Styles necessary for the proper functioning of S5 in - Opera Show. - - * slides.js: the JavaScript that drives the dynamic side of the - slide show (actions and navigation controls). It automatically - IDs the slides when the document loads, builds the navigation - menu, handles the hiding and showing of slides, and so on. The - code also manages the fallback to Opera Show if you're using - the Opera web browser. - - Two files are included to support PNG transparency (alpha - channels) in Internet Explorer: - - - iepngfix.htc - - blank.gif - - -Making a Custom Theme -===================== - -.. class:: incremental - -1. Run "``rst2s5.py --theme <base-theme> <doc>.txt <doc>.html``". - - .. class:: handout - - This initializes the ``ui`` directory with the base theme files. - -2. Copy ``ui/<base-theme>`` to ``ui/<new-theme>``. - -3. Edit the styles. - - .. class:: handout - - Start with ``pretty.css``; edit ``framing.css`` if you need to make - layout changes. - -4. Run "``rst2s5.py --theme <new-theme> <doc>.txt <doc>.html``". - - .. class:: handout - - Open your ``<doc>.html`` in a browser to test the new theme. - -5. Rinse & repeat. - - .. class:: handout - - Repeat from step 3 until you're satisfied. - -.. TODO: What to do next: - - * add a ``__base__`` file - * create a personal reusable theme (plugin) - * submit the new theme to Docutils - - ``docutils/writers/s5_html/themes/<theme>`` - -.. container:: handout - - Resources: - - * W3C's `Learning CSS <http://www.w3.org/Style/CSS/learning>`__ - - * `Creating An S5 Theme <http://home.cogeco.ca/~ve3ll/s5themes.htm>`__ - - * A short tutorial on how to create themes (in German): - `Eigenes Theme erstellen <http://yatil.de/s5/dokumentation/9/>`__ - - -Classes: Incremental (1) -======================== - -.. class:: handout - - Several "class" attribute values have built-in support in the - themes supplied with Docutils. - -.. class:: incremental - - As described earlier, - - * ``.. class:: incremental`` - - * ``.. container:: incremental`` - - * :: - - .. sidebar:: title - :class: incremental - - -Classes: Incremental (2) -======================== - -The "incremental" interpreted text role is also supported: - -.. class:: incremental - - :: - - :incremental:`This will appear first,` `and - this will appear second.`:incremental: - - Requires "``.. include:: <s5defs.txt>``". - -.. container:: handout - - As you can see, this markup is not very convenient. - -.. class:: incremental - - | But ``s5defs.txt`` includes this useful definition: - | "``.. default-role:: incremental``". So: - - :: - - `This` `is` `all` `we` `need` - -`This` `is` `all` `we` `need` `to mark up incremental text.` - - -Classes: Incremental (3) -======================== - -.. class:: small - -:: - - .. container:: animation - - .. image:: images/empty.png - :class: hidden slide-display - - .. class:: incremental hidden slide-display - - .. image:: images/1.png - .. image:: images/2.png - - .. image:: images/3.png - :class: incremental - -.. container:: handout - - This is how the example works. - - The animation effects are caused by placing successive images at - the same location, laying each image over the last. For best - results, all images should be the same size, and the positions of - image elements should be consistent. Use image transparency (alpha - channels) to get overlay effects. - - Absolute positioning is used, which means that the images take up - no space in the flow. If you want text to follow the images, you - have to specify the total size of the container via a style. - Otherwise, the images and any following text will overlap. - - These class values do the work: - - animation - This wraps the container with styles that position the images - absolutely, overlaying them over each other. Only useful on a - container. - - hidden - Unless overridden (by "slide-display", for example), these - elements will not be displayed. Only the last image will be - displayed in handout mode, when print, or when processed to - ordinary HTML, because it does *not* carry a "hidden" class. - - slide-display - In conjunction with "hidden", these elements will only appear - on the slide, preventing clutter in the handout. - - incremental - The second and subsequent images will appear one at a time. - The first image will already be present when the slide is - displayed, because it does *not* carry an "incremental" class. - - -Classes: Text Size -================== - -.. class:: incremental - - * :tiny:`tiny` (class & role name: "tiny", e.g. "``:tiny:`text```") - * :small:`small` ("small") - * normal (unstyled) - * :big:`big` ("big") - * :huge:`huge` ("huge") - - Requires "``.. include:: <s5defs.txt>``". - - -Classes: Alignment -================== - -.. class:: incremental - - .. class:: left - - Left (class name: "left") - - .. class:: center - - Center ("center" & "centre") - - .. class:: right - - Right ("right") - -.. class:: handout - - These classes apply to block-level elements only. They cannot be - used for inline text (i.e., they're not interpreted text roles). - -.. class:: incremental - - Example:: - - .. class:: center - - Text to be centered. - - -Classes: Text Colours -===================== - -:black:`black` [black], :gray:`gray`, :silver:`silver`, :white:`white` -[white], :maroon:`maroon`, :red:`red`, :magenta:`magenta`, -:fuchsia:`fuchsia`, :pink:`pink`, :orange:`orange`, :yellow:`yellow`, -:lime:`lime`, :green:`green`, :olive:`olive`, :teal:`teal`, -:cyan:`cyan`, :aqua:`aqua`, :blue:`blue`, :navy:`navy`, -:purple:`purple` - -The class names and role names are the same as the colour names. For -example, "``:orange:`text```" produces ":orange:`text`". - -.. class:: incremental - -Requires "``.. include:: <s5defs.txt>``". - - -Classes: Borderless Tables -========================== - -.. class:: handout - - Here's an ordinary, unstyled table: - -.. class:: incremental - - ========= ======= - Sometimes borders - --------- ------- - are useful. - ========= ======= - - And after applying "``.. class:: borderless``": - - .. class:: borderless - - ======= ========== ======= - But sometimes, borders - ------- ---------- ------- - are **not** wanted. - ======= ========== ======= - - -Classes: Print-Only -=================== - -.. class:: handout - - Elements with ``class="print"`` attributes display their contents - when printed, overriding ``class="hidden"``. - -.. class:: incremental - - Example: the "target-notes" directive:: - - .. topic:: Links - :class: hidden print - - .. target-notes:: - :class: hidden print - -.. container:: handout - - One good example, used in this document, is the "target-notes" - directive. For each external target (hyperlink) in the text, this - directive generates a footnote containing the visible URL as - content. Footnote references are placed after each hyperlink - reference. - - The "topic" directive is given a "class" attribute with values - "hidden" and "print", so the entire topic will only be displayed - when printed. The "target-notes" directive also assigns a "class" - attributes with values "hidden" and "print" to each of the footnote - references it inserts throughout the text; they will only show up - when printed. - -.. class:: incremental - - Other uses may require "``.. include:: <s5defs.txt>``". - - -Useful Extensions For Firefox -============================= - -* `Autohide`__ - - .. class:: handout - - Automatically hides toolbars in full-screen mode. - - __ http://www.krickelkrackel.de/autohide/autohide.htm - -* `Web Developer`__ - - .. class:: handout - - Adds a context submenu and a toolbar with a lot of useful - functionality, including the viewing and live editing of - stylesheets, and sizing the browser window. - - __ http://chrispederick.com/work/webdeveloper/ - - -To Do -===== - -.. class:: incremental - - * Multi-display support: - - - speaker's notes on the laptop screen - - slides on the projector - - two views stay in sync - - presentation controlled from either display - - * Add timeout to incremental style. - - .. class:: handout - - I.e., incremental-specific style should go away (revert to - normal) after a certain interval. - - These will require some serious JavaScript-fu! - - -That's All, Folks! -================== - -.. class:: huge - - Further information: - http://docutils.sf.net - - Docutils users' mailing list: - docutils-users@lists.sf.net - - `Any questions?` - - -.. topic:: Links - :class: hidden print - - .. target-notes:: :class: hidden print diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt deleted file mode 100644 index 20f5a3b2f..000000000 --- a/docutils/docs/user/tools.txt +++ /dev/null @@ -1,389 +0,0 @@ -========================== - Docutils Front-End Tools -========================== - -:Author: David Goodger -:Contact: goodger@python.org -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - --------------- - Introduction --------------- - -Once the Docutils package is unpacked, you will discover a "``tools``" -directory containing several front ends for common Docutils -processing. Rather than a single all-purpose program, Docutils has -many small front ends, each specialized for a specific "Reader" (which -knows how to interpret a file in context), a "Parser" (which -understands the syntax of the text), and a "Writer" (which knows how -to generate a specific data format). - -Most front ends have common options and the same command-line usage -pattern:: - - toolname [options] [<source> [<destination]] - -(The exceptions are buildhtml.py_ and rstpep2html.py_.) See -rst2html.py_ for concrete examples. Each tool has a "``--help``" -option which lists the `command-line options`_ and arguments it -supports. Processing can also be customized with `configuration -files`_. - -The two arguments, "source" and "destination", are optional. If only -one argument (source) is specified, the standard output (stdout) is -used for the destination. If no arguments are specified, the standard -input (stdin) is used for the source as well. - - -Getting Help -============ - -First, try the "``--help``" option each front-end tool has. - -Users who have questions or need assistance with Docutils or -reStructuredText should post a message to the Docutils-users_ mailing -list. - -.. _Docutils-users: mailing-lists.html#docutils-users - - ------------ - The Tools ------------ - -HTML-Generating Tools -===================== - -buildhtml.py ------------- - -:Readers: Standalone, PEP -:Parser: reStructuredText -:Writers: HTML, PEP/HTML - -Use ``buildhtml.py`` to generate .html from all the .txt files -(including PEPs) in each <directory> given, and their subdirectories -too. (Use the ``--local`` option to skip subdirectories.) - -Usage:: - - buildhtml.py [options] [<directory> ...] - -After unpacking the Docutils package, the following shell commands -will generate HTML for all included documentation:: - - cd docutils/tools - buildhtml.py .. - -For official releases, the directory may be called "docutils-X.Y", -where "X.Y" is the release version. Alternatively:: - - cd docutils - tools/buildhtml.py --config=tools/docutils.conf - -The current directory (and all subdirectories) is chosen by default if -no directory is named. Some files may generate system messages -(docs/user/rst/demo.txt contains intentional errors); use the -``--quiet`` option to suppress all warnings. The ``--config`` option -ensures that the correct settings are in place (a ``docutils.conf`` -`configuration file`_ in the current directory is picked up -automatically). Command-line options may be used to override config -file settings or replace them altogether. - - -rst2html.py ------------ - -:Reader: Standalone -:Parser: reStructuredText -:Writer: HTML - -The ``rst2html.py`` front end reads standalone reStructuredText source -files and produces HTML 4 (XHTML 1) output compatible with modern -browsers that support cascading stylesheets (CSS). A stylesheet is -required for proper rendering; a simple but complete stylesheet is -installed and used by default (see Stylesheets_ below). - -For example, to process a reStructuredText file "``test.txt``" into -HTML:: - - rst2html.py test.txt test.html - -Now open the "``test.html``" file in your favorite browser to see the -results. To get a footer with a link to the source file, date & time -of processing, and links to the Docutils project, add some options:: - - rst2html.py -stg test.txt test.html - - -Stylesheets -``````````` - -``rst2html.py`` inserts into the generated HTML a cascading stylesheet -(or a link to a stylesheet, when passing the "``--link-stylesheet``" -option). A stylesheet is required for proper rendering. The default -stylesheet (``docutils/writers/html4css1/html4css1.css``, located in -the installation directory) is provided for basic use. To use a -different stylesheet, you must specify the stylesheet's location with -a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a -local file) command-line option, or with `configuration file`_ -settings (e.g. ``./docutils.conf`` or ``~/.docutils``). To experiment -with styles, please see the `guide to writing HTML (CSS) stylesheets -for Docutils`__. - -__ ../howto/html-stylesheets.html - - -rstpep2html.py --------------- - -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML - -``rstpep2html.py`` reads a new-style PEP (marked up with -reStructuredText) and produces HTML. It requires a template file and -a stylesheet. By default, it makes use of a "``pep-html-template``" -file and the "``pep.css``" stylesheet (both in the -``docutils/writers/pep_html/`` directory), but these can be overridden -by command-line options or configuration files. - -For example, to process a PEP into HTML:: - - cd <path-to-docutils>/docs/peps - rstpep2html.py pep-0287.txt pep-0287.html - - -rst2s5.py ---------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: S5/HTML - -The ``rst2s5.py`` front end reads standalone reStructuredText source -files and produces (X)HTML output compatible with S5_, the "Simple -Standards-based Slide Show System" by Eric Meyer. A theme is required -for proper rendering; several are distributed with Docutils and others -are available; see Themes_ below. - -For example, to process a reStructuredText file "``slides.txt``" into -S5/HTML:: - - rst2s5.py slides.txt slides.html - -Now open the "``slides.html``" file in your favorite browser, switch -to full-screen mode, and enjoy the results. - -.. _S5: http://meyerweb.com/eric/tools/s5/ - - -Themes -`````` - -Each S5 theme consists of a directory containing several files: -stylesheets, JavaScript, and graphics. These are copied into a -``ui/<theme>`` directory beside the generated HTML. A theme is chosen -using the "``--theme``" option (for themes that come with Docutils) or -the "``--theme-url``" option (for themes anywhere). For example, the -"medium-black" theme can be specified as follows:: - - rst2s5.py --theme medium-black slides.txt slides.html - -The theme will be copied to the ``ui/medium-black`` directory. - -Several themes are included with Docutils: - -``default`` - This is a simplified version of S5's default theme. - - :Main content: black serif text on a white background - :Text capacity: about 13 lines - :Headers: light blue, bold sans-serif text on a dark blue - background; titles are limited to one line - :Footers: small, gray, bold sans-serif text on a dark blue - background - -``small-white`` - (Small text on a white background.) - - :Main content: black serif text on a white background - :Text capacity: about 15 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: small, dark gray, bold sans-serif text on a white - background - -``small-black`` - :Main content: white serif text on a black background - :Text capacity: about 15 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: small, light gray, bold sans-serif text on a black - background - -``medium-white`` - :Main content: black serif text on a white background - :Text capacity: about 9 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: small, dark gray, bold sans-serif text on a white - background - -``medium-black`` - :Main content: white serif text on a black background - :Text capacity: about 9 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: small, light gray, bold sans-serif text on a black - background - -``big-white`` - :Main content: black, bold sans-serif text on a white background - :Text capacity: about 5 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: not displayed - -``big-black`` - :Main content: white, bold sans-serif text on a black background - :Text capacity: about 5 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: not displayed - -If a theme directory contains a file named ``__base__``, the name of -the theme's base theme will be read from it. Files are accumulated -from the named theme, any base themes, and the "default" theme (which -is the implicit base of all themes). - -For details, please see `Easy Slide Shows With reStructuredText & -S5 <slide-shows.html>`_. - - -LaTeX-Generating Tools -====================== - -rst2latex.py ------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: LaTeX2e - -The ``rst2latex.py`` front end reads standalone reStructuredText -source files and produces LaTeX2e output. For example, to process a -reStructuredText file "``test.txt``" into LaTeX:: - - rst2latex.py test.txt test.tex - -The output file "``test.tex``" should then be processed with ``latex`` -or ``pdflatex`` to get a typeset document. - -Some limitations and difference apply: - -- GIF, JPG and PNG images are not handled, when processed with - ``latex``; use ``pdflatex`` instead. -- Only the Latin-1 output encoding has been tested up to now (Latin-1 - has been made the default output encoding for LaTeX). -- The optional stylesheet file allows the inclusion of special packages - or overwriting default settings for LaTeX. -- Not all constructs are possible, see `Generating LaTeX with Docutils`_. - - -XML-Generating Tools -==================== - -rst2xml.py ----------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: XML (Docutils native) - -The ``rst2xml.py`` front end produces Docutils-native XML output. -This can be transformed with standard XML tools such as XSLT -processors into arbitrary final forms. - - -Testing/Debugging Tools -======================= - -rst2pseudoxml.py ----------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: Pseudo-XML - -``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to -Transform to Writer" pipeline. It produces a compact pretty-printed -"pseudo-XML", where nesting is indicated by indentation (no end-tags). -External attributes for all elements are output, and internal -attributes for any leftover "pending" elements are also given. - - -quicktest.py ------------- - -:Reader: N/A -:Parser: reStructuredText -:Writer: N/A - -The ``quicktest.py`` tool is used for testing the reStructuredText -parser. It does not use a Docutils Reader or Writer or the standard -Docutils command-line options. Rather, it does its own I/O and calls -the parser directly. No transforms are applied to the parsed -document. Various forms output are possible: - -- Pretty-printed pseudo-XML (default) -- Test data (Python list of input and pseudo-XML output strings; - useful for creating new test cases) -- Pretty-printed native XML -- Raw native XML (with or without a stylesheet reference) - - - ---------------- - Customization ---------------- - -Command-Line Options -==================== - -Each front-end tool supports command-line options for one-off -customization. For persistent customization, use `configuration -files`_. Command-line options take priority over configuration file -settings. - -Use the "--help" option on each of the front ends to list the -command-line options it supports. Command-line options and their -corresponding configuration file entry names are listed in the -`Docutils Configuration Files`_ document. - - -.. _configuration file: - -Configuration Files -=================== - -Configuration files are used for persistent customization; they can be -set once and take effect every time you use a front-end tool. - -For details, see `Docutils Configuration Files`_. - -.. _Docutils Configuration Files: config.html -.. _Generating LaTeX with Docutils: latex.html - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: |
