[Zope-Checkins] CVS: Zope/lib/python/third_party/docutils/docs/dev
- enthought-plan.txt:1.1.2.1 enthought-rfp.txt:1.1.2.1
policies.txt:1.1.2.1 pysource.dtd:1.1.2.1
pysource.txt:1.1.2.1 release.txt:1.1.2.1
semantics.txt:1.1.2.1 testing.txt:1.1.2.1 todo.txt:1.1.2.1
website.txt:1.1.2.1
Andreas Jung
andreas at andreas-jung.com
Fri Oct 29 14:24:45 EDT 2004
Update of /cvs-repository/Zope/lib/python/third_party/docutils/docs/dev
In directory cvs.zope.org:/tmp/cvs-serv11767/docutils/docs/dev
Added Files:
Tag: ajung-docutils-cleanup-branch
enthought-plan.txt enthought-rfp.txt policies.txt pysource.dtd
pysource.txt release.txt semantics.txt testing.txt todo.txt
website.txt
Log Message:
moved
=== Added File Zope/lib/python/third_party/docutils/docs/dev/enthought-plan.txt ===
===========================================
Plan for Enthought API Documentation Tool
===========================================
:Author: David Goodger
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:45 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: 2004 by `Enthought, Inc. <http://www.enthought.com>`_
:License: `Enthought License`_ (BSD-style)
.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
This document should be read in conjunction with the `Enthought API
Documentation Tool RFP`__ prepared by Janet Swisher.
__ enthought-rfp.html
.. contents::
.. sectnum::
Introduction
============
In March 2004 at I met Eric Jones, president and CTO of `Enthought,
Inc.`_, at `PyCon 2004`_ in Washington DC. He told me that Enthought
was using reStructuredText_ for source code documentation, but they
had some issues. He asked if I'd be interested in doing some work on
a customized API documentation tool. Shortly after PyCon, Janet
Swisher, Enthought's senior technical writer, contacted me to work out
details. Some email, a trip to Austin in May, and plenty of Texas
hospitality later, we had a project. This document will record the
details, milestones, and evolution of the project.
In a nutshell, Enthought is sponsoring the implementation of an open
source API documentation tool that meets their needs. Fortuitously,
their needs coincide well with the "Python Source Reader" description
in `PEP 258`_. In other words, Enthought is funding some significant
improvements to Docutils, improvements that were planned but never
implemented due to time and other constraints. The implementation
will take place gradually over several months, on a part-time basis.
This is an ideal example of cooperation between a corporation and an
open-source project. The corporation, the project, I personally, and
the community all benefit. Enthought, whose commitment to open source
is also evidenced by their sponsorship of SciPy_, benefits by
obtaining a useful piece of software, much more quickly than would
have been possible without their support. Docutils benefits directly
from the implementation of one of its core subsystems. I benefit from
the funding, which allows me to justify the long hours to my wife and
family. All the corporations, projects, and individuals that make up
the community will benefit from the end result, which will be great.
All that's left now is to actually do the work!
.. _PyCon 2004: http://pycon.org/dc2004/
.. _reStructuredText: http://docutils.sf.net/rst.html
.. _SciPy: http://www.scipy.org/
Development Plan
================
1. Analyze prior art, most notably Epydoc_ and HappyDoc_, to see how
they do what they do. I have no desire to reinvent wheels
unnecessarily. I want to take the best ideas from each tool,
combined with the outline in `PEP 258`_ (which will evolve), and
build at least the foundation of the definitive Python
auto-documentation tool.
.. _Epydoc: http://epydoc.sourceforge.net/
.. _HappyDoc: http://happydoc.sourceforge.net/
.. _PEP 258:
http://docutils.sf.net/spec/pep-0258.html#python-source-reader
2. Decide on a base platform. The best way to achieve Enthought's
goals in a reasonable time frame may be to extend Epydoc or
HappyDoc. Or it may be necessary to start fresh.
3. Extend the reStructuredText parser. See `Proposed Changes to
reStructuredText`_ below.
4. Depending on the base platform chosen, build or extend the
docstring & doc comment extraction tool. This may be the biggest
part of the project, but I won't be able to break it down into
details until more is known.
Repository
==========
If possible, all software and documentation files will be stored in
the CVS repository of Docutils and/or the base project, which are all
publicly-available via anonymous pserver access.
The Docutils project is very open about granting CVS write access; so
far, everyone who asked has been given access. Any Enthought staff
member who would like CVS write access will get it.
If either Epydoc or HappyDoc is chosen as the base platform, I will
ask the project's administrator for CVS access for myself and any
Enthought staff member who wants it. If sufficient access is not
granted -- although I doubt that there would be any problem -- we may
have to begin a fork, which could be hosted on SourceForge, on
Enthought's Subversion server, or anywhere else deemed appropriate.
Copyright & License
===================
Most existing Docutils files have been placed in the public domain, as
follows::
:Copyright: This document has been placed in the public domain.
This is in conjunction with the "Public Domain Dedication" section of
COPYING.txt__.
__ http://docutils.sourceforge.net/COPYING.html
The code and documentation originating from Enthought funding will
have Enthought's copyright and license declaration. While I will try
to keep Enthought-specific code and documentation separate from the
existing files, there will inevitably be cases where it makes the most
sense to extend existing files.
I propose the following:
1. New files related to this Enthought-funded work will be identified
with the following field-list headers::
:Copyright: 2004 by Enthought, Inc.
:License: Enthought License (BSD Style)
The license field text will be linked to the license file itself.
2. For significant or major changes to an existing file (more than 10%
change), the headers shall change as follows (for example)::
:Copyright: 2001-2004 by David Goodger
:Copyright: 2004 by Enthought, Inc.
:License: BSD-style
If the Enthought-funded portion becomes greater than the previously
existing portion, Enthought's copyright line will be shown first.
3. In cases of insignificant or minor changes to an existing file
(less than 10% change), the public domain status shall remain
unchanged.
A section describing all of this will be added to the Docutils
`COPYING`__ instructions file.
If another project is chosen as the base project, similar changes
would be made to their files, subject to negotiation.
__ http://docutils.sf.net/COPYING.html
Proposed Changes to reStructuredText
====================================
Doc Comment Syntax
------------------
The "traits" construct is implemented as dictionaries, where
standalone strings would be Python syntax errors. Therefore traits
require documentation in comments. We also need a way to
differentiate between ordinary "internal" comments and documentation
comments (doc comments).
Javadoc uses the following syntax for doc comments::
/**
* The first line of a multi-line doc comment begins with a slash
* and *two* asterisks. The doc comment ends normally.
*/
Python doesn't have multi-line comments; only single-line. A similar
convention in Python might look like this::
##
# The first line of a doc comment begins with *two* hash marks.
# The doc comment ends with the first non-comment line.
'data' : AnyValue,
## The double-hash-marks could occur on the first line of text,
# saving a line in the source.
'data' : AnyValue,
How to indicate the end of the doc comment? ::
##
# The first line of a doc comment begins with *two* hash marks.
# The doc comment ends with the first non-comment line, or another
# double-hash-mark.
##
# This is an ordinary, internal, non-doc comment.
'data' : AnyValue,
## First line of a doc comment, terse syntax.
# Second (and last) line. Ends here: ##
# This is an ordinary, internal, non-doc comment.
'data' : AnyValue,
Or do we even need to worry about this case? A simple blank line
could be used::
## First line of a doc comment, terse syntax.
# Second (and last) line. Ends with a blank line.
# This is an ordinary, internal, non-doc comment.
'data' : AnyValue,
Other possibilities::
#" Instead of double-hash-marks, we could use a hash mark and a
# quotation mark to begin the doc comment.
'data' : AnyValue,
## We could require double-hash-marks on every line. This has the
## added benefit of delimiting the *end* of the doc comment, as
## well as working well with line wrapping in Emacs
## ("fill-paragraph" command).
# Ordinary non-doc comment.
'data' : AnyValue,
#" A hash mark and a quotation mark on each line looks funny, and
#" it doesn't work well with line wrapping in Emacs.
'data' : AnyValue,
These styles (repeated on each line) work well with line wrapping in
Emacs::
## #> #| #- #% #! #*
These styles do *not* work well with line wrapping in Emacs::
#" #' #: #) #. #/ #@ #$ #^ #= #+ #_ #~
The style of doc comment indicator used could be a runtime, global
and/or per-module setting. That may add more complexity than it's
worth though.
Recommendation
``````````````
I recommend adopting "#*" on every line::
# This is an ordinary non-doc comment.
#* This is a documentation comment, with an asterisk after the
#* hash marks on every line.
'data' : AnyValue,
I initially recommended adopting double-hash-marks::
# This is an ordinary non-doc comment.
## This is a documentation comment, with double-hash-marks on
## every line.
'data' : AnyValue,
But Janet Swisher rightly pointed out that this could collide with
ordinary comments that are then block-commented. This applies to
double-hash-marks on the first line only as well. So they're out.
Docstring Density & Whitespace Minimization
-------------------------------------------
One problem with extensively documented classes & functions, is that
there is a lot of screen space wasted on whitespace. Here's some
current Enthought code (from lib/cp/fluids/gassmann.py)::
def max_gas(temperature, pressure, api, specific_gravity=.56):
"""
Computes the maximum dissolved gas in oil using Batzle and
Wang (1992).
Parameters
----------
temperature : sequence
Temperature in degrees Celsius
pressure: sequence
Pressure in MPa
api : sequence
Stock tank oil API
specific_gravity : sequence
Specific gravity of gas at STP, default is .56
Returns
-------
max_gor : sequence
Maximum dissolved gas in liters/liter
Description
-----------
This estimate is based on equations given by Mavko, Mukerji,
and Dvorkin, (1998, pp. 218-219, or 2003, p. 236) obtained
originally from Batzle and Wang (1992).
"""
code...
The docstring is 24 lines long.
Rather than using subsections, field lists (which exist now) can save
5 lines::
def max_gas(temperature, pressure, api, specific_gravity=.56):
"""
Computes the maximum dissolved gas in oil using Batzle and
Wang (1992).
:Parameters:
temperature : sequence
Temperature in degrees Celsius
pressure: sequence
Pressure in MPa
api : sequence
Stock tank oil API
specific_gravity : sequence
Specific gravity of gas at STP, default is .56
:Returns:
max_gor : sequence
Maximum dissolved gas in liters/liter
:Description:
This estimate is based on equations given by Mavko,
Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236)
obtained originally from Batzle and Wang (1992).
"""
code...
The output for field lists is typically a table structure. For
example:
:Parameters:
temperature : sequence
Temperature in degrees Celsius
pressure: sequence
Pressure in MPa
api : sequence
Stock tank oil API
specific_gravity : sequence
Specific gravity of gas at STP, default is .56
:Returns:
max_gor : sequence
Maximum dissolved gas in liters/liter
:Description:
This estimate is based on equations given by Mavko,
Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236)
obtained originally from Batzle and Wang (1992).
But the definition lists describing the parameters and return values
are still wasteful of space. There are a lot of half-filled lines.
Definition lists are currently defined as::
term : classifier
definition
Where the classifier part is optional.
* We could allow multiple classifiers::
term : classifier one : two : three ...
definition
* We could allow the definition on the same line as the term, but only
in limited and well-known contexts::
term -- definition
This is the syntax used by StructuredText (one of reStructuredText's
predecessors). It was not adopted for reStructuredText because it
is ambiguous -- people often use "--" in their text, as I just did.
But given a constrained context, the ambiguity would be acceptable.
That context would be: in docstrings, within a field list, perhaps
only with certain well-defined field names (parameters, returns).
Recommendation
``````````````
Combining these ideas, the function definition becomes::
def max_gas(temperature, pressure, api, specific_gravity=.56):
"""
Computes the maximum dissolved gas in oil using Batzle and
Wang (1992).
:Parameters:
temperature : sequence -- Temperature in degrees Celsius
pressure: sequence -- Pressure in MPa
api : sequence -- Stock tank oil API
specific_gravity : sequence -- Specific gravity of gas at
STP, default is .56
:Returns:
max_gor : sequence -- Maximum dissolved gas in liters/liter
:Description:
This estimate is based on equations given by Mavko,
Mukerji, and Dvorkin, (1998, pp. 218-219, or 2003, p. 236)
obtained originally from Batzle and Wang (1992).
"""
code...
The docstring is reduced to 15 lines, from the original 24. For
longer docstrings with many parameters and return values, the
difference would be more significant.
=== Added File Zope/lib/python/third_party/docutils/docs/dev/enthought-rfp.txt ===
==================================
Enthought API Documentation Tool
==================================
-----------------------
Request for Proposals
-----------------------
:Author: Janet Swisher, Senior Technical Writer
:Organization: `Enthought, Inc. <http://www.enthought.com>`_
:Copyright: 2004 by Enthought, Inc.
:License: `Enthought License`_ (BSD Style)
.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
The following is excerpted from the full RFP, and is published here
with permission from `Enthought, Inc.`_ See the `Plan for Enthought
API Documentation Tool`__.
__ enthought-plan.html
.. contents::
.. sectnum::
Requirements
============
The documentation tool will address the following high-level goals:
Documentation Extraction
------------------------
1. Documentation will be generated directly from Python source code,
drawing from the code structure, docstrings, and possibly other
comments.
2. The tool will extract logical constructs as appropriate, minimizing
the need for comments that are redundant with the code structure.
The output should reflect both documented and undocumented
elements.
Source Format
-------------
1. The docstrings will be formatted in as terse syntax as possible.
Required tags, syntax, and white space should be minimized.
2. The tool must support the use of Traits. Special comment syntax
for Traits may be necessary. Information about the Traits package
is available at http://old.scipy.org/site_content/traits. In the
following example, each trait definition is prefaced by a plain
comment::
__traits__ = {
# The current selection within the frame.
'selection' : Trait([], TraitInstance(list)),
# The frame has been activated or deactivated.
'activated' : TraitEvent(),
'closing' : TraitEvent(),
# The frame is closed.
'closed' : TraitEvent(),
}
3. Support for ReStructuredText (ReST) format is desirable, because
much of the existing docstrings uses ReST. However, the complete
ReST specification need not be supported, if a subset can achieve
the project goals. If the tool does not support ReST, the
contractor should also provide a tool or path to convert existing
docstrings.
Output Format
-------------
1. Documentation will be output as a navigable suite of HTML
files.
2. The style of the HTML files will be customizable by a cascading
style sheet and/or a customizable template.
3. Page elements such as headers and footer should be customizable, to
support differing requirements from one documentation project to
the next.
Output Structure and Navigation
-------------------------------
1. The navigation scheme for the HTML files should not rely on frames,
and should harmonize with conversion to Microsoft HTML Help (.chm)
format.
2. The output should be structured to make navigable the architecture
of the Python code. Packages, modules, classes, traits, and
functions should be presented in clear, logical hierarchies.
Diagrams or trees for inheritance, collaboration, sub-packaging,
etc. are desirable but not required.
3. The output must include indexes that provide a comprehensive view
of all packages, modules, and classes. These indexes will provide
readers with a clear and exhaustive view of the code base. These
indexes should be presented in a way that is easily accessible and
allows easy navigation.
4. Cross-references to other documented elements will be used
throughout the documentation, to enable the reader to move quickly
relevant information. For example, where type information for an
element is available, the type definition should be
cross-referenced.
5. The HTML suite should provide consistent navigation back to the
home page, which will include the following information:
* Bibliographic information
- Author
- Copyright
- Release date
- Version number
* Abstract
* References
- Links to related internal docs (i.e., other docs for the same
product)
- Links to related external docs (e.g., supporting development
docs, Python support docs, docs for included packages)
It should be possible to specify similar information at the top
level of each package, so that packages can be included as
appropriate for a given application.
License
=======
Enthought intends to release the software under an open-source
("BSD-style") license.
=== Added File Zope/lib/python/third_party/docutils/docs/dev/policies.txt ===
===========================
Docutils Project Policies
===========================
:Author: David Goodger; open to all Docutils developers
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:45 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: This document has been placed in the public domain.
.. contents::
A few quotes sum up the policies of the Docutils project. The IETF's
classic credo (by MIT professor Dave Clark) is an ideal we can aspire
to:
We reject: kings, presidents, and voting. We believe in: rough
consensus and running code.
As architect, chief cook and bottle-washer, I currently function as
BDFN (Benevolent Dictator For Now), but I would happily abdicate the
throne given a suitable candidate. Any takers?
Eric S. Raymond, anthropologist of the hacker subculture, writes in
his essay `The Magic Cauldron`_:
The number of contributors [to] projects is strongly and inversely
correlated with the number of hoops each project makes a user go
through to contribute.
.. _The Magic Cauldron:
http://www.tuxedo.org/~esr/writings/magic-cauldron/
Therefore, we will endeavour to keep the barrier to entry as low as
possible. The policies below should not be thought of as barriers,
but merely as a codification of experience to date. These are "best
practices", not absolutes; exceptions are expected, tolerated, and
used as a source of improvement.
As for control issues, Emmett Plant (CEO of the Xiph.org Foundation,
originators of Ogg Vorbis) put it well when he said:
Open source dictates that you lose a certain amount of control
over your codebase, and that's okay with us.
Python Coding Conventions
=========================
These are the conventions I use in my own code. Contributed code will
not be refused merely because it does not strictly adhere to these
conditions; as long as it's internally consistent, clean, and correct,
it probably will be accepted. But don't be surprised if the
"offending" code gets fiddled over time to conform to these
conventions.
The Docutils project shall follow the generic coding conventions as
specified in the `Style Guide for Python Code`_ and `Docstring
Conventions`_ PEPs, with the following clarifications (from most to
least important):
* 4 spaces per indentation level. No tabs.
* Use only ASCII, no 8-bit strings. See `Docutils
Internationalization`_.
* No one-liner compound statements (i.e., no ``if x: return``: use two
lines & indentation), except for degenerate class or method
definitions (i.e., ``class X: pass`` is O.K.).
* Lines should be no more than 78 characters long.
* Use "StudlyCaps" for class names (except for element classes in
docutils.nodes).
* Use "lowercase" or "lowercase_with_underscores" for function,
method, and variable names. For short names, maximum two words,
joined lowercase may be used (e.g. "tagname"). For long names with
three or more words, or where it's hard to parse the split between
two words, use lowercase_with_underscores (e.g.,
"note_explicit_target", "explicit_target"). If in doubt, use
underscores.
* Use 'single quotes' for string literals, and """triple double
quotes""" for docstrings.
.. _Style Guide for Python Code:
http://www.python.org/peps/pep-0008.html
.. _Docstring Conventions: http://www.python.org/peps/pep-0257.html
.. _Docutils Internationalization: ../howto/i18n.html#python-code
Copyrights and Licensing
========================
The majority of the Docutils project code and documentation has been
placed in the public domain. Unless clearly and explicitly indicated
otherwise, any patches (modifications to existing files) submitted to
the project for inclusion (via CVS, SourceForge trackers, mailing
lists, or private email) are assumed to be in the public domain as
well.
Any new files contributed to the project should clearly state their
intentions regarding copyright, in one of the following ways:
* Public domain (preferred): include the statement "This
module/document has been placed in the public domain."
* Copyright & open source license: include a copyright notice, along
with either an embedded license statement, a reference to an
accompanying license file, or a license URL.
One of the goals of the Docutils project, once complete, is to be
incorporated into the Python standard library. At that time copyright
of the Docutils code will be assumed by or transferred to the Python
Software Foundation (PSF), and will be released under Python's
license. If the copyright/license option is chosen for new files, the
license should be compatible with Python's current license, and the
author(s) of the files should be willing to assign copyright to the
PSF.
CVS Check-ins
=============
Instructions for CVS access can be found at
http://sourceforge.net/cvs/?group_id=38414. Anyone can access the CVS
repository anonymously. Only project developers can make changes.
See `Setting Up For Docutils Development`_ below for more info.
Unless you really *really* know what you're doing, please limit your
CVS commands to ``cvs checkout``, ``cvs commit/checkin``, and ``cvs
add``. Do **NOT** use ``cvs import`` unless you're absolutely sure
you know what you're doing. Even then, grab a copy of the `nightly
CVS tarball`_, set it up on your own machine, and experiment *there*
first.
The `main source tree`_ ("docutils" CVS module) should always be kept
in a stable state (usable and as problem-free as possible). The
Docutils project shall follow the `Python Check-in Policies`_ (as
applicable), with particular emphasis as follows:
* Before checking in any changes, run the entire Docutils test suite
to be sure that you haven't broken anything. From a shell::
cd docutils/test
./alltests.py
Docutils currently supports Python 2.1 [1]_ or later, with some
things only working (and being tested) on 2.3. Therefore, you
should actually have Pythons 2.1 [1]_, 2.2 and 2.3 installed and
always run the tests on all of them. (A good way to do that is to
always run the test suite through a short script that runs
``alltests.py`` under each version of Python.) If you can't afford
intalling 3 Python versions, the edge cases (2.1 and 2.3) should
cover most of it.
.. [1] Python 2.1 may be used providing the compiler package is
installed. The compiler package can be found in the Tools/
directory of Python 2.1's source distribution.
Good resources covering the differences between Python versions:
* `What's New in Python 2.2`__
* `What's New in Python 2.3`__
* `What's New in Python 2.4`__
* `PEP 290 - Code Migration and Modernization`__
__ http://www.python.org/doc/2.2.3/whatsnew/whatsnew22.html
__ http://www.python.org/doc/2.3.4/whatsnew/whatsnew23.html
__ http://www.python.org/dev/doc/devel/whatsnew/whatsnew24.html
__ http://www.python.org/peps/pep-0290.html
Note that there are currently some known issues with development
versions of Python 2.4-to-be (see the thread about `Python 2.4
compatibility`_ for details). There is no need to pass the test
suite under it, unless you wish to tackle these issues...
.. _Python 2.4 compatibility:
http://thread.gmane.org/gmane.text.docutils.devel/2071
* When adding new functionality (or fixing bugs), be sure to add test
cases to the test suite. Practise test-first programming; it's fun,
it's addictive, and it works!
* The `sandbox CVS directory`_ is the place to put new, incomplete or
experimental code. See `Additions to Docutils`_ and `The Sandbox`_
below.
* For bugs or omissions that have an obvious fix and can't possibly
mess up anything else, go right ahead and check it in directly.
* For larger changes, use your best judgement. If you're unsure of
the impact, or feel that you require advice or approval, patches or
`the sandbox`_ are the way to go.
Docutils will pursue an open and trusting policy for as long as
possible, and deal with any aberrations if (and hopefully not when)
they happen. I'd rather see a torrent of loose contributions than
just a trickle of perfect-as-they-stand changes. The occasional
mistake is easy to fix. That's what CVS is for.
.. _main source tree:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/docutils/
.. _Python Check-in Policies: http://www.python.org/dev/tools.html
.. _sandbox CVS directory:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/sandbox/
.. _nightly CVS tarball:
http://cvs.sourceforge.net/cvstarballs/docutils-cvsroot.tar.bz2
Additions to Docutils
---------------------
Additions to the project, such as new components, should be developed
in the `sandbox CVS directory`_ until they're in `good shape`_,
usable_, documented_, and `reasonably complete`_. Adding to the `main
source tree`_ or to a `parallel project`_ implies a commitment to the
Docutils user community.
* Why the sandbox?
Developers should be able to try out new components while they're
being developed for addition to main source tree. See `The
Sandbox`_ below.
* _`Good shape` means that the component code is clean, readable, and
free of junk code (unused legacy code; by analogy with "junk DNA").
* _`Usable` means that the code does what it claims to do. An "XYZ
Writer" should produce reasonable XYZ.
* _`Documented`: The more the better. The modules/files must be at
least minimally documented internally. `Docutils Front-End Tools`_
should have a new section for any front-end tool that is added.
`Docutils Configuration Files`_ should be modified with any
settings/options defined.
* _`Reasonably complete` means that the code must handle all input.
Here "handle" means that no input can cause the code to fail (cause
an exception, or silently and incorrectly produce nothing).
"Reasonably complete" does not mean "finished" (no work left to be
done). For example, a writer must handle every standard element
from the Docutils document model; for unimplemented elements, it
must *at the very least* warn that "Output for element X is not yet
implemented in writer Y".
If you really want to check code into the main source tree, you can,
but you'll have to be prepared to work on it intensively and complete
it quickly. People will start to use it and they will expect it to
work! If there are any issues with your code, or if you only have
time for gradual development, you should put it in the sandbox first.
It's easy to move code over to the main source tree once it's closer
to completion.
.. _Docutils Front-End Tools: ../user/tools.html
.. _Docutils Configuration Files: ../user/config.html
CVS Startup File
----------------
In your ~/.cvsrc file, make sure you have a line like this::
update -dP
This ensures that new directories are created and empty directories
are pruned (removed) from your working copy. In addition, these lines
are useful::
cvs -q -z3
diff -u
``cvs -q`` suppresses many non-essential messages. ``-z3`` compresses
data between client and server. ``diff -u`` creates "unified diffs";
specify ``diff -c`` if you prefer context diffs.
Setting Up For Docutils Development
-----------------------------------
When making changes to the code, good developers always test their
changes. That means running the code to check that it produces the
expected results, and running the test suite too. The modified
Docutils code has to be accessible to Python for the tests to have any
meaning. There are two ways to keep the Docutils code accessible:
* Update your ``PYTHONPATH`` environment variable so that Python picks
up your local working copy of the code. This is the recommended
method.
For the bash shell and Docutils checked out from CVS in
``~/projects/docutils/``, add this to your ``~/.profile``::
PYTHONPATH=$HOME/projects/docutils/docutils
PYTHONPATH=$PYTHONPATH:$HOME/projects/docutils/docutils/extras
export PYTHONPATH
The first line points to the directory containing the ``docutils``
package. The second line adds the directory containing the
third-party modules Docutils depends on. The third line exports
this environment variable. You may also wish to add the ``tools``
directory to your ``PATH``::
PATH=$PATH:$HOME/projects/docutils/docutils/tools
* Before you run anything, every time you make a change, reinstall
Docutils::
python setup.py install
.. CAUTION::
This method is **not** recommended for day-to-day development;
it's too easy to forget. Confusion inevitably ensues.
If you install Docutils this way, Python will always pick up the
last-installed copy of the code. If you ever forget to reinstall
the "docutils" package, Python won't see your latest changes.
Mailing Lists
=============
Developers should subscribe to the mailing lists:
* The `Python Documentation Special Interest Group (Doc-SIG) mailing
list`__ for high-level discussions on syntax, strategy, and design
(email to Doc-SIG at python.org).
* Docutils-develop__, for implementation discussions
(email to docutils-develop at lists.sourceforge.net).
* Docutils-checkins__, to monitor CVS checkin messages (automatically
generated; normally read-only).
* Docutils-users__, to monitor and help out with usage issues and bug
reports.
__ http://mail.python.org/mailman/listinfo/doc-sig
__ http://lists.sourceforge.net/lists/listinfo/docutils-develop
__ http://lists.sourceforge.net/lists/listinfo/docutils-checkins
__ http://lists.sourceforge.net/lists/listinfo/docutils-users
The Sandbox
===========
The `sandbox CVS directory`_ is a place to play around, to try out and
share ideas. It's a part of the CVS repository but it isn't
distributed as part of Docutils releases. Feel free to check in code
to the CVS sandbox; that way people can try it out but you won't have
to worry about it working 100% error-free, as is the goal of the `main
source tree`_. Each developer who wants to play in the sandbox should
create either a project-specific subdirectory or personal subdirectory
(suggested name: SourceForge ID, nickname, or given name + family
initial). It's OK to make a mess! But please, play nice.
Please update the `sandbox README`_ file with links and a brief
description of your work.
In order to minimize the work necessary for others to install and try
out new, experimental components, the following sandbox directory
structure is recommended::
sandbox/
project_name/ # For a project where you invite contributions.
# Structure as in userid/component_name below.
userid/ # For personal space.
component_name/ # A verbose name is best.
README.txt # Please explain requirements,
# purpose/goals, and usage.
docs/
...
component.py # The component is a single module.
# *OR* (but *not* both)
component/ # The component is a package.
__init__.py # Contains the Reader/Writer class.
other1.py # Other modules and data files used
data.txt # by this component.
...
test/ # Test suite.
...
tools/ # For front ends etc.
...
setup.py # Use Distutils to install the component
# code and tools/ files into the right
# places in Docutils.
Some sandbox projects are destined to become Docutils components once
completed. Others, such as add-ons to Docutils or applications of
Docutils, graduate to become `parallel projects`_.
.. _sandbox README: http://docutils.sf.net/sandbox/README.html
.. _parallel project:
Parallel Projects
=================
Parallel projects contain useful code that is not central to the
functioning of Docutils. Examples are specialized add-ons or
plug-ins, and applications of Docutils. They use Docutils, but
Docutils does not require their presence to function.
An official parallel project will have its own CVS directory beside
(or parallel to) the main Docutils CVS directory. It can have its own
web page in the docutils.sourceforge.net domain, its own file releases
and downloadable CVS snapshots, and even a mailing list if that proves
useful. However, an official parallel project has implications: it is
expected to be maintained and continue to work with changes to the
core Docutils.
A parallel project requires a project leader, who must commit to
coordinate and maintain the implementation:
* Answer questions from users and developers.
* Review suggestions, bug reports, and patches.
* Monitor changes and ensure the quality of the code and
documentation.
* Coordinate with Docutils to ensure interoperability.
* Put together official project releases.
Of course, related projects may be created independently of Docutils.
The advantage of a parallel project is that the SourceForge
environment and the developer and user communities are already
established. Core Docutils developers are available for consultation
and may contribute to the parallel project. It's easier to keep the
projects in sync when there are changes made to the core Docutils
code.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
=== Added File Zope/lib/python/third_party/docutils/docs/dev/pysource.dtd ===
<!--
======================================================================
Docutils Python Source DTD
======================================================================
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:Revision: $Revision: 1.1.2.1 $
:Date: $Date: 2004/10/29 18:24:45 $
:Copyright: This DTD has been placed in the public domain.
:Filename: pysource.dtd
This DTD (document type definition) extends the Generic DTD (see
below).
More information about this DTD and the Docutils project can be found
at http://docutils.sourceforge.net/. The latest version of this DTD
is available from
http://docutils.sourceforge.net/docs/dev/pysource.dtd.
The formal public identifier for this DTD is::
+//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML
-->
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter Entity Overrides
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!ENTITY % additional.section.elements
" | package_section | module_section | class_section
| method_section | function_section
| module_attribute_section | function_attribute_section
| class_attribute_section | instance_attribute_section ">
<!ENTITY % additional.inline.elements
" | package | module | class | method | function
| variable | parameter | type | attribute
| module_attribute | class_attribute | instance_attribute
| exception_class | warning_class ">
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Generic DTD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This DTD extends the Docutils Generic DTD, available from
http://docutils.sourceforge.net/docs/ref/docutils.dtd.
-->
<!ENTITY % docutils PUBLIC
"+//IDN python.org//DTD Docutils Generic//EN//XML"
"docutils.dtd">
%docutils;
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additional Section Elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!ELEMENT package_section
(package, fullname?, import_list?, %structure.model;)>
<!ATTLIST package_section %basic.atts;>
<!ELEMENT module_section
(module, fullname?, import_list?, %structure.model;)>
<!ATTLIST module_section %basic.atts;>
<!ELEMENT class_section
(class, inheritance_list?, fullname?, subclasses?,
%structure.model;)>
<!ATTLIST class_section %basic.atts;>
<!ELEMENT method_section
(method, parameter_list?, fullname?, overrides?,
%structure.model;)>
<!ATTLIST method_section %basic.atts;>
<!ELEMENT function_section
(function, parameter_list?, fullname?, %structure.model;)>
<!ATTLIST function_section %basic.atts;>
<!ELEMENT module_attribute_section
(attribute, initial_value?, fullname?, %structure.model;)>
<!ATTLIST module_attribute_section %basic.atts;>
<!ELEMENT function_attribute_section
(attribute, initial_value?, fullname?, %structure.model;)>
<!ATTLIST function_attribute_section %basic.atts;>
<!ELEMENT class_attribute_section
(attribute, initial_value?, fullname?, overrides?,
%structure.model;)>
<!ATTLIST class_attribute_section %basic.atts;>
<!ELEMENT instance_attribute_section
(attribute, initial_value?, fullname?, overrides?,
%structure.model;)>
<!ATTLIST instance_attribute_section %basic.atts;>
<!--
Section Subelements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!ELEMENT fullname
(package | module | class | method | function | attribute)+>
<!ATTLIST fullname %basic.atts;>
<!ELEMENT import_list (import_item+)>
<!ATTLIST import_list %basic.atts;>
<!--
Support ``import module``, ``import module as alias``, ``from module
import identifier``, and ``from module import identifier as alias``.
-->
<!ELEMENT import_item (fullname, identifier?, alias?)>
<!ATTLIST import_item %basic.atts;>
<!ELEMENT inheritance_list (class+)>
<!ATTLIST inheritance_list %basic.atts;>
<!ELEMENT subclasses (class+)>
<!ATTLIST subclasses %basic.atts;>
<!ELEMENT parameter_list
((parameter_item+, optional_parameters*) | optional_parameters+)>
<!ATTLIST parameter_list %basic.atts;>
<!ELEMENT parameter_item
((parameter | parameter_tuple), parameter_default?)>
<!ATTLIST parameter_item %basic.atts;>
<!ELEMENT optional_parameters (parameter_item+, optional_parameters*)>
<!ATTLIST optional_parameters %basic.atts;>
<!ELEMENT parameter_tuple (parameter | parameter_tuple)+>
<!ATTLIST parameter_tuple %basic.atts;>
<!ELEMENT parameter_default (#PCDATA)>
<!ATTLIST parameter_default %basic.atts;>
<!ELEMENT overrides (fullname+)>
<!ATTLIST overrides %basic.atts;>
<!ELEMENT initial_value (#PCDATA)>
<!ATTLIST initial_value %basic.atts;>
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additional Inline Elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!-- Also used as the `package_section` identifier/title. -->
<!ELEMENT package (#PCDATA)>
<!ATTLIST package
%basic.atts;
%reference.atts;>
<!-- Also used as the `module_section` identifier/title. -->
<!ELEMENT module (#PCDATA)>
<!ATTLIST module
%basic.atts;
%reference.atts;>
<!--
Also used as the `class_section` identifier/title, and in the
`inheritance` element.
-->
<!ELEMENT class (#PCDATA)>
<!ATTLIST class
%basic.atts;
%reference.atts;>
<!-- Also used as the `method_section` identifier/title. -->
<!ELEMENT method (#PCDATA)>
<!ATTLIST method
%basic.atts;
%reference.atts;>
<!-- Also used as the `function_section` identifier/title. -->
<!ELEMENT function (#PCDATA)>
<!ATTLIST function
%basic.atts;
%reference.atts;>
<!--
??? Use this instead of the ``*_attribute`` elements below? Add a
"type" attribute to differentiate?
Also used as the identifier/title for `module_attribute_section`,
`class_attribute_section`, and `instance_attribute_section`.
-->
<!ELEMENT attribute (#PCDATA)>
<!ATTLIST attribute
%basic.atts;
%reference.atts;>
<!--
Also used as the `module_attribute_section` identifier/title. A module
attribute is an exported module-level global variable.
-->
<!ELEMENT module_attribute (#PCDATA)>
<!ATTLIST module_attribute
%basic.atts;
%reference.atts;>
<!-- Also used as the `class_attribute_section` identifier/title. -->
<!ELEMENT class_attribute (#PCDATA)>
<!ATTLIST class_attribute
%basic.atts;
%reference.atts;>
<!--
Also used as the `instance_attribute_section` identifier/title.
-->
<!ELEMENT instance_attribute (#PCDATA)>
<!ATTLIST instance_attribute
%basic.atts;
%reference.atts;>
<!ELEMENT variable (#PCDATA)>
<!ATTLIST variable
%basic.atts;
%reference.atts;>
<!-- Also used in `parameter_list`. -->
<!ELEMENT parameter (#PCDATA)>
<!ATTLIST parameter
%basic.atts;
%reference.atts;
excess_positional %yesorno; #IMPLIED
excess_keyword %yesorno; #IMPLIED>
<!ELEMENT type (#PCDATA)>
<!ATTLIST type
%basic.atts;
%reference.atts;>
<!ELEMENT exception_class (#PCDATA)>
<!ATTLIST exception_class
%basic.atts;
%reference.atts;>
<!ELEMENT warning_class (#PCDATA)>
<!ATTLIST warning_class
%basic.atts;
%reference.atts;>
<!--
Local Variables:
mode: sgml
indent-tabs-mode: nil
fill-column: 70
End:
-->
=== Added File Zope/lib/python/third_party/docutils/docs/dev/pysource.txt ===
======================
Python Source Reader
======================
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:Revision: $Revision: 1.1.2.1 $
:Date: $Date: 2004/10/29 18:24:45 $
:Copyright: This document has been placed in the public domain.
This document explores issues around extracting and processing
docstrings from Python modules.
For definitive element hierarchy details, see the "Python Plaintext
Document Interface DTD" XML document type definition, pysource.dtd_
(which modifies the generic docutils.dtd_). Descriptions below list
'DTD elements' (XML 'generic identifiers' or tag names) corresponding
to syntax constructs.
.. contents::
Model
=====
The Python Source Reader ("PySource") model that's evolving in my mind
goes something like this:
1. Extract the docstring/namespace [#]_ tree from the module(s) and/or
package(s).
.. [#] See `Docstring Extractor`_ below.
2. Run the parser on each docstring in turn, producing a forest of
doctrees (per nodes.py).
3. Join the docstring trees together into a single tree, running
transforms:
- merge hyperlinks
- merge namespaces
- create various sections like "Module Attributes", "Functions",
"Classes", "Class Attributes", etc.; see pysource.dtd_
- convert the above special sections to ordinary doctree nodes
4. Run transforms on the combined doctree. Examples: resolving
cross-references/hyperlinks (including interpreted text on Python
identifiers); footnote auto-numbering; first field list ->
bibliographic elements.
(Or should step 4's transforms come before step 3?)
5. Pass the resulting unified tree to the writer/builder.
I've had trouble reconciling the roles of input parser and output
writer with the idea of modes ("readers" or "directors"). Does the
mode govern the tranformation of the input, the output, or both?
Perhaps the mode should be split into two.
For example, say the source of our input is a Python module. Our
"input mode" should be the "Python Source Reader". It discovers (from
``__docformat__``) that the input parser is "reStructuredText". If we
want HTML, we'll specify the "HTML" output formatter. But there's a
piece missing. What *kind* or *style* of HTML output do we want?
PyDoc-style, LibRefMan style, etc. (many people will want to specify
and control their own style). Is the output style specific to a
particular output format (XML, HTML, etc.)? Is the style specific to
the input mode? Or can/should they be independent?
I envision interaction between the input parser, an "input mode" , and
the output formatter. The same intermediate data format would be used
between each of these, being transformed as it progresses.
Docstring Extractor
===================
We need code that scans a parsed Python module, and returns an ordered
tree containing the names, docstrings (including attribute and
additional docstrings), and additional info (in parentheses below) of
all of the following objects:
- packages
- modules
- module attributes (+ values)
- classes (+ inheritance)
- class attributes (+ values)
- instance attributes (+ values)
- methods (+ formal parameters & defaults)
- functions (+ formal parameters & defaults)
(Extract comments too? For example, comments at the start of a module
would be a good place for bibliographic field lists.)
In order to evaluate interpreted text cross-references, namespaces for
each of the above will also be required.
See python-dev/docstring-develop thread "AST mining", started on
2001-08-14.
Interpreted Text
================
DTD elements: package, module, class, method, function,
module_attribute, class_attribute, instance_attribute, variable,
parameter, type, exception_class, warning_class.
To classify identifiers explicitly, the role is given along with the
identifier in either prefix or suffix form::
Use :method:`Keeper.storedata` to store the object's data in
`Keeper.data`:instance_attribute:.
The role may be one of 'package', 'module', 'class', 'method',
'function', 'module_attribute', 'class_attribute',
'instance_attribute', 'variable', 'parameter', 'type',
'exception_class', 'exception', 'warning_class', or 'warning'. Other
roles may be defined.
.. _pysource.dtd: pysource.dtd
.. _docutils.dtd: ../ref/docutils.dtd
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
End:
=== Added File Zope/lib/python/third_party/docutils/docs/dev/release.txt ===
=============================
Docutils_ Release Procedure
=============================
:Author: David Goodger; open to all Docutils developers
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:45 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: This document has been placed in the public domain.
.. _Docutils: http://docutils.sourceforge.net/
1. Edit the version number in the following files:
* docutils:
- setup.py
- HISTORY.txt
- docutils/__init__.py
* web: index.txt
2. Run the test suite: ``cd test ; alltests.py``.
3. Isolate from outside influence:
(a) Remove the old installation from site-packages (including
roman.py, and optparse.py, textwrap.py for pre-2.3
installations).
(b) Clear/unset the PYTHONPATH environment variable.
4. Create the release tarball:
(a) Create a new empty directory and ``cd`` into it.
(b) Get a clean snapshot of the CVS files::
cvs -z3 -d:pserver:anonymous at cvs.sf.net:/cvsroot/docutils \
export -rHEAD docutils
(c) Use Distutils to create the release tarball::
cd docutils
python setup.py sdist
5. Expand and install the release tarball **in isolation** (as per
step 3 above):
(a) Expand the tarball in a new location, not over any existing
files.
(b) Install from expanded directory::
cd docutils-X.Y
python setup.py install
The "install" command may require root permissions.
6. Run the test suite from the expanded archive directory: ``cd test ;
alltests.py``.
7. Run ``cd tools ; buildhtml.py ..`` to confirm that there are no
unexpected issues with the docs.
8. Upload the release tarball::
$ ftp upload.sourceforge.net
Connected to osdn.dl.sourceforge.net.
...
Name (upload.sourceforge.net:david): anonymous
331 Anonymous login ok, send your complete e-mail address as password.
Password:
...
230 Anonymous access granted, restrictions apply.
ftp> bin
200 Type set to I.
ftp> cd /incoming
250 CWD command successful.
ftp> put filename
9. Log in to the SourceForge web interface.
10. Access the file release system on SourceForge (Admin interface).
Fill in the fields:
:Package ID: docutils
:Release Name: <use release number only, e.g. 0.3>
:Release Date: <today's date>
:Status: Active
:File Name: <select the file just uploaded>
:File Type: Source .gz
:Processor Type: Platform-Independent
:Release Notes: <insert README.txt file here>
:Change Log: <insert summary from announcement>
Also check the "Preserve my pre-formatted text" box.
11. Wait up to 30 minutes for the file to become available on
SourceForge.
12. Download the release tarball and verify its integrity by walking
through an installation, as outlined above (steps 5, 6, & 7).
13. Add a SourceForge News item, with title "Docutils 0.x released"
and containing the release tarball's download URL.
14. Send announcement email to:
* docutils-develop at lists.sourceforge.net
* docutils-users at lists.sourceforge.net
* doc-sig at python.org
* python-list at python.org
* python-announce at python.org
15. Register
(a) with PyPI (Fill in details. ``python setup.py register``?
How to log in?)
(b) with Vaults of Parnassus
(c) with FreshMeat?
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
=== Added File Zope/lib/python/third_party/docutils/docs/dev/semantics.txt ===
=====================
Docstring Semantics
=====================
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:Revision: $Revision: 1.1.2.1 $
:Date: $Date: 2004/10/29 18:24:45 $
:Copyright: This document has been placed in the public domain.
These are notes for a possible future PEP providing the final piece of
the Python docstring puzzle: docstring semantics or documentation
methodology. `PEP 257`_, Docstring Conventions, sketches out some
guidelines, but does not get into methodology details.
I haven't explored documentation methodology more because, in my
opinion, it is a completely separate issue from syntax, and it's even
more controversial than syntax. Nobody wants to be told how to lay
out their documentation, a la JavaDoc_. I think the JavaDoc way is
butt-ugly, but it *is* an established standard for the Java world.
Any standard documentation methodology has to be formal enough to be
useful but remain light enough to be usable. If the methodology is
too strict, too heavy, or too ugly, many/most will not want to use it.
I think a standard methodology could benefit the Python community, but
it would be a hard sell. A PEP would be the place to start. For most
human-readable documentation needs, the free-form text approach is
adequate. We'd only need a formal methodology if we want to extract
the parameters into a data dictionary, index, or summary of some kind.
PythonDoc
=========
(Not to be confused with Daniel Larsson's pythondoc_ project.)
A Python version of the JavaDoc_ semantics (not syntax). A set of
conventions which are understood by the Docutils. What JavaDoc has
done is to establish a syntax that enables a certain documentation
methodology, or standard *semantics*. JavaDoc is not just syntax; it
prescribes a methodology.
- Use field lists or definition lists for "tagged blocks". By this I
mean that field lists can be used similarly to JavaDoc's ``@tag``
syntax. That's actually one of the motivators behind field lists.
For example, we could have::
"""
:Parameters:
- `lines`: a list of one-line strings without newlines.
- `until_blank`: Stop collecting at the first blank line if
true (1).
- `strip_indent`: Strip common leading indent if true (1,
default).
:Return:
- a list of indented lines with mininum indent removed;
- the amount of the indent;
- whether or not the block finished with a blank line or at
the end of `lines`.
"""
This is taken straight out of docutils/statemachine.py, in which I
experimented with a simple documentation methodology. Another
variation I've thought of exploits the Grouch_-compatible
"classifier" element of definition lists. For example::
:Parameters:
`lines` : [string]
List of one-line strings without newlines.
`until_blank` : boolean
Stop collecting at the first blank line if true (1).
`strip_indent` : boolean
Strip common leading indent if true (1, default).
- Field lists could even be used in a one-to-one correspondence with
JavaDoc ``@tags``, although I doubt if I'd recommend it. Several
ports of JavaDoc's ``@tag`` methodology exist in Python, most
recently Ed Loper's "epydoc_".
Other Ideas
===========
- Can we extract comments from parsed modules? Could be handy for
documenting function/method parameters::
def method(self,
source, # path of input file
dest # path of output file
):
This would save having to repeat parameter names in the docstring.
Idea from Mark Hammond's 1998-06-23 Doc-SIG post, "Re: [Doc-SIG]
Documentation tool":
it would be quite hard to add a new param to this method without
realising you should document it
- Frederic Giacometti's `iPhrase Python documentation conventions`_ is
an attachment to his Doc-SIG post of 2001-05-30.
.. _PEP 257: http://www.python.org/peps/pep-0257.html
.. _JavaDoc: http://java.sun.com/j2se/javadoc/
.. _pythondoc: http://starship.python.net/crew/danilo/pythondoc/
.. _Grouch: http://www.mems-exchange.org/software/grouch/
.. _epydoc: http://epydoc.sf.net/
.. _iPhrase Python documentation conventions:
http://mail.python.org/pipermail/doc-sig/2001-May/001840.html
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
=== Added File Zope/lib/python/third_party/docutils/docs/dev/testing.txt ===
===================
Docutils_ Testing
===================
:Author: Felix Wiemann
:Revision: $Revision: 1.1.2.1 $
:Date: $Date: 2004/10/29 18:24:45 $
:Copyright: This document has been placed in the public domain.
.. _Docutils: http://docutils.sourceforge.net/
.. contents::
This document describes how the tests are organized and how to add new
tests or modify existing tests.
Unit Tests
==========
Unit tests test single functions or modules (i.e. whitebox testing).
XXX Some details to be written.
Setting Up For Testing
----------------------
Recent versions of Python's ``unittest.py`` module have an annoying
new "feature", where newlines in test failure output are displayed as
``\n`` (two characters) instead of as actual newlines. This means
that test failure output is unreadable and unuseable. Earlier
versions didn't have this feature, and the output could easily be
copied and pasted into test data modules. Revision `1.7.2.1 of
unittest.py`__ works well. Download it, place it in the ``test/``
directory, and enjoy much better output.
__ http://cvs.sf.net/viewcvs.py/*checkout*/python/python/dist/src/Lib/unittest.py?rev=1.7.2.1
.. _functional::
Functional Tests
================
The directory ``test/functional/`` contains data for functional tests.
Performing functional testing means testing the Docutils system as a
whole (i.e. blackbox testing).
Directory Structure
-------------------
+ ``functional/`` The main data directory.
+ ``input/`` The input files.
- ``some_test.txt``, for example.
+ ``output/`` The actual output.
- ``some_test.html``, for example.
+ ``expected/`` The expected output.
- ``some_test.html``, for example.
+ ``tests/`` The config files for processing the input files.
- ``some_test.py``, for example.
- ``_default.py``, the `default configuration file`_.
The Testing Process
-------------------
When running ``test_functional.py``, all config files in
``functional/some_test.py`` are processed.
An example of what this means:
Provided ``functional/tests/some_test.py`` reads like this::
# Source and destination file names.
test_source = "some_test.txt"
test_destination = "some_test.html"
# Keyword parameters passed to publish_file.
reader_name = "standalone"
parser_name = "rst"
writer_name = "html"
settings_overrides['output-encoding'] = 'utf-8'
The two variables ``test_source`` and ``test_destination`` contain the
input file name (relative to ``functional/input/``) and the output
file name (relative to ``functional/output/`` and
``functional/expected/``). Note that the file names can be chosen
arbitrarily. However, the file names in ``functional/output/`` *must*
match the file names in ``functional/expected/``.
All other variables are passed as keyword arguments to
``docutils.core.publish_file``, so you can set reader, parser,
writer and anything else you want to configure.
Note that ``settings_overrides`` is already initialized as an empty
dictionary *before* the execution of the config file. This is done in
order to allow subsequent assignments to ``settings_overrides`` in the
`default configuration file`_ and in the actual configuration file.
Creating New Tests
------------------
In order to create a new test, put the input test file into
``functional/input/``. Then create a config file in
``functional/tests/`` which sets at least input and output file names,
reader, parser and writer.
Now run ``test_functional.py``. The test will fail, of course,
because you do not have an expected output yet.
However, an output file will be generated in ``functional/output/``.
Check this output file for validity and correctness. Then copy the
file to ``functional/expected/``.
If you run ``test_functional.py`` later and the actual output doesn't
match the expected output anymore, the test will fail.
If this is the case and you made an intentional change, check the
actual output for validity and correctness and copy it to
``functional/expected/``, overwriting the old expected output.
.. _default configuration file:
The Default Configuration File
------------------------------
The file ``functional/tests/_default.py`` contains default settings.
It is executed just before the actual configuration files, which has
the same effect as if the contents of ``_default.py`` were prepended
to every configuration file.
=== Added File Zope/lib/python/third_party/docutils/docs/dev/todo.txt ===
======================
Docutils_ To Do List
======================
:Author: David Goodger (with input from many); open to all Docutils
developers
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:45 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: This document has been placed in the public domain.
.. _Docutils: http://docutils.sourceforge.net/
.. contents::
Priority items are marked with "@" symbols. The more @s, the higher
the priority. Items in question form (containing "?") are ideas which
require more thought and debate; they are potential to-do's.
Many of these items are awaiting champions. If you see something
you'd like to tackle, please do! If there's something you'd like to
see done but are unable to implement it yourself, `please consider
contributing`__ in other ways.
__ http://docutils.sf.net/#please-contribute
Priorities
==========
* Always high priority: `FIX BUGS!`__
__ ../../BUGS.html
* Include substitution files for character entities, produced by the
tools/unicode2rstsubs.py. As static data, these files could go
inside the docutils package somewhere.
* A Python Source Reader component (Python auto-documentation) will be
added. See the document `"Plan for Enthought API Documentation
Tool"`__ for details. If you'd like to help, let me know!
__ enthought-plan.html
* `Nested inline markup`_.
General
=======
* Refactor
- Rename methods & variables according to the `Python coding
conventions <policies.html#python-coding-conventions>`_.
- The name-to-id conversion and hyperlink resolution code needs to be
checked for correctness and refactored. I'm afraid it's a bit of
a spaghetti mess now.
* Language modules: in accented languages it may be useful to have
both accented and unaccented entries in the ``bibliographic_fields``
mapping for versatility.
* Add a "--strict-language" option & setting: no English fallback for
language-dependent features.
* Add internationalization to _`footer boilerplate text` (resulting
from "--generator", "--source-link", and "--date" etc.), allowing
translations.
* Need a Unicode to HTML entities codec for HTML writer? No, the
"xmlcharrefreplace" output error handler is sufficient.
Make it the default for HTML & XML writers?
* Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP.
* Ask Python-dev for opinions (GvR for a pronouncement) on special
variables (__author__, __version__, etc.): convenience vs. namespace
pollution. Ask opinions on whether or not Docutils should recognize
& use them.
* In ``docutils.readers.get_reader_class`` (& ``parsers`` &
``writers`` too), should we be importing "standalone" or
"docutils.readers.standalone"? (This would avoid importing
top-level modules if the module name is not in docutils/readers.
Potential nastiness.)
* @@@ Perhaps store a _`name-to-id mapping file`? This could be
stored permanently, read by subsequent processing runs, and updated
with new entries. ("Persistent ID mapping"?)
* Perhaps the ``Component.supports`` method should deal with
individual features ("meta" etc.) instead of formats ("html" etc.)?
* Add _`object numbering and object references` (tables & figures).
These would be the equivalent of DocBook's "formal" elements.
We may need _`persistent sequences`, such as chapter numbers. See
`OpenOffice.org XML`_ "fields". Should the sequences be automatic
or manual (user-specifyable)?
We need to name the objects:
- "name" option for the "figure" directive? ::
.. figure:: image.png
:name: image's name
Same for the "table" directive::
.. table:: optional title here
:name: table's name
===== =====
x not x
===== =====
True False
False True
===== =====
This would also allow other options to be set, like border
styles. The same technique could be used for other objects.
A preliminary "table" directive has been implemented, supporting
table titles. Perhaps the name should derive from the title.
- The object could also be done this way::
.. _figure name:
.. figure:: image.png
This may be a more general solution, equally applicable to tables.
However, explicit naming using an option seems simpler to users.
We'll also need syntax for object references. See `OpenOffice.org
XML`_ "reference fields":
- Parameterized substitutions? For example::
See |figure (figure name)| on |page (figure name)|.
.. |figure (name)| figure-ref:: (name)
.. |page (name)| page-ref:: (name)
The result would be::
See figure 3.11 on page 157.
But this would require substitution directives to be processed at
reference-time, not at definition-time as they are now. Or,
perhaps the directives could just leave ``pending`` elements
behind, and the transforms do the work? How to pass the data
through? Too complicated.
- An interpreted text approach is simpler and better::
See :figure:`figure name` on :page:`figure name`.
The "figure" and "page" roles could generate appropriate
boilerplate text. The position of the role (prefix or suffix)
could also be utilized.
See `Interpreted Text`_ below.
.. _OpenOffice.org XML: http://xml.openoffice.org/
* Think about _`large documents` made up of multiple subdocument
files. Issues: continuity (`persistent sequences`_ above),
cross-references (`name-to-id mapping file`_ above and `targets in
other documents`_ below).
When writing a book, the author probably wants to split it up into
files, perhaps one per chapter (but perhaps even more detailed).
However, we'd like to be able to have references from one chapter to
another, and have continuous numbering (pages and chapters, as
applicable). Of course, none of this is implemented yet. There has
been some thought put into some aspects; see `the "include"
directive`__ and the `Reference Merging`_ transform below.
When I was working with SGML in Japan, we had a system where there
was a top-level coordinating file, book.sgml, which contained the
top-level structure of a book: the <book> element, containing the
book <title> and empty component elements (<preface>, <chapter>,
<appendix>, etc.), each with filename attributes pointing to the
actual source for the component. Something like this::
<book id="bk01">
<title>Title of the Book</title>
<preface inrefid="pr01"></preface>
<chapter inrefid="ch01"></chapter>
<chapter inrefid="ch02"></chapter>
<chapter inrefid="ch03"></chapter>
<appendix inrefid="ap01"></appendix>
</book>
(The "inrefid" attribute stood for "insertion reference ID".)
The processing system would process each component separately, but
it would recognize and use the book file to coordinate chapter and
page numbering, and keep a persistent ID to (title, page number)
mapping database for cross-references. Docutils could use a similar
system for large-scale, multipart documents.
__ ../ref/rst/directives.html#including-an-external-document-fragment
Aahz's idea:
First the ToC::
.. ToC-list::
Introduction.txt
Objects.txt
Data.txt
Control.txt
Then a sample use::
.. include:: ToC.txt
As I said earlier in chapter :chapter:`Objects.txt`, the
reference count gets increased every time a binding is made.
Which produces::
As I said earlier in chapter 2, the
reference count gets increased every time a binding is made.
The ToC in this form doesn't even need to be references to actual
reST documents; I'm simply doing it that way for a minimum of
future-proofing, in case I do want to add the ability to pick up
references within external chapters.
Perhaps, instead of ToC (which would overload the "contents"
directive concept already in use), we could use "manifest". A
"manifest" directive might associate local reference names with
files::
.. manifest::
intro: Introduction.txt
objects: Objects.txt
data: Data.txt
control: Control.txt
Then the sample becomes::
.. include:: manifest.txt
As I said earlier in chapter :chapter:`objects`, the
reference count gets increased every time a binding is made.
* Add testing for Docutils' front end tools?
* Changes to sandbox/davidg/infrastructure/docutils-update?
- Modify the script to only update the snapshots if files have
actually changed in CVS (saving some SourceForge server cycles).
- Make passing the test suite a prerequisite to snapshot update,
but only if the process is completely automatic.
- Rewrite in Python?
* Publisher: "Ordinary setup" shouldn't requre specific ordering; at
the very least, there ought to be error checking higher up in the
call chain. [Aahz]
``Publisher.get_settings`` requires that all components be set up
before it's called. Perhaps the I/O *objects* shouldn't be set, but
I/O *classes*. Then options are set up (``.set_options``), and
``Publisher.set_io`` (or equivalent code) is called with source &
destination paths, creating the I/O objects.
Perhaps I/O objects shouldn't be instantiated until required. For
split output, the Writer may be called multiple times, once for each
doctree, and each doctree should have a separate Output object (with
a different path). Is the "Builder" pattern applicable here?
* Perhaps I/O objects should become full-fledged components (i.e.
subclasses of ``docutils.Component``, as are Readers, Parsers, and
Writers now), and thus have associated option/setting specs and
transforms.
* Multiple file I/O suggestion from Michael Hudson: use a file-like
object or something you can iterate over to get file-like objects.
* Add an "--input-language" option & setting? Specify a different
language module for input (bibliographic fields, directives) than
for output. The "--language" option would set both input & output
languages.
* Auto-generate reference tables for language-dependent features?
Could be generated from the source modules. A special command-line
option could be added to Docutils front ends to do this. (Idea from
Engelbert Gruber.)
* Change the "class" attribute of elements (set with
Element.set_class) to a list?
* Enable feedback of some kind from internal decisions, such as
reporting the successful input encoding. Modify runtime settings?
System message? Simple stderr output?
* Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.
* The "docutils.conf" included with Docutils should become complete,
with examples of every setting (many/most commented out). It's
currently sparse, requiring doc lookups.
* Merge docs/user/latex.txt info into tools.txt and config.txt.
* Add an "--include file" command-line option (config setting too?),
equivalent to ".. include:: file" as the first line of the doc text?
Especially useful for character entity sets, text transform specs,
boilerplate, etc.
* Parameterize the Reporter object or class? See the `2004-02-18
"rest checking and source path"`_ thread.
.. _2004-02-18 "rest checking and source path":
http://thread.gmane.org/gmane.text.docutils.user/1112
* Add a "disable_transforms" setting? And a dummy Writer subclass
that does nothing when its .write() method is called? Would allow
for easy syntax checking. See the `2004-02-18 "rest checking and
source path"`_ thread.
* Add a generic meta-stylesheet mechanism? An external file could
associate style names ("class" attributes) with specific elements.
Could be generalized to arbitrary output attributes; useful for HTML
& XMLs. Aahz implemented something like this in
sandbox/aahz/Effective/EffMap.py.
* William Dode suggested that table cells be assigned "class"
attributes by columns, so that stylesheets can affect text
alignment. Unfortunately, there doesn't seem to be a way (in HTML
at least) to leverage the "colspec" elements (HTML "col" tags) by
adding classes to them. The resulting HTML is very verbose::
<td class="col1">111</td>
<td class="col2">222</td>
...
At the very least, it should be an option. People who don't use it
shouldn't be penalized by increases in their HTML file sizes.
Table rows could also be assigned classes (like odd/even). That
would be easier to implement.
How should it be implemented?
* There could be writer options (column classes & row classes) with
standard values.
* The table directive could grow some options. Something like
":cell-classes: col1 col2 col3" (either must match the number of
columns, or repeat to fill?) and ":row-classes: odd even" (repeat
to fill; body rows only, or header rows too?).
Probably per-table directive options are best. The "class" values
could be used by any writer, and applying such classes to all tables
in a document with writer options is too broad.
* Make the csv-table directive work with Python 2.1/2.2. (See the
discussion_ on the mailing list.)
.. _discussion: http://thread.gmane.org/gmane.text.docutils.user/1319
* The docutils.nodes.Element APIs could use some simplification. For
example, ``node[x]`` is ambiguous (different results if x is a
string or an integer). Replace with ``node[int]`` and
``node.attributes[string]``?
* Add file-specific settings support to config files, like::
[file index.txt]
compact-lists: no
Is this even possible? Should the criterion be the name of the
input file or the output file?
* The "validator" support added to OptionParser is very similar to
"traits_" in SciPy_. Perhaps something could be done with them?
(Had I known about traits when I was implementing docutils.frontend,
I may have used them instead of rolling my own.)
.. _traits: http://old.scipy.org/site_content/traits
.. _SciPy: http://www.scipy.org/
Documentation
=============
User Docs
---------
What else is needed?
Developer Docs
--------------
* Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_.
* @@@ Improve the internal module documentation (docstrings in the
code). Specific deficiencies listed below.
- docutils.parsers.rst.states.State.build_table: data structure
required (including StringList).
- docutils.parsers.rst.states: more complete documentation of parser
internals.
* docs/ref/doctree.txt: DTD element structural relationships,
semantics, and attributes. In progress; element descriptions to be
completed.
* Document the ``pending`` elements, how they're generated and what
they do.
* Document the transforms (perhaps in docstrings?): how they're used,
what they do, dependencies & order considerations.
* Document the HTML classes used by html4css1.py.
* Write an overview of the Docutils architecture, as an introduction
for developers. What connects to what, why, and how. Either update
PEP 258 (see PEPs_ below) or as a separate doc.
* Give information about unit tests. Maybe as a howto?
* Document the docutils.nodes APIs.
* Complete the docs/api/publisher.txt docs.
How-Tos
-------
* Creating Docutils Writers
* Creating Docutils Readers
* Creating Docutils Transforms
* Creating Docutils Parsers
* Using Docutils as a Library
PEPs
----
* Complete PEP 258 Docutils Design Specification.
- Fill in the blanks in API details.
- Specify the nodes.py internal data structure implementation?
[Tibs:] Eventually we need to have direct documentation in
there on how it all hangs together - the DTD is not enough
(indeed, is it still meant to be correct? [Yes, it is.
--DG]).
* Rework PEP 257, separating style from spec from tools, wrt Docutils?
See Doc-SIG from 2001-06-19/20.
Python Source Reader
====================
General:
* Analyze Tony Ibbs' PySource code.
* Analyze Doug Hellmann's HappyDoc project.
* Investigate how POD handles literate programming.
* Take the best ideas and integrate them into Docutils.
Miscellaneous ideas:
* If we can detect that a comment block begins with ``##``, a la
JavaDoc, it might be useful to indicate interspersed section headers
& explanatory text in a module. For example::
"""Module docstring."""
##
# Constants
# =========
a = 1
b = 2
##
# Exception Classes
# =================
class MyException(Exception): pass
# etc.
* Should standalone strings also become (module/class) docstrings?
Under what conditions? We want to prevent arbitrary strings from
becomming docstrings of prior attribute assignments etc. Assume
that there must be no blank lines between attributes and attribute
docstrings? (Use lineno of NEWLINE token.)
Triple-quotes are sometimes used for multi-line comments (such as
commenting out blocks of code). How to reconcile?
* HappyDoc's idea of using comment blocks when there's no docstring
may be useful to get around the conflict between `additional
docstrings`_ and ``from __future__ import`` for module docstrings.
A module could begin like this::
#!/usr/bin/env python
# :Author: Me
# :Copyright: whatever
"""This is the public module docstring (``__doc__``)."""
# More docs, in comments.
# All comments at the beginning of a module could be
# accumulated as docstrings.
# We can't have another docstring here, because of the
# ``__future__`` statement.
from __future__ import division
Using the JavaDoc convention of a doc-comment block beginning with
``##`` is useful though. It allows doc-comments and implementation
comments.
.. _additional docstrings:
../peps/pep-0258.html#additional-docstrings
* HappyDoc uses an initial comment block to set "parser configuration
values". Do the same thing for Docutils, to set runtime settings on
a per-module basis? I.e.::
# Docutils:setting=value
Could be used to turn on/off function parameter comment recognition
& other marginal features. Could be used as a general mechanism to
augment config files and command-line options (but which takes
precedence?).
* Multi-file output should be divisible at arbitrary level.
* Support all forms of ``import`` statements:
- ``import module``: listed as "module"
- ``import module as alias``: "alias (module)"
- ``from module import identifier``: "identifier (from module)"
- ``from module import identifier as alias``: "alias (identifier
from module)"
- ``from module import *``: "all identifiers (``*``) from module"
* Have links to colorized Python source files from API docs? And
vice-versa: backlinks from the colorized source files to the API
docs!
* In summaries, use the first *sentence* of a docstring if the first
line is not followed by a blank line.
reStructuredText Parser
=======================
Also see the `... Or Not To Do?`__ list.
__ rst/alternatives.html#or-not-to-do
* The parser doesn't know anything about double-width characters such
as Chinese hanza & Japanese kanji/kana. Also, it's dependent on
whitespace and punctuation as markup delimiters, which may not be
applicable in these languages.
Python 2.4 introduces the iswide() and width() string methods, so
this problem will be resolved later, when Python 2.4 is being used
more widely.
* Clean up the code; refactor as required.
* Add motivation sections for constructs in spec.
* Document title should grow an implicit target.
* Allow very long titles (on two or more lines)?
* And for the sake of completeness, should definition list terms be
allowed to be very long (two or more lines) also?
* Support generic hyperlink references to _`targets in other
documents`? Not in an HTML-centric way, though (it's trivial to say
``http://www.example.com/doc#name``, and useless in non-HTML
contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
2001-08-10.
* .. _adaptable file extensions:
In target URLs, it would be useful to not explicitly specify the
file extension. If we're generating HTML, then ".html" is
appropriate; if PDF, then ".pdf"; etc. How about using ".*" to
indicate "choose the most appropriate filename extension? For
example::
.. _Another Document: another.*
Should the choice be from among existing files only? Documents
only, or objects (images, etc.) also? (How to differentiate?
Element context [within "image"]?)
This may not be just a parser issue though; it may need framework
support.
Mailing list thread: `Images in both HTML and LaTeX`__
__ http://thread.gmane.org/gmane.text.docutils.user/1239
* Implement the header row separator modification to table.el. (Wrote
to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
support for "=====" header rows. On 2001-08-17 he replied, saying
he'd put it on his to-do list, but "don't hold your breath".)
* Tony says inline markup rule 7 could do with a *little* more
exposition in the spec, to make clear what is going on for people
with head colds.
* @@ Fix the parser's indentation handling to conform with the
stricter definition in the spec. (Explicit markup blocks should be
strict or forgiving?)
* @@ Tighten up the spec for indentation of "constructs using complex
markers": field lists and option lists? Bodies may begin on the
same line as the marker or on a subsequent line (with blank lines
optional). Require that for bodies beginning on the same line as
the marker, all lines be in strict alignment. Currently, this is
acceptable::
:Field-name-of-medium-length: Field body beginning on the same
line as the field name.
This proposal would make the above example illegal, instead
requiring strict alignment. A field body may either begin on the
same line::
:Field-name-of-medium-length: Field body beginning on the same
line as the field name.
Or it may begin on a subsequent line::
:Field-name-of-medium-length:
Field body beginning on a line subsequent to that of the
field name.
This would be especially relevant in degenerate cases like this::
:Number-of-African-swallows-requried-to-carry-a-coconut:
It would be very difficult to align the field body with
the left edge of the first line if it began on the same
line as the field name.
* Allow for variant styles by interpreting _`indented lists` as if
they weren't indented? For example, currently the list below will
be parsed as a list within a block quote::
paragraph
* list item 1
* list item 2
But a lot of people seem to write that way, and HTML browsers make
it look as if that's the way it should be. The parser could check
the contents of block quotes, and if they contain only a single
list, remove the block quote wrapper. There would be two problems:
1. What if we actually *do* want a list inside a block quote?
2. What if such a list comes immediately after an indented
construct, such as a literal block?
Both could be solved using empty comments (problem 2 already exists
for a block quote after a literal block). But that's a hack.
Perhaps a runtime setting, allowing or disabling this convenience,
would be appropriate. But that raises issues too:
User A, who writes lists indented (and their config file is set
up to allow it), sends a file to user B, who doesn't (and their
config file disables indented lists). The result of processing
by the two users will be different.
It may seem minor, but it adds ambiguity to the parser, which is
bad.
See the `Doc-SIG discussion starting 2001-04-18`__ with Ed Loper's
"Structuring: a summary; and an attempt at EBNF", item 4 (and
follow-ups, here__ and here__). Also `docutils-users,
2003-02-17`__ and `beginning 2003-08-04`__.
__ http://mail.python.org/pipermail/doc-sig/2001-April/001776.html
__ http://mail.python.org/pipermail/doc-sig/2001-April/001789.html
__ http://mail.python.org/pipermail/doc-sig/2001-April/001793.html
__ http://sourceforge.net/mailarchive/message.php?msg_id=3838913
__ http://sf.net/mailarchive/forum.php?thread_id=2957175&forum_id=11444
* Make the parser modular. Allow syntax constructs to be added or
disabled at run-time. Or is subclassing enough?
* Continue to report (info, level 1) enumerated lists whose start
value is not ordinal-1?
* Generalize the "doctest block" construct (which is overly
Python-centric) to other interactive sessions? "Doctest block"
could be renamed to "I/O block" or "interactive block", and each of
these could also be recognized as such by the parser:
- Shell sessions::
$ cat example1.txt
A block beginning with a "$ " prompt is interpreted as a shell
session interactive block. As with Doctest blocks, the
interactive block ends with the first blank line, and wouldn't
have to be indented.
- Root shell sessions::
# cat example2.txt
A block beginning with a "# " prompt is interpreted as a root
shell session (the user is or has to be logged in as root)
interactive block. Again, the block ends with a blank line.
Other standard (and unambiguous) interactive session prompts could
easily be added (such as "> " for WinDOS).
Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread
"docutils feedback").
* Should the "doctest" element go away, and the construct simply be a
front-end to generic literal blocks?
* Add support for pragma (syntax-altering) directives.
Some pragma directives could be local-scope unless explicitly
specified as global/pragma using ":global:" options.
* Remove leading numbers from section titles for implicit link names?
A section titled "3. Conclusion" could then be referred to by
"``Conclusion_``" (i.e., without the "3.").
* `Syntax for line blocks`__ (currently a directive)?
__ rst/alternatives.html#syntax-for-line-blocks
* Implement auto-enumerated lists? See `Auto-Enumerated Lists`__.
__ rst/alternatives.html#auto-enumerated-lists
* Support whitespace in angle-bracketed standalone URLs according to
Appendix E ("Recommendations for Delimiting URI in Context") of `RFC
2396`_.
.. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt
* Use the vertical spacing of the source text to determine the
corresponding vertical spacing of the output?
* [From Mark Nodine] For cells in simple tables that comprise a
single line, the justification can be inferred according to the
following rules:
1. If the text begins at the leftmost column of the cell,
then left justification, ELSE
2. If the text begins at the rightmost column of the cell,
then right justification, ELSE
3. Center justification.
The onus is on the author to make the text unambiguous by adding
blank columns as necessary. There should be a parser setting to
turn off justification-recognition (normally on would be fine).
Decimal justification?
* Make enumerated list parsing more strict, so that this would parse
as a paragraph with an info message::
1. line one
3. line two
* Generalize the "target-notes" directive into a command-line option
somehow? See docutils-develop 2003-02-13.
* Include the _`character entity substitution definition files`
`temporarily stored here <http://docutils.sf.net/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?
A "break" or "page-break" directive would be easy to add. A new
doctree element would be required though (perhaps "break"). The
final behavior would be up to the Writer. The directive argument
could be one of page/column/recto/verso for added flexibility.
Currently ^L (Python's "\f") characters are treated as whitespace.
They're converted to single spaces, actually, as are vertical tabs
(^K, Python's "\v"). It would be possible to recognize form feeds
as markup, but it requires some thought and discussion first. Are
there any downsides? Many editing environments do not allow the
insertion of control characters. Will it cause any harm? It would
be useful as a shorthand for the directive.
It's common practice to use ^L before Emacs "Local Variables"
lists::
^L
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
These are already present in many PEPs and Docutils project
documents. From the Emacs manual (info):
A "local variables list" goes near the end of the file, in the
last page. (It is often best to put it on a page by itself.)
It would be unfortunate if this construct caused a final blank page
to be generated (for those Writers that recognize the page breaks).
We'll have to add a transform that looks for a "break" plus zero or
more comments at the end of a document, and removes them.
* Could the "break" concept above be extended to inline forms?
E.g. "^L" in the middle of a sentence could cause a line break.
Only recognize it at the end of a line (i.e., "\f\n")?
Or is formfeed inappropriate? Perhaps vertical tab ("\v"), but even
that's a stretch. Can't use carriage returns, since they're
commonly used for line endings.
* Allow a "::"-only paragraph (first line, actually) to introduce a
literal block without a blank line? (Idea from Paul Moore.) ::
::
This is a literal block
Is indentation enough to make the separation between a paragraph
which contains just a ``::`` and the literal text unambiguous?
There's one problem with this concession. What if one wants a
definition list item which defines the term "::"? We'd have to
escape it. Currenty, "\::" doesn't work (although it should;
**bug**), and ":\:" is misinterpreted as a field name (name "\";
also a **bug**). Assuming these bugs are squashed, I suppose it's a
useful special case. It would only be reasonable to apply it to
"::"-only paragraphs though. I think the blank line is visually
necessary if there's text before the "::"::
The text in this paragraph needs separation
from the literal block following::
This doesn't look right.
Another idea. Would it be worthwhile to allow literal blocks to
begin without a newline after the "::"? Example::
:: while True:
print 'hello world'
Perhaps. Perhaps not.
* Add new syntax for _`nested inline markup`? Or extend the parser to
parse nested inline markup somehow? See the `collected notes
<rst/alternatives.html#nested-inline-markup>`__.
* Drop the backticks from embedded URIs with omitted reference text?
Should the angle brackets be kept in the output or not? ::
<file_name>_
Probably not worth the trouble.
* Add ``^superscript^`` inline markup? The only common non-markup
uses of "^" I can think of are as short hand for "superscript"
itself and for describing control characters ("^C to cancel"). The
former supports the proposed syntax, and it could be argued that the
latter ought to be literal text anyhow (e.g. "``^C`` to cancel").
* Add _`math markup`. We should try for a general solution, that's
applicable to any output format. Using a standard, such as MathML_,
would be best. TeX (or itex_) would be acceptable as a *front-end*
to MathML. See `the culmination of a relevant discussion
<http://article.gmane.org/gmane.text.docutils.user/118>`__.
Both a directive and an interpreted text role will be necessary (for
each markup). Directive example::
.. itex::
\alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda)
The same thing inline::
The equation in question is :itex:`\alpha_t(i) = P(O_1, O_2,
\dots O_t, q_t = S_i \lambda)`.
.. _MathML: http://www.w3.org/TR/MathML2/
.. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html
* How about a syntax for alternative hyperlink behavior, such as "open
in a new window" (as in HTML's ``<a target="_blank">``)? Double
angle brackets might work for inline targets::
The `reference docs <<url>>`__ may be handy.
But what about explicit targets?
The MoinMoin wiki uses a caret ("^") at the beginning of the URL
("^" is not a legal URI character). That could work for both inline
and explicit targets::
The `reference docs <^url>`__ may be handy.
.. _name: ^url
* Allow _`transitions` between sections? A transition immediately
preceding a section title could be interpreted as a sibling of that
section. The context would obviate the need for a special
directive. The document model would have to accommodate the
change::
<!ENTITY % structure.model
" ( ( (%body.elements; | topic | sidebar)+,
(transition, (%body.elements; | topic | sidebar)+ )*,
(transition?, (%section.elements;))* )
| (transition?, (%section.elements;))+ ) ">
* Add an option to allow arbitrary URI schemes (not just those in
urischemes.py)? This would make text like "signal:noise" into a
URI.
* Add an option to add URI schemes at runtime.
* _`Segmented lists`::
: segment : segment : segment
: segment : segment : very long
segment
: segment : segment : segment
The initial colon (":") can be thought of as a type of bullet
We could even have segment titles::
:: title : title : title
: segment : segment : segment
: segment : segment : segment
This would correspond well to DocBook's SegmentedList. Output could
be tabular or "name: value" pairs, as described in DocBook's docs.
* Allow backslash-escaped colons in field names::
:Case Study\: Event Handling: This chapter will be dropped.
* _`footnote spaces`:
When using superscripted footnote references, the space looks ugly.
We could automatically activate --trim-footnote-reference-space when
--footnote-references=superscript (or --use-latex-footnotes for the
LaTeX writer) is supplied.
There should be also an option to deactivate the space-trimming,
e.g. --leave-footnote-reference-space. The implementation logic is
a bit tricky: --leave-footnote-reference-space can't just be
"settings.trim_footnote_reference_space = False", because of the
automatic activation, unless the order of options is significant.
If the order is significant, the automatic activation has to take
place in the option-handling code. But config files are handled
after the fact, so order can't be relied upon there. So they have
to be two independent settings.
* Enable _`tables inside XML comments`, where "--" ends comments. I
see three implementation possibilities:
1. Make the table syntax characters into "table" directive options.
This is the most flexible but most difficult, and we probably
don't need that much flexibility.
2. Substitute "~" for "-" with a specialized directive option
(e.g. ":tildes:").
3. Make the standard table syntax recognize "~" as well as "-", even
without a directive option. Individual tables would have to be
internally consistent.
Directive options are preferable to configuration settings, because
tables are document-specific. A pragma directive would be another
approach, to set the syntax once for a whole document.
Directives
----------
Directives below are often referred to as "module.directive", the
directive function. The "module." is not part of the directive name
when used in a document.
* Allow directives to be added at run-time?
* Use the language module for directive option names?
* Add "substitution_only" and "substitution_ok" function attributes,
and automate context checking?
* Change directive functions to directive classes? Superclass'
``__init__()`` could handle all the bookkeeping.
* Implement options on existing directives:
- Add a "name" option to directives, to set an author-supplied
identifier?
- All directives that produce titled elements should grow implicit
reference names based on the titles.
- _`images.image`: "border"?
_`Units of measure`? (See `docutils-users, 2003-03-02
<http://article.gmane.org/gmane.text.docutils.user/154>`__, and
`docutils-develop, 2004-04-29
<http://article.gmane.org/gmane.text.docutils.devel/1439>`_.)
- _`images.figure`: "title" and "number", to indicate a formal
figure?
- _`parts.sectnum`: "local"?, "start", "refnum"
A "local" option could enable numbering for sections from a
certain point down, and sections in the rest of the document are
not numbered. For example, a reference section of a manual might
be numbered, but not the rest. OTOH, an all-or-nothing approach
would probably be enough.
The "start" option will specify the sequence set to use at the
same time as the starting value, for the first part of the section
number (i.e., section, not subsection). For example::
.. sectnum: :start: 1
.. sectnum: :start: A
.. sectnum: :start: 5
.. sectnum: :start: I
The first one is the default: start at 1, numbered. The second
one specifies letters, and start at "A". The third specifies
numbers, start at 5. The last example could signal Roman
numerals, although I don't know if they'd be applicable here.
Enumerated lists already do all this; perhaps that code could be
reused.
Here comes the tricky part. The "sectnum" directive should be
usable multiple times in a single document. For example, in a
long document with "chapter" and "appendix" sections, there could
be a second "sectnum" before the first appendix, changing the
sequence used (from 1,2,3... to A,B,C...). This is where the
"local" concept comes in. This part of the implementation can be
left for later.
A "refnum" option (better name?) would insert reference names
(targets) consisting of the reference number. Then a URL could be
of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow
internal references by number? Allow name-based *and*
number-based ids at the same time, or only one or the other (which
would the table of contents use)? Usage issue: altering the
section structure of a document could render hyperlinks invalid.
- _`parts.contents`: Add a "suppress" or "prune" option? It would
suppress contents display for sections in a branch from that point
down. Or a new directive, like "prune-contents"?
Add an option to include topics in the TOC? Another for sidebars?
See docutils-develop 2003-01-29.
- _`misc.include`:
- @@@ Allow whitespace in paths (just not at line boundaries).
- "encoding" option? Take default from runtime settings. Use
Input component to read it in?
- Option to select a range of lines?
- 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?
How about an environment variable, say RSTINCLUDEPATH or
RSTPATH? This could be combined with a setting/option to allow
user-defined include directories.
For a specific application, see the discussion of `character
entity substitution definition files`_ above.
Instead of C-include "<syntax>", perhaps a new "include-sys"
directive?
- _`misc.raw`: "encoding" option?
- _`misc.class`: @@@ Allow multiple classes (whitespace-separated)
to be declared.
* 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
directive_function_name, or it could differ.
- _`html.imagemap` (Useful outside of HTML? If not, replace with
image only in non-HTML writers?)
- _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.
- _`parts.citations`: See `Footnote & Citation Gathering`_.
- _`misc.exec`: Execute Python code & insert the results. Perhaps
dangerous? Call it "python" to allow for other languages?
- _`misc.system`?: Execute an ``os.system()`` call, and insert the
results (possibly as a literal block). Definitely dangerous! How
to make it safe? Perhaps such processing should be left outside
of the document, in the user's production system (a makefile or a
script or whatever). Or, the directive could be disabled by
default and only enabled with an explicit command-line option or
config file setting. Even then, an interactive prompt may be
useful, such as:
The file.txt document you are processing contains a "system"
directive requesting that the ``sudo rm -rf /`` command be
executed. Allow it to execute? (y/N)
- _`misc.eval`: Evaluate an expression & insert the text. At parse
time or at substitution time? Dangerous? Perhaps limit to canned
macros; see text.date_ below.
- _`misc.encoding`: Specify the character encoding of the input
data. But there are problems:
- When it sees the directive, the parser will already have read
the input data, and encoding determination will already have
been done.
- If a file with an "encoding" directive is edited and saved with
a different encoding, the directive may cause data corruption.
- _`misc.language`: Specify the language of a document. There is a
problem similar to the first problem listed for misc.encoding_,
although to a lesser degree.
- _`misc.settings`: Set any Docutils runtime setting from within a
document?
- _`misc.charents`: Equivalent to::
.. include:: {includepath}/charents.txt
- .. _conditional directives:
Docutils already has the ability to say "use this content for
Writer X" (via the "raw" directive), but it doesn't have the
ability to say "use this content for any Writer other than X". It
wouldn't be difficult to add this ability though.
My first idea would be to add a set of conditional directives.
Let's call them "writer-is" and "writer-is-not" for discussion
purposes (don't worry about implemention details). We might
have::
.. writer-is:: text-only
::
+----------+
| SNMP |
+----------+
| UDP |
+----------+
| IP |
+----------+
| Ethernet |
+----------+
.. writer-is:: pdf
.. figure:: protocol_stack.eps
.. writer-is-not:: text-only pdf
.. figure:: protocol_stack.png
This could be an interface to the Filter transform
(docutils.transforms.components.Filter).
The ideas in `adaptable file extensions`_ above may also be
applicable here.
Here's an example of a directive that could produce multiple
outputs (*both* raw troff pass-through *and* a GIF, for example)
and allow the Writer to select. ::
.. eqn::
.EQ
delim %%
.EN
%sum from i=o to inf c sup i~=~lim from {m -> inf}
sum from i=0 to m sup i%
.EQ
delim off
.EN
- _`body.qa` (directive a.k.a. "faq", "questions"): Questions &
Answers. Implement as a generic two-column marked list? As a
standalone (non-directive) construct? (Is the markup ambiguous?)
Add support to parts.contents.
New elements would be required. Perhaps::
<!ELEMENT question_list (question_list_item+)>
<!ATTLIST question_list
numbering (none | local | global)
#IMPLIED
start NUMBER #IMPLIED>
<!ELEMENT question_list_item (question, answer*)>
<!ELEMENT question %text.model;>
<!ELEMENT answer (%body.elements;)+>
Originally I thought of implementing a Q&A list with special
syntax::
Q: What am I?
A: You are a question-and-answer
list.
Q: What are you?
A: I am the omniscient "we".
Where each "Q" and "A" could also be numbered (e.g., "Q1").
However, a simple enumerated or bulleted list will do just fine
for syntax. A directive could treat the list specially; e.g. the
first paragraph could be treated as a question, the remainder as
the answer (multiple answers could be represented by nested
lists). Without special syntax, this directive becomes low
priority.
- _`body.example`: Examples; suggested by Simon Hefti. Semantics as
per Docbook's "example"; admonition-style, numbered, reference,
with a caption/title.
- _`body.index`: Index targets.
Were I writing a book with an index, I guess I'd need two
different kinds of index targets: inline/implicit and
out-of-line/explicit. For example::
In this `paragraph`:index:, several words are being
`marked`:index: inline as implicit `index`:index:
entries.
.. index:: markup
.. index:: syntax
The explicit index directives above would refer to
this paragraph. It might also make sense to allow multiple
entries in an ``index`` directive:
.. index::
markup
syntax
The words "paragraph", "marked", and "index" would become index
entries pointing at the words in the first paragraph. The index
entry words appear verbatim in the text. (Don't worry about the
ugly ":index:" part; if indexing is the only/main application of
interpreted text in your documents, it can be implicit and
omitted.) The two directives provide manual indexing, where the
index entry words ("markup" and "syntax") do not appear in the
main text. We could combine the two directives into one::
.. index:: markup; syntax
Semicolons instead of commas because commas could *be* part of the
index target, like::
.. index:: van Rossum, Guido
Another reason for index directives is because other inline markup
wouldn't be possible within inline index targets.
Sometimes index entries have multiple levels. Given::
.. index:: statement syntax: expression statements
In a hypothetical index, combined with other entries, it might
look like this::
statement syntax
expression statements ..... 56
assignment ................ 57
simple statements ......... 58
compound statements ....... 60
Inline multi-level index targets could be done too. Perhaps
something like::
When dealing with `expression statements <statement syntax:>`,
we must remember ...
The opposite sense could also be possible::
When dealing with `index entries <:multi-level>`, there are
many permutations to consider.
Also "see / see also" index entries.
Given::
Here's a paragraph.
.. index:: paragraph
(The "index" directive above actually targets the *preceding*
object.) The directive should produce something like this XML::
<paragraph>
<index_entry text="paragraph"/>
Here's a paragraph.
</paragraph>
This kind of content model would also allow true inline
index-entries::
Here's a `paragraph`:index:.
If the "index" role were the default for the application, it could be
dropped::
Here's a `paragraph`.
Both of these would result in this XML::
<paragraph>
Here's a <index_entry>paragraph</index_entry>.
</paragraph>
- _`body.literal`: Literal block, possibly "formal" (see `object
numbering and object references`_ above). Possible options:
- "highlight" a range of lines
- "number" or "line-numbers"
- "styled" could indicate that the directive should check for
style comments at the end of lines to indicate styling or
markup.
Specific derivatives (i.e., a "python-interactive" directive)
could interpret style based on cues, like the ">>> " prompt and
"input()"/"raw_input()" calls.
See docutils-users 2003-03-03.
- _`body.sidebar`: Add to the already implemented directive. Allow
internal section structure, with adornment styles independent of
the main document.
- _`body.list-table`: See `List-Driven Tables
<rst/alternatives.html#list-driven-tables>`_.
- _`colorize.python`: Colorize Python code. Fine for HTML output,
but what about other formats? Revert to a literal block? Do we
need some kind of "alternate" mechanism? Perhaps use a "pending"
transform, which could switch its output based on the "format" in
use. Use a factory function "transformFF()" which returns either
"HTMLTransform()" instance or "GenericTransform" instance?
If we take a Python-to-HTML pretty-printer and make it output a
Docutils internal doctree (as per nodes.py) instead of HTML, then
each output format's stylesheet (or equivalent) mechanism could
take care of the rest. The pretty-printer code could turn this
doctree fragment::
<literal_block xml:space="preserve">
print 'This is Python code.'
for i in range(10):
print i
</literal_block>
into something like this ("</>" is end-tag shorthand)::
<literal_block xml:space="preserve" class="python">
<keyword>print</> <string>'This is Python code.'</>
<keyword>for</> <identifier>i</> <keyword
>in</> <expression>range(10)</>:
<keyword>print</> <expression>i</>
</literal_block>
But I'm leaning toward adding a single new general-purpose
element, "phrase", equivalent to HTML's <span>. Here's the
example rewritten using the generic "phrase"::
<literal_block xml:space="preserve" class="python">
<phrase class="keyword">print</> <phrase
class="string">'This is Python code.'</>
<phrase class="keyword">for</> <phrase
class="identifier">i</> <phrase class="keyword">in</> <phrase
class="expression">range(10)</>:
<phrase class="keyword">print</> <phrase
class="expression">i</>
</literal_block>
It's more verbose but more easily extensible and more appropriate
for the case at hand. It allows us to edit style sheets to add
support for new formats, not the Docutils code itself.
Perhaps a single directive with a format parameter would be
better::
.. colorize:: python
print 'This is Python code.'
for i in range(10):
print i
But directives can have synonyms for convenience. "format::
python" was suggested, but "format" seems too generic.
- _`text.date`: Datestamp. For substitutions. The directive could
be followed by a formatting string, using strftime codes. Default
is "%Y-%m-%d" (ISO 8601 date), but time fields can also be used.
- Combined with the "include" directive, implement canned macros?
E.g.::
.. include:: <macros>
Today's date is |date|.
Where "macros" contains ``.. |date| date::``, among others.
- _`text.time`: Timestamp. For substitutions. Shortcut for
``.. date:: %H:%M``. Date fields can also be used.
- _`pysource.usage`: Extract a usage message from the program,
either by running it at the command line with a ``--help`` option
or through an exposed API. [Suggestion for Optik.]
Interpreted Text
----------------
Interpreted text is entirely a reStructuredText markup construct, a
way to get around built-in limitations of the medium. Some roles are
intended to introduce new doctree elements, such as "title-reference".
Others are merely convenience features, like "RFC".
All supported interpreted text roles must already be known to the
Parser when they are encountered in a document. Whether pre-defined
in core/client code, or in the document, doesn't matter; the roles
just need to have already been declared. Adding a new role often
involves adding a new element to the DTD and may require extensive
support, therefore such additions should be well thought-out. There
should be a limited number of roles.
The only place where no limit is placed on variation is at the start,
at the Reader/Parser interface. Transforms are inserted by the Reader
into the Transformer's queue, where non-standard elements are
converted. Once past the Transformer, no variation from the standard
Docutils doctree is possible.
An example is the Python Source Reader, which will use interpreted
text extensively. The default role will be "Python identifier", which
will be further interpreted by namespace context into <class>,
<method>, <module>, <attribute>, etc. elements (see pysource.dtd),
which will be transformed into standard hyperlink references, which
will be processed by the various Writers. No Writer will need to have
any knowledge of the Python-Reader origin of these elements.
* Alan Jaffray suggested (and I agree) that it would be sensible to:
- have a directive and/or command-line option to specify a default
role for interpreted text
- allow the reST processor to take an argument for the default role
(this will be subsumed by the above via the runtime settings
mechanism)
- issue a warning when processing documents with no default role
which contain interpreted text with no explicitly specified role
(there will always be a default role, so this won't happen)
* Add explicit interpreted text roles for the rest of the implicit
inline markup constructs: named-reference, anonymous-reference,
footnote-reference, citation-reference, substitution-reference,
target, uri-reference (& synonyms).
* Add directives for each role as well? This would allow indirect
nested markup::
This text contains |nested inline markup|.
.. |nested inline markup| emphasis::
nested ``inline`` markup
* Implement roles:
- "acronym" and "abbreviation": Associate the full text with a short
form. Jason Diamond's description:
I want to translate ```reST`:acronym:`` into ``<acronym
title='reStructuredText'>reST</acronym>``. The value of the
title attribute has to be defined out-of-band since you can't
parameterize interpreted text. Right now I have them in a
separate file but I'm experimenting with creating a directive
that will use some form of reST syntax to let you define them.
Should Docutils complain about undefined acronyms or
abbreviations?
What to do if there are multiple definitions? How to
differentiate between CSS (Content Scrambling System) and CSS
(Cascading Style Sheets) in a single document? David Priest
responds,
The short answer is: you don't. Anyone who did such a thing
would be writing very poor documentation indeed. (Though I
note that `somewhere else in the docs`__, there's mention of
allowing replacement text to be associated with the
abbreviation. That takes care of the duplicate
acronyms/abbreviations problem, though a writer would be
foolish to ever need it.)
__ `inline parameter syntax`_
How to define the full text? Possibilities:
1. With a directive and a definition list? ::
.. acronyms::
reST
reStructuredText
DPS
Docstring Processing System
Would this list remain in the document as a glossary, or would
it simply build an internal lookup table? A "glossary"
directive could be used to make the intention clear.
Acronyms/abbreviations and glossaries could work together.
Then again, a glossary could be formed by gathering individual
definitions from around the document.
2. Some kind of `inline parameter syntax`_? ::
`reST <reStructuredText>`:acronym: is `WYSIWYG <what you
see is what you get>`:acronym: plaintext markup.
.. _inline parameter syntax:
rst/alternatives.html#parameterized-interpreted-text
3. A combination of 1 & 2?
The multiple definitions issue could be handled by establishing
rules of priority. For example, directive-based lookup tables
have highest priority, followed by the first inline definition.
Multiple definitions in directive-based lookup tables would
trigger warnings, similar to the rules of `implicit hyperlink
targets`__.
__ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
- "annotation": The equivalent of the HTML "title" attribute. This
is secondary information that may "pop up" when the pointer hovers
over the main text. A corresponding directive would be required
to associate annotations with the original text (by name, or
positionally as in anonymous targets?).
- "figure", "table", "listing", "chapter", "page", etc: See `object
numbering and object references`_ above.
- "term"?: Unfamiliar or specialized terminology.
- "glossary-term": This would establish a link to a glossary. It
would require an associated "glossary-entry" directive, whose
contents could be a definition list::
.. glossary-entry::
term1
definition1
term2
definition2
This would allow entries to be defined anywhere in the document,
and collected (via a "glossary" directive perhaps) at one point.
Unimplemented Transforms
========================
* _`Footnote & Citation Gathering`
Collect and move footnotes & citations to the end of a document.
(Separate transforms.)
* _`Hyperlink Target Gathering`
It probably comes in two phases, because in a Python context we need
to *resolve* them on a per-docstring basis [do we? --DG], but if the
user is trying to do the callout form of presentation, they would
then want to group them all at the end of the document.
* _`Reference Merging`
When merging two or more subdocuments (such as docstrings),
conflicting references may need to be resolved. There may be:
* duplicate reference and/or substitution names that need to be made
unique; and/or
* duplicate footnote numbers that need to be renumbered.
Should this be done before or after reference-resolving transforms
are applied? What about references from within one subdocument to
inside another?
* _`Document Splitting`
If the processed document is written to multiple files (possibly in
a directory tree), it will need to be split up. Internal references
will have to be adjusted.
(HTML only? Initially, yes. Eventually, anything should be
splittable.)
Idea: insert a "destination" attribute into the root element of each
split-out document, containing the path/filename. The Output object
or Writer will recognize this attribute and split out the files
accordingly. Must allow for common headers & footers, prev/next,
breadcrumbs, etc.
* _`Navigation`
If a document is split up, each segment will need navigation links:
parent, children (small TOC), previous (preorder), next (preorder).
Part of `Document Splitting`_?
* _`List of System Messages`
The ``system_message`` elements are inserted into the document tree,
adjacent to the problems themselves where possible. Some (those
generated post-parse) are kept until later, in
``document.messages``, and added as a special final section,
"Docutils System Messages".
Docutils could be made to generate hyperlinks to all known
system_messages and add them to the document, perhaps to the end of
the "Docutils System Messages" section.
Fred L. Drake, Jr. wrote:
I'd like to propose that both parse- and transformation-time
messages are included in the "Docutils System Messages" section.
If there are no objections, I can make the change.
The advantage of the current way of doing things is that parse-time
system messages don't require a transform; they're already in the
document. This is valuable for testing (unit tests,
tools/quicktest.py). So if we do decide to make a change, I think
the insertion of parse-time system messages ought to remain as-is
and the Messages transform ought to move all parse-time system
messages (remove from their originally inserted positions, insert in
System Messages section).
* _`Index Generation`
HTML Writer
===========
* Construct a _`templating system`, as in ht2html/yaptu, using
directives and substitutions for dynamic stuff? Or a specialized
writer to generate .ht & links.h files for ht2html?
This is an overly generic, ambitious, and unnecessary idea. The two
systems, ht2html & yaptu, represent different approaches to
templating. Ht2html stiches bits of HTML together to make unified
web pages. Yaptu is for generic programmable text replacement.
Templating should simply be left to other systems. Users can choose
a templating system to apply to their reStructuredText documents as
best serves their interests.
* Add more support for <link> elements, especially for navigation
bars.
* Make the admonitions more distinctive and varied.
* Make the "class" attributes optional? Implies no stylesheet?
* Base list compaction on the spacing of source list? Would require
parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)
* Add a tool tip ("title" attribute?) to footnote back-links
identifying them as such. Text in Docutils language module.
* Add an option to restrict the document title to <head><title> only,
and not include it in the document body. Subtitle?
* Insert a comment at the top of HTML files that describes how to deal
with the broken servers w.r.t. encodings? Perhaps something like
this:
<!--
If your browser is showing gibberish, the server may be broken.
Try manually setting the character coding to "UTF-8". In
Mozilla/Firefox, do ... In Internet Explorer, do ...
For details, see <URL>.
-->
Front-End Tools
===============
* What about if we don't know which Reader and/or Writer we are
going to use? If the Reader/Writer is specified on the
command-line? (Will this ever happen?)
Perhaps have different types of front ends:
a) _`Fully qualified`: Reader and Writer are hard-coded into the
front end (e.g. ``pep2html [options]``, ``pysource2pdf
[options]``).
b) _`Partially qualified`: Reader is hard-coded, and the Writer is
specified a sub-command (e.g. ``pep2 html [options]``,
``pysource2 pdf [options]``). The Writer is known before option
processing happens, allowing the OptionParser to be built
dynamically. Alternatively, the Writer could be hard-coded and
the Reader specified as a sub-command (e.g. ``htmlfrom pep
[options]``).
c) _`Unqualified`: Reader and Writer are specified as subcommands
(e.g. ``publish pep html [options]``, ``publish pysource pdf
[options]``). A single front end would be sufficient, but
probably only useful for testing purposes.
d) _`Dynamic`: Reader and/or Writer are specified by options, with
defaults if unspecified (e.g. ``publish --writer pdf
[options]``). Is this possible? The option parser would have
to be told about new options it needs to handle, on the fly.
Component-specific options would have to be specified *after*
the component-specifying option.
Allow common options before subcommands, as in CVS? Or group all
options together? In the case of the `fully qualified`_
front ends, all the options will have to be grouped together
anyway, so there's no advantage (we can't use it to avoid
conflicts) to splitting common and component-specific options
apart.
* Parameterize help text & defaults somehow? Perhaps a callback? Or
initialize ``settings_spec`` in ``__init__`` or ``init_options``?
* Disable common options that don't apply?
* Implement the "sectnum" directive as a command-line option also?
* @@@ Come up with better names for the most-used tools, and install
them as scripts.
* Create a single dynamic_ or unqualified_ front end that can be
installed?
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
=== Added File Zope/lib/python/third_party/docutils/docs/dev/website.txt ===
===================
Docutils Web Site
===================
:Author: David Goodger; open to all Docutils developers
:Contact: goodger at python.org
:Date: $Date: 2004/10/29 18:24:45 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: This document has been placed in the public domain.
The Docutils web site, <http://docutils.sourceforge.net/>, is
maintained automatically by the docutils-update script, run as an
hourly cron job (by user "goodger"). The script will process any .txt
file which is newer than the corresponding .html file in the project's
web directory on SourceForge (``/home/groups/d/do/docutils/htdocs/``).
For a new .txt file, just SSH to SourceForge and ::
touch filename.html
chmod g+w filename.html
sleep 1
touch filename.txt
The script will take care of the rest within an hour. Thereafter
whenever the .txt file is modified (checked in to CVS), the .html will
be regenerated automatically.
After adding directories to CVS, allow the script to run once to
create the directories in the filesystem before preparing for HTML
processing as described above.
The docutils-update__ script is in CVS as
``sandbox/davidg/infrastructure/docutils-update``.
__ http://docutils.sf.net/sandbox/davidg/infrastructure/docutils-update
..
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