docs/index.txt

   1 ==========================================
   2  Docutils_ Project Documentation Overview
   3 ==========================================
   4
   5 :Author: David Goodger
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 The latest working documents may be accessed individually below, or
  12 from the ``docs`` directory of the `Docutils distribution`_.
  13
  14 .. _Docutils: http://docutils.sourceforge.net/
  15 .. _Docutils distribution: http://docutils.sourceforge.net/#download
  16
  17 .. contents::
  18
  19
  20 Docutils Stakeholders
  21 =====================
  22
  23 Docutils stakeholders can be categorized in several groups:
  24
  25 1. End-users: users of reStructuredText and the Docutils tools.
  26    Although some are developers (e.g. Python developers utilizing
  27    reStructuredText for docstrings in their source), many are not.
  28
  29 2. Client-developers: developers using Docutils as a library,
  30    programmers developing *with* Docutils.
  31
  32 3. Component-developers: those who implement application-specific
  33    components, directives, and/or roles, separately from Docutils.
  34
  35 4. Core-developers: developers of the Docutils codebase and
  36    participants in the Docutils project community.
  37
  38 5. Re-implementers: developers of alternate implementations of
  39    Docutils.
  40
  41 There's a lot of overlap between these groups.  Most (perhaps all)
  42 core-developers, component-developers, client-developers, and
  43 re-implementers are also end-users.  Core-developers are also
  44 client-developers, and may also be component-developers in other
  45 projects.  Component-developers are also client-developers.
  46
  47
  48 Project Fundamentals
  49 ====================
  50
  51 These files are for all Docutils stakeholders.  They are kept at the
  52 top level of the Docutils project directory.
  53
  54 :README.txt_: Project overview: quick-start, requirements,
  55               installation, and usage.
  56 :COPYING.txt_: Conditions for Docutils redistribution, with links to
  57                licenses.
  58 :FAQ.txt_: Docutils Frequently Asked Questions.  If you have a
  59            question or issue, there's a good chance it's already
  60            answered here.
  61 :BUGS.txt_: A list of known bugs, and how to report a bug.
  62 :RELEASE-NOTES.txt_: Summary of the major changes in recent releases.
  63 :HISTORY.txt_: Detailed change history log.
  64 :THANKS.txt_: Acknowledgements.
  65
  66 .. _README.txt: ../README.html
  67 .. _BUGS.txt: ../BUGS.html
  68 .. _COPYING.txt: ../COPYING.html
  69 .. _Docutils FAQ:
  70 .. _FAQ.txt: ../FAQ.html
  71 .. _RELEASE-NOTES.txt: ../RELEASE-NOTES.html
  72 .. _HISTORY.txt: ../HISTORY.html
  73 .. _THANKS.txt: ../THANKS.html
  74
  75
  76 .. _user:
  77
  78 ``user/``: Introductory & Tutorial Material for End-Users
  79 =========================================================
  80
  81 Docutils-general:
  82
  83 * `Docutils Front-End Tools <user/tools.html>`__
  84 * `Docutils Configuration <user/config.html>`__
  85 * `Docutils Mailing Lists <user/mailing-lists.html>`__
  86 * `Docutils Link List <user/links.html>`__
  87
  88 Writer-specific:
  89
  90 * `Docutils HTML writers <user/html.html>`__
  91 * `Easy Slide Shows With reStructuredText & S5 <user/slide-shows.html>`__
  92 * `Docutils LaTeX Writer <user/latex.html>`__
  93 * `Docutils ODF/OpenOffice/odt Writer <user/odt.html>`__
  94
  95 `reStructuredText <http://docutils.sourceforge.net/rst.html>`_:
  96
  97 * `A ReStructuredText Primer (HTML) <user/rst/quickstart.html>`__ (or
  98   `text source <user/rst/quickstart.txt>`__)
  99 * `Quick reStructuredText <user/rst/quickref.html>`__ (user reference)
 100 * `reStructuredText Cheat Sheet <user/rst/cheatsheet.txt>`__ (text
 101   only; 1 page for syntax, 1 page directive & role reference)
 102 * `reStructuredText Demonstration <user/rst/demo.html>`_ (a
 103   demonstration of most reStructuredText features; you can also have a
 104   look at the `text source <user/rst/demo.txt>`__)
 105
 106 Editor support:
 107
 108 * `Emacs support for reStructuredText <user/emacs.html>`_
 109
 110
 111 .. _ref:
 112
 113 ``ref/``: Reference Material for All Groups
 114 ===========================================
 115
 116 Many of these files began as developer specifications, but now that
 117 they're mature and used by end-users and client-developers, they have
 118 become reference material.  Successful specs evolve into refs.
 119
 120 Docutils-general:
 121
 122 * `The Docutils Document Tree <ref/doctree.html>`__ (incomplete)
 123 * `Docutils Transforms <ref/transforms.html>`__
 124 * `Docutils Generic DTD <ref/docutils.dtd>`__
 125 * `OASIS XML Exchange Table Model Declaration Module
 126   <ref/soextblx.dtd>`__ (CALS tables DTD module)
 127
 128 Although not in the "ref" directory, `PEP 258`_ is a must-read
 129 reference for any Docutils developer.
 130
 131 reStructuredText_:
 132
 133 * `An Introduction to reStructuredText <ref/rst/introduction.html>`__
 134   (includes the `Goals <ref/rst/introduction.html#goals>`__ and
 135   `History <ref/rst/introduction.html#history>`__ of reStructuredText)
 136 * `reStructuredText Markup Specification <ref/rst/restructuredtext.html>`__
 137 * `reStructuredText Directives <ref/rst/directives.html>`__
 138 * `reStructuredText Interpreted Text Roles <ref/rst/roles.html>`__
 139 * `reStructuredText Standard Definition Files
 140   <ref/rst/definitions.html>`_
 141
 142 Prehistoric:
 143
 144 * `Setext Documents Mirror
 145   <http://docutils.sourceforge.net/mirror/setext.html>`__
 146
 147
 148 .. _peps:
 149
 150 ``peps/``: Python Enhancement Proposals
 151 =======================================
 152
 153 * `PEP 256: Docstring Processing System Framework`__ is a high-level
 154   generic proposal.  [`PEP 256`__ in the `master repository`_]
 155 * `PEP 257: Docstring Conventions`__ addresses docstring style and
 156   touches on content.  [`PEP 257`__ in the `master repository`_]
 157 * `PEP 258: Docutils Design Specification`__ is an overview of the
 158   architecture of Docutils.  It documents design issues and
 159   implementation details.  [`PEP 258`__ in the `master repository`_]
 160 * `PEP 287: reStructuredText Docstring Format`__ proposes a standard
 161   markup syntax.  [`PEP 287`__ in the `master repository`_]
 162
 163 Please note that PEPs in the `master repository`_ may not be current,
 164 whereas the local versions are.
 165
 166 __ peps/pep-0256.html
 167 __ http://www.python.org/peps/pep-0256.html
 168 __ peps/pep-0257.html
 169 __ http://www.python.org/peps/pep-0257.html
 170 .. _PEP 258:
 171 __ peps/pep-0258.html
 172 __ http://www.python.org/peps/pep-0258.html
 173 __ peps/pep-0287.html
 174 __ http://www.python.org/peps/pep-0287.html
 175 .. _master repository: http://www.python.org/peps/
 176
 177
 178 .. _api:
 179
 180 ``api/``: API Reference Material for Client-Developers
 181 ======================================================
 182
 183 * `The Docutils Publisher <api/publisher.html>`__
 184 * `Inside A Docutils Command-Line Front-End Tool <api/cmdline-tool.html>`__
 185 * `Docutils Runtime Settings <api/runtime-settings.html>`__
 186 * (`Docutils Transforms <ref/transforms.html>`__ should be moved here)
 187
 188 `PEP 258`_ is an overview of the architecture of Docutils.
 189
 190
 191 .. _howto:
 192
 193 ``howto/``: Instructions for Developers
 194 =======================================
 195
 196 * **Security:** `Deploying Docutils Securely <howto/security.html>`__
 197 * `Writing HTML (CSS) Stylesheets for Docutils
 198   <howto/html-stylesheets.html>`__
 199 * `Docutils Internationalization <howto/i18n.html>`__
 200 * `Creating reStructuredText Directives <howto/rst-directives.html>`__
 201 * `Creating reStructuredText Interpreted Text Roles
 202   <howto/rst-roles.html>`__
 203
 204
 205 .. _dev:
 206
 207 ``dev/``: Development Notes and Plans for Core-Developers
 208 =========================================================
 209
 210 Docutils-general:
 211
 212 * `Docutils Hacker's Guide <dev/hacking.html>`__
 213 * `Docutils Distributor's Guide <dev/distributing.html>`__
 214 * `Docutils To Do List <dev/todo.html>`__
 215 * `Docutils Project Policies <dev/policies.html>`__
 216 * `Docutils Web Site <dev/website.html>`__
 217 * `Docutils Release Procedure <dev/release.html>`__
 218 * `The Docutils Subversion Repository <dev/repository.html>`__
 219 * `Docutils Testing <dev/testing.html>`__
 220 * `Docstring Semantics <dev/semantics.html>`__ (incomplete)
 221 * `Python Source Reader <dev/pysource.html>`_ (incomplete)
 222 * `Docutils Python DTD <dev/pysource.dtd>`_ (experimental)
 223 * `Plan for Enthought API Documentation Tool <dev/enthought-plan.html>`_
 224 * `Enthought API Documentation Tool RFP <dev/enthought-rfp.html>`_
 225
 226 reStructuredText_:
 227
 228 * `A Record of reStructuredText Syntax Alternatives
 229   <dev/rst/alternatives.html>`__
 230 * `Problems With StructuredText <dev/rst/problems.html>`__
 231
 232 \f
 233 ..
 234    Local Variables:
 235    mode: indented-text
 236    indent-tabs-mode: nil
 237    sentence-end-double-space: t
 238    fill-column: 70
 239    End: