This commit was manufactured by cvs2svn to create branch 'ax'.ax

git-svn-id: http://svn.code.sf.net/p/docutils/code/branches/ax@1551 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 0 insertions, 480 deletions

diff --git a/docutils/FAQ.txt b/docutils/FAQ.txt
deleted file mode 100644
index 327c1ddf5..000000000
--- a/docutils/FAQ.txt
+++ /dev/null
@@ -1,480 +0,0 @@
-=====================================
- Docutils Frequently Asked Questions
-=====================================
-
-:Date: $Date$
-:Web site: http://docutils.sourceforge.net/
-:Copyright: This document has been placed in the public domain.
-
-.. Please note that until there's a Q&A-specific construct available,
-   this FAQ will use section titles for questions.  Therefore
-   questions must fit on one line.  The title may be a summary of the
-   question, with the full question in the section body.
-
-
-.. contents::
-.. sectnum::
-
-
-This is a work in progress.  Please feel free to ask questions and/or
-provide answers; `send email`__ to the `Docutils-Users mailing
-list`__.  Project members should feel free to edit the source text
-file directly.
-
-.. _let us know:
-__ mailto:docutils-users@lists.sourceforge.net
-__ http://lists.sourceforge.net/lists/listinfo/docutils-users
-
-
-Docutils
-========
-
-What is Docutils?
------------------
-
-Docutils_ is a system for processing plaintext documentation into
-useful formats, such as HTML, XML, and TeX.  It supports multiple
-types of input, such as standalone files (implemented), inline
-documentation from Python modules and packages (under development),
-`PEPs (Python Enhancement Proposals)`_ (implemented), and others as
-discovered.
-
-For an overview of the Docutils project implementation, see `PEP
-258`_, "Docutils Design Specification".
-
-Docutils is implemented in Python_.
-
-.. _Docutils: http://docutils.sourceforge.net/
-.. _PEPs (Python Enhancement Proposals):
-   http://www.python.org/peps/pep-0012.html
-.. _PEP 258: spec/pep-0258.html
-.. _Python: http://www.python.org/
-
-
-Why is it called "Docutils"?
-----------------------------
-
-Docutils is short for "Python Documentation Utilities".  The name
-"Docutils" was inspired by "Distutils", the Python Distribution
-Utilities architected by Greg Ward, a component of Python's standard
-library.
-
-The earliest known use of the term "docutils" in a Python context was
-a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in
-the Python Doc-SIG mailing list.  It was suggested `as a project
-name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
-a question from Tony "Tibs" Ibbs: "What do we want to *call* this
-thing?".  This was shortly after David Goodger first `announced
-reStructuredText`__ on Doc-SIG.
-
-Tibs used the name "Docutils" for `his effort`__ "to document what the
-Python docutils package should support, with a particular emphasis on
-documentation strings".  Tibs joined the current project (and its
-predecessors) and graciously donated the name.
-
-For more history of reStructuredText and the Docutils project, see `An
-Introduction to reStructuredText`_.
-
-Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
-or any other variation.
-
-.. _An Introduction to reStructuredText: spec/rst/introduction.html
-__ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html
-__ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html
-__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
-__ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html
-
-
-Is there a GUI authoring environment for Docutils?
---------------------------------------------------
-
-DocFactory_ is under development.  It uses wxPython and looks very
-promising.
-
-.. _DocFactory:
-   http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
-
-
-What is the status of the Docutils project?
--------------------------------------------
-
-Although useful and relatively stable, Docutils is experimental code,
-with APIs and architecture subject to change.
-
-Our highest priority is to fix bugs as they are reported.  So the
-latest code from CVS (or `development snapshots`_) is almost always
-the most stable (bug-free) as well as the most featureful.
-
-
-What is the Docutils project release policy?
---------------------------------------------
-
-It ought to be "release early & often", but official releases are a
-significant effort and aren't done that often.  We have
-automatically-generated `development snapshots`_ which always contain
-the latest code from CVS.  As the project matures, we may formalize on
-a stable/development-branch scheme, but we're not using anything like
-that yet.
-
-If anyone would like to volunteer as a release coordinator, please
-`contact the project coordinator`_.
-
-.. _development snapshots:
-   http://docutils.sf.net/#development-snapshots
-
-.. _contact the project coordinator:
-   mailto:goodger@python.org
-
-
-reStructuredText
-================
-
-What is reStructuredText?
--------------------------
-
-reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
-plaintext markup syntax and parser system.  The reStructuredText
-parser is a component of Docutils_.  reStructuredText is a revision
-and reinterpretation of the StructuredText_ and Setext_ lightweight
-markup systems.
-
-If you are reading this on the web, you can see for yourself.  `The
-source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open
-it in another window and compare them side by side.
-
-`A ReStructuredText Primer <docs/rst/quickstart.html>`_ and the `Quick
-reStructuredText <docs/rst/quickref.html>`_ user reference are a good
-place to start.  The `reStructuredText Markup Specification
-<spec/rst/reStructuredText.html>`_ is a detailed technical
-specification.
-
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _StructuredText:
-   http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
-.. _Setext: mirror/setext.html
-
-
-Why is it called "reStructuredText"?
-------------------------------------
-
-The name came from a combination of "StructuredText", one of
-reStructuredText's predecessors, with "re": "revised", "reworked", and
-"reinterpreted", and as in the ``re.py`` regular expression module.
-For a detailed history of reStructuredText and the Docutils project,
-see `An Introduction to reStructuredText`_.
-
-
-What's the standard abbreviation for "reStructuredText"?
---------------------------------------------------------
-
-"RST" and "ReST" (or "reST") are both acceptable.  Care should be
-taken with capitalization, to avoid confusion with "REST__", an
-acronym for "Representational State Transfer".
-
-The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
-they overemphasize reStructuredText's precedessor, Zope's
-StructuredText.
-
-__ http://www.xml.com/pub/a/2002/02/06/rest.html
-
-
-What's the standard filename extension for a reStructuredText file?
--------------------------------------------------------------------
-
-It's ".txt".  Some people would like to use ".rest" or ".rst" or
-".restx", but why bother?  ReStructuredText source files are meant to
-be readable as plaintext, and most operating systems already associate
-".txt" with text files.  Using a specialized filename extension would
-require that users alter their OS settings, which is something that
-many users will not be willing or able to do.
-
-
-Are there any reStructuredText editor extensions?
--------------------------------------------------
-
-There is `some code under development for Emacs`__.
-
-Extensions for other editors are welcome.
-
-__ http://docutils.sf.net/tools/editors/emacs/
-
-
-How can I indicate the document title?  Subtitle?
--------------------------------------------------
-
-A uniquely-adorned section title at the beginning of a document is
-treated specially, as the document title.  Similarly, a
-uniquely-adorned section title immediately after the document title
-becomes the document subtitle.  For example::
-
-    This is the Document Title
-    ==========================
-
-    This is the Document Subtitle
-    -----------------------------
-
-    Here's an ordinary paragraph.
-
-Counterexample::
-
-    Here's an ordinary paragraph.
-
-    This is *not* a Document Title
-    ==============================
-
-    The "ordinary paragraph" above the section title
-    prevents it from becoming the document title.
-
-
-How can I represent esoteric characters (e.g. character entities) in a document?
---------------------------------------------------------------------------------
-
-For example, say you want an em-dash (XML character entity &mdash;,
-Unicode character ``\u2014``) in your document: use a real em-dash.
-Insert concrete characters (e.g. type a *real* em-dash) into your
-input file, using whatever encoding suits your application, and tell
-Docutils the input encoding.  Docutils uses Unicode internally, so the
-em-dash character is a real em-dash internally.
-
-ReStructuredText has no character entity subsystem; it doesn't know
-anything about XML charents.  To Docutils, "&mdash;" in input text is
-7 discrete characters; no interpretation happens.  When writing HTML,
-the "&" is converted to "&amp;", so in the raw output you'd see
-"&amp;mdash;".  There's no difference in interpretation for text
-inside or outside inline literals or literal blocks -- there's no
-character entity interpretation in either case.
-
-If you can't use a Unicode-compatible encoding and must rely on 7-bit
-ASCII, there is a workaround.  Files containing character entity set
-substitution definitions using the "unicode" directive `are available
-<tmp/charents/>`__ (`tarball <tmp/charents.tgz>`__).  A description
-and instructions for use `are here <tmp/charents/README.html>`__.
-Thanks to David Priest for the original idea.  Incorporating these
-files into Docutils is on the `to-do list <spec/notes.html#to-do>`_.
-
-If you insist on using XML-style charents, you'll have to implement a
-pre-processing system to convert to UTF-8 or something.  That
-introduces complications though; you can no longer *write* about
-charents naturally; instead of writing "&mdash;" you'd have to write
-"&amp;mdash;".
-
-
-How can I generate backticks using a Scandinavian keyboard?
------------------------------------------------------------
-
-The use of backticks in reStructuredText is a bit awkward with
-Scandinavian keyboards, where the backtick is a "dead" key.  To get
-one ` character one must press SHIFT-` + SPACE.
-
-Unfortunately, with all the variations out there, there's no way to
-please everyone.  For Scandinavian programmers and technical writers,
-this is not limited to reStructuredText but affects many languages and
-environments.
-
-Possible solutions include
-
-* If you have to input a lot of backticks, simply type one in the
-  normal/awkward way, select it, copy and then paste the rest (CTRL-V
-  is a lot faster than SHIFT-` + SPACE).
-
-* Use keyboard macros.
-
-* Remap the keyboard.  The Scandinavian keyboard layout is awkward for
-  other programming/technical characters too; for example, []{}
-  etc. are a bit awkward compared to US keyboards.
-
-If anyone knows of other/better solutions, please `let us know`_.
-
-
-Are there any tools for HTML/XML-to-reStructuredText?  (Round-tripping)
------------------------------------------------------------------------
-
-People have tossed the idea around, but little if any actual work has
-ever been done.  There's no reason why reStructuredText should not be
-round-trippable to/from XML; any technicalities which prevent
-round-tripping would be considered bugs.  Whitespace would not be
-identical, but paragraphs shouldn't suffer.  The tricky parts would be
-the smaller details, like links and IDs and other bookkeeping.
-
-For HTML, true round-tripping may not be possible.  Even adding lots
-of extra "class" attributes may not be enough.  A "simple HTML" to RST
-filter is possible -- for some definition of "simple HTML" -- but HTML
-is used as dumb formatting so much that such a filter may not be
-particularly useful.  No general-purpose filter exists.  An 80/20
-approach should work though: build a tool that does 80% of the work
-automatically, leaving the other 20% for manual tweaks.
-
-
-Are there any Wikis that use reStructuredText syntax?
------------------------------------------------------
-
-There are several, with various degrees of completeness.  With no
-implied endorsement or recommendation, and in no particular order:
-
-* `Ian Bicking's experimental code <sandbox/ianb/wiki/WikiPage.py>`__
-* `MoinMoin <http://moin.sf.net>`__ has some support; `here's a sample
-  <http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample>`__
-* Zope-based `Zwiki <http://zwiki.org/>`__
-* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
-
-Please `let us know`_ of any other reStructuredText Wikis.
-
-The example application for the `Web Framework Shootout
-<http://colorstudy.com/docs/shootout.html>` article is a Wiki using
-reStructuredText.
-
-
-Are there any Weblog (Blog) projects that use reStructuredText syntax?
-----------------------------------------------------------------------
-
-With no implied endorsement or recommendation, and in no particular
-order:
-
-* `Python Desktop Server <http://pyds.muensterland.org/>`__
-* `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom>`__
-
-Please `let us know`_ of any other reStructuredText Blogs.
-
-
-HTML Writer
-===========
-
-What is the status of the HTML Writer?
---------------------------------------
-
-The HTML Writer module, ``docutils/writers/html4css1.py``, is a
-proof-of-concept reference implementation.  While it is a complete
-implementation, some aspects of the HTML it produces may be
-incompatible with older browsers or specialized applications (such as
-web templating).  Alternate implementations are welcome.
-
-
-What kind of HTML does it produce?
-----------------------------------
-
-It produces XHTML compatible with the `HTML 4.01`_ and `XHTML 1.0`_
-specifications.  A cascading style sheet ("default.css" by default) is
-required for proper viewing with a modern graphical browser.  Correct
-rendering of the HTML produced depends on the CSS support of the
-browser.
-
-.. _HTML 4.01: http://www.w3.org/TR/html4/
-.. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
-
-
-What browsers are supported?
-----------------------------
-
-No specific browser is targeted; all modern graphical browsers should
-work.  Some older browsers, text-only browsers, and browsers without
-full CSS support are known to produce inferior results.  Mozilla
-(version 1.0 and up) and MS Internet Explorer (version 5.0 and up) are
-known to give good results.  Reports of experiences with other
-browsers are welcome.
-
-
-Unexpected results from tools/html.py: H1, H1 instead of H1, H2.  Why?
-----------------------------------------------------------------------
-
-Here's the question in full:
-
-    I have this text::
-
-        Heading 1
-        =========
-
-        All my life, I wanted to be H1.
-
-        Heading 1.1
-        -----------
-
-        But along came H1, and so shouldn't I be H2?
-        No!  I'm H1!
-
-        Heading 1.1.1
-        *************
-
-        Yeah, imagine me, I'm stuck at H3!  No?!?
-
-    When I run it through tools/html.py, I get unexpected results
-    (below).  I was expecting H1, H2, then H3; instead, I get H1, H1,
-    H2::
-
-        ...
-        <html lang="en">
-        <head>
-        ...
-        <title>Heading 1</title>
-        <link rel="stylesheet" href="default.css" type="text/css" />
-        </head>
-        <body>
-        <div class="document" id="heading-1">
-        <h1 class="title">Heading 1</h1>                <-- first H1
-        <p>All my life, I wanted to be H1.</p>
-        <div class="section" id="heading-1-1">
-        <h1><a name="heading-1-1">Heading 1.1</a></h1>        <-- H1
-        <p>But along came H1, and so now I must be H2.</p>
-        <div class="section" id="heading-1-1-1">
-        <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
-        <p>Yeah, imagine me, I'm stuck at H3!</p>
-        ...
-
-    What gives? 
-
-Check the "class" attribute on the H1 tags, and you will see a
-difference.  The first H1 is actually ``<h1 class="title">``; this is
-the document title, and the default stylesheet renders it centered.
-There can also be an ``<h2 class="subtitle">`` for the document
-subtitle.
-
-If there's only one highest-level section title at the beginning of a
-document, it is treated specially, as the document title.  (Similarly,
-a lone second-highest-level section title may become the document
-subtitle.)  Rather than use a plain H1 for that, we use ``<h1
-class="title">`` so that we can use H1 again within the document.  Why
-do we do this?  HTML only has H1-H6, so by making H1 do double duty,
-we effectively reserve these tags to provide 6 levels of heading
-beyond the single document title.
-
-HTML is being used for dumb formatting for nothing but final display.
-A stylesheet *is required*, and one is provided:
-tools/stylesheets/default.css.  Of course, you're welcome to roll your
-own.
-
-(Thanks to Mark McEahern for the question and much of the answer.)
-
-
-Why do enumerated lists only use numbers (no letters or roman numerals)?
-------------------------------------------------------------------------
-
-The rendering of enumerators (the numbers or letters acting as list
-markers) is completely governed by the stylesheet, so either the
-browser can't find the stylesheet (try using the "--embed-stylesheet"
-option), or the browser can't understand it (try a recent Mozilla or
-MSIE).
-
-
-Python Source Reader
-====================
-
-Can I use Docutils for Python auto-documentation?
--------------------------------------------------
-
-Docstring extraction is still under development.  There is most of a
-source code parsing module in docutils/readers/python/moduleparser.py.
-I (David Goodger) haven't worked on it in a while, but I do plan to
-finish it eventually.  Ian Bicking wrote an initial front end for my
-moduleparser module, in sandbox/ianb/extractor/extractor.py.
-
-
-Miscellaneous
-=============
-
-Is the Docutils document model based on any existing XML models?
-----------------------------------------------------------------
-
-Not directly, no.  It borrows bits from DocBook, HTML, and others.  I
-(David Goodger) have designed several document models over the years,
-and have my own biases.  The Docutils document model is designed for
-simplicity and extensibility, and has been influenced by the needs of
-the reStructuredText markup.