diff options
Diffstat (limited to 'web')
| -rw-r--r-- | web/.htaccess | 62 | ||||
| -rw-r--r-- | web/PyBanner016.png | bin | 720 -> 0 bytes | |||
| -rw-r--r-- | web/default.css | 18 | ||||
| -rw-r--r-- | web/docutils.conf | 4 | ||||
| -rw-r--r-- | web/index.txt | 405 | ||||
| -rw-r--r-- | web/mirror/setext.txt | 27 | ||||
| -rw-r--r-- | web/rst.png | bin | 1170 -> 0 bytes | |||
| -rw-r--r-- | web/rst.txt | 235 |
8 files changed, 0 insertions, 751 deletions
diff --git a/web/.htaccess b/web/.htaccess deleted file mode 100644 index 7ec07ec10..000000000 --- a/web/.htaccess +++ /dev/null @@ -1,62 +0,0 @@ -# Do not edit arbitrarily. Check with docutils-develop@lists.sf.net first. - -# Redirect snapshots to BerliOS. The target URL may change in the -# future, so use a temporary redirect (status 302). - -RedirectMatch temp /([^#]*-snapshot.tgz) ftp://ftp.berlios.de/pub/docutils/$1 - -# Redirection from old URLs to new URLs after a site reorganization. - -Redirect permanent /docs/config.html http://docutils.sourceforge.net/docs/user/config.html -Redirect permanent /docs/config.txt http://docutils.sourceforge.net/docs/user/config.txt -Redirect permanent /docs/latex.html http://docutils.sourceforge.net/docs/user/latex.html -Redirect permanent /docs/latex.txt http://docutils.sourceforge.net/docs/user/latex.txt -Redirect permanent /docs/tools.html http://docutils.sourceforge.net/docs/user/tools.html -Redirect permanent /docs/tools.txt http://docutils.sourceforge.net/docs/user/tools.txt - -RedirectMatch permanent /docs/rst/([^#]*) http://docutils.sourceforge.net/docs/user/rst/$1 -# instead of: -# Redirect permanent /docs/rst/quickref.html http://docutils.sourceforge.net/docs/user/rst/quickref.html -# Redirect permanent /docs/rst/quickstart.html http://docutils.sourceforge.net/docs/user/rst/quickstart.html -# Redirect permanent /docs/rst/quickstart.txt http://docutils.sourceforge.net/docs/user/rst/quickstart.txt -# Redirect permanent /docs/rst/cheatsheet.txt http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt -# Redirect permanent /docs/rst/quickref.html http://docutils.sourceforge.net/docs/user/rst/quickref.html - -RedirectMatch permanent /spec/howto/([^#]*) http://docutils.sourceforge.net/docs/howto/$1 - -Redirect permanent /spec/pysource.dtd http://docutils.sourceforge.net/docs/dev/pysource.dtd -Redirect permanent /spec/pysource.txt http://docutils.sourceforge.net/docs/dev/pysource.txt -Redirect permanent /spec/pysource.html http://docutils.sourceforge.net/docs/dev/pysource.html -Redirect permanent /spec/semantics.txt http://docutils.sourceforge.net/docs/dev/semantics.txt -Redirect permanent /spec/semantics.html http://docutils.sourceforge.net/docs/dev/semantics.html -Redirect permanent /spec/notes.txt http://docutils.sourceforge.net/docs/dev/todo.txt -Redirect permanent /spec/notes.html http://docutils.sourceforge.net/docs/dev/todo.html - -Redirect permanent /spec/doctree.txt http://docutils.sourceforge.net/docs/ref/doctree.txt -Redirect permanent /spec/doctree.html http://docutils.sourceforge.net/docs/ref/doctree.html -Redirect permanent /spec/docutils.dtd http://docutils.sourceforge.net/docs/ref/docutils.dtd -Redirect permanent /spec/soextblx.dtd http://docutils.sourceforge.net/docs/ref/soextblx.dtd - -Redirect permanent /spec/transforms.txt http://docutils.sourceforge.net/docs/ref/transforms.txt -Redirect permanent /spec/transforms.html http://docutils.sourceforge.net/docs/ref/transforms.html - -Redirect permanent /spec/rst/alternatives.txt http://docutils.sourceforge.net/docs/dev/rst/alternatives.txt -Redirect permanent /spec/rst/alternatives.html http://docutils.sourceforge.net/docs/dev/rst/alternatives.html -Redirect permanent /spec/rst/problems.txt http://docutils.sourceforge.net/docs/dev/rst/problems.txt -Redirect permanent /spec/rst/problems.html http://docutils.sourceforge.net/docs/dev/rst/problems.html - -Redirect permanent /spec/rst/reStructuredText.txt http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.txt -Redirect permanent /spec/rst/reStructuredText.html http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html -Redirect permanent /spec/rst/restructuredtext.txt http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.txt -Redirect permanent /spec/rst/restructuredtext.html http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html -Redirect permanent /spec/rst/directives.txt http://docutils.sourceforge.net/docs/ref/rst/directives.txt -Redirect permanent /spec/rst/directives.html http://docutils.sourceforge.net/docs/ref/rst/directives.html -Redirect permanent /spec/rst/interpreted.txt http://docutils.sourceforge.net/docs/ref/rst/roles.txt -Redirect permanent /spec/rst/interpreted.html http://docutils.sourceforge.net/docs/ref/rst/roles.html -Redirect permanent /spec/rst/introduction.txt http://docutils.sourceforge.net/docs/ref/rst/introduction.txt -Redirect permanent /spec/rst/introduction.html http://docutils.sourceforge.net/docs/ref/rst/introduction.html - -RedirectMatch permanent /spec/pep-([^#]*) http://docutils.sourceforge.net/docs/peps/pep-$1 - -Redirect permanent /tools/test.txt http://docutils.sourceforge.net/docs/user/rst/demo.txt -Redirect permanent /tools/test.html http://docutils.sourceforge.net/docs/user/rst/demo.html diff --git a/web/PyBanner016.png b/web/PyBanner016.png Binary files differdeleted file mode 100644 index 3c79b2ef7..000000000 --- a/web/PyBanner016.png +++ /dev/null diff --git a/web/default.css b/web/default.css deleted file mode 100644 index f5fa65b01..000000000 --- a/web/default.css +++ /dev/null @@ -1,18 +0,0 @@ -/* -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:date: $Date$ -:version: $Revision$ -:copyright: This stylesheet has been placed in the public domain. - -Default cascading style sheet for Docutils web pages. -*/ - -/* Most of the style rules are in here: */ -@import url(tools/stylesheets/default.css); - -body { - background-color: #F0F0FF } - -p img { - vertical-align: text-top } diff --git a/web/docutils.conf b/web/docutils.conf deleted file mode 100644 index b7f07a9fd..000000000 --- a/web/docutils.conf +++ /dev/null @@ -1,4 +0,0 @@ -[html4css1 writer] - -# Files in the homepage's root directory want their own stylesheet: -stylesheet-path: ./default.css diff --git a/web/index.txt b/web/index.txt deleted file mode 100644 index 324703268..000000000 --- a/web/index.txt +++ /dev/null @@ -1,405 +0,0 @@ -=================================== - Docutils: Documentation Utilities -=================================== ---------------------------------------------------------- - Written in Python, for General- and Special-Purpose Use ---------------------------------------------------------- - -:Date: $Date$ - -.. This document is *not* meant to be a model for good - reStructuredText usage. It is full of external hyperlinks, and - makes extensive use of anonymous hyperlink syntax, which is not - easy to follow from the source text. Please refer to the processed - HTML instead: http://docutils.sourceforge.net/index.html - -The purpose of the Docutils project is to create a set of tools for -processing plaintext documentation into useful formats, such as HTML, -XML, and LaTeX. Includes reStructuredText_, the easy to read, easy to -use, what-you-see-is-what-you-get plaintext markup language. Several -sources are or will be supported: - -- Standalone files (implemented). -- Inline documentation from Python modules and packages, extracted - with namespace context. -- `PEPs (Python Enhancement Proposals)`_ (implemented). -- And others as discovered. - -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 - :width: 88 - :height: 32 - :alt: Support the Docutils project! - -.. contents:: - - -Getting Started -=============== - -To get up & running quickly, see the Quick-Start_ section of the -README_ file. - -.. _Quick-Start: README.html#quick-start - - -Documentation -============= - -Please see the `Docutils Project Documentation Overview -<docs/index.html>`_. - - -Feedback -======== - -To the developers of an open source project, feedback is a great -motivator and very welcome. We're working on Docutils in our own way, -pushing it along a more-or-less linear path that makes sense to us, -but may not necessarily be useful to everyone else. Community -feedback helps steer development in immediately useful directions. - -In other words: if you tell us what you need, you may just get it! If -you really need something, please consider contributing_ to Docutils -in some way. - -Please post any feedback to the appropriate `mailing list`_. - -.. _contributing: `Please Contribute!`_ - - -Project Status -============== - -The Docutils project began with the merging of the reStructuredText__ -parser and the `Python Docstring Processing System`__ projects. The -merge has been completed, and those projects are now inactive. - -__ http://structuredtext.sourceforge.net/ -__ http://docstring.sourceforge.net/ - -Docutils currently consists of a reStructuredText_ parser, readers for -standalone files and PEPs_, and writers for HTML, LaTeX, -Docutils-native XML, plus pseudo-XML for testing purposes. Writers -for DocBook XML and PDF have been started, and a Python source reader -(docstring extraction with context) is also under way. There is a lot -of design and implementation work to do, which could greatly benefit -from a joint effort with existing projects. The project `To Do list`_ -is brimming over with ideas. - -Docutils is in active development and should be considered highly -experimental. We're learning as we go. APIs are subject to change at -any time. - - -Requirements -============ - -- Python 2.2 or later [#py21]_ must already be installed to run the - code and the test suite. The latest release is recommended. Python - is available from http://www.python.org/. - -- Docutils uses Greg Ward's Optik_/optparse option processing package. - It is included in the Docutils distribution. - -- The `Python Imaging Library`, or PIL, is used for some image - manipulation operations if it is installed. - -.. [#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's source distribution. - -.. _Optik: http://optik.sourceforge.net/ -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - - -Download -======== - -Development Snapshots ---------------------- - -Development snapshots of the project files are available as .tgz -tarballs. They are generated automatically from the Subversion -repository, usually within an hour of a change being checked in. The -snapshots are highly recommended over the "official" releases, as they -contain the latest features and bug fixes. However, they may contain -transient bugs or incompatibilities. - -- `Snapshot of Docutils code, tests, documentation, and - specifications`__ -- `Snapshot of the Sandbox`__ (experimental, contributed code; see - `The Sandbox`_ below for details) -- `Snapshot of DocFactory project files`__ (this is a subset of the - Sandbox snapshot above; you don't need both) -- `Snapshot of web files`__ (the files that generate this web site) - -__ http://docutils.sourceforge.net/docutils-snapshot.tgz -__ http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz -__ http://docutils.sourceforge.net/docfactory-snapshot.tgz -__ http://docutils.sourceforge.net/docutils-web-snapshot.tgz - -`Anonymous Subversion access`_ is available. You can also `browse the -Subversion repository`_ and read the latest README_, HISTORY_, -COPYING_, FAQ_ and BUGS_ files. - - -Project Releases ----------------- - -The `latest project release package`_ (Docutils 0.3.7, 2004-12-24) and -past project releases can be downloaded from the `project files -page`_. - -Major changes since Docutils 0.3.5: - -* A special "`line block`_" syntax useful for addresses, verse, and - other cases of significant line breaks has been added (also refer to - the `reStructuredText Markup Specification`__). - - .. _line block: docs/user/rst/quickref.html#line-blocks - __ docs/ref/rst/restructuredtext.html#line-blocks - -* Empty sections are now allowed. - -* A "raw_" role has been added. - - .. _raw: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw - -* The LaTeX writer now escapes consecutive dashes (like "--" or "---") - so that they are no longer transformed by LaTeX to en or em dashes. - If you want to write en or em dashes using pure ASCII, please refer - to the `FAQ entry about non-ASCII characters`__. - - __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document - -* A `dependency recorder`_ has been added. - - .. _dependency recorder: docs/user/config.html#record-dependencies - -* A directive has been added for `compound paragraphs`_. - - .. _compound paragraphs: docs/ref/rst/directives.html#compound-paragraph - -* Many other improvements and bug fixes; see the `history file of - Docutils 0.3.7`__. - - __ 0.3.7/HISTORY.html - - -.. _mailing list: - -Mailing Lists -============= - -Users who have questions or need assistance with Docutils or -reStructuredText should first check the `Docutils FAQ`_. If the -question or problem is not answered there, please `post a message`__ -to the `Docutils-users mailing list`__ [#docutils-users]_. - -Developers can keep up to date and help out by joining the mailing -lists. - -High-level discussions take place on the `Python Documentation Special -Interest Group (Doc-SIG) mailing list`__ (email to -Doc-SIG@python.org). - -Two lists have been set up specifically for developers of the Docutils -project: - -- Docutils-develop__, for implementation discussions - (email to docutils-develop@lists.sourceforge.net). -- Docutils-checkins__, to monitor change/checkin messages - (automatically generated; normally read-only). - -The Doc-SIG_ has greater exposure and is therefore a better forum for -general discussions (such as reStructuredText syntax or the high-level -Docutils project model), whereas the Docutils-specific lists are more -focused on the implementation. - -You can also access the mailing lists via the web (at Gmane): -Docutils-users__, Docutils-develop__, Docutils-checkins__ and -Doc-SIG__. - -.. [#docutils-users] Due to overwhelming amounts of spam, the - docutils-users@lists.sourceforge.net mailing list has been set up - for subscriber posting only. Non-subscribers who post to - docutils-users will receive a message with "Subject: Your message - to Docutils-users awaits moderator approval". Legitimate messages - are accepted and posted as soon as possible (a list administrator - must verify the message manually). If you'd like to subscribe to - docutils-users, please visit - <http://lists.sourceforge.net/lists/listinfo/docutils-users>. - -.. _FAQ: -.. _Docutils FAQ: FAQ.html -__ mailto:docutils-users@lists.sourceforge.net -__ http://lists.sourceforge.net/lists/listinfo/docutils-users -__ http://mail.python.org/mailman/listinfo/doc-sig -__ http://lists.sourceforge.net/lists/listinfo/docutils-develop -__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins -__ http://news.gmane.org/gmane.text.docutils.user -__ http://news.gmane.org/gmane.text.docutils.devel -__ http://news.gmane.org/gmane.text.docutils.cvs -__ http://news.gmane.org/gmane.comp.python.documentation - - -The Sandbox -=========== - -The Sandbox__ 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 (you can get a recent tarball from the -`development snapshots`_). Each developer who wants to play in it -should create their own subdirectory (suggested name: SourceForge ID, -or given name + family initial). - -Please feel free to `visit the sandbox`__. - -It's OK to make a mess in the Sandbox! But please, play nice. - -__ -__ sandbox/ - - -Sandbox Projects ----------------- - -Anyone is welcome to contribute to any of these projects. Interested -developers are welcome to take on any projects which appear to be -dormant. Please direct any email to -docutils-develop@lists.sourceforge.net. - -* ZReST_, by Richard Jones, is a "ReStructuredText Document for Zope" - application that is complete and ready to install. - -* PySource_, by Tony Ibbs, is an experimental Python source Reader. - In some form, it will soon become part of core Docutils. There is - some related code in David Goodger's sandbox (pysource_reader_) and - a `Python Source Reader <docs/dev/pysource.html>`__ document. - -* Docutils interface to PythonPoint_, also by Richard Jones, produces - PDF presentations using ReportLabs. - -* Engelbert Gruber has begun `LaTeX Writer`_ and `ManPage Writer`_ components. - -* ? has taken over `ReportLabs/PDF Writer`_ components. - -* Oliver Rutherfurd has begun a `DocBook Writer`_ component and - `HT2HTML integration`_ component. - -* Gunnar Schwant's DocFactory_ is a wxPython GUI application for - Docutils. - -* Aahz has begun an `OpenOffice.org Writer`_. - -* Ian Bicking is working on code for a Wiki_. - -* 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. - -.. _ZReST: sandbox/richard/ZReST/ -.. _PySource: sandbox/tibs/pysource/ -.. _pysource_reader: sandbox/davidg/pysource_reader/ -.. _PythonPoint: sandbox/richard/pythonpoint/ -.. _LaTeX Writer: sandbox/grubert/latex/ -.. _Manpage Writer: sandbox/grubert/man/ -.. _ReportLabs/PDF Writer: sandbox/dreamcatcher/rlpdf/ -.. _DocBook Writer: sandbox/oliverr/docbook/ -.. _HT2HTML integration: sandbox/oliverr/ht/ -.. _DocFactory: sandbox/gschwant/docfactory/doc/ -.. _OpenOffice.org Writer: sandbox/aahz/OO/ -.. _Wiki: sandbox/ianb/wiki/ -.. _simple HTML writer: sandbox/bbum/DocArticle/ -.. _preprocessing module: sandbox/cben/rolehack/ -.. _Makefile: sandbox/cben/make/ - - -Please Contribute! -================== - -Please help this project succeed by contributing. We're looking for -all kinds of contributions: testing, ideas, code, bug reports, -administration, tasty snacks, computer equipment, and large sums of -money. There's a `To Do list`_ full of interesting ideas awaiting a -champion. If you're interested in participating in any way, please -`contact the project coordinator`__. - -Please consider donating to Docutils: |donate| - -__ mailto_ - - -Project Links -============= - -- `Project Summary page`__: `released files`__, `bug reports`__, - patches__, `mailing lists`__, and news__. -- `Docutils Subversion repository`__ -- Project coordinator and architect: `David Goodger`_ -- Please direct discussions to the `Python Documentation Special - Interest Group (Doc-SIG)`__: doc-sig@python.org. -- Powered by |Python|__ -- Hosted by |SourceForge|__ - - __ http://sourceforge.net/projects/docutils/ - __ `project files page`_ - __ http://sourceforge.net/tracker/?group_id=38414&atid=422030 - __ http://sourceforge.net/tracker/?group_id=38414&atid=422032 - __ http://sourceforge.net/mail/?group_id=38414 - __ http://sourceforge.net/news/?group_id=38414 - - __ Subversion_ - - __ Doc-SIG_ - - __ http://www.python.org/ - .. |Python| image:: PyBanner016.png - .. :border: 0 - - __ http://sourceforge.net/ - .. |SourceForge| image:: - http://sourceforge.net/sflogo.php?group_id=38414 - :alt: SourceForge Logo - .. :border: 0 - -.. _reStructuredText: rst.html -.. _project files page: - http://sourceforge.net/project/showfiles.php?group_id=38414 -.. _Anonymous Subversion access: - http://docutils.sourceforge.net/docs/dev/repository.html -.. _Subversion: -.. _browse the Subversion repository: - http://svn.berlios.de/viewcvs/docutils/ -.. _To Do list: docs/dev/todo.html -.. _README: README.html -.. _HISTORY: HISTORY.html -.. _COPYING: COPYING.html -.. _BUGS: BUGS.html -.. _mailto: -.. _David Goodger: mailto:goodger@users.sourceforge.net -.. _Doc-SIG: http://www.python.org/sigs/doc-sig/ - -.. _PEPs: -.. _PEPs (Python Enhancement Proposals): http://www.python.org/peps/ - -.. _latest project release package: - http://prdownloads.sourceforge.net/docutils/docutils-0.3.7.tar.gz?download - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: diff --git a/web/mirror/setext.txt b/web/mirror/setext.txt deleted file mode 100644 index 48d0ee6db..000000000 --- a/web/mirror/setext.txt +++ /dev/null @@ -1,27 +0,0 @@ -========================= - Setext Documents Mirror -========================= - -Here are `local copies of some Setext documents`__, made available to -document the prehistory of the Docutils_ project (and especially the -reStructuredText_ markup). - -__ -.. _Setext mirror: setext/ -.. _Docutils: ../ -.. _reStructuredText: ../rst.html - -The source for the original Setext (structure-enhanced text) documents -was http://www.bsdi.com/setext/, but it seems to have disappeared from -the Web. The files in the "`Setext mirror`_" are all the files -relating to Setext that I have (including `a tarball of the lot`__). - -__ setext/setext.tgz - -I have not been able to locate the originators of Setext, Ian Feldman -or Tony Sanders. If you know how to contact them, or if you know of -an official repository for the Setext documents, please `inform me`__. - -__ mailto:goodger@users.sourceforge.net - -David Goodger, 2002-03-25 diff --git a/web/rst.png b/web/rst.png Binary files differdeleted file mode 100644 index 1bc546c7b..000000000 --- a/web/rst.png +++ /dev/null diff --git a/web/rst.txt b/web/rst.txt deleted file mode 100644 index b16959cfd..000000000 --- a/web/rst.txt +++ /dev/null @@ -1,235 +0,0 @@ -==================== - |reStructuredText| -==================== -------------------------------------------------- - Markup Syntax and Parser Component of Docutils_ -------------------------------------------------- - -:Date: $Date$ - -.. contents:: - -reStructuredText is an easy-to-read, what-you-see-is-what-you-get -plaintext markup syntax and parser system. It is useful for in-line -program documentation (such as Python docstrings), for quickly -creating simple web pages, and for standalone documents. -reStructuredText is designed for extensibility for specific -application domains. The reStructuredText parser is a component of -Docutils_. reStructuredText is a revision and reinterpretation of the -StructuredText_ and Setext_ lightweight markup systems. - -The primary goal of reStructuredText is to define and implement 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 markup is the conversion -of reStructuredText documents into useful structured data formats. - -See statemachine.py_ for an example of a Python module fully -documented using reStructuredText. - - -User Documentation -================== - -- `A ReStructuredText Primer`__ (HTML file, or `text source`__). -- `Quick reStructuredText`__ (user reference) -- `reStructuredText Cheat Sheet`__ (text only; 1 page for syntax, 1 - page directive & role reference) - -Users who have questions or need assistance with Docutils or -reStructuredText should `post a message`__ to the `Docutils-Users -mailing list`__. - -__ docs/user/rst/quickstart.html -__ docs/user/rst/quickstart.txt -__ docs/user/rst/quickref.html -__ docs/user/rst/cheatsheet.txt -__ mailto:docutils-users@lists.sourceforge.net -__ http://lists.sourceforge.net/lists/listinfo/docutils-users - - -Reference Documentation -======================= - -- `An Introduction to reStructuredText`__ (includes the Goals__ and - History__ of reStructuredText) -- `reStructuredText Markup Specification`__ -- `reStructuredText Directives`__ -- `reStructuredText Interpreted Text Roles`__ - -__ docs/ref/rst/introduction.html -__ docs/ref/rst/introduction.html#goals -__ docs/ref/rst/introduction.html#history -__ docs/ref/rst/restructuredtext.html -__ docs/ref/rst/directives.html -__ docs/ref/rst/roles.html - - -Developer Documentation -======================= - -- `A Record of reStructuredText Syntax Alternatives`__ -- `Problems With StructuredText`__ - -__ docs/dev/rst/alternatives.html -__ docs/dev/rst/problems.html - - -How-To's --------- - -- `Creating reStructuredText Directives`__ -- `Creating reStructuredText Interpreted Text Roles`__ - -__ docs/howto/rst-directives.html -__ docs/howto/rst-roles.html - - -Testimonials -============ - -The following testimonials are excerpts from unsolicited posts to -mailing lists and the comp.lang.python newsgroup. Being excerpts, -there's often context missing, which sometimes tones down the message. - -`Ueli Schlaepfer on Doc-SIG, 2002-03-28`__: - -__ http://mail.python.org/pipermail/doc-sig/2002-March/002526.html - - I have adopted reST as my tool of choice for producing notes while - doing lab work (mostly in a matlab environment). Since then, the - quality of such documentation has increased noticeably, mostly for - two reasons: - - - I no longer need to switch to another tool, so the threshold has - fallen to very low. Note that "another tool" means Winword... - - Still, I have a powerful set of markup constructs at my - fingertips that let me create the kind of documents I need with - more ease than any other tool I can think of. - - Thanks to reST/DPS [now Docutils --ed], I'll soon be able to go - ahead and apply the same tools for extracting documentation out of - my Python code. Hey, that's a printable and a browsable version - *for free*! Personally, I consider this a large benefit. - - ... All essential constructs for everyday use are there, and much - more if needed. ... - -`Guido van Rossum, enthusiastic about PEP 287 but a bit hasty (see the -follow-ups) on Python-Dev, 2002-04-02`__: - -__ http://mail.python.org/pipermail/python-dev/2002-April/022131.html - - Good PEP, David! What's the next step? Should the processing - code be incorporated in the standard library? Should we start - converting the standard library docs to reStructuredText? - -`Timothy Delaney on comp.lang.python, 2002-04-03`__: - -__ http://mail.python.org/pipermail/python-list/2002-April/096013.html - - I read through all the reStructuredText docs, comparing the text - versions to the html versions. I found the text versions to be - *very* easy to read, whilst making it obvious in most cases when - something was "special". - - I particularly like the system of doing hyperlinks... - - Definitely +1 from me ... I would really like a standard, clean - docstring format. Might make it easier to get my next project - done in Python... - -`Guido van Rossum on Python-Dev, 2002-04-03`__: - -__ http://mail.python.org/pipermail/python-dev/2002-April/022212.html - - I think that reStructuredText is a good format for marking up - docstrings; it's probably as good as it gets given the - requirements (a fairly elaborate feature set, yet more readable - "in the raw" than HTML). - -`Richard Jones on comp.lang.python, 2002-04-03`__: - -__ http://mail.python.org/pipermail/python-list/2002-April/096117.html - - How I see it is that ReST is a middle ground between markup and - non-. It has markup, and you can use it to the extreme. Or you - can follow some simple conventions (the most basic form of markup) - and not worry about all the finer detail stuff. The difference - between:: - - @section{The Section Title} - - and:: - - The Section Title - ----------------- - - Is pretty clearly to me that the second doesn't *look* like - markup, even though it is. - -`Guido van Rossum on Python-Dev, 2002-04-04`__: - -__ http://mail.python.org/pipermail/python-dev/2002-April/022247.html - - Structured text is really a great idea for certain situations; - reST is a much better implementation of the idea than any versions - I've seen before. - -`Max M on comp.lang.python, 2002-04-05`__: - -__ http://mail.python.org/pipermail/python-list/2002-April/096656.html - - Any programmer can learn the basics in 15 minutes or less. - - And it really is very very easy to write documents in it. I do - belive that if I were ever to write a book (again) I would write - it in ReST. - - And as far as I can tell from the specs, ReST solves most of the - problems I have had with structured text. A few things gets a - little more complicated and some get simpler. All in all a good - bargain. - - I would certainly use it. I also hope that it gets integrated - into Zope. - -`David Abrahams on Python-Dev, 2002-04-06`__: - -__ http://mail.python.org/pipermail/python-dev/2002-April/022443.html - - Incidentally, I'm really excited about reST. I've been looking - for a tolerable markup for C++ comments, and reST looks like it - might fit the bill. - -`Eric Jones on Python-Dev, 2002-08-01`__: - -__ http://mail.python.org/pipermail/python-dev/2002-August/027198.html - - I would very much like to see reStructuredText, or some minor - variation on it, move forward as a "standard" for doc-strings very - soon. I have long lamented not having a prescribed format *and* - an associated processing tool suite included in the standard - library. Even if the format isn't perfect (I think it looks very - good), it is time to pick a reasonable candidate and go. - -This being the Internet, there were plenty of people opposed to the -idea of reStructuredText, some vehemently. Discovering *those* gems -is left as an exercise for the reader. - -.. _Docutils: index.html -.. _StructuredText: - http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/ -.. _Setext: mirror/setext.html -.. _statemachine.py: docutils/statemachine.py - -.. |reStructuredText| image:: rst.png - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: |
