Menu
▾
▴
[Docutils-checkins] r5621 - in branches/adjacent-citations: FAQ.txt HISTORY.txt README.txt RELEASE-NOTES.txt THANKS.txt docs/api/cmdline-tool.txt docs/api/publisher.txt docs/dev/distributing.txt docs/dev/hacking.txt docs/dev/release.txt docs/dev/repository.txt docs/dev/rst/alternatives.txt docs/dev/testing.txt docs/dev/todo.txt docs/dev/website.txt docs/howto/html-stylesheets.txt docs/howto/rst-directives.txt docs/ref/rst/restructuredtext.txt docs/user/config.txt docs/user/emacs.txt docs/user/latex.txt docs/user/links.txt docs/user/mailing-lists.txt docutils/__init__.py docutils/core.py docutils/frontend.py docutils/languages/__init__.py docutils/languages/pt_br.py docutils/nodes.py docutils/parsers/__init__.py docutils/parsers/rst/directives/__init__.py docutils/parsers/rst/directives/admonitions.py docutils/parsers/rst/directives/body.py docutils/parse ...
Author: strank Date: 2008-07-28 17:24:27 +0200 (Mon, 28 Jul 2008) New Revision: 5621 Added: branches/adjacent-citations/test/test_parsers/test_parser.py Modified: branches/adjacent-citations/FAQ.txt branches/adjacent-citations/HISTORY.txt branches/adjacent-citations/README.txt branches/adjacent-citations/RELEASE-NOTES.txt branches/adjacent-citations/THANKS.txt branches/adjacent-citations/docs/api/cmdline-tool.txt branches/adjacent-citations/docs/api/publisher.txt branches/adjacent-citations/docs/dev/distributing.txt branches/adjacent-citations/docs/dev/hacking.txt branches/adjacent-citations/docs/dev/release.txt branches/adjacent-citations/docs/dev/repository.txt branches/adjacent-citations/docs/dev/rst/alternatives.txt branches/adjacent-citations/docs/dev/testing.txt branches/adjacent-citations/docs/dev/todo.txt branches/adjacent-citations/docs/dev/website.txt branches/adjacent-citations/docs/howto/html-stylesheets.txt branches/adjacent-citations/docs/howto/rst-directives.txt branches/adjacent-citations/docs/ref/rst/restructuredtext.txt branches/adjacent-citations/docs/user/config.txt branches/adjacent-citations/docs/user/emacs.txt branches/adjacent-citations/docs/user/latex.txt branches/adjacent-citations/docs/user/links.txt branches/adjacent-citations/docs/user/mailing-lists.txt branches/adjacent-citations/docutils/__init__.py branches/adjacent-citations/docutils/core.py branches/adjacent-citations/docutils/frontend.py branches/adjacent-citations/docutils/languages/__init__.py branches/adjacent-citations/docutils/languages/pt_br.py branches/adjacent-citations/docutils/nodes.py branches/adjacent-citations/docutils/parsers/__init__.py branches/adjacent-citations/docutils/parsers/rst/directives/__init__.py branches/adjacent-citations/docutils/parsers/rst/directives/admonitions.py branches/adjacent-citations/docutils/parsers/rst/directives/body.py branches/adjacent-citations/docutils/parsers/rst/directives/images.py branches/adjacent-citations/docutils/parsers/rst/directives/misc.py branches/adjacent-citations/docutils/parsers/rst/directives/parts.py branches/adjacent-citations/docutils/parsers/rst/directives/tables.py branches/adjacent-citations/docutils/parsers/rst/languages/__init__.py branches/adjacent-citations/docutils/parsers/rst/languages/de.py branches/adjacent-citations/docutils/parsers/rst/roles.py branches/adjacent-citations/docutils/parsers/rst/states.py branches/adjacent-citations/docutils/readers/__init__.py branches/adjacent-citations/docutils/readers/python/__init__.py branches/adjacent-citations/docutils/readers/python/moduleparser.py branches/adjacent-citations/docutils/statemachine.py branches/adjacent-citations/docutils/transforms/frontmatter.py branches/adjacent-citations/docutils/transforms/parts.py branches/adjacent-citations/docutils/transforms/references.py branches/adjacent-citations/docutils/transforms/writer_aux.py branches/adjacent-citations/docutils/utils.py branches/adjacent-citations/docutils/writers/__init__.py branches/adjacent-citations/docutils/writers/html4css1/__init__.py branches/adjacent-citations/docutils/writers/html4css1/html4css1.css branches/adjacent-citations/docutils/writers/latex2e/__init__.py branches/adjacent-citations/docutils/writers/newlatex2e/__init__.py branches/adjacent-citations/docutils/writers/newlatex2e/unicode_map.py branches/adjacent-citations/docutils/writers/s5_html/__init__.py branches/adjacent-citations/extras/optparse.py branches/adjacent-citations/extras/roman.py branches/adjacent-citations/setup.py branches/adjacent-citations/test/DocutilsTestSupport.py branches/adjacent-citations/test/coverage.sh branches/adjacent-citations/test/docutils_difflib.py branches/adjacent-citations/test/functional/expected/compact_lists.html branches/adjacent-citations/test/functional/expected/dangerous.html branches/adjacent-citations/test/functional/expected/field_name_limit.html branches/adjacent-citations/test/functional/expected/latex_docinfo.tex branches/adjacent-citations/test/functional/expected/misc_rst_html4css1.html branches/adjacent-citations/test/functional/expected/pep_html.html branches/adjacent-citations/test/functional/expected/standalone_rst_html4css1.html branches/adjacent-citations/test/functional/expected/standalone_rst_latex.tex branches/adjacent-citations/test/functional/expected/standalone_rst_pseudoxml.txt branches/adjacent-citations/test/functional/expected/standalone_rst_s5_html_1.html branches/adjacent-citations/test/functional/expected/standalone_rst_s5_html_2.html branches/adjacent-citations/test/functional/input/data/standard.txt branches/adjacent-citations/test/functional/tests/standalone_rst_html4css1.py branches/adjacent-citations/test/functional/tests/standalone_rst_latex.py branches/adjacent-citations/test/functional/tests/standalone_rst_pseudoxml.py branches/adjacent-citations/test/functional/tests/standalone_rst_s5_html_1.py branches/adjacent-citations/test/functional/tests/standalone_rst_s5_html_2.py branches/adjacent-citations/test/test_dependencies.py branches/adjacent-citations/test/test_functional.py branches/adjacent-citations/test/test_io.py branches/adjacent-citations/test/test_language.py branches/adjacent-citations/test/test_nodes.py branches/adjacent-citations/test/test_parsers/test_rst/test_citations.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_block_quotes.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_class.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_images.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_parsed_literals.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_raw.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_sectnum.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_tables.py branches/adjacent-citations/test/test_parsers/test_rst/test_directives/test_title.py branches/adjacent-citations/test/test_publisher.py branches/adjacent-citations/test/test_settings.py branches/adjacent-citations/test/test_transforms/test___init__.py branches/adjacent-citations/test/test_transforms/test_expose_internals.py branches/adjacent-citations/test/test_transforms/test_writer_aux.py branches/adjacent-citations/test/test_utils.py branches/adjacent-citations/test/test_writers/test_docutils_xml.py branches/adjacent-citations/test/test_writers/test_html4css1_misc.py branches/adjacent-citations/test/test_writers/test_html4css1_parts.py branches/adjacent-citations/test/test_writers/test_html4css1_template.py branches/adjacent-citations/test/test_writers/test_latex2e.py branches/adjacent-citations/test/test_writers/test_null.py branches/adjacent-citations/test/test_writers/test_pseudoxml.py branches/adjacent-citations/test/test_writers/test_s5.py branches/adjacent-citations/tools/dev/create_unimap.py branches/adjacent-citations/tools/dev/profile_docutils.py branches/adjacent-citations/tools/dev/unicode2rstsubs.py branches/adjacent-citations/tools/editors/emacs/README.txt branches/adjacent-citations/tools/editors/emacs/rst.el branches/adjacent-citations/tools/editors/emacs/tests/Makefile branches/adjacent-citations/tools/quicktest.py Log: Merged trunk r5043:5619 to adjacent-citations branch. Modified: branches/adjacent-citations/FAQ.txt =================================================================== --- branches/adjacent-citations/FAQ.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/FAQ.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -203,7 +203,9 @@ require that users alter their OS settings, which is something that many users will not be willing or able to do. +Also see `What's the official MIME type for reStructuredText data?`_ + Are there any reStructuredText editor extensions? ------------------------------------------------- @@ -915,6 +917,20 @@ __ mailto:cb...@us... +What's the official MIME type for reStructuredText data? +-------------------------------------------------------- + +While there is no registered MIME type for reStructuredText, the +"official unofficial" standard MIME type is "text/x-rst". This was +invented for the build system for PEPs (Python Enhancement Proposals), +and it's used by the python.org web site build system. + +(The "x-" prefix means it's an unregistered MIME type.) + +Also see `What's the standard filename extension for a +reStructuredText file?`_ + + HTML Writer =========== Modified: branches/adjacent-citations/HISTORY.txt =================================================================== --- branches/adjacent-citations/HISTORY.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/HISTORY.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -14,9 +14,26 @@ .. contents:: -Changes Since 0.4 +Changes Since 0.5 ================= +* General: + + - Backwards-compatible changes to remove python2.6 -3 deprecation warnings + - Text nodes now subclass unicode rather than UserString + (which is gone in python 3.0) + +* docutils/nodes.py: + + - Added ``Element.__contains__`` method, for the in-operator. + +* docutils/writers/latex2e/__init__.py: + + - Change: has_key for dictionaries (not Nodes) to in-operator. + +Release 0.5 (2008-06-25) +======================== + * docutils/languages/he.py: Added to project: Hebrew mappings by Meir Kriheli. @@ -46,6 +63,7 @@ * docutils/parsers/rst/states.py: + - Allow ``+`` and ``:`` in reference names. - Unquoted targets beginning with an underscore (``.. __target: URI``) are no longer accepted. - Added support for multiple attributions in a physical block quote @@ -99,6 +117,8 @@ universally supported now). - ``template.txt`` is now opened in text mode instead of binary mode (to ensure Windows compatibility). + - ``a`` elements now have an "internal" or "external" class, + depending on reference type. * docutils/writers/html4css1/template.txt: Added to project. @@ -114,6 +134,25 @@ * docutils/writers/latex2e/__init__.py: + - Add ``--literal-block-env`` + - Fix: escaping ``%`` in href urls. + - Move usepackage hyperref after stylesheet inclusion. + - Fix: scrartcl does not have chapter but scrreprt. + - Add newline after ``\end{verbatim}``. + - Merge smaller differences from latex2e_adaptive_preamble. + - Add ``use-part-section``. + - Put leavevmode before longtable to avoid having it moved before sub/pargraph. + - Using leavemode option_list no longer needs to check if parent + is a definition list. + - Append ``\leavemode`` to definition list terms. + - No longer write visit\_/depart_definition_list_item comments to + output. + - Table column width with 3 decimal places. + - Add table stubs support (boldfont). + - Add assemble_parts to writer. + - Add simply support for nested tables. + - Fix verbatim in tables if use-verbatim-when-possible. + - Use section commands down to subparagraph. - Put ensuremath around some latin1 chars. - Set ``usepackage[utf8x]{inputenc}`` for utf-8. - New option ``--use-bibtex=style,db1,db2``. @@ -693,7 +732,7 @@ - Converted the line-block directive to use the new structure. - Extracted the old line-block functionality to the ``block`` function (still used). - - Added ``compound`` directive (thanks to Felix Wiemann). + - Added ``compound`` directive (thanks to Lea Wiemann). * docutils/parsers/rst/directives/misc.py: @@ -849,7 +888,7 @@ - Added ``THANKS.txt`` from "Acknowledgements" in ``HISTORY.txt``. - Added "How To Report Bugs" to ``BUGS.txt``. - Went through all the sources and docs (including under web/) and - updated links. Mostly done by Felix Wiemann; thanks Felix! + updated links. Mostly done by Lea Wiemann; thanks Lea! (Still need to update links in the sandboxes.) Specific: Modified: branches/adjacent-citations/README.txt =================================================================== --- branches/adjacent-citations/README.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/README.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -149,8 +149,9 @@ * docutils: The project source directory, installed as a Python package. -* extras: Directory for third-party modules that Docutils depends on. - These are only installed if they're not already present. +* extras: Directory for third-party modules that Docutils depends on + (roman.py, optparse.py, textwrap.py). These are only installed if + they're not already present. * docs: The project documentation directory. Read ``docs/index.txt`` for an overview. Modified: branches/adjacent-citations/RELEASE-NOTES.txt =================================================================== --- branches/adjacent-citations/RELEASE-NOTES.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/RELEASE-NOTES.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,8 +2,8 @@ Docutils Release Notes ======================== -:Author: Felix Wiemann -:Contact: Fel...@os... +:Author: Lea Wiemann +:Contact: LeW...@gm... :Date: $Date$ :Revision: $Revision$ :Web site: http://docutils.sourceforge.net/ @@ -18,9 +18,30 @@ .. contents:: -Changes Since 0.4 +Changes Since 0.5 ================= + +Release 0.5 (2008-06-25) +======================== + +Components: + +* HTML writer. + + - Dropped all ``name`` attributes of ``a`` elements (``id`` is + universally supported now). + +* LaTeX2e writer: + + - Better bibTeX citation support. + - Add ``--literal-block-env`` + +* PEP writer: + + - Changed to support new python.org website structure and + pep2pyramid.py. + reStructuredText: * Changed the directive API to a new object-oriented system. @@ -30,7 +51,27 @@ __ docs/howto/rst-directives.html +* Allow ``+`` and ``:`` in reference names requested for citations. +Documentation: + +* Added `Deploying Docutils Securely`__ + + __ docs/howto/security.txt + +Internationalization: + +* Added hebrew mappings. + +General: + +* Configuration files are now assumed and required to be + UTF-8-encoded. + +* Added docutils/writers/html4css1/template.txt. + +* Enhance emacs support. + Release 0.4 (2006-01-09) ======================== Modified: branches/adjacent-citations/THANKS.txt =================================================================== --- branches/adjacent-citations/THANKS.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/THANKS.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -150,7 +150,7 @@ * Barry Warsaw * Wu Wei * Edward Welbourne -* Felix Wiemann +* Lea Wiemann * Anthony Williams * Ka-Ping Yee * Moshe Zadka Modified: branches/adjacent-citations/docs/api/cmdline-tool.txt =================================================================== --- branches/adjacent-citations/docs/api/cmdline-tool.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/api/cmdline-tool.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -55,7 +55,7 @@ 'reStructuredText sources. ' + default_description) Now we call the Publisher convenience function, which takes over. -Most of it's defaults are used ("standalone" Reader, +Most of its 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:: Modified: branches/adjacent-citations/docs/api/publisher.txt =================================================================== --- branches/adjacent-citations/docs/api/publisher.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/api/publisher.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -11,13 +11,28 @@ .. contents:: +The ``docutils.core.Publisher`` class is the core of Docutils, +managing all the processing and relationships between components. See +`PEP 258`_ for an overview of Docutils components. + +The ``docutils.core.publish_*`` convenience functions are the normal +entry points for using Docutils as a library. + +See `Inside A Docutils Command-Line Front-End Tool`_ for an overview +of a typical Docutils front-end tool, including how the Publisher +class is used. + +.. _PEP 258: ../peps/pep-0258.html +.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html + + 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: +handles everything else. There are several 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/`` @@ -45,8 +60,8 @@ `publish_from_doctree`_. :_`publish_from_doctree`: for programmatic use to render from an - existing document tree data structure (doctree); returns a pair of - encoded string output and document parts. + existing document tree data structure (doctree); returns the encoded + output as a string. :_`publish_programmatically`: for custom programmatic use. This function implements common code and is used by ``publish_file``, @@ -99,8 +114,7 @@ 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. +described below. Not all writers implement all parts. Parts Provided By All Writers @@ -254,3 +268,26 @@ ```````````````````````````````````` The S5/HTML writer provides the same parts as the `HTML writer`_. + +Parts Provided by the LaTeX2e Writer +```````````````````````````````````` + +__`head_prefix` + ``parts['head_prefix']`` contains the LaTeX document class, package + and stylesheet inclusion. + +__`head` + ``parts['head']`` currently is empty. + +__`body_prefix` + ``parts['body_prefix']`` contains the LaTeX ``\begin{document}`` and + title page. + +__`body` + ``parts['body']`` contains the LaTeX document content, less + the ``\begin{document}`` and ``\end{document}`` tags themselves. + +__`body_suffix` + ``parts['body_suffix']`` contains the LaTeX ``\end{document}``. + + Modified: branches/adjacent-citations/docs/dev/distributing.txt =================================================================== --- branches/adjacent-citations/docs/dev/distributing.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/distributing.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,8 +2,8 @@ Docutils_ Distributor's Guide =============================== -:Author: Felix Wiemann -:Contact: Fel...@os... +:Author: Lea Wiemann +:Contact: LeW...@gm... :Revision: $Revision$ :Date: $Date$ :Copyright: This document has been placed in the public domain. Modified: branches/adjacent-citations/docs/dev/hacking.txt =================================================================== --- branches/adjacent-citations/docs/dev/hacking.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/hacking.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,8 +2,8 @@ Docutils_ Hacker's Guide ========================== -:Author: Felix Wiemann -:Contact: Fel...@os... +:Author: Lea Wiemann +:Contact: LeW...@gm... :Revision: $Revision$ :Date: $Date$ :Copyright: This document has been placed in the public domain. Modified: branches/adjacent-citations/docs/dev/release.txt =================================================================== --- branches/adjacent-citations/docs/dev/release.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/release.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,7 +2,7 @@ Docutils_ Release Procedure ============================= -:Authors: David Goodger; Felix Wiemann; open to all Docutils developers +:Authors: David Goodger; Lea Wiemann; open to all Docutils developers :Contact: go...@py... :Date: $Date$ :Revision: $Revision$ @@ -12,7 +12,7 @@ Steps in boldface text are *not* covered by the release script at -sandbox/fwiemann/release.sh. "Not covered" means that you aren't even +sandbox/infrastructure/release.sh. "Not covered" means that you aren't even reminded of them. .. Note:: This document does not cover branching and tagging, but the @@ -147,6 +147,8 @@ * Update the web page (web/index.txt). * Run docutils-update on the server. + +* **Run alltests.py with svn version** * **Send announcement email to:** Modified: branches/adjacent-citations/docs/dev/repository.txt =================================================================== --- branches/adjacent-citations/docs/dev/repository.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/repository.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,8 +2,8 @@ The Docutils_ Subversion Repository ===================================== -:Author: Felix Wiemann -:Contact: Fel...@os... +:Author: Lea Wiemann +:Contact: LeW...@gm... :Revision: $Revision$ :Date: $Date$ :Copyright: This document has been placed in the public domain. @@ -114,7 +114,7 @@ If you would like to have write access to the repository, register with SourceForge.net_ and BerliOS_, and send your SourceForge.net and -BerliOS user names to `Felix Wiemann <Fel...@os...>`_. +BerliOS user names to `Lea Wiemann <LeW...@gm...>`_. (Note that there may be a delay of several hours until you can commit changes to the repository.) @@ -167,7 +167,7 @@ Developers who had write-access for Docutils' CVS repository on SourceForge.net should `register with BerliOS`__ and send a message -with their BerliOS user name to `Felix Wiemann`_. +with their BerliOS user name to `Lea Wiemann`_. __ https://developer.berlios.de/account/register.php Modified: branches/adjacent-citations/docs/dev/rst/alternatives.txt =================================================================== --- branches/adjacent-citations/docs/dev/rst/alternatives.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/rst/alternatives.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -1320,7 +1320,7 @@ | Ethan Hunt | Jim Phelps | Claire Phelps - | CIA: Felix Leiter + | CIA: Lea Leiter Note that the "nested" list does not have nested syntax (the "|" are not further indented); the leading whitespace would still be Modified: branches/adjacent-citations/docs/dev/testing.txt =================================================================== --- branches/adjacent-citations/docs/dev/testing.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/testing.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,7 +2,7 @@ Docutils_ Testing =================== -:Authors: Felix Wiemann <Fel...@os...>; +:Authors: Lea Wiemann <LeW...@gm...>; David Goodger <go...@py...> :Revision: $Revision$ :Date: $Date$ Modified: branches/adjacent-citations/docs/dev/todo.txt =================================================================== --- branches/adjacent-citations/docs/dev/todo.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/todo.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -873,7 +873,7 @@ 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?`__, + `this summary of Lea's objections`__), `more-universal links?`__, `Output-format-sensitive link targets?`__ __ http://thread.gmane.org/gmane.text.docutils.user/1239 Modified: branches/adjacent-citations/docs/dev/website.txt =================================================================== --- branches/adjacent-citations/docs/dev/website.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/dev/website.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -10,14 +10,46 @@ 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 :: +hourly cron job on shell.berlios.de (by user "wiemann"). 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. +Please **do not** add any generated .html files to the Docutils +repository. They will be generated automatically after a one-time +setup (`described below`__). + +__ `Adding .txt Files`_ + +The docutils-update__ script is located at +``sandbox/infrastructure/docutils-update``. + +__ http://docutils.sf.net/sandbox/infrastructure/docutils-update + +If you want to share files via the web, you can upload them using the +uploaddocutils.sh__ script +(``sandbox/infrastructure/uploaddocutils.sh``). + +__ http://docutils.sf.net/sandbox/infrastructure/uploaddocutils.sh + + +Adding Directories +================== + +After adding directories to SVN, allow the update script to run once +to create the directories in the filesystem before preparing for HTML +processing as described below. + + +Adding .txt Files +================= + +For a new .txt file, just SSH to ``<username>@shell.berlios.de`` and +:: + cd /home/groups/docutils/htdocs/aux/htdocs/ + cd [path to your file's subdirectory] touch filename.html chmod g+w filename.html sleep 1 @@ -27,20 +59,16 @@ 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``. +Renoving Files & Directories +============================ -__ http://docutils.sf.net/sandbox/infrastructure/docutils-update +Removing files and directories from SVN will not trigger their removal +from the web site. Files and directories must be manually removed +from both berlios.de (under +``/home/groups/docutils/htdocs/aux/htdocs/``) and from sourceforge.net +(under ``/home/groups/d/do/docutils/htdocs/``). -If you want to share files via the web, you can upload them using the -uploaddocutils.sh__ script (``sandbox/fwiemann/uploaddocutils.sh``). - -__ http://docutils.sf.net/sandbox/fwiemann/uploaddocutils.sh - .. Local Variables: Modified: branches/adjacent-citations/docs/howto/html-stylesheets.txt =================================================================== --- branches/adjacent-citations/docs/howto/html-stylesheets.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/howto/html-stylesheets.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,8 +2,8 @@ Writing HTML (CSS) Stylesheets for Docutils_ ============================================== -:Author: Felix Wiemann -:Contact: Fel...@os... +:Author: Lea Wiemann +:Contact: LeW...@gm... :Date: $Date$ :Revision: $Revision$ :Copyright: This document has been placed in the public domain. Modified: branches/adjacent-citations/docs/howto/rst-directives.txt =================================================================== --- branches/adjacent-citations/docs/howto/rst-directives.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/howto/rst-directives.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -2,9 +2,9 @@ Creating reStructuredText_ Directives ======================================= -:Authors: Dethe Elza, David Goodger, Felix Wiemann +:Authors: Dethe Elza, David Goodger, Lea Wiemann :Contact: de...@en..., go...@py..., - Fel...@os... + LeW...@gm... :Date: $Date$ :Revision: $Revision$ :Copyright: This document has been placed in the public domain. Modified: branches/adjacent-citations/docs/ref/rst/restructuredtext.txt =================================================================== --- branches/adjacent-citations/docs/ref/rst/restructuredtext.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/ref/rst/restructuredtext.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -378,11 +378,11 @@ =============== 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. +plus isolated (no two adjacent) internal hyphens, underscores, +periods, colons and plus signs; 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". @@ -2222,14 +2222,18 @@ 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 + |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 + .. |RST| replace:: reStructuredText + .. _RST: http://docutils.sourceforge.net/rst.html + Note the trailing underscore in the first use of a substitution + reference. This indicates a reference to the corresponding + hyperlink target. + Substitution is also appropriate when the replacement text cannot be represented using other inline constructs, or is obtrusively long:: Modified: branches/adjacent-citations/docs/user/config.txt =================================================================== --- branches/adjacent-citations/docs/user/config.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/user/config.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -404,18 +404,22 @@ List of "classes" attribute values to remove from all elements in the document tree. + .. WARNING:: Potentially dangerous; use with caution. + Default: disabled (None). Option: ``--strip-class``. _`strip_comments` Enable the removal of comment elements from the document tree. - Default: disabled (None). Options: ``--strip-comment``, + Default: disabled (None). Options: ``--strip-comments``, ``--leave-comments``. _`strip_elements_with_classes` List of "classes" attribute values; matching elements to be removed from the document tree. + .. WARNING:: Potentially dangerous; use with caution. + Default: disabled (None). Option: ``--strip-element-with-class``. _`title` Modified: branches/adjacent-citations/docs/user/emacs.txt =================================================================== --- branches/adjacent-citations/docs/user/emacs.txt 2008-07-28 08:48:31 UTC (rev 5620) +++ branches/adjacent-citations/docs/user/emacs.txt 2008-07-28 15:24:27 UTC (rev 5621) @@ -5,7 +5,7 @@ ======================================== :Author: Martin Blais <bl...@fu...> -:Date: $Date$ +:Date: 2007-12-03 :Abstract: High-level description of the existing emacs support for editing @@ -15,30 +15,34 @@ .. contents:: .. 1 Introduction - 2 Basic Setup - 3 Section Decoration Adjustment - 3.1 Promoting and Demoting Many Sections - 3.2 Redoing All the Decorations to Your Taste - 3.3 Customizations - 4 Viewing the Hierarchy of Section Decorations - 5 Table of Contents - 5.1 Inserting a Table of Contents - 5.2 Maintaining the Table of Contents Up-to-date - 6 Navigating Between the Section Titles - 7 Shifting Bullet List Levels - 8 Bulleting and Enumerating Lists - 8.1 Straightening Existing Bullet List Hierarchies - 9 Creating and Remove Line Blocks - 10 Major Mode for Editing reStructuredText Documents - 11 Converting Documents from Emacs - 12 Other / External Useful Emacs Settings - 12.1 Settings for Filling Lists - 12.2 ``text-mode`` Settings - 12.3 Editing Tables: Emacs table mode - 12.4 Character Processing - 13 Credits - 14 Obsolete Files - 15 Future Work + 2 Installation + 3 Section Decorations + 3.1 Adjusting a Section Title + 3.2 Promoting and Demoting Many Sections + 3.3 Redoing All the Decorations to Your Taste + 3.4 Customizations for Decorations + 3.5 Viewing the Hierarchy of Section Decorations + 4 Section Movement and Selection + 5 Operating on Blocks of Text + 5.1 Shifting Text Horizontally Intelligently + 5.2 Bulleting and Enumerating Lists + 5.2.1 Straightening Existing Bullet List Hierarchies + 5.3 Creating and Removing Line Blocks + 5.4 Commenting a Region of Text + 6 Converting Documents from Emacs + 7 Table-of-Contents Features + 7.1 Inserting a Table of Contents + 7.2 Maintaining the Table of Contents Up-to-date + 8 Syntax Highlighting via Font-Lock + 8.1 Face Customization + 8.1.1 Default Fonts + 9 Other Useful Settings + 9.1 ``text-mode`` Settings + 9.2 Editing Tables: Emacs table mode + 9.3 Character Processing + 10 Credits + 10.1 Obsolete Files + 11 Future Work Introduction @@ -46,49 +50,75 @@ 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``. +text files. For people who use Emacs_, there is a package that adds a +major mode that supports editing in the conventions of +reStructuredText_: ``rst.el``. This document describes the features it +provides, and how to setup your emacs to use them and how to invoke +them. -This document describes the most important features that it provides, -how to setup your emacs to use them and how to invoke them. +Installation +============ -Basic Setup -=========== +The emacs support is implemented as an Emacs major mode (``rst-mode``) +provided by the ``rst.el`` emacs package. In order to use +``rst-mode``, you need to put the ``rst.el`` in a directory located in +your emacs ``load-path``, and to load it with:: -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) - (require 'rst) ;; or (load "rst") +To enable ``rst-mode``, simple type ``M-x rst-mode``. Alternatively, +you can modify ``auto-mode-alist`` to automatically turn it on +whenever you visit reStructuredText_ documents:: -Additional configuration variables can be customized and can be found -by browsing the source code for ``rst.el``. + (setq auto-mode-alist + (append '(("\\.txt$" . rst-mode) + ("\\.rst$" . rst-mode) + ("\\.rest$" . rst-mode)) auto-mode-alist)) -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:: +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:: - (add-hook 'text-mode-hook 'rst-text-mode-bindings) + .. -*- mode: rst -*- -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 ...``. +Or this at the end of your documents:: + .. + Local Variables: + mode: rst + End: -Section Decoration Adjustment -============================= +``rst-mode`` automatically binds several keys for invoking special +handy functions for editing ReStructuredText. As is the custom for +Emacs major modes, most keys are bound to ``C-c C-LETTER``. +If you insert an inline table-of-contents at the top of the document, +you may want to add a hook to automatically update it everytime you +adjust a section title:: + + (add-hook 'rst-adjust-hook 'rst-toc-update) + +Additional configuration variables can be customized and can be found +by browsing the source code for ``rst.el``. + + +Section Decorations +=================== + 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 +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. +Adjusting 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: +decorations: ``rst-adjust`` (bound to ``C-c C-a``, 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.:: @@ -114,7 +144,6 @@ documentation of ``rst-adjust`` for more description of the prefix arguments to alter the behaviour of the function. - Promoting and Demoting Many Sections ------------------------------------ @@ -124,151 +153,56 @@ binding is invoked, all the section titles that are within the region are promoted accordingly (or demoted, with negative prefix arg). - Redoing All the Decorations to Your Taste ----------------------------------------- If you open someone else's file and the decorations it contains are unfamiliar, you may want to readjust them to fit your own preferred -hierarchy of decorations. This can be difficult to perform by hand. -However, you can do this easily by invokeing -``rst-straighten-decorations`` (C-c p s), which operates on the entire -buffer. +hierarchy of decorations. This can be difficult to perform by hand. +However, you can do this easily by invoking +``rst-straighten-decorations`` (``C-c C-s``), which operates on the +entire buffer. +Customizations for Decorations +------------------------------ -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 +bound on ``C-c C-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 -================= +Section Movement and Selection +============================== -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. +You can move the cursor between the different section titles by using +the ``rst-backward-section`` and ``rst-forward-section`` functions, by +default bound to the ``C-c C-p`` and ``C-c C-n`` keys. -Invoke this function (``rst-toc``) with ``C-c p t``. It should -present a temporary buffer that looks something like this:: +To mark the section that cursor lies in, use ``rst-mark-section`` +(``C-c C-m``). - 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. +Operating on Blocks of Text +=========================== -Inserting a Table of Contents ------------------------------ +Shifting Text Horizontally Intelligently +---------------------------------------- -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. +Due to the nature of reStructuredText_, lists are indented by two or +three characters, e.g. bulleted lists use two chars:: -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_, bulleted lists are indented by -two characters (unless they are part of a blockquote), e.g. :: - - Fruits - Bananas @@ -280,7 +214,7 @@ - Zucchini - Chick Peas -Enumerated lists, however, as indented by 3 or more characters :: +while enumerated lists are indented by 3 or more characters :: 9. Apples @@ -290,25 +224,24 @@ Oranges are zesty. +To this effect, when shifting text, it can be useful to have functions +which understand which indent to use by using the context around the +region. Those functions are ``rst-shift-region-right`` and +``rst-shift-region-left``. -To this effect, when re-organizing bullet lists, it can be useful to -have functions to shift regions of text by appropriate indents, which -are figured out automatically by emacs. +You can use ``C-c C-r`` and ``C-c C-l`` to shift the active region. +These bindings are similar to the ones provided by python-mode for +editing python code and behave similarly. They automatically inspect +the lines of text before the currently selected region to determine +what the appropriate column positions are. -You can use ``C-c C-r`` and ``C-c C-l`` to shift the current region -(``rst-shift-region-right`` and ``rst-shift-region-left``). These -bindings are similar to the ones provided by python-mode for editing -python code and behave similarly. They inspect the lines of text -before the currently selected region to determine what the appropriate -column positions are. - Bulleting and Enumerating Lists -=============================== +------------------------------- Sometimes it can be useful to insert bullet list markers enumeration number before a number of lines or paragraphs. You can do this easily -by invoking ``rst-enumerate-region`` (``C-c p e``), for example, the +by invoking ``rst-enumerate-region`` (``C-c C-e``), for example, the following:: Apples @@ -325,7 +258,7 @@ 3. Bananas -``rst-listify-region`` (``C-c p b``) does the same, but only adds +``rst-listify-region`` (``C-c C-b``) does the same, but only adds bullet list markers, e.g.:: Apples @@ -337,9 +270,9 @@ becomes:: - Apples - + - Oranges - + - Bananas @@ -347,24 +280,24 @@ highlighted region will be taken to be a single list or enumeration item, for example, enumerating the following:: - An apple a day + An apple a day keeps the doctor away. - - But oranges + + But oranges are tastier than apples. - + If you preferred bananas you may be a monkey. Will result in:: - 1. An apple a day + 1. An apple a day keeps the doctor away. - - 2. But oranges + + 2. But oranges are tastier than apples. - + 3. If you preferred bananas you may be a monkey. @@ -382,12 +315,10 @@ - Oranges - Bananas - - Straightening Existing Bullet List Hierarchies ----------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you invoke ``rst-straighten-bullets-region`` (C-c p w), the +If you invoke ``rst-straighten-bullets-region`` (C-c C-w), the existing bullets in the highlighted region will be replaced to reflect their respective level. This does not make a difference in the document structure that reStructuredText_ defines, but looks better in @@ -395,11 +326,11 @@ the character ``-``, and all of the 2nd level items use ``*``, etc. -Creating and Remove Line Blocks -=============================== +Creating and Removing Line Blocks +--------------------------------- To create line blocks, first select the region to convert and invoke -``rst-toggle-line-block`` with ``C-c p B``, for example, the +``rst-toggle-line-block`` with ``C-c C-d``, for example, the following:: Apples @@ -416,113 +347,228 @@ select a region and invoke with a prefix argument. -Major Mode for Editing reStructuredText Documents -================================================= +Commenting a Region of Text +--------------------------- -The great majority of the functionality for supporting -reStructuredText_ can be invoked directly from Emacs' vanilla -text-mode. +If you use the Emacs ``comment-region`` function (bound to ``C-c +C-c``), the appropriate comment syntax will be added to the active +block of text:: -However, there is also a major mode that adds syntax highlighting to -reStructuredText_ constructs. This mode was written by Stefan Merten -[#]_. It mostly provides lazy syntax coloring for many of the -constructs that reStructuredText_ prescribes. + Apples + Oranges + Bananas -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:: +becomes:: - (add-to-list 'auto-mode-alist '("\\.rst$" . rst-mode) ) + .. Apples + .. Oranges + .. Bananas -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 =============================== -We provide a function (``rst-compile``) for invoking the document -converters from within emacs. It is bound on ``C-c p c``. +The major mode provides a number of functions for running documents +being edited through the docutils tools. -This function basically creates a compilation command with the correct +The main generic function is ``rst-compile`` (``C-c 1``). 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. +cmdline options. There is also an alternative function in case you +often need run your document in a second toolset (``C-c 2``). -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``). +You can customize the commands being used by setting +``rst-compile-primary-toolset`` and ``rst-compile-secondary-toolset``. +Other commands are available for other formats: + +- ``rst-compile-pseudo-region`` (``C-c 3``): When crafting documents, + it is often convenient to view which data structures docutils will + parse them into. You can use to run the active region through + ``rst2pseudoxml.py`` and have the output automatically be displayed + in a new buffer. + +- ``rst-compile-pdf-preview`` (``C-c 4``): Convert the current + document to PDF and launch a viewer on the results. + +- ``rst-compile-slides-preview`` (``C-c 5``): Convert the current + document to S5 slides and view in a web browser. + + +Table-of-Contents Features +========================== + +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 C-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 (press ``RET``), 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 C-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``. + .. 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. + The table-of-contents inserted by ``rst-mode`` has text properties + added to it so that if you type ``C-c C-f`` while the cursor is on + one of its entries, the cursor will jump to the corresponding + section in the document. + +Maintaining the Table of Contents Up-to-date +-------------------------------------------- -Other / External Useful Emacs Settings -====================================== +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-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:: -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. + (add-hook 'rst-adjust-hook 'rst-toc-update) +You can invoke the update on the current buffer with ``C-c C-u``. -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.:: +Syntax Highlighting via Font-Lock +================================= - - Bananas; - - One Apple a day keeps the doctor away, and eating more keeps the pirates at bay; - - Oranges; +``rst-mode`` also provides syntax highlighting to reStructuredText_ +constructs. (This mode was written by Stefan Merten.) -Becomes:: +Lazy syntax coloring is implemented for many of the constructs that +reStructuredText_ prescribes. 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). - - Bananas; One Apple a day keeps the doctor away, and eating more - - keeps the pirates at bay; Oranges; +``font-lock`` syntax highlighting is enabled by default. If you prefer +to turn off syntax highlighting (on some machines it can slow down +editing a little bit), you can use the following in your Emacs +configuration:: -This is usually not what you want. What you want is this:: + (setq font-lock-global-modes '(not rst-mode)) - - 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:: +Face Customization +------------------ - (add-hook 'text-mode-hook 'rst-set-paragraph-separation) +The ``rst-faces`` group contains all necessary for customizing +fonts. The default settings use standard ``font-lock-*-face`` so if +you set these to your liking they are probably good in rst-mode also. +The group is contained in the faces group as well as in the rst group. + +Default Fonts +~~~~~~~~~~~~~ + +The ``rst-faces-defaults`` group contains all necessary for +customizing the default fonts used for section title faces. + +The general idea for section title faces is to have a non-default +background but do not change the background. The section level is +shown by the lightness of the background color. If you like this +general idea of generating faces for section titles but do not like +the details this group is the point where you can customize the +details. If you do not like the general idea, however, you should +customize the faces used in ``rst-adornment-faces-alist``. + +Note: If you are using a dark background please make sure the variable +``frame-background-mode`` is set to the symbol dark. This triggers +some default values which are probably right for you. + +The group is contained in the ``... [truncated message content] |