[Doc-SIG] [ANN] Character entity sets for reStructuredText

[David Goodger]

I have generated files containing substitution definitions (that use
the "unicode" directive) and temporarily posted them here:
<http://docutils.sf.net/tmp/charents/> (tarball:
<http://docutils.sf.net/tmp/charents.tgz>).  A description and
instructions for use are here:
<http://docutils.sf.net/tmp/charents/README.html>`__.  Thanks to David
Priest for the original idea.  Incorporating these files into Docutils
is on the to-do list.

I'm thinking of adding these to Docutils in a built-in "include"
directory.  From the to-do list:

     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?

An invocation would look like this::

     .. include:: <isonum.txt>

Other possiblilities for the standard includes directory are macros;
see <http://docutils.sf.net/spec/notes.html#text-date> for an example.

If there are enough other standard include files, it may be desirable
to make subdirectories, such as "charents".  Under such a scheme, an
invocation would look like this::

     .. include:: <charents/isonum.txt>

Comments are welcome.

-- 
David Goodger    http://starship.python.net/~goodger
For hire: http://starship.python.net/~goodger/cv
Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)