updated

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

2 files changed, 43 insertions, 16 deletions

diff --git a/docutils/FAQ.txt b/docutils/FAQ.txt
index 24ca08165..327c1ddf5 100644
--- a/docutils/FAQ.txt
+++ b/docutils/FAQ.txt
@@ -237,24 +237,26 @@ 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.  "—" in input text is 7 discrete
-characters to Docutils; no interpretation happens.  When writing HTML,
-the "&" is converted to "&", so in the output you'd see
+anything about XML charents.  To Docutils, "—" in input text is
+7 discrete characters; no interpretation happens.  When writing HTML,
+the "&" is converted to "&", so in the raw output you'd see
 "—".  There's no difference in interpretation for text
-inside or outside inline literals or literal blocks -- no character
-entity interpretation in either case.
+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, although ugly.  David Priest developed a
-substitution table for character entities; see
-<http://article.gmane.org/gmane.comp.python.documentation/432> and
-David's other March Doc-SIG posts.  Incorporating this into Docutils
-is on the `to-do list <spec/notes.html#to-do>`_.
+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 opens a
-can of worms though; you can no longer *write* about charents
-naturally; you'd have to write "&amp;mdash;".
+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?
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 3b86cc09b..0d937e255 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -746,9 +746,10 @@ __ rst/alternatives.html#or-not-to-do
 * Generalize the "target-notes" directive into a command-line option
   somehow?  See docutils-develop 2003-02-13.
 
-* Include (after any necessary cleanup & completion) David Priest's
-  substitution table for character entities; see
-  <http://article.gmane.org/gmane.comp.python.documentation/432>.
+* Include the _`character entity substitution definition files`
+  `temporarily stored here <tmp/charents>`__, perhaps in a
+  ``docutils/parsers/rst/includes/`` directory.  See `misc.include`_
+  below.
 
 * Should ^L (or something else in reST) be defined to mean
   force/suggest page breaks in whatever output we have?
@@ -914,6 +915,30 @@ when used in a document.
 
     Option to label lines?
 
+    Default directory for "built-in includes", using the C syntax
+    ``#include <name>``?
+
+        Use C-preprocessor semantics for locating include files?
+        E.g., ``.. include:: file.txt`` will read another file into
+        the current one, relative to the current file's directory, and
+        ``.. include:: <standard>`` will read a standard include file
+        from ``docutils/include/``.  (Should "quotes" be required
+        around non-standard include files?)
+
+        -- http://sf.net/mailarchive/message.php?msg_id=1938401
+
+    I now think that ``docutils/parsers/rst/include/`` is a better
+    place for these files, since they're reStructuredText-specific.
+
+    Keeping standard data files together with the package code makes
+    sense to me.  It seems much less complex to implement than a
+    separate system data directory, such as ``/usr/share/docutils``.
+    Any reason a system data directory should be used?  How does
+    Distutils handle data files?
+
+    For a specific application, see the discussion of `character
+    entity substitution definition files`_ above.
+
 * Implement directives.  Each of the list items below begins with an
   identifier of the form, "module_name.directive_function_name".  The
   directive name itself could be the same as the