diff options
Diffstat (limited to 'docs')
68 files changed, 31456 insertions, 0 deletions
diff --git a/docs/api/cmdline-tool.txt b/docs/api/cmdline-tool.txt new file mode 100644 index 000000000..3d3d4a635 --- /dev/null +++ b/docs/api/cmdline-tool.txt @@ -0,0 +1,68 @@ +=============================================== + 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/docs/api/publisher.txt b/docs/api/publisher.txt new file mode 100644 index 000000000..73cfc0ef2 --- /dev/null +++ b/docs/api/publisher.txt @@ -0,0 +1,176 @@ +======================== + 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/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt new file mode 100644 index 000000000..2d60aa3e1 --- /dev/null +++ b/docs/api/runtime-settings.txt @@ -0,0 +1,192 @@ +=========================== + 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/docs/dev/distributing.txt b/docs/dev/distributing.txt new file mode 100644 index 000000000..c81807279 --- /dev/null +++ b/docs/dev/distributing.txt @@ -0,0 +1,146 @@ +=============================== + 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/docs/dev/enthought-plan.txt b/docs/dev/enthought-plan.txt new file mode 100644 index 000000000..0ab0d3c83 --- /dev/null +++ b/docs/dev/enthought-plan.txt @@ -0,0 +1,480 @@ +=========================================== + 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/docs/dev/enthought-rfp.txt b/docs/dev/enthought-rfp.txt new file mode 100644 index 000000000..986f5604f --- /dev/null +++ b/docs/dev/enthought-rfp.txt @@ -0,0 +1,146 @@ +================================== + 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/docs/dev/hacking.txt b/docs/dev/hacking.txt new file mode 100644 index 000000000..d0ec9a3fb --- /dev/null +++ b/docs/dev/hacking.txt @@ -0,0 +1,264 @@ +========================== + 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/docs/dev/policies.txt b/docs/dev/policies.txt new file mode 100644 index 000000000..25fb4f2e9 --- /dev/null +++ b/docs/dev/policies.txt @@ -0,0 +1,549 @@ +=========================== + 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/docs/dev/pysource.dtd b/docs/dev/pysource.dtd new file mode 100644 index 000000000..fb8af4091 --- /dev/null +++ b/docs/dev/pysource.dtd @@ -0,0 +1,259 @@ +<!-- +====================================================================== + 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/docs/dev/pysource.txt b/docs/dev/pysource.txt new file mode 100644 index 000000000..6f173a709 --- /dev/null +++ b/docs/dev/pysource.txt @@ -0,0 +1,130 @@ +====================== + 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/docs/dev/release.txt b/docs/dev/release.txt new file mode 100644 index 000000000..fa58bc46f --- /dev/null +++ b/docs/dev/release.txt @@ -0,0 +1,168 @@ +============================= + 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/docs/dev/repository.txt b/docs/dev/repository.txt new file mode 100644 index 000000000..2c613b10e --- /dev/null +++ b/docs/dev/repository.txt @@ -0,0 +1,217 @@ +===================================== + 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/docs/dev/rst/alternatives.txt b/docs/dev/rst/alternatives.txt new file mode 100644 index 000000000..12874c5fb --- /dev/null +++ b/docs/dev/rst/alternatives.txt @@ -0,0 +1,3129 @@ +================================================== + 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/docs/dev/rst/problems.txt b/docs/dev/rst/problems.txt new file mode 100644 index 000000000..bc0101cbf --- /dev/null +++ b/docs/dev/rst/problems.txt @@ -0,0 +1,872 @@ +============================== + 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/docs/dev/semantics.txt b/docs/dev/semantics.txt new file mode 100644 index 000000000..cd20e15f6 --- /dev/null +++ b/docs/dev/semantics.txt @@ -0,0 +1,119 @@ +===================== + 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/docs/dev/testing.txt b/docs/dev/testing.txt new file mode 100644 index 000000000..bde54116f --- /dev/null +++ b/docs/dev/testing.txt @@ -0,0 +1,246 @@ +=================== + 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/docs/dev/todo.txt b/docs/dev/todo.txt new file mode 100644 index 000000000..6f1c6291d --- /dev/null +++ b/docs/dev/todo.txt @@ -0,0 +1,1964 @@ +====================== + 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/docs/dev/website.txt b/docs/dev/website.txt new file mode 100644 index 000000000..193e9c0f2 --- /dev/null +++ b/docs/dev/website.txt @@ -0,0 +1,46 @@ +=================== + 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/docs/howto/html-stylesheets.txt b/docs/howto/html-stylesheets.txt new file mode 100644 index 000000000..9369f2d3c --- /dev/null +++ b/docs/howto/html-stylesheets.txt @@ -0,0 +1,76 @@ +============================================== + 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/docs/howto/i18n.txt b/docs/howto/i18n.txt new file mode 100644 index 000000000..4a5b1de5a --- /dev/null +++ b/docs/howto/i18n.txt @@ -0,0 +1,191 @@ +================================ + 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/docs/howto/rst-directives.txt b/docs/howto/rst-directives.txt new file mode 100644 index 000000000..6210940c8 --- /dev/null +++ b/docs/howto/rst-directives.txt @@ -0,0 +1,399 @@ +====================================== + 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/docs/howto/rst-roles.txt b/docs/howto/rst-roles.txt new file mode 100644 index 000000000..f8ce08bca --- /dev/null +++ b/docs/howto/rst-roles.txt @@ -0,0 +1,228 @@ +================================================== + 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/docs/index.txt b/docs/index.txt new file mode 100644 index 000000000..18761f312 --- /dev/null +++ b/docs/index.txt @@ -0,0 +1,236 @@ +========================================== + 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/docs/peps/pep-0256.txt b/docs/peps/pep-0256.txt new file mode 100644 index 000000000..1e5e87e35 --- /dev/null +++ b/docs/peps/pep-0256.txt @@ -0,0 +1,297 @@ +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/docs/peps/pep-0257.txt b/docs/peps/pep-0257.txt new file mode 100644 index 000000000..23094c56a --- /dev/null +++ b/docs/peps/pep-0257.txt @@ -0,0 +1,328 @@ +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/docs/peps/pep-0258.txt b/docs/peps/pep-0258.txt new file mode 100644 index 000000000..0d646bb82 --- /dev/null +++ b/docs/peps/pep-0258.txt @@ -0,0 +1,1029 @@ +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/docs/peps/pep-0287.txt b/docs/peps/pep-0287.txt new file mode 100644 index 000000000..689d6b919 --- /dev/null +++ b/docs/peps/pep-0287.txt @@ -0,0 +1,815 @@ +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/docs/ref/doctree.txt b/docs/ref/doctree.txt new file mode 100644 index 000000000..25e5f9594 --- /dev/null +++ b/docs/ref/doctree.txt @@ -0,0 +1,4970 @@ +============================ + 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/docs/ref/docutils.dtd b/docs/ref/docutils.dtd new file mode 100644 index 000000000..154566033 --- /dev/null +++ b/docs/ref/docutils.dtd @@ -0,0 +1,606 @@ +<!-- +====================================================================== + 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/docs/ref/rst/definitions.txt b/docs/ref/rst/definitions.txt new file mode 100644 index 000000000..78a2bf8da --- /dev/null +++ b/docs/ref/rst/definitions.txt @@ -0,0 +1,180 @@ +============================================ + 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/docs/ref/rst/directives.txt b/docs/ref/rst/directives.txt new file mode 100644 index 000000000..af88a3d4e --- /dev/null +++ b/docs/ref/rst/directives.txt @@ -0,0 +1,1727 @@ +============================= + 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/docs/ref/rst/introduction.txt b/docs/ref/rst/introduction.txt new file mode 100644 index 000000000..b7829816e --- /dev/null +++ b/docs/ref/rst/introduction.txt @@ -0,0 +1,314 @@ +===================================== + 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/docs/ref/rst/restructuredtext.txt b/docs/ref/rst/restructuredtext.txt new file mode 100644 index 000000000..1445619b3 --- /dev/null +++ b/docs/ref/rst/restructuredtext.txt @@ -0,0 +1,2879 @@ +======================================= + 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/docs/ref/rst/roles.txt b/docs/ref/rst/roles.txt new file mode 100644 index 000000000..3b8b114bc --- /dev/null +++ b/docs/ref/rst/roles.txt @@ -0,0 +1,318 @@ +========================================= + 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/docs/ref/soextblx.dtd b/docs/ref/soextblx.dtd new file mode 100644 index 000000000..56ba311ba --- /dev/null +++ b/docs/ref/soextblx.dtd @@ -0,0 +1,312 @@ +<!-- +=========================================================================== + 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/docs/ref/transforms.txt b/docs/ref/transforms.txt new file mode 100644 index 000000000..54446f8dd --- /dev/null +++ b/docs/ref/transforms.txt @@ -0,0 +1,116 @@ +===================== + 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/docs/user/Makefile.docutils-update b/docs/user/Makefile.docutils-update new file mode 100644 index 000000000..89097b5ff --- /dev/null +++ b/docs/user/Makefile.docutils-update @@ -0,0 +1,6 @@ +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/docs/user/config.txt b/docs/user/config.txt new file mode 100644 index 000000000..0413dd5be --- /dev/null +++ b/docs/user/config.txt @@ -0,0 +1,1041 @@ +============================== + 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/docs/user/emacs.txt b/docs/user/emacs.txt new file mode 100644 index 000000000..49687f599 --- /dev/null +++ b/docs/user/emacs.txt @@ -0,0 +1,497 @@ +.. -*- 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/docs/user/images/big-black.png b/docs/user/images/big-black.png Binary files differnew file mode 100644 index 000000000..869a0cf9f --- /dev/null +++ b/docs/user/images/big-black.png diff --git a/docs/user/images/big-white.png b/docs/user/images/big-white.png Binary files differnew file mode 100644 index 000000000..1ce6d7d7d --- /dev/null +++ b/docs/user/images/big-white.png diff --git a/docs/user/images/default.png b/docs/user/images/default.png Binary files differnew file mode 100644 index 000000000..509eeddad --- /dev/null +++ b/docs/user/images/default.png diff --git a/docs/user/images/happy_monkey.png b/docs/user/images/happy_monkey.png Binary files differnew file mode 100644 index 000000000..2164c06dd --- /dev/null +++ b/docs/user/images/happy_monkey.png diff --git a/docs/user/images/medium-black.png b/docs/user/images/medium-black.png Binary files differnew file mode 100644 index 000000000..f851e679e --- /dev/null +++ b/docs/user/images/medium-black.png diff --git a/docs/user/images/medium-white.png b/docs/user/images/medium-white.png Binary files differnew file mode 100644 index 000000000..e5a465a56 --- /dev/null +++ b/docs/user/images/medium-white.png diff --git a/docs/user/images/rsp-all.png b/docs/user/images/rsp-all.png Binary files differnew file mode 100644 index 000000000..3e5f5ede3 --- /dev/null +++ b/docs/user/images/rsp-all.png diff --git a/docs/user/images/rsp-breaks.png b/docs/user/images/rsp-breaks.png Binary files differnew file mode 100644 index 000000000..f2a31b098 --- /dev/null +++ b/docs/user/images/rsp-breaks.png diff --git a/docs/user/images/rsp-covers.png b/docs/user/images/rsp-covers.png Binary files differnew file mode 100644 index 000000000..597c2c2a8 --- /dev/null +++ b/docs/user/images/rsp-covers.png diff --git a/docs/user/images/rsp-cuts.png b/docs/user/images/rsp-cuts.png Binary files differnew file mode 100644 index 000000000..aa46b3876 --- /dev/null +++ b/docs/user/images/rsp-cuts.png diff --git a/docs/user/images/rsp-empty.png b/docs/user/images/rsp-empty.png Binary files differnew file mode 100644 index 000000000..f6b93c38b --- /dev/null +++ b/docs/user/images/rsp-empty.png diff --git a/docs/user/images/rsp-objects.png b/docs/user/images/rsp-objects.png Binary files differnew file mode 100644 index 000000000..43ce276f1 --- /dev/null +++ b/docs/user/images/rsp-objects.png diff --git a/docs/user/images/rsp.svg b/docs/user/images/rsp.svg new file mode 100644 index 000000000..03445d3bc --- /dev/null +++ b/docs/user/images/rsp.svg @@ -0,0 +1,636 @@ +<?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/docs/user/images/s5-files.png b/docs/user/images/s5-files.png Binary files differnew file mode 100644 index 000000000..53cbbf250 --- /dev/null +++ b/docs/user/images/s5-files.png diff --git a/docs/user/images/s5-files.svg b/docs/user/images/s5-files.svg new file mode 100644 index 000000000..a3e644a22 --- /dev/null +++ b/docs/user/images/s5-files.svg @@ -0,0 +1,639 @@ +<?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/docs/user/images/small-black.png b/docs/user/images/small-black.png Binary files differnew file mode 100644 index 000000000..f8d80d387 --- /dev/null +++ b/docs/user/images/small-black.png diff --git a/docs/user/images/small-white.png b/docs/user/images/small-white.png Binary files differnew file mode 100644 index 000000000..65f96895d --- /dev/null +++ b/docs/user/images/small-white.png diff --git a/docs/user/latex.txt b/docs/user/latex.txt new file mode 100644 index 000000000..ce8447692 --- /dev/null +++ b/docs/user/latex.txt @@ -0,0 +1,388 @@ +================================ + 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/docs/user/links.txt b/docs/user/links.txt new file mode 100644 index 000000000..3bb2aaa70 --- /dev/null +++ b/docs/user/links.txt @@ -0,0 +1,137 @@ +===================== + 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/docs/user/mailing-lists.txt b/docs/user/mailing-lists.txt new file mode 100644 index 000000000..8137e29e7 --- /dev/null +++ b/docs/user/mailing-lists.txt @@ -0,0 +1,111 @@ +========================= + 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/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt new file mode 100644 index 000000000..dfea5bcb7 --- /dev/null +++ b/docs/user/rst/cheatsheet.txt @@ -0,0 +1,125 @@ +===================================================== + 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/docs/user/rst/demo.txt b/docs/user/rst/demo.txt new file mode 100644 index 000000000..7a0abd033 --- /dev/null +++ b/docs/user/rst/demo.txt @@ -0,0 +1,552 @@ +.. 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/docs/user/rst/images/ball1.gif b/docs/user/rst/images/ball1.gif Binary files differnew file mode 100644 index 000000000..3e14441d9 --- /dev/null +++ b/docs/user/rst/images/ball1.gif diff --git a/docs/user/rst/images/biohazard.png b/docs/user/rst/images/biohazard.png Binary files differnew file mode 100644 index 000000000..ae4629d8b --- /dev/null +++ b/docs/user/rst/images/biohazard.png diff --git a/docs/user/rst/images/title.png b/docs/user/rst/images/title.png Binary files differnew file mode 100644 index 000000000..cc6218efe --- /dev/null +++ b/docs/user/rst/images/title.png diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html new file mode 100644 index 000000000..604cfe6bc --- /dev/null +++ b/docs/user/rst/quickref.html @@ -0,0 +1,1352 @@ +<!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/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt new file mode 100644 index 000000000..735dcf512 --- /dev/null +++ b/docs/user/rst/quickstart.txt @@ -0,0 +1,387 @@ +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/docs/user/slide-shows.txt b/docs/user/slide-shows.txt new file mode 100644 index 000000000..6732f4f44 --- /dev/null +++ b/docs/user/slide-shows.txt @@ -0,0 +1,1004 @@ +.. 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/docs/user/tools.txt b/docs/user/tools.txt new file mode 100644 index 000000000..20f5a3b2f --- /dev/null +++ b/docs/user/tools.txt @@ -0,0 +1,389 @@ +========================== + 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: |
