[Zope-Checkins] CVS: Zope/lib/python/third_party/docutils/docs - index.txt:1.1.2.1

Andreas Jung andreas at andreas-jung.com
Fri Oct 29 14:24:44 EDT 2004 

Update of /cvs-repository/Zope/lib/python/third_party/docutils/docs
In directory cvs.zope.org:/tmp/cvs-serv11767/docutils/docs

Added Files:
      Tag: ajung-docutils-cleanup-branch
	index.txt 
Log Message:
moved


=== Added File Zope/lib/python/third_party/docutils/docs/index.txt ===
==========================================
 Docutils_ Project Documentation Overview
==========================================

:Author: David Goodger
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:44 $
:Revision: $Revision: 1.1.2.1 $
: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 `development snapshots`__.  They
are also distributed with the `latest project release package`__, but
those may not be completely up to date.

__ http://docutils.sourceforge.net/#development-snapshots
__ http://docutils.sourceforge.net/#project-releases
.. _Docutils: http://docutils.sourceforge.net/

.. 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.
:HISTORY.txt_: Change history log.
:THANKS.txt_: Acknowledgements.

.. _README.txt: ../README.html
.. _BUGS.txt: ../BUGS.html
.. _COPYING.txt: ../COPYING.html
.. _Docutils FAQ:
.. _FAQ.txt: ../FAQ.html
.. _HISTORY.txt: ../HISTORY.html
.. _THANKS.txt: ../THANKS.html


``user/``: Introductory & Tutorial Material for End-Users
=========================================================

Docutils-general:

* `Docutils Front-End Tools <user/tools.html>`__
* `Docutils Configuration Files <user/config.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>`__)


``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>`__

Prehistoric:

* `Setext Documents Mirror
  <http://docutils.sourceforge.net/mirror/setext.html>`__


``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 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/``: Instructions for Developers
=======================================

* `Docutils Internationalization <howto/i18n.html>`__
* `Creating reStructuredText Directives <howto/rst-directives.html>`__
* `Creating reStructuredText Interpreted Text Roles
  <howto/rst-roles.html>`__


``dev/``: Development Notes and Plans for Core-Developers
=========================================================

Docutils-general:

* `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>`__
* `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:

More information about the Zope-Checkins mailing list